The Body of a Skill

What it is for

An agent ignores a SKILL.md for a small number of specific reasons: it is too long, it explains instead of instructing, it repeats what the model already knows, or it buries the rule under context. This covers what to put in the body and what to take out.

The skill Copy

The body is read only after the description has matched. Write it for an agent
that is already mid-task and short of context.

Structure that works:
1. **The rule, first, in the imperative.** "Read the file before editing it."
   Not "it is generally advisable to...".
2. **The failure it prevents, immediately after.** A rule with no consequence
   attached is the first thing dropped when context gets tight.
3. **One correct example from a real codebase.** The agent pattern-matches on
   it far more strongly than on prose.
4. **The anti-pattern, named, with its symptom.** "If you see X, this rule was
   not followed."

Four things that make a skill get ignored:
- **Length.** Past a few hundred lines it is sampled, not followed. Split it and
  reference the parts.
- **Prose without imperatives.** An essay about a topic gives nothing to obey.
- **Rules with no reason.** They are dropped first.
- **Contradicting the user's own instructions.** A skill loses that argument,
  and should: it is a default, not an override.

Reference material — long tables, API surfaces, edge-case catalogues — goes in
sibling files that the body points at by name. The body stays the part that is
always read; the references are read when needed.

How to install it Copy

Claude Code / Claude Desktop

1. Create a folder named after the skill inside your skills directory:
   - Claude Code: `~/.claude/skills/<skill-name>/`
   - A project-local skill: `<project>/.claude/skills/<skill-name>/`
2. Save the text below as `SKILL.md` in that folder, keeping the
   `---` frontmatter block at the top — the `name` and `description`
   fields are what make the skill discoverable.
3. Restart Claude Code, or run `/skills` to confirm it is listed.

The skill loads only when its `description` matches what you are doing,
so a precise description matters more than a long body.

Did it work for you?

Where it came from