Guide
Anatomy of a SKILL.md
The SKILL.md spec is intentionally minimal — only name and description are required. But what you put in those two fields decides whether your skill is ever loaded. Here is the practical breakdown.
Spec
The frontmatter contract
--- name: pdf-processing description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction. --- # PDF Processing ## Quick start [procedural knowledge here]
- name — lowercase + hyphens, max 64 chars. Cannot contain "anthropic" or "claude" (reserved). No XML tags.
- description — non-empty, max 1024 chars. Both what it does and when to use it. No XML tags.
Loading model
Three levels, three token costs
| Level | When | Token cost | Content |
|---|---|---|---|
| 1 · Metadata | Always | ~100 tokens | name + description |
| 2 · Instructions | When triggered | <5K tokens | Body of SKILL.md |
| 3 · Resources | As needed | ~unlimited | Reference files, scripts (run via bash, output only enters context) |
This is why a Skill can ship 50 reference files without bloating context — the agent reads only what each task actually needs.
Workflow
The 5-step authoring loop
- 1.
Pick a focused name and description
Name: lowercase + hyphens, max 64 chars, no "anthropic"/"claude". Description: max 1024 chars, but should be 1-2 sentences. Both load into the system prompt every conversation, so they are your only chance to get triggered.
- 2.
Write a description that names the trigger
Include both what the skill does AND when to use it. The agent decides whether to load your skill from the description alone — vague descriptions miss real matches.
- 3.
Keep SKILL.md body lean
The body loads only when triggered. Aim for under 5K tokens. Push reference material into bundled files (FORMS.md, REFERENCE.md) loaded on demand.
- 4.
Bundle scripts for deterministic ops
When a step needs to be exact (file parsing, API calls), ship a script. Scripts run via bash; only their output enters context, not the source.
- 5.
Audit before publishing
Have a reviewer (or another agent) load and use it. If the skill loads at the wrong times or fails to load when you need it, the description is the first thing to fix.
Description patterns
What gets you picked vs ignored
Picked up
"Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."
Names triggers explicitly. The agent has clear cues for when to load.
Ignored
"A useful skill for working with documents."
Vague verbs, no triggers. The agent has nothing concrete to match against.
Constraints
Per-surface gotchas
- Claude.ai: network access varies by plan/admin settings. Skills that fetch external data may behave differently than in Code/API.
- Claude API: no network access, no runtime package install. Use only pre-installed packages.
- Claude Code: full network + filesystem access. Most permissive. Avoid global package installs in your scripts (install locally).
- Cross-surface sync: Skills do not auto-sync between Claude.ai, the API, and Code. Maintain three separate uploads (or use Code's filesystem-based skills as the canonical source).
Want to see good examples? Browse Best Official Skills and read their SKILL.md files on GitHub. The Anthropic ones are the reference grammar.