What every part of a SKILL.md is for
A skill is one Markdown file and, optionally, a folder of supporting files. Everything an agent needs to decide whether to use the skill, and how, lives in that file.
The shape of the file
A SKILL.md has exactly two parts: a YAML frontmatter block delimited by ---, and a Markdown body beneath it.
The frontmatter is metadata the agent reads to decide whether to use the skill. The body is the instructions it follows once it has decided. Both matter, and they fail in different ways: weak frontmatter means the skill never fires, weak body copy means it fires and does the wrong thing.
---
name: pdf-review-checklist
description: Use when the user asks for a contract or PDF to be reviewed. Walks the standard clause checklist and reports findings by severity.
---
# PDF review checklist
Work through the clauses in order. Report every finding with its severity.
## Steps
1. Confirm the parties and the effective date.
2. Check the termination clause against `references/termination.md`.
3. Summarise findings, most severe first.Nothing else is required. A skill with a valid name, a description that says when to use it, and a body that says what to do is a complete skill.
The frontmatter
Two fields are required (name and description), and four are optional: allowed-tools, license, compatibility and metadata.
Each field, its constraints, and what a good value looks like are covered in the frontmatter reference.
The description is the trigger
The body
The body is read after the skill has been selected, so it does not need to sell itself; it needs to be followable. Three things make the difference:
- Write instructions, not description. "Confirm the parties and the effective date" beats "This skill covers party confirmation."
- Name the artefacts. Which checklist, which threshold, which output format. An agent cannot infer a house convention.
- Order the steps. If sequence matters, number them. If it does not, say so; otherwise the agent will assume it does.
Headings are the body's structure and also its only durable anchor: when a host merges several context files into one, headings survive and filenames do not.
Supporting files
A skill may ship supporting files in three folders beside its SKILL.md. Each folder means something specific:
| Path | What belongs there |
|---|---|
SKILL.md | The skill itself: frontmatter plus body. Always at the root, always this exact filename. |
references/ | Longer material the body links to: rubrics, checklists, worked examples. Read on demand rather than every time. |
scripts/ | Executable helpers the skill tells the agent to run. |
assets/ | Templates and files the skill produces or fills in. |
Paths are exactly one folder deep. references/termination.md is valid; references/clauses/termination.md is not.
Link supporting files by path
references/termination.md, not "the termination reference". The path is what makes it reachable.How long it should be
Body length is a retrieval concern, not a style preference. A long body is more context for the agent to hold and more places for the instruction that matters to get lost:
| Body length | What happens |
|---|---|
| Under 400 lines | Fine. No warning. |
| 400–500 lines | Flagged as a warning. Worth splitting before it grows further. |
| Over 500 lines | Flagged as an error. Move detail into references/ and link to it. |
The fix is progressive disclosure: keep the decision and the steps in the body, move the detail behind a link. The agent reads the reference only when the step it is on needs it.
Writing it to travel
The same skill may run in more than one host, and the hosts disagree about where files live. Three habits keep a skill working everywhere, and the host comparison explains why each one matters:
- Never name the host. The skill does not know where it is running.
- Never reference another context file by name. Files merge between hosts; point at a heading instead.
- Never hard-code where your own files live. The plugin decides paths; the agent already has the skill.