10. Agent Skills use progressive disclosure with durable activations

Copy Markdown View Source

Date: 2026-06-01 Status: Accepted

Context

Pixir has deferred SKILL.md support since v0.1, but its existing architecture already sets two hard constraints. First, the Log is the source of truth (ADR 0003/0004), so anything that changes what the model knew during a Turn must be replayable on resume and fork. Second, file tools are confined to the Workspace (ADR 0006), while user skills may live in user-level or agent-level directories outside the Workspace.

Codex, Pi, and Hermes all converge on the same shape: expose cheap skill metadata first, then load full instructions only when a skill is selected. Pixir should follow that progressive-disclosure pattern without weakening Workspace confinement.

Decision

A Skill is a reusable instruction package, not an Agent and not a Tool. Pixir will surface available Skills through a dedicated Skills layer that lists bounded metadata and loads Skill content from registered skill roots. The existing read Tool remains Workspace-confined; it does not gain permission to read arbitrary user skill paths.

The model-facing v1 surface is read-only Tools: skills_list for bounded metadata and skill_view for a selected Skill's instructions or an explicit supporting file. These Tools follow ADR 0005 like every other Tool (__tool__/0, dry-run, structured errors, bounded model output), but they are not the Skills themselves; they are the controlled way to inspect registered Skill packages.

Calling skill_view for the main SKILL.md counts as a Skill Activation and records the canonical activation event. Calling skill_view for supporting files does not create a new activation; it is an auxiliary read of an already discoverable resource. There is no separate activate_skill action in v1.

Each Turn includes a compact, budgeted index of available Skills, shaped like name / description / location, so the model can decide when a Skill is relevant. Full instructions are loaded only through skill_view or explicit user invocation; the index is discovery metadata, not the Skill body. Duplicate warnings and richer discovery details remain available through skills_list; they do not need to occupy every Turn's system prompt.

Explicit user invocation accepts both Codex-style $skill-name mentions and terminal-style /skill-name commands where the presenter can support slash commands. Both syntaxes resolve to the same Skill Activation semantics and canonical event.

Pixir discovers Skills from both the shared agent convention and Pixir's own global state: repository .agents/skills roots, user ~/.agents/skills, and ~/.pixir/skills (respecting PIXIR_HOME for the Pixir root). This keeps Pixir interoperable with Codex/Pi/Hermes-style Skill bundles while preserving a Pixir-native home for local state and future first-party Skills.

When multiple Skills declare the same name, Pixir resolves by scope precedence: repo Skills win over user Skills, which win over Pixir-global Skills. The selected activation still records the exact path and hash, and the loader reports duplicate-name warnings so shadowing is visible.

A Skill Activation is canonical History. When a Skill is selected by the user or by the model to guide a Turn, Pixir records a durable activation event. That event stores the Skill identity, source, resolved path, content hash, and the loaded SKILL.md instruction snapshot used for that Turn. Supporting files (references/, templates/, scripts/, assets/) remain progressively disclosed: they are read and persisted only if explicitly loaded later.

Skill Activations are per-Turn, not sticky Session state. A later Turn may activate the same Skill again, but no Skill remains active merely because it was used earlier.

Skill scripts are never auto-run as part of loading or activating a Skill. skill_view may reveal or list them, but executing one is an ordinary bash Tool call subject to the current permission mode and all existing Tool ergonomics.

Consequences

  • Resume, fork, and replay preserve which Skill shaped a Turn, even if the on-disk Skill changes later.
  • Skill reads outside the Workspace go through a narrow, auditable Skills surface instead of expanding the authority of read.
  • Logs grow when a Skill is activated, but only by the instruction snapshot actually sent to the model; supporting resources remain on-demand.
  • Adding skill_activation is a deliberate extension of the canonical Event vocabulary, so Pixir.Event, Pixir.Log.fold/2, Provider history folding, and presentation layers must all be updated together.