| name | capability-remove |
| description | Removes an installed aos capability exactly, walking its lockfile entry backwards — jobs, symlinks, marker blocks, config keys, agents it created, its tool — and leaving the user's MOD.md in place so a re-install returns personalized. Use when the user says "remove", "uninstall", or "get rid of" and names an installed capability. Do NOT use to undo one setting or turn off a single schedule — that is capability-evolve — and not to retire something upstream, which is capability-contribute. |
| metadata | {"aos":{"origin":"capability-lifecycle@0.3.7"}} |
capability-remove
Not in context yet? Load the capability-lifecycle skill first — the map, the
contract, and the Experience rules.
aos-cap show <id> → the entry: artifacts and links (including the
capability's tool binary, recorded as an artifact), schedules_owned, config keys,
env variable names, scripts.- Scope: removing the capability entirely, or from one harness while it
stays installed elsewhere? Per-harness removal: run step 4 for that harness only
and skip its render deletion (the render is shared — it stays), then re-
record the
reduced set (start from aos-cap show, drop that harness's links/artifacts/jobs,
keep everything else), then step 6's verify scoped to that harness. The lockfile
entry and the MOD file both stay. Skip step 5. Step 3's dependents check still applies scoped to this harness (a
capability installed here that depends on this one). Note the lockfile's
schedules_owned is a flat id list with no harness dimension (§5.5), so identify
this harness's jobs by introspecting the harness, not by reading the lockfile.
Whole removal continues below.
- Dependents check: another entry in
aos-cap list whose manifest
depends.capabilities names this one → say so; stop unless the user insists (then
remove dependents first).
- Un-write per the cheat-sheet's Removal section (load
the
capability-lifecycle skill's reference/harness-<harness-runtime>.md now), in its
stated order — typically: jobs →
skill symlinks (delete the links; then delete only personal/capabilities/<id>/skills/
via a commit — never the capability directory itself and never its MOD.md — revertible, the persist
hook's dated message says why) → marker blocks → config keys → .env lines (ask
first) → agents this capability created and nothing else uses → scripts/hooks →
its tool (uv tool uninstall). A recorded link into <home>/vendor is a referenced
third-party skill: unlink it, and offer to drop the vendor clone only if no other entry
links into it.
Its machine-local state under <home>/.aos/ is not in the lockfile, so nothing walks
it backwards — removing kb leaves kb-principal.yml behind. Offer to delete it, and
say what it is: the list mapping this machine's human principals to their bases. It is
the user's, not the capability's, so an unasked deletion loses an answer they gave; a
re-install would otherwise adopt the old identity silently, which is right often enough
to be worth asking about rather than guessing.
- Tell the user their MOD.md stays: "your answers survive — in your personal repo,
reinstalling brings it back personalized."
- Verify: re-introspect until no
metadata.aos.origin, aos: names, marker
blocks, or links into personal/ remain; aos-cap remove <id>; friendly close.
