Skip to main content

Triggered skills are installed where the runtime finds them

Mission Control gave an agent its triggered skills its own way: their names and descriptions in the opening prompt, and the skill itself through mission-control skill get, rendered for the task as a template (ADR 0008) with its files written to the run's directory. The runtimes we use have skills of their own that work differently: a skill is a directory with a SKILL.md, its name and description in the frontmatter, found in a known place and loaded when the runtime decides it fits. Codex looks in ~/.agents/skills, Claude Code in ~/.claude/skills, and npx skills keeps one copy in the first with a link from the second. An agent with two ideas of what a skill is uses ours less well than its own, which is ADR 0023's lesson again. We decided that triggered skills are installed into the role's home (ADR 0023), which is the runtime's HOME: before every run, Mission Control writes each triggered skill the role has to ~/.agents/skills/<slug> and links it from ~/.claude/skills/<slug>, and the runtime finds and loads it as it would any skill. Mission Control stays where skills are kept, given to roles, edited and versioned; the home is where they are used. Ambient skills are unchanged: they are part of the opening prompt.

Considered Options​

  • Keeping triggered skills in the prompt and behind skill get: rejected; it is the last place a run differs from the runtime it runs on, and the runtime cannot load a skill it does not know.
  • A skill source npx skills installs from: deferred. Serving an organization's skills as a repository the tool understands is more than this needs; the layout it uses is what matters, and a person gets the same with mission-control skill sync.
  • The agent installing its skills itself, with a command in its instructions: rejected. Mission Control knows which skills a role has when the run starts, and a skill that depends on the agent remembering to install it is one it will sometimes lack.
  • Rendering triggered skills for the task before installing them: rejected. A role's home is shared by its runs at once, so an installed skill cannot be one task's. No triggered skill we have uses a template; ambient skills, which are in the prompt, still do.

Consequences​

  • Mission Control owns only what it installed. A manifest in ~/.agents/skills lists the skills it wrote. Each run start writes those the role has now, replacing each whole, and removes those it no longer has; a skill the agent installed itself is left alone, and wins when it has the same name, which is logged.
  • Edits in the home are overwritten at the next run start. A role with write access to a skill changes it in Mission Control, with mission-control skill update <slug> --dir <path> from an edited copy, so the change is versioned and reaches every role that has it.
  • A person gets the same layout with mission-control skill sync, for a role's skills (--role) or the organization's, so a coding agent on a laptop has the skills its organization wrote, installed as its runtime expects.
  • The prompt no longer lists triggered skills, and skill get reads a skill as it is stored, no longer rendered for a run. Triggered skills are plain text: a template in one renders as written.
  • Which skills a run used is no longer recorded as a run event, since the runtime loads them itself; the transcript shows it, and reading it from there is left for later.
  • Skill files are no longer written to each run's directory for triggered skills; ambient skills' files still are, as the prompt points at them.