How to Write a Claude Skill (SKILL.md Structure + Real Examples)
A practical guide to writing a Claude skill: the SKILL.md structure, the frontmatter rules, and the description mistakes that stop skills from triggering — from a team running 25 of them in production.
On this page
Here is how to write a Claude skill in one sentence: create a folder, put a SKILL.md file inside it, and write a description good enough that Claude knows when to reach for it. That's the whole mechanism. The part that actually decides whether your skill works is 1,024 characters long, and it's the description field Anthropic uses to pick your skill out of the 100-plus that might be loaded. We run 25 skills in production on the Techsy community library, and the ones that fail almost never fail on their instructions. They fail on that one line.
Quick summary
To write a Claude skill: (1) make a folder named for the skill, (2) add a SKILL.md with YAML frontmatter (name and description) plus Markdown instructions, (3) write the description in third person with clear trigger words, (4) keep the body under 500 lines and push detail into reference files, and (5) test it with real tasks before you trust it.
What a Claude skill actually is
A skill is a folder with a SKILL.md file at its root. Nothing more is required. That file holds two things: metadata that tells Claude when to use the skill, and instructions that tell Claude how to do the task once it's activated.
The reason this stays cheap is a loading model Anthropic calls progressive disclosure. At startup, Claude reads only the name and description of every installed skill, roughly 100 tokens each. It reads the full SKILL.md only when your description matches the task in front of it, and it reads any bundled reference files only when the instructions point to them. So you can ship a large, detailed skill without paying for it on every request. You can see a working catalogue of these in our Skills library.
The SKILL.md skeleton you can copy
Every skill starts from the same shape. Here is the minimal version that works:
--- name: reviewing-pull-requests description: Reviews pull request diffs for bugs, security issues, and style. Use when the user asks for a code review, mentions a PR, or shares a diff. --- # Reviewing Pull Requests 1. Read the diff and summarize what changed. 2. Flag likely bugs and edge cases, most severe first. 3. Check for hardcoded secrets and injection risks. 4. Note style issues only if they hurt readability. 5. End with a short verdict: approve, or request changes.
Two --- markers wrap the frontmatter. Below them, the body is plain Markdown. Across our 25 skills, the structure that survived real use is boring and consistent: a one-line title, then a numbered or bulleted procedure, then any templates or examples. When we got clever with prose, Claude skimmed it. When we wrote steps, it followed them. If you want to study finished ones, the 25 skills on the Techsy community site are all readable SKILL.md files you can open and copy.
Frontmatter rules: name and description
The frontmatter has exactly two required fields, and both have hard limits worth memorizing because Anthropic's tooling validates them.
| Field | Limit | Rules |
|---|---|---|
name | 64 characters max | Lowercase letters, numbers, hyphens only. No spaces, no XML tags. Cannot contain the reserved words "anthropic" or "claude". |
description | 1,024 characters max | Non-empty. Written in third person. States what the skill does and when to use it. |
A useful convention from Anthropic's best-practices guide: name skills in gerund form, so processing-pdfs, writing-documentation, analyzing-spreadsheets. It reads well in a list and describes the activity rather than a vague noun like helper or utils. Keep the name matching the folder name so the two never drift apart. For the full validation rules, the Anthropic best-practices doc is the source of truth.
Write a description that actually triggers
This is the section most tutorials skip, and it's the one that decides whether your work gets used. The description is injected into the system prompt, and Claude reads it to decide whether to load your skill at all. A perfect body behind a vague description is a skill that never runs.
Three rules make the difference:
Write in third person. The description describes the skill, not you and not the user. First- or second-person phrasing confuses selection.
# Good description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDFs or when the user mentions forms or document extraction. # Avoid description: I can help you work with your PDF files whenever you need.
State both what and when. "Processes data" tells Claude nothing about which task matches. Name the concrete capability and the concrete triggers.
Include the words a user would actually type. If people say "PR", "diff", and "code review", put those terms in the description. Claude matches on them. This is the single highest-impact edit you can make to a skill, and it costs one line.
Progressive disclosure and file structure
Once a skill grows past a screen or two, structure starts to matter. Anthropic's guidance is concrete: keep the SKILL.md body under 500 lines, and move anything longer into separate reference files that the body links to. Those files cost zero tokens until Claude actually reads them.
A skill that has grown up looks like this:
reviewing-pull-requests/
├── SKILL.md # overview + the core procedure
├── security.md # detailed security checklist (read when needed)
├── style-guide.md # house style rules (read when needed)
└── scripts/
└── diff_stats.py # executed, never loaded into contextTwo rules keep this working. First, keep references one level deep: link every file directly from SKILL.md, never file-to-file-to-file, because Claude may only preview deeply nested files with a partial read and miss content. Second, give any reference file longer than 100 lines a table of contents at the top so a partial read still shows the full scope. Anthropic's engineering write-up on Agent Skills explains the architecture behind this if you want the deeper model. When your skill starts orchestrating tools, our MCP catalogue is a useful companion for wiring in servers.
Degrees of freedom (and when to add scripts)
Not every instruction should be equally strict. Match how tightly you script a step to how fragile that step is.
| Freedom | Use when | How to write it |
|---|---|---|
| High | Many valid approaches; context decides | Plain-text guidance: "Analyze the code, then suggest improvements." |
| Medium | A preferred pattern with some variation | Pseudocode or a script with parameters to adjust. |
| Low | Fragile, high-stakes, exact sequence | An exact command: "Run python scripts/migrate.py --verify. Do not change the flags." |
When a step is deterministic, ship a script instead of asking Claude to generate code each time. A bundled script is more reliable, saves tokens, and stays consistent between runs. Two habits keep scripts honest: handle errors inside the script instead of deferring to Claude, and justify every constant so you have no unexplained magic numbers. This is also where skills differ from subagents, which carry their own tool allowlist and system prompt; our automations library collects subagent examples, and you can compare the two approaches on the Techsy AI automations page.
Test it: eval-driven skill development
The best skill authors write tests before they write documentation. Anthropic recommends building evaluations first: run Claude on three representative tasks without the skill, note exactly where it fails, then write only enough instruction to fix those failures. That keeps you solving real problems instead of documenting imagined ones.
A practical loop:
- Pick three real tasks the skill should handle.
- Run them with no skill loaded and record what breaks.
- Write the minimal
SKILL.mdthat fixes those breaks. - Test again with the skill loaded, ideally across Claude Haiku, Sonnet, and Opus, since a skill that guides Opus well may under-specify for Haiku.
- Watch how Claude navigates the files. If it ignores a reference, your link isn't prominent enough. If it re-reads the same file constantly, that content belongs in
SKILL.md.
For a hands-on walkthrough that builds a skill end to end, our sister site has a full Claude Skills tutorial; it pairs well with the authoring rules here. You can also track your build against our enterprise build checklists.
Common mistakes that kill a skill
Most broken skills fail for one of a short list of reasons:
- A description written for humans. Marketing copy reads nicely and triggers nothing. Write for the model: capabilities and triggers.
- Too many options. "Use pypdf, or pdfplumber, or PyMuPDF, or..." makes Claude hesitate. Give one default with a single escape hatch.
- Deeply nested references. Files that link to files that link to files get partially read. Keep everything one hop from
SKILL.md. - Time-sensitive instructions. "Before August, do X" rots. Put deprecated guidance in a collapsed "old patterns" note instead.
- Windows-style paths. Always use forward slashes; backslashes break on Unix runners.
- Inconsistent terminology. Pick one word for a thing ("field", not "field/box/element/control") and use it throughout.
The pattern behind all six: a skill is an instruction set for a very capable reader who has no patience for ambiguity. Say the specific thing, once.
About the author
Mert Batur Gurbuz is Co-Founder of Techsy, University of Birmingham. He and the Techsy team build AI agents, automation systems, and voice/SDR pipelines for B2B clients, and maintain the 25-skill library referenced throughout this guide. Connect on LinkedIn. More builder guides live on the TECHSY.community blog.
Frequently Asked Questions
Where do Claude skill files live?
A skill is a folder containing a SKILL.md file. In Claude Code, personal skills go in ~/.claude/skills/{skill-name}/ and project skills in .claude/skills/{skill-name}/. On the API and claude.ai, you upload the skill folder. The folder name should match the name field in the frontmatter.
Does the skill name have to match the folder name?
Yes, keep them identical. The name field must be 64 characters or fewer, use only lowercase letters, numbers, and hyphens, and avoid the reserved words "anthropic" and "claude". Matching the folder name prevents drift and makes the skill easy to reference in conversation and documentation.
How long can a SKILL.md be?
Keep the SKILL.md body under 500 lines for reliable performance. There is no hard token limit, because reference files and scripts cost nothing until read, but a bloated main file competes with everything else in the context window. When you approach 500 lines, split detail into reference files linked directly from SKILL.md.
Why isn't my skill triggering?
Almost always the description. Claude selects skills by matching the task to the description field, so if yours is vague or written in first person, it never activates. Rewrite it in third person, state what the skill does and when to use it, and include the exact words a user would type for that task.
What is the difference between a skill, a subagent, and an MCP server?
A skill is packaged instructions Claude loads when relevant. A subagent is a separate agent with its own tool allowlist and system prompt that handles a delegated task. An MCP server exposes external tools and data over the Model Context Protocol. Skills describe how to do work; MCP servers provide what to act on.
Can a Claude skill run code?
Yes. Skills can bundle executable scripts that Claude runs as tools rather than reading into context, which is cheaper and more reliable for deterministic work like validation or file conversion. Make the intent explicit in your instructions: say "run this script" for execution, or "see this script" when it is reference material.
Do skills work in both the API and claude.ai?
Yes, though the runtime differs. On claude.ai the code execution environment can install packages from npm and PyPI, while the Claude API has no network access or runtime package installation. List required packages in your SKILL.md and confirm they are available in the target environment before you rely on them.
How many skills can Claude have loaded at once?
Many, because only each skill's name and description sit in context at startup, roughly 100 tokens apiece. That is why the description matters so much: Claude may be choosing among 100-plus skills, and a precise description is what lets it pick yours correctly. The full body only loads once the skill is selected.