How to write a SKILL.md file

01 / Decision

Which frontmatter fields travel, and which stop at Claude Code

The Agent Skills specification defines six frontmatter fields. Claude Code accepts all six and adds fourteen more of its own. The distinction matters the moment a skill leaves the machine it was written on: claude.ai uploads, the Skills API, and packaging with the package_skill.py script from anthropics/skills accept only the six specification fields, and an extra key fails the operation with an unexpected-key error instead of being ignored.

02 / Workflow

Write a SKILL.md that fires, then finishes the job

The order matters. Triggering is decided before the body is ever read, so the description comes before the instructions, and the validation step comes before you hand the folder to anyone. Every constraint quoted below is cited beside the step it belongs to.

1. 01

   Start from a task you have already done, not from an idea

   The documented failure mode of skill authoring is asking a model to generate a skill from general knowledge, which produces vague procedure such as handle errors appropriately rather than the API patterns, edge cases, and project conventions that make a skill worth loading. Work through the real task with an agent first, then extract the reusable part: the sequence that worked, the corrections you made along the way, the input and output shapes, and the project facts the agent did not already have.

   Output: A page of notes that no general-purpose model could have written for you.

2. 02

   Name the directory, then match the frontmatter to it

   Create the folder first, because the specification requires the name field to match the parent directory name. The constraints are one to 64 characters, lowercase letters, numbers, and hyphens only, and no leading, trailing, or consecutive hyphen. Anthropic's authoring guidance adds two rules the specification does not state: prefer gerund names such as processing-pdfs over vague ones such as helper or utils, and avoid the reserved words anthropic and claude in the name. Claude Code treats the field as optional and, in a personal or project skill, uses it only as a display label, so a mismatch between file and folder passes locally and fails validation.

   Output: One directory whose name is also the command, and a name field that agrees with it.

3. 03

   Write the description as the trigger, not as a title

   This is the field with the highest leverage in the file. At startup an agent loads only the name and description of each installed skill, roughly a hundred tokens each, and decides from that alone whether to read the rest. Say what the skill does and when to use it, in the words a person would actually type, and include the cases where the user will not name the domain at all. Note that the two primary sources disagree on voice: Anthropic's best practices tell you to write in third person and treat you can use this to as an anti-pattern, while the specification site tells you to use imperative phrasing such as use this skill when. The descriptions Anthropic itself publishes reconcile the two by stating the capability in third person and the trigger as a Use when clause.

   Output: A description under 1024 characters that a stranger could match to their own request.

4. 04

   Write the body for an agent that is already competent

   Once the skill activates, the whole body enters the context window, and in Claude Code it stays there for the rest of the session, so every line is a recurring cost. Add only what the agent would get wrong without you: project conventions, non-obvious edge cases, the specific tool to use. Skip the paragraph explaining what a PDF is. Match the specificity to the fragility of the task: leave room where several approaches work and explain why, and be exact where a sequence must not vary. Where several tools would do, give one default and one escape hatch instead of a menu.

   Output: A body where every paragraph would change what the agent does.

5. 05

   Split anything long into referenced files, one level deep

   The specification recommends keeping SKILL.md under 500 lines and its instructions under roughly 5,000 tokens, with everything else in scripts, references, or assets beside it. Those files cost nothing until they are read. The rule that gets broken is depth: references have to link directly from SKILL.md, because an agent following a reference inside a reference often previews the file rather than reading it, and takes away partial information. Say when to load each one, not just that it exists, and put a table of contents at the top of any reference file longer than a hundred lines.

   Output: A SKILL.md that reads as a map, with the detail one hop away.

6. 06

   Bundle scripts only for work that should be deterministic

   A bundled script never enters the context window; only its output does, which makes it cheaper and more repeatable than asking the agent to regenerate the same logic each run. Use one when you see the agent reinventing the same parsing, chart, or validation step across runs. Write the script to handle its own error cases rather than failing and leaving the agent to improvise, justify any constant it hard-codes, and use forward slashes in every path so it works on all platforms. Say explicitly whether the agent should run the script or read it as reference.

   Output: Fewer generated lines, and a step that produces the same result twice.

7. 07

   Validate the frontmatter before anyone else runs it

   The specification points at one validator, the skills-ref reference library: skills-ref validate ./my-skill checks the frontmatter and the naming rules. Read its warning first, because the project states plainly that it is for demonstration purposes and not meant for production, so treat a pass as a syntax check rather than a certification. Inside Claude Code the equivalent checks are indirect: malformed YAML loads the body with empty metadata, so the slash command still works while the skill never triggers on its own, and starting with the debug flag shows the parse error.

   Output: Frontmatter that parses, and a name that will not be rejected on upload.

