Skip to main content

ADR-040: SKILL.md Body Structure

Date: 2026-11-16
Status: Accepted

Context

A SKILL.md body is an instruction document a model follows with no editor and no ability to ask
questions. Free-form prose gives the model no way to tell a definition from a step, a preference from
a hard rule, or an excuse from a prohibition. Every member written from scratch invents its own
layout, and the ones that work share a shape the others do not.

Two costs follow from an unstructured body. A body that mixes "what this is" into the middle of the
process gets truncated first when the budget bites, and a body with no stop conditions lets the model
rationalise past the rule it was given.

Decision

A member body has six sections, in this order. The Sentinel checks for them.

SectionContentWhy it exists
## OverviewWhat the member is, the failure it preventsThe model needs the goal before the steps
## When to UseConcrete triggers, and what it is not forRouting and false-positive prevention
## ProcessOrdered, imperative, verifiable stepsThe work itself
## Red FlagsWhat to stop and reportStop conditions, not preferences
## RationalizationsExcuse → counter, usually a tableThe shortcut the model would take
## VerificationHow to check the work before claiming doneThe definition of finished

Rules that follow from the shape:

  1. The body is instructions, not documentation. No changelog, no history, no author biography. Background that a step needs is one line inside that step.
  2. Progressive disclosure. A body stays under about 5000 tokens (verify --tokens); long material moves to references/ and the body says when to read it. The body is paid for again on every activation.
  3. Relative paths only. Files a body points at resolve from the skill directory, never the project root, and never escape it (findMissingReferences, ADR-036).
  4. Cross-skill calls are by name. A skill that needs another calls activate_skill; it never copies the other body in (ADR-038). One-shot instructions opt out of replay with compaction-replay: false.
  5. The six sections are prose, the frontmatter is the contract. Tools, model targets, requirements and variants belong in frontmatter where they are parsed and gated (ADR-028, ADR-037), never in prose.

Alternatives Considered

OptionProsConsWhy Rejected
Free-form bodymaximum author freedomno way to verify completeness, drift between membersRejected: the Sentinel audit needs a shape
A rigid template with required bullet countsmechanical checkingproduces filler; the worst members are the ones filling slotsRejected
XML-tagged sectionsmachine-parseableunreadable for humans reviewing the diffRejected: SKILL.md is reviewed as prose

Consequences

  • A new member starts from the Oracle template, not from a blank file.
  • A missing section is a review finding, not a runtime error: the body is instructions, and the runtime has no schema for prose.
  • The rationale for the shape lives here, so a reviewer can say "this is an ADR-040 problem" instead of arguing style.

References

  • The Oracle: the template and the section contract
  • ADR-028: the frontmatter half of the contract
  • ADR-038: compaction protection and replay
  • CONTRIBUTING-skills.md: the authoring checklist