install
Installs an aos capability into this harness: reads its briefing, gates the skill names it would claim, renders it against the user's MOD.md, and materializes agents, symlinks, cron jobs and context blocks behind a diff gate. Use when the user says "install" or "set up" and names a capability, offers a capability directory or CAPABILITY.md to install, or when another install needs a missing dependency installed first. Do NOT use to re-render an already-installed capability against fresher upstream — that is capability-upgrade — and not to change how an installed one behaves, which is capability-evolve. The interview it runs mid-install belongs to capability-onboard.
- License 许可
- MIT
- 所属仓库
- AlmogBaku/aos
- 最近更新
- 2026-11-15
- Stars
- ★ 5
- Forks
- 2
01 前言 Front Matter
- name
- install
- description
- Installs an aos capability into this harness: reads its briefing, gates the skill names it would claim, renders it against the user's MOD.md, and materializes agents, symlinks, cron jobs and context blocks behind a diff gate. Use when the user says "install" or "set up" and names a capability, offers a capability directory or CAPABILITY.md to install, or when another install needs a missing dependency installed first. Do NOT use to re-render an already-installed capability against fresher upstream — that is capability-upgrade — and not to change how an installed one behaves, which is capability-evolve. The interview it runs mid-install belongs to capability-onboard.
03 SKILL.md 正文
capability-install
Not in context yet? Load the capability-lifecycle skill first — the map, the contract,
the overlay doctrine, and the Experience rules. Then:
- Resolve the capability dir across the household —
personal/capabilities/<id>first, thenupstream/capabilities/<id>, counting a directory as a source only if it holds aCAPABILITY.md(a MOD-only directory is the user's overlay at its mirrored path, not a package); both are real packages → say so loudly and ask which (never silently prefer). Thenaos-cap manifest <dir>→ validated JSON. Validation failure → show the tool's error, offer fix-or-report; never improvise a parse. Then hold the briefing to the declarations: it may say how to wire things, never where — a briefing that places something the manifest does not declare ("a dedicated profile", "every profile that calls me") → stop and report a package defect (contract). aos-cap show <id>: installed at this version → say so, stop; older → hand to {{skill: upgrade}}.- Dependencies: each
depends.capabilitiesmissing fromaos-cap list→ announce briefly ("work-tracker needs kb — setting that up first"), install it first, its interview included. Everyusesprovider is a dependency, so it is installed by now; itsuses[].installed_namecomes from the manifest JSON. - Your harness is the program hosting you. When
aos-cap --home <aos_home> harness showexits 20 (none recorded), record it:aos-cap --home <aos_home> harness set <harness-runtime>; a household that records another harness keeps it (the oneaos-sessiondrives). Load your harness's cheat-sheet now — it travels with thecapability-lifecycleskill asreference/harness-<harness-runtime>.md(load that skill, then read the file). Thedepends.hostrows (mapping.<word>) first, read as what the harness can express, not as what the user has wired today (contract): arequiredfeature atsupport: none→ friendly stop with the reason; a supported-but-unconfigured channel → install, and say what they still need to set up;preferredunsupported → note each cron job's declared degraded mode for recording. - Name gate, before anything is written:
aos-cap --home <aos_home> skills <dir> --check --harness-skills <dir> …— one--harness-skillsper skills dir this harness reads, per the cheat-sheet'smapping.skill. Read itschecked:lines — a source it could not reach is named in capitals, and "clean" against two of three sources is not clean. Exit 17 → stop and report which name is taken and by whom; a collision is fixed in the package ({{skill: contribute}}, or the user's own source), never by renaming here. Clean → the printed installed names are what every later step uses (thecapability-lifecycleskill'sreference/naming.md). In the same breath, if the capability shipsagents/:aos-cap --home <aos_home> agents <dir> --check— agents land in a flat per-harness namespace too, so the same exit 17 and the same rule (fix the package, never rename here). It checks two of three sources; the third — agents already in the harness — has no enumeration yet and says so in capitals, so glance at what the harness already has. - Interview, iff the capability ships ONBOARDING.md — run it per the
capability-lifecycleskill'sreference/overlay.md(batched, typed validation, secrets → store per the cheat-sheet's Secrets section) → write<aos_home>/personal/capabilities/<id>/MOD.md(capability-lifecycle's own:<aos_home>/personal/MOD.md— thecapability-lifecycleskill'sreference/overlay.md, Which MOD.md). - Render into staging, then transform:
aos-cap render <dir> <skill-id> --out <aos_home>/rendered/.staging/<id>/skillsper declared skill, plus any other subtree the briefing pins (adapters/, say, leaving__pycache__and*.pycbehind) copied torendered/.staging/<id>/— mechanical: installed name, frontmattername,metadata.aos.origin. Then the transform per thecapability-lifecycleskill'sreference/overlay.md, against this capability's MOD.md (Which MOD.md): fill{{mod}}slots, weave its prose statements, bake<aos_home>— and a baked render path namesrendered/<id>/, the live render, never.staging/. Source files stay untouched. - STAGE per the cheat-sheet's Materialization guide: the render sits in
rendered/.staging/<id>/, nothing live yet, plus the exact native command plan — agents (an existing one is adopted only on positive evidence it is this capability's, never re-created; none → stop and ask — contract), skill symlinks (the installed name → the render, perused_by; container harness → verify the<aos_home>/renderedmount per the cheat-sheet),useslinks (per row: the provider's recorded render fromaos-cap show <provider>→ each listed agent's skills location, underinstalled_name; a path another entry or a stranger holds → stop), cron jobs (aos:<cap>:<cron-id>, single-owner check first), context blocks (markers), config keys, the capability's own tool install line — plus, when the package does not declare it, the default an agent only the user talks to gets (contract), the cheat-sheet's standing links, and whatever the root MOD's household rules add to each agent this install creates or adopts (thecapability-lifecycleskill'sreference/overlay.md). Touch no harness file yet. Second-harness install: stage links + native plan only (the render already exists); cron jobs stay with their current owner unless the user reassigns. - GATE: show the full plan, payoff-framed — each artifact → what it does
for the user — with the staged render's contents (
diff -ruN -x __pycache__ -x '*.pyc' <an empty dir> <aos_home>/rendered/.staging/<id>lists every file). Wait (unless the root MOD.md says auto-accept). Declined →aos-cap discard <id>, and stop. - EXECUTE the approved plan:
aos-cap swap <id>puts the render live atrendered/<id>/, then create the symlinks into it and run the native plan;kb:zones → draft grant rows into each target KB's## Grantstable, user approves. A capability's tool may write machine-local files under<aos_home>/.aos/— kb writeskb-principal.yml(kb init --principalfills in a missing one,kb config set principal.id=changes it) andkb-registry.yaml(onkb init/kb adopt). Do not create them yourself: the tool owns them, the same wayaos-capowns the lockfile. Say they exist in the summary so the user is not surprised by files nobody mentioned, and leave them out ofrecord(machine-local state is not a materialized artifact — hashing it would report drift the first time the tool touched it). aos-cap record <id> --version <v> --source-root <root> --artifact <render-file>… --link <symlink>… --uses-link <symlink>… --job <id>… --config-key <k>…(--jobids land incron_owned) —useslinks go to--uses-link, never--link(exit 19: one owner per link) —<root>is whichever root step 1 resolved the capability dir in (upstreamfor shipped capabilities,personalfor the user's own); render files go to--artifact(hashed), symlinks to--link(a symlink passed as--artifactfails: exit 16 — so a tool binary needsreadlink -f $(command -v <tool>)first, sinceuv tool installputs a link on PATH).recordreplaces the entry wholesale: on a second-harness install, start fromaos-cap show <id>and pass the combined set (both harnesses' links), never just this harness's.aos-cap verify <id>— exit 13 means what you just recorded does not match what is on disk (a link that is a copy, a missed render, a hash taken before the transform). Fix it now: you still know what you wrote, and the next person to find out would be {{skill: upgrade}}, months from now. Hooks get the same check from the harness side: each one consented and active per the cheat-sheet (its doctor, where the harness has one) — a hook the harness skips fails silently.- Celebrate specifically: what, where, which cron jobs, degraded modes in effect.
04 同仓库更多 Skills
wt-update
Updates an existing commitment when the user reports progress: completion, a new deadline, a stall, or abandonment. Use when the user says "I did that", "finished X", "still waiting on Y", "push that to next week", "I started it", or "forget it, I'm not doing X". Finds the matching open action, applies the change, and routes any knowledge the report carries to the knowledge base. Do NOT use to file a new commitment (that is wt-capture) or to find time for one (wt-schedule).
wt-steward
Maintains an existing commitments backlog: overdue, about to expire, stalled, and repeatedly-rescheduled commitments, and someday items gone cold. Use when the nightly cron job fires or the user asks to review or tidy their backlog ('review my backlog', 'what's gone stale on my list'). Does not capture or schedule new work — that happens when the user speaks, through wt-capture and wt-schedule.
wt-schedule
Estimates a commitment, links it to its project, and blocks time for it on the user's calendar. Use when the user asks to find time for something — "when can I do this?", "find me two hours for the CFP", "block time for that tomorrow", "I want to work on it today" — and immediately after wt-capture files a commitment that needs real hours. Do NOT use for a commitment that needs only a deadline or a reminder, and do NOT use to change what the user committed to — that is wt-update.
wt-capture
Records something the user has said they must do themselves: classifies the commitment as next, waiting, someday or trivial, writes it as an action page in their commitments base, and hands off to wt-schedule when it needs real hours. Use when the user commits to work of their own — "I need to find time to…", "I have to…", "remind me to…", "help me remember…", "put that on my list", "I should … at some point". Do NOT use when the user asks the assistant to do the work ("write the CFP", "research X", "email Sam") — that is a request to act now, not a commitment to track. Do NOT use for thoughts, facts or notes carrying no commitment; those are knowledge and belong to kb-capture.
work-tracker
Answers questions about the user's own commitments by querying their commitments base, explains the four statuses (next, waiting, someday, done), routes a request to the right work-tracker skill, and states who may change what without asking. Use when the user asks what they should be working on, what is overdue, what they are waiting on, or how their task tracking works, and no narrower work-tracker skill matches. Do NOT use to file a commitment the user just made (that is wt-capture), to find time for one (wt-schedule), or to report progress on one (wt-update).
kb
Explains how the user's knowledge bases are laid out and which kb skill handles a given job — the tree, the one queue, expiry, links, base health, maintenance. Use when the user asks how their knowledge base works, what state a base is in, why something was or was not kept, or wants base maintenance run, and no narrower kb skill matches. Do NOT use to file something the user just said (that is kb-capture), to answer a question from stored knowledge (that is kb-recall), or to pick a destination base for a write already in hand (that is kb-route).