Skip to main content

ADR 0047: Keep Skill Routing Metadata Concise

Status​

Accepted.

Context​

Codex sees every installed skill's frontmatter name and description while it decides whether to load the skill body. This makes the description an always-visible routing surface, unlike the procedural body that is loaded only after selection.

STAGE's three descriptions had grown from routing summaries into abbreviated policy copies. Together they used 969 characters. The visual-review description alone repeated explicit invocation, inventory stopping, and detached-artifact rules already owned by its body. That duplication consumed shared context on unrelated tasks and created another policy surface that could drift.

Decision​

Keep each skill description at or below 220 characters. It must identify:

  • what job the skill performs;
  • when that job should trigger; and
  • only the route boundary needed to distinguish it from neighboring skills.

Detailed authority, stopping, preservation, evidence, and execution rules stay in SKILL.md. Launcher examples remain governed separately by ADR 0046.

Consequences​

  • Unrelated tasks carry less STAGE routing metadata.
  • Skill selection retains the terms needed to distinguish ordinary delivery, project mapping, and bounded visual diagnosis.
  • Policy has one agent-facing source after a skill is selected.
  • The smaller descriptions do not by themselves prove lower whole-task token use; model traces report aggregate context rather than description-level attribution.
Last updated on