skills: inject a catalog, not full bodies, every turn #557

Parent

#548 (agent session architecture)

Problem

#526 injects up to 256 KiB of skill bodies into the system prompt every turn
(HARNESS_SESSION_MAX_ATTACHED_BODY_BYTES). We also shipped find_skill /
fetch_skill (#527). Other harnesses (Pi / OpenCode / Oh My Pi) do not
stuff playbook bodies into every request:

• Discover skills at start; put a short catalog (name, slug, one-line
  purpose) in the system block.
• hide: true / unattached → catalog-only or omitted.
• Full body only on explicit fetch or a small attach set.

Our 1.2M cached input on a normal turn is the static prefix (tools +
persona + skills + addenda). Bodies in that prefix make it huge and, when they
change, bust the KV cache.

Goal

Default inject = catalog (slugs + summaries). Bodies ride fetch_skill
(already exists) or a tight attach budget the operator chose.

Success: a new session with skills configured does not ship hundreds of KiB of
playbook text until the model (or user /skill-name) asks.

Constraints

• Do not remove /skill-name attach or Settings CRUD.
• Changing HARNESS_SESSION_MAX_ATTACHED_BODY_BYTES is a cap change —
  human gate in create-plan (plan-review rule). Prefer stop using the
  ceiling as the default inject over silently lowering the store cap.
• Feature-divide: host/server assemble; Wasm only shows skill_attached.
• Not status bar: show current context occupancy in addition to summed turn usage #556 (occupancy meter).

Maps from peer harnesses

Pi/OMP: YAML-frontmatter skills → XML manifest in system; hidden skills
reachable via skill:// or /skill:. We already have fetch; we should
stop double-paying (manifest and full bodies).

Suggested next

create-plan after or with #551 (budget). Touches the same system-prompt assembly as #558 (cache-stable blocks).

Orrery (2026-08-15)

Skill catalog and MCP / meta tool schemas live in the stable prefix. Snapshot the mounted tool list at session start. A mid-session tools/list_changed (or hanging extra meta_* tools) is a cache flush — honor it only at the same phase boundaries as #552, not mid-turn.

Gateway-style MCP (one small tool surface) stays dumb on our side: no 500-tool fan-out into the prefix.