A good SKILL.md has a short, specific, third person description that tells Claude what the skill does and when to use it, and a body under 500 lines that keeps everything else in files loaded on demand. That is the core of Anthropic's guidance. Below I add what I learned from the 26 skills I keep in my own ~/.claude/skills folder.
TL;DR
- Only two fields are required:
name(up to 64 characters, lowercase, numbers, hyphens) anddescription(up to 1024 characters).- The description is the trigger. Third person, specific, with the words you really type in your prompts.
- Body under 500 lines, references one level deep, a table of contents in any reference file longer than 100 lines.
- Write at least three test scenarios first, documentation second. Test on the model you will use.
- Keep scripts short enough that a stranger can read them before installing. They should.
Anatomy of a SKILL.md
A skill is a folder with a SKILL.md file and optional supporting files. In Anthropic's words: "Each Skill packages instructions, metadata, and optional resources (scripts, templates) that Claude uses automatically when relevant." The file opens with YAML frontmatter, followed by Markdown instructions.
Frontmatter fields and limits
| Field | Required | Rules from the docs |
|---|---|---|
name | yes | max 64 characters, lowercase letters, numbers and hyphens only, no XML tags, no reserved words "anthropic" or "claude" |
description | yes | non-empty, max 1024 characters, no XML tags, states what the skill does and when to use it |
disable-model-invocation | no (Claude Code) | true means Claude will not invoke the skill on its own; only you can, via /name |
user-invocable | no (Claude Code) | false means only Claude invokes it |
For names, Anthropic recommends the gerund form, such as processing-pdfs. pdf-processing and process-pdfs are acceptable too. Avoid helper, utils, tools, documents, data and files. They tell neither you nor the model anything.
A minimal example
Here is a small skill for cleaning up meeting notes. I made it up for this article, but it follows the same shape as the skills I use every day:
meeting-notes/
SKILL.md
references/
format.md
---
name: summarizing-meeting-notes
description: Summarizes meeting transcripts and notes into decisions, action items with owners and open questions. Use when the user pastes a meeting transcript or call notes, or asks for a meeting summary or a follow-up email.
---
# Summarizing meeting notes
1. Read the whole transcript before writing anything.
2. Extract decisions, action items (owner + deadline if stated) and open questions.
3. Never invent an owner or a deadline. Write "not stated" instead.
4. Use the output format from references/format.md.
Three things to notice. The name says what the skill does. The description has two halves: what it does, and when to use it. The output format lives in a separate file that SKILL.md points to directly.
The description is the trigger
This is the most important line in the file. The docs describe progressive disclosure: the metadata (name plus description) costs roughly 100 tokens per skill and is always in context. The SKILL.md body ("Under 5k tokens", per the docs) loads only when the skill matches the task. Extra files and scripts load later still, on demand. So Claude decides whether to use your skill having seen nothing but the description.
Anthropic is blunt about it: "Always write in third person." Their examples:
| Good | Bad |
|---|---|
| "Processes Excel files and generates reports." | "I can help you process Excel files." |
| specific actions and keywords | "Helps with documents" |
Match the language of your prompts
One thing the docs do not cover, and which mattered for me: I write most prompts in Polish, while the skills I install describe themselves in English. When I asked for a colour palette in Polish, none of my words appeared in the description. So I rewrote the description of my installed UI/UX Pro Max skill in Polish, and it now triggers on my Polish prompts. Nothing in the spec forbids this; it only asks for non-empty text up to 1024 characters. If your team prompts in German or Spanish, the same logic applies.
My own skills follow the same rule. humanizer enforces my Polish writing style, fact-checker demands a source for every number, remove-ai-marks strips invisible characters. Each description names concrete situations: an email, a proposal, a post. When a description was vague, the skill either stayed silent or fired on the wrong tasks.
The body: under 500 lines, one level of references
From the docs: "Keep the SKILL.md body under 500 lines for optimal performance." When you approach that, split the content into files. Three rules:
- References one level deep. "Keep references one level deep from SKILL.md." SKILL.md can link to
a.md, buta.mdshould not send Claude on tob.md. - A table of contents in long files. Any reference file over 100 lines gets one at the top.
- SKILL.md keeps what is always needed. Detailed formats, long examples and tables go into files Claude reads only when it needs them.
I cover the same idea from the cost side in my Claude Code token optimization guide: the less you load at startup, the better.
Rules for scripts
- "Solve, don't defer". The script handles its own errors instead of leaving them for Claude to sort out.
- No "voodoo constants". Every constant gets a reason. If a limit has a specific value, say why.
- Run or read. State clearly whether Claude should execute the script or read it as a reference.
- Forward slashes in every path.
Anti-patterns
- Windows style paths.
- Offering too many options at once instead of one default path.
- Time sensitive information in the main text (keep old patterns in a separate section).
- Inconsistent terminology, such as "invoice" in one place and "bill" in another.
- Assuming a tool is already installed.
The last one is what I hit most often in other people's skills. If your skill needs Python or Playwright, say so in SKILL.md and say what to do when it is missing.
Testing: scenarios before documentation
Anthropic flips the usual order: "Create evaluations BEFORE writing extensive documentation." Write at least three scenarios, meaning prompts the skill should respond to, and check the result. Test on the models you will use: Haiku, Sonnet or Opus. A skill that works on one will not necessarily behave the same on another.
One honest caveat from the same page: "There is not currently a built-in way to run these evaluations." You run them yourself. Mine are a handful of prompts saved next to the skill that I rerun after every change to the description. I also add a negative scenario: a prompt where the skill should stay quiet.
Claude Code specific fields
By default both you (via /name) and Claude can invoke a skill. Two fields change that:
disable-model-invocation: true: Claude never invokes it on its own. Useful for skills that do something you never want to happen by accident.user-invocable: false: only Claude invokes it; there is no slash command.
Where files live: personal skills in ~/.claude/skills/<name>/SKILL.md, project skills in .claude/skills/<name>/SKILL.md (commit these for your team), and plugin skills are called as /plugin-name:skill-name. Claude Code watches skill directories and picks up changes without a restart, so you can test a new description immediately. The older .claude/commands/ format still works.
I keep my skills as symlinks from ~/.agents/skills and separate private ones from work ones: work skills live in their own .claude/skills folder inside the work repository. That way a skill built for my own sales proposals never fires during work for my employer.
Where to start
The anthropics/skills repository (187,751 stars, November 2026) has three things worth opening before you write anything:
- the
skill-creatorskill, built to help you create new skills, - the
template/folder with a SKILL.md template, - the
spec/folder withagent-skills-spec.md, the format specification.
Add the repository to Claude Code as a marketplace with /plugin marketplace add anthropics/skills. If you are new to skills, start with what Claude skills are and how to install them, then read my breakdown of the frontend-design SKILL.md, which shows how Anthropic writes its own instructions.
Security, for authors too
Anthropic's guidance: "Use Skills only from trusted sources: those you created yourself or obtained from Anthropic." and "Audit thoroughly: Review all files bundled in the Skill." As an author, turn that around: would a stranger read your skill and decide they can trust it?
The caution is justified. Snyk's ToxicSkills report (February 2026) scanned 3,984 skills from ClawHub and skills.sh. 1,467 of them (36.82%) had at least one security issue, 534 (13.4%) had at least one critical issue, and researchers confirmed 76 malicious payloads covering credential theft, backdoors and data exfiltration. Your skill will be judged against that background.
- Keep scripts short and readable, with no obfuscated code.
- Say in the README whether scripts touch the network or install anything. UI/UX Pro Max is a good model: its README states the scripts use the standard library only, install nothing and make no network calls. I checked, and its runtime scripts import only the Python standard library.
- Never put keys or passwords in a skill. A skill is plain files that end up in a repository and in the model's context.
- Agent Skills are not covered by ZDR. Claude Enterprise can turn on content scanning for custom skills uploaded to claude.ai and Cowork.
The rule for anyone installing someone else's skill stays the same: read the SKILL.md and the scripts before you install.
Checklist before you share a skill
| Check | Criterion |
|---|---|
| name | up to 64 characters, lowercase, numbers, hyphens, no "anthropic" or "claude", gerund form preferred |
| description | up to 1024 characters, third person, what it does and when to use it, words from your real prompts |
| Body length | under 500 lines |
| References | one level deep, table of contents in files over 100 lines |
| Scripts | handle errors, justified constants, explicit "run" or "read", forward slashes |
| Dependencies | listed, never assumed |
| Tests | at least three scenarios, on the model you will use |
| Security | no secrets, clear statement about network access and installs |
FAQ
Which fields are required in SKILL.md?
Only two: name and description. The name is at most 64 characters, lowercase letters, numbers and hyphens only, with no XML tags and without the reserved words anthropic and claude. The description must be non-empty, at most 1024 characters, and say what the skill does and when to use it.
How long can a SKILL.md be?
Anthropic recommends keeping the SKILL.md body under 500 lines. As you get close, move details into separate files that SKILL.md links to directly, without chains of references.
Why doesn't Claude use my skill?
Usually the description is to blame. At startup Claude only sees the name and description, so the description has to be specific, written in third person and contain the words you actually use in your prompts.
Can the description be written in a language other than English?
The documentation only requires a non-empty text of up to 1024 characters without XML tags. I rewrote the description of an installed skill in Polish so it triggers on my Polish prompts.
How should I test a skill before sharing it?
Write at least three test scenarios before you write extensive documentation, and run them on the models you will actually use: Haiku, Sonnet or Opus. There is no built-in way to run these evaluations yet, so you run them yourself.
This article went through my own multi-agent pipeline, where fact-checker and humanizer are the skills described above. Below the article you will find a free pack of two UX skills: Laws of UX and a design system template. Related reading: the complete guide to Claude skills for UI/UX design, UI/UX Pro Max: install, review and is it safe, and the best Claude Code skills in 2026.