Anatomy of a Skill

A skill is built for progressive disclosure: three layers of information, each revealed only when it's needed. Get the layering right and the agent pays attention to the right thing at the right moment. Get it wrong — everything crammed into one always-loaded blob — and you drown the signal you worked so hard to isolate in Module 01.

The three layers

The Agent Skills standard structures a skill so that progressively more detail loads as the agent commits to using it:

1. Metadata — the frontmatter name and description. Always in the agent's context, for every skill in the library. This is how the agent decides whether a skill is relevant at all.
2. The SKILL.md body — loaded only when the skill triggers. The workflow, commands, and gotchas.
3. references/ and scripts/ — loaded or executed only when the body points to them. The bulky detail and the runnable helpers.

The economics follow the layering: layer 1 is cheap and ever-present, so it must be tiny; layer 3 can be large because it's rarely paid for. Most authoring mistakes are a layer confusion — putting layer-3 bulk in layer 2, or layer-2 triggers in a layer-1 that's already too long.

What's on disk

Here's the workshop's incident_triage skill, a complete example you'll dissect by hand in the exercises:

library/skills/incident_triage/
├── SKILL.md                      # frontmatter (layer 1) + body (layer 2)
├── EVAL.yaml                     # the contract: what "working" means
├── OWNERS                        # who's accountable
├── references/
│   └── summary_template.md       # layer 3: loaded only at the drafting step
└── scripts/
    └── seed_fixture.sh           # deterministic data for the eval

SKILL.md is the only required file, but a skill you intend to operate — ship, review, retire — needs the others too. EVAL.yaml is its contract (Module 05): without it you have no way to answer "is this skill still working?" except anecdote. OWNERS names the accountable team (Module 06): without it, a skill that regresses has no one on the hook to fix it, and a library of unowned skills is how rot sets in. Neither file is optional once a skill is shared beyond the person who wrote it — they're the difference between a personal note and a component other people can trust, review, and eventually retire on evidence.

Layer 1: the description does the discovery

Only the name and description sit in the system prompt, so the description is the entire basis on which the agent decides to load a skill. It has a job to do, not space to fill:

description: >-
  Triages production incidents: pulls recent alerts, correlates deployments and
  error spikes, identifies the likely owning service, and drafts an incident
  summary with severity and next steps. Use when investigating an outage, a
  latency spike, a surge in errors, a failing health check, or when asked
  "what's broken" / "why are bookings failing". Don't use for postmortem
  writing (use the postmortem skill) or for filing routine bugs.

Notice the shape: a third-person capability statement, then concrete "Use when" triggers phrased the way a real user would, then "Don't use for" negative triggers that fence it off from sibling skills. That structure is what makes the skill trigger — the single biggest failure mode is a description so vague the agent never loads the skill at all. Module 03 is entirely about getting this right; for now, just see that discovery lives here, in layer 1.

Layers 2 and 3: split, don't duplicate

The body carries the workflow and the gotchas. When a chunk of detail is bulky and only needed at one step, it moves to references/ and the body links to it:

<!-- In SKILL.md (layer 2) — a pointer, not the whole template -->
Fill the template in [references/summary_template.md](references/summary_template.md).

Two rules keep this clean, and both have the same rationale — avoid paying for context you don't need and avoid contradictions. First, information lives in SKILL.md or in references/, never duplicated in both; duplicated content drifts out of sync and the agent can't tell which copy is authoritative. Second, references stay one level deep — linked from SKILL.md, never from another reference — so the agent never has to chase a chain to find what it needs. And use repo-relative paths only, never file:// or a machine-specific path: a skill runs in someone else's checkout, in CI, or inside a different agent, and an absolute path from your laptop resolves to nothing there — the reference silently fails to load and the agent proceeds as if it never existed.

scripts/ follows the same on-demand logic as references/, but earns its place for a different reason: put something there when the agent needs a deterministic action rather than information — incident_triage ships seed_fixture.sh so its eval builds identical mock data every run. If the agent could just as well write the script itself from the task, it doesn't belong here (that's the one-off-script boundary from Module 01); reserve scripts/ for helpers whose exact behavior the skill depends on.

Key takeaways

• A skill is three disclosure layers: always-on metadata, on-trigger body, on-demand references. Match each piece of content to the cheapest layer that can hold it.
• SKILL.md is required; EVAL.yaml and OWNERS are what make a skill operable rather than a personal note.
• The description is layer 1 and does all the discovery work; references are layer 3 and stay one level deep, never duplicating the body.

Drill it

• ex01_dissect_a_skill — walk incident_triage layer by layer and predict, from the description alone, when it will and won't trigger.
• ex03_fix_the_trigger — repair a deliberately vague description using validate_skill.py as the feedback loop.

(Exercises unlock in the Exercises section; the cross-linking pass wires direct links once they're built.)