# 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.

Source: <https://www.contexory.com/docs/reference/skill-md-anatomy>

## 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.
```

_A complete, minimal skill. The frontmatter is two fields; everything else is prose._

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](/docs/reference/frontmatter-reference).

> **The description is the trigger**
>
> An agent chooses a skill by reading descriptions, not bodies. A description that names a topic ("Contract review.") gives it nothing to match on; one that names a situation ("Use when the user asks for a contract to be reviewed…") does. This is the single most common reason a skill never fires.

## 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**
>
> Refer to a supporting file the way the body will need to resolve it: `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](/docs/reference/claude-code-vs-openclaw) 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.