8. 08

   Test triggering and output as two separate questions

   Seeing a skill fire tells you the description worked, not that the instructions did. Test them apart. For triggering, write around twenty realistic prompts, half that should fire the skill and half near-misses that share its vocabulary but need something else, run each a few times because model behavior varies, and keep a validation subset back so you tune the description rather than memorize the test set. For output, build the evaluation cases before writing more documentation, and compare each run in a fresh session against the same task with the skill turned off.

   Output: Two numbers you can move independently: how often it fires, and how good the result is.

Once the folder exists, it still has to land somewhere the agent reads, which is the subject of how to install Claude skills in Claude Code.

03 / Record

The record worth keeping beside the skill

Six lines written once, next to the folder. They answer what the next author would otherwise have to reverse engineer from the file, and they record the date the constraints were checked, because both the specification and the products keep moving.

Directory and name

The folder name, and confirmation that the frontmatter name matches it exactly.

Trigger

The requests this skill should fire on, and the near-misses it should stay out of.

Freedom

Which parts of the body are prescriptive on purpose, and why that part is fragile.

Bundled files

Every file beside SKILL.md, and the condition under which the agent should open it.

Validation

The command that was run, its result, and whether the folder has to pass the six-field rule.

Reviewed at

Who checked the constraints, on what date, against which documentation page.

---
name: release-notes
description: Drafts release notes from merged pull requests and groups them by change type. Use when preparing a release, writing a changelog, or summarizing what shipped since the last tag.
license: Apache-2.0
---

# Release notes

## When this applies
The user is preparing a release or asking what shipped since a tag.

## Steps
1. List the pull requests merged since the last tag.
2. Group them into Added, Changed, and Fixed.
3. Write one line per change, in plain language, from the reader's point of view.
4. Link every entry to its pull request.

## Gotchas
- Squashed commits hide the original PR title. Read the merge commit body.
- Dependency bumps go in a single collapsed line, not one line each.

## Reference
For the full changelog format, read references/format.md before writing.

## Output
A Markdown section ready to paste into the release description.

04 / Pitfalls

Where a first SKILL.md goes wrong

05 / Checklist

Ready to share with the team?

• The skill came out of a task you had already completed, not out of a plausible idea.
• The directory name and the frontmatter name are the same string.
• The description names both the capability and the requests that should reach it.
• The body is under 500 lines, and everything longer sits in a file the agent is told when to open.
• The frontmatter passes a validation run, and you know whether it has to stay inside the six specification fields.
• You have tested triggering and output separately, in a session that was not the one you wrote the skill in.

06 / Questions

Frequently asked questions

What is the minimum valid SKILL.md file?

A directory containing SKILL.md, with YAML frontmatter holding a name and a description, followed by Markdown instructions. Nothing else is required. Anthropic's own published template is five lines: the two fields between frontmatter markers and a single heading you replace with the instructions.

Which frontmatter fields does SKILL.md support?

The specification defines six: name and description are required, and license, compatibility, metadata, and allowed-tools are optional. Claude Code accepts those six and adds fourteen of its own, including when_to_use, disable-model-invocation, user-invocable, context, and paths. The additional fields work only inside Claude Code.

How long should a SKILL.md file be?

Under 500 lines, and the instructions under roughly 5,000 tokens. That guidance appears in both the specification and Anthropic's authoring documentation. Longer material belongs in separate files under scripts, references, or assets, which stay on disk and cost nothing until the agent is told to open one.

Why does my skill never trigger?

Almost always the description. The agent sees only names and descriptions at startup and reads the body afterwards, so an unspecific description ends the decision before your instructions are seen. Malformed YAML is the other cause: the body loads with empty metadata, so the command works while automatic matching cannot.

Should the description be written in first, second, or third person?

The two primary sources disagree. Anthropic's best practices require third person and name second person as an anti-pattern. The specification site recommends imperative phrasing such as use this skill when. The published examples reconcile them: state the capability in third person, then add a Use when clause.

How do I validate a SKILL.md before sharing it?

Run skills-ref validate on the skill directory, using the reference library the specification links to. Read its caveat first: the project describes itself as demonstration software rather than production software. Inside Claude Code, starting a session with the debug flag surfaces frontmatter parse errors that otherwise fail silently.