How to Write a SKILL.md File
Updated September 17, 2026
Writing a SKILL.md file is mostly a writing problem, not a formatting one. The format is two required fields and some Markdown. What decides whether Claude uses the skill is the description, and what decides whether the result is any good is how the instructions are written. This guide covers both, using the rules in Anthropic's authoring guide and the Agent Skills specification.
The short answer
- Write the description in third person, saying what the skill does and when to use it, with the words a real request would contain.
- Assume Claude is capable. Add only what it does not already know: your steps, your rules, your format.
- Show an example of input and output where the quality of the result depends on style.
- Add a feedback loop: check the result against a list or a script, fix, repeat.
- Leave out dates that will go stale, menus of alternatives, Windows-style paths, and explanations of things Claude knows.
The description decides whether the skill is used
When a session starts, Claude loads only the name and description of every available skill. It reads the rest of SKILL.md after a request matches one. That makes the description the single line that most decides whether your work is ever read.
Anthropic's guide has three firm rules. Write in third person, because the description is injected into the system prompt and a first-person “I can help you…” reads inconsistently there. Say what the skill does and when to use it, in that order. And include the specific terms a user would type: file types, task names, the nouns in the request. Its example of a description that works: “Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.” Its examples of ones that fail: “Helps with documents”, “Processes data”, “Does stuff with files”.
The limit is 1,024 characters and it may not contain XML tags. In Claude Code, the description and the optional when_to_use field are combined and cut at 1,536 characters, so put the trigger words early.
Write the body for a reader who is already smart
Anthropic's default assumption is stated plainly: Claude is already very smart, so add only the context it lacks. Its own comparison is a fifty-token instruction that names a library and shows the call, against a hundred-and-fifty-token version that explains what a PDF is first. The short one wins, because the context window is shared with everything else in the conversation.
The other choice is how much freedom to give. Match it to how fragile the task is:
| Freedom | Use when | Looks like |
|---|---|---|
| High | Several approaches are valid and context decides | Numbered steps in prose: analyse, check, suggest, verify |
| Medium | A preferred pattern exists but variation is fine | A template or pseudocode with parameters to fill |
| Low | The operation is fragile or the sequence is fixed | An exact command, with “do not modify or add flags” |
Show, don't describe
Where the result's style matters, an input and output pair teaches more than a paragraph about tone. Anthropic's example is a commit-message skill that gives three real inputs with the exact commit text expected for each, then one line: follow this style. For output formats, provide a template, and say whether it is strict (“always use this exact structure”) or a sensible default to adapt.
Consistency in your own wording helps too. Pick one term for each thing and keep it: always “field”, never a mix of “field”, “box”, and “control”. Claude follows instructions more reliably when the vocabulary does not shift.
Build in a feedback loop
The pattern Anthropic reports as the biggest quality improvement is simple: produce, validate, fix, repeat, and only proceed when validation passes. The validator can be a script (“run validate.py; if it fails, fix the XML and run it again”) or a document (“review against the checklist in STYLE_GUIDE.md; revise; review again”). For long procedures, give Claude a checklist it can copy into its reply and tick off, so a critical step is not skipped.
What to leave out
- Time-sensitive instructions such as “before August use the old API”. Describe the current method, and put the old one in a clearly labelled legacy section.
- A menu of options. Give one default and one escape hatch (“use pdfplumber; for scanned PDFs use OCR instead”), not five libraries.
- Windows-style paths. Always forward slashes: scripts/helper.py.
- Assumed tools. If a package is needed, say so and show the install line.
- Claims you cannot back. Do not write that the skill is tested if it has not been. Test it, then say what you tested.
A worked example: release notes
Say you keep asking Claude to turn merged pull-request titles into notes for end users. The name is writing-release-notes. The description: “Turns a list of merged pull request titles into end-user release notes grouped under Added, Changed, and Fixed. Use when the user asks for release notes or a changelog for a version.” The body has four short parts: the steps (read the titles, drop internal refactors, translate jargon, group), the rules (one line per bullet, no ticket numbers), one example input with its output, and one edge case (a version with no user-facing changes gets a single line saying so).
That is under forty lines and it is complete. If you would rather start from a draft, the SKILL.md Generator produces one from a description like the sentence above and checks the frontmatter while you edit. It is a draft; the editing above is still yours to do.
Common questions
- How long should the description be?
- Long enough to say what the skill does and when to use it, with the key terms a request would contain. Two sentences is typical. The hard limit is 1,024 characters; in Claude Code the description plus when_to_use is truncated at 1,536.
- Should I write the description in first or third person?
- Third person, always. Anthropic's guide says inconsistent point of view in the system prompt can cause discovery problems. “Processes Excel files and generates reports”, not “I can help you process Excel files”.
- Does SKILL.md need a heading structure?
- The specification puts no format rules on the body. Headings help Claude and you navigate, and the sections it recommends are step-by-step instructions, examples of inputs and outputs, and common edge cases.
- Can Claude write the SKILL.md for me?
- Yes. Anthropic's guide says Claude understands the format natively, and suggests completing a task together first, then asking Claude to capture what you kept explaining as a skill. Review it for padding afterwards. The generator on this site does the same from a form, with format checks.
- How do I know if the instructions are working?
- Use the skill on real requests and watch what Claude does: which files it reads, which steps it skips. Anthropic recommends at least three test scenarios and testing with every model you use. Adjust the wording or prominence of a rule when it is missed, then test again.
Try it yourself
These live under Developer tools, alongside the rest of the claude skills & skill.md guides on the guides page.