How to Write Your First SKILL.md: Structure, Examples, and Common Mistakes
A field-by-field walk through a SKILL.md file, one complete example you can copy, and the mistakes that stop a skill from loading or from ever being picked.
A skill is a folder with one required file in it, SKILL.md. That file does two jobs. The top part tells the agent what the skill is for, so it can decide when to load it. The rest tells the agent what to do once it has.
Most first skills fail at the first job, not the second. The instructions are fine, but the agent never picks the skill up because the description is vague or the name doesn’t match the folder. This guide goes through the file in order, builds one complete example, and then lists the mistakes we see most.
If you haven’t installed a skill before, read How to Install a Skill in Claude Code, Cursor, and Codex first. This post assumes you know where the folder goes.
Start with a job you keep repeating
The Claude Code docs put it well: write a skill when you keep pasting the same instructions, checklist or multi-step procedure into chat. That’s the test. If you can’t name the thing you’re tired of typing, you probably don’t need a skill yet.
For this guide we’ll use a common one: writing a pull request description from the current branch’s changes.
The shape of the file
pr-description/
└── SKILL.md
---
name: pr-description
description: ...
---
Instructions go here.
The block between the two --- lines is YAML frontmatter. Everything after it is ordinary Markdown. The Agent Skills specification, which Claude Code, Cursor and Codex all follow, requires two fields: name and description.
The name field
The rules are strict, and a wrong name can mean the skill never loads:
- 1 to 64 characters.
- Lowercase letters, numbers and hyphens only.
- No hyphen at the start or end, and no double hyphens (
--). - It must match the folder name.
pr-description/SKILL.mdgetsname: pr-description.
Anthropic’s authoring guide adds two more for Claude: no XML tags, and don’t use the reserved words “anthropic” or “claude” in the name. It also suggests a consistent naming style across your skills. Gerunds like writing-pr-descriptions are its first choice, but noun phrases and plain verbs are fine. What matters is that you can tell what a skill does from its name, so avoid things like helper or utils.
The description field
This field decides if your skill ever gets used. At startup the agent loads only the name and description of every skill it can see. It reads the full file only when a request seems to match. So the description has to say two things: what the skill does, and when to use it.
The spec allows up to 1,024 characters. You rarely need that many, but don’t be stingy either. Compare these two:
description: Helps with PRs.
description: Writes a pull request title and description from the current branch's commits and diff. Use when the user asks for a PR description, PR summary, or help opening a pull request.
The second one names the input, the output and the phrases a person would actually type. Three habits help:
- Write in the third person. “Writes a pull request description”, not “I can help you write” or “You can use this to”. Anthropic’s guide says the description is injected into the system prompt, and a mixed point of view can cause discovery problems.
- Put the main use case first. Claude Code caps each skill’s combined description and
when_to_usetext at 1,536 characters in its skill listing, and with lots of skills installed it may drop some descriptions altogether. The start of the text is what survives. - Use the words people use. If your team says “PR” and “pull request”, put both in.
The body
After the frontmatter, write instructions the way you’d brief a capable colleague who has never seen your repo. The spec doesn’t enforce any format, but it suggests three kinds of content: step-by-step instructions, examples of inputs and outputs, and common edge cases.
Keep it short. Anthropic’s guide makes a point that’s easy to forget: the model already knows what a pull request is. Spend your words on what it can’t guess, like your team’s template, what to leave out, and how to handle an empty diff. Both the spec and the Claude Code docs say to keep SKILL.md under 500 lines and move long reference material into separate files.
One more Claude Code detail worth knowing. When a long conversation gets compacted, Claude Code may keep only the start of a skill it already loaded, so put the instructions that must never be skipped near the top.
A complete example
Here’s the whole file. It works as written in any tool that follows the standard, because it uses only the two required fields.
---
name: pr-description
description: Writes a pull request title and description from the current branch's commits and diff. Use when the user asks for a PR description, PR summary, or help opening a pull request.
---
# Writing a pull request description
1. Run `git log --oneline main..HEAD` and `git diff main...HEAD --stat`
to see what changed. If the base branch isn't `main`, ask which one it is.
2. Read the full diff for any file that the stat output shows changed a lot.
3. Write the description using the template below.
4. If the diff is empty, say there's nothing to describe and stop.
## Template
**Title:** under 70 characters, imperative mood ("Add retry to upload client").
**What changed**
Two to four bullets. Describe behavior, not file names.
**Why**
One or two sentences. If the commits don't say why, write "Reason not stated
in commits" instead of guessing.
**How to test**
Numbered steps a reviewer can follow.
## Rules
- Don't list every file. Reviewers can see the file list.
- Mention any change to a public API, database schema or config file
in its own bullet, even if it's small.
- Never invent ticket numbers. Include one only if it appears in a commit message.
A few things in there are deliberate. The steps tell the agent what to run, so it works from the real diff instead of guessing. The “Reason not stated” line gives it something to do when information is missing, which is better than letting it make something up. The rules cover the two or three mistakes you’d otherwise correct by hand every time.
When to add more files
Once a skill grows, you can put supporting files next to SKILL.md. The spec suggests scripts/ for code the agent can run, references/ for longer documentation, and assets/ for templates and data. Link to them with relative paths, such as See [the style guide](references/STYLE.md), and keep references one level deep. Anthropic’s guide warns that when one reference file points to another, the agent may only preview the second file instead of reading it in full.
You don’t need any of that for a first skill. Start with one file.
Test it like you mean it
Seeing the skill in a menu only proves it loaded. To know it works:
- Start a fresh session, so nothing from writing the skill is still in context.
- Ask the way a person would, without naming the skill: “Can you write up a PR for this branch?”
- Check that the agent used the skill, then check the output against your template.
- Run the same request with the skill turned off and compare.
In Claude Code you can also ask “What skills are available?” or invoke it directly with /pr-description. If the direct call works but the agent never picks the skill on its own, the description is the problem. Make it more specific and add the phrases people actually use.
Common mistakes
The frontmatter isn’t on line one. Claude Code reads frontmatter only when the opening --- is the very first line. A blank line or a title above it means the whole file, markers included, gets treated as instructions with no name or description.
The YAML doesn’t parse. In Claude Code a skill with broken YAML still loads, but with no fields set. /pr-description may work while automatic matching never does. Run claude --debug to see the parse error. A colon followed by a space inside an unquoted description is an easy way to break it, so put the description in quotes if it has one.
The name and folder don’t match. The spec requires them to match, and Cursor is strict about it.
Claude Code-only fields in a skill you share. Claude Code supports extra fields like argument-hint, disable-model-invocation and context. Uploading to claude.ai or packaging for the Skills API allows only the six spec fields: name, description, license, compatibility, metadata and allowed-tools. Anything else fails with an “Unexpected key(s) in SKILL.md frontmatter” error. If the skill is meant to travel, stick to the spec.
Explaining what the model already knows. Three paragraphs on what a pull request is cost tokens every time the skill loads, and they don’t change the output.
Dates that will go stale. “Before March, use the old template” will be wrong one day. Anthropic’s guide suggests describing the current method and putting old patterns in a clearly labeled section.
Too many options. “Use pypdf, or pdfplumber, or PyMuPDF…” leaves the agent to choose. Pick a default and name one exception if there is one.
Backslashes in paths. Write scripts/check.py, not scripts\check.py. Forward slashes work everywhere.
Granting tools without thinking. allowed-tools lets a skill pre-approve tools. In Claude Code that grant lasts for the turn that invokes the skill, and the docs note that workspace trust doesn’t gate it for project skills. Only add it when you’ve decided the commands are safe to run without asking, and read the field in any skill you didn’t write.
Before you share it
A short checklist, adapted from Anthropic’s:
- The description says what the skill does and when to use it, in the third person.
namefollows the rules and matches the folder.- The body is under 500 lines, and any extra files are linked one level deep.
- You’ve tested it in a fresh session with real requests, at least three of them.
- Nothing in it depends on today’s date.
When it’s working, it’s worth looking at how others structure theirs. Every skill in the Skillaisle library is a folder you can open and read.
Sources
- Agent Skills: Specification
- Claude Code docs: Extend Claude with skills
- Claude docs: Skill authoring best practices
Products change quickly. If something here no longer matches what you see, the official page above is the reference.
Related on Skillaisle
Want the setup steps? Browse the Learn guides or walk the skills aisle.