The SKILL.md format: frontmatter fields and examples
A skill is a folder with a SKILL.md file: YAML frontmatter that says what the skill does and when to use it, then Markdown instructions. This page covers every field, the limits, and how to lay out a skill so agents load it reliably.
Updated · Skill Index docs
A minimal SKILL.md
The file must start with frontmatter between two --- lines, and the opening --- has to be the very first line. Everything after the closing --- is the body the agent follows:
--- name: release-notes description: Writes release notes from merged pull requests. Use when the user asks for release notes, a changelog, or "what shipped". --- # Release notes 1. List the pull requests merged since the last tag. 2. Group them into Features, Fixes, and Internal. 3. Write one plain-language line per change.
The folder name and name match (release-notes/SKILL.md). That is all a working skill needs.
Required frontmatter fields
| Field | Rules (Agent Skills spec) |
|---|---|
name | 1–64 characters; lowercase letters, numbers and hyphens only; no leading, trailing or double hyphens; must match the parent folder name. |
description | 1–1,024 characters. Says what the skill does and when to use it, with the words a user would actually type. |
PDF-Processing, -pdf and pdf--processing are all invalid names; pdf-processing is fine.
Optional fields
--- name: pdf-processing description: Extracts text and tables from PDF files, fills PDF forms, and merges PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction. license: Apache-2.0 compatibility: Requires Python 3 and the pypdf package metadata: author: example-org version: "1.0" ---
| Field | What it is for |
|---|---|
license | License name, or a reference to a bundled license file. |
compatibility | Up to 500 characters on environment needs (product, system packages, network access). Most skills don't need it. |
metadata | A map of string keys to string values for anything else, such as author or version. |
allowed-tools | Space-separated tools the skill may use without asking, e.g. Bash(git:*) Read. Marked experimental; support varies by agent. |
Extra fields Claude Code understands
Claude Code accepts the spec fields plus its own. Other agents ignore fields they don't know, so these are safe to add but only take effect in Claude Code:
| Field | Effect in Claude Code |
|---|---|
when_to_use | Extra trigger context appended to the description. Description + when_to_use are capped at 1,536 characters in the skill listing. |
disable-model-invocation | true = only you can run it with /skill-name; Claude won't load it on its own. |
user-invocable | false = hidden from the / menu; only Claude invokes it. |
argument-hint, arguments | Autocomplete hint and named arguments for /skill-name. |
model, effort | Model or effort level for the turn that runs the skill. |
context: fork, agent | Run the skill in a forked subagent, optionally of a given type. |
paths | Glob patterns; the skill auto-activates only for matching files. |
hooks | Hooks registered while the skill is active. |
Field names must match exactly: Claude Code silently ignores a misspelled field rather than reporting an error.
Writing a description that triggers
Agents read only the name and description of every installed skill up front and decide from that alone whether to load the rest. A vague description is the most common reason a skill never fires.
- Weak:
description: Helps with PDFs. - Strong:
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
Put the main use case first: if many skills are installed, long descriptions are the first thing to get cut.
Folder layout and progressive disclosure
pdf-processing/
├── SKILL.md # required: frontmatter + instructions
├── scripts/ # optional: code the agent can run
│ └── extract.py
├── references/ # optional: docs loaded only when needed
│ └── FORMS.md
└── assets/ # optional: templates, schemas, images
└── invoice-template.pdfAgents load a skill in three steps, which is why the layout matters:
- Metadata (about 100 tokens): name and description, loaded at startup for every skill.
- Instructions (under ~5,000 tokens recommended): the SKILL.md body, loaded when the skill activates.
- Resources: files in
scripts/,references/andassets/, opened only when needed.
Keep SKILL.md under 500 lines, link to supporting files with relative paths (references/FORMS.md), and keep those references one level deep. In Claude Code, ${CLAUDE_SKILL_DIR}resolves to the skill's folder wherever it is installed.
Create and validate a skill
Scaffold a new skill folder with the skills CLI:
$ npx skills init my-skillCheck the frontmatter against the specification with the reference validator:
$ skills-ref validate ./my-skillOr find SKILL.md files whose frontmatter doesn't parse, with Claude Code v2.1.233 or later:
$ claude plugin validate ~/.claude/skillsTo have Claude write and test the skill with you, install Anthropic's skill-creator skill; obra's writing-skills covers the same job test-first.
Real SKILL.md examples
Every skill page on this site shows the full SKILL.md when its license allows. A few worth reading for structure:
- frontend-design — a long, opinionated instruction set in one file.
- mcp-builder — a multi-phase workflow that points to reference files.
- brainstorming — a process skill with a tight trigger description.
- grill-me — proof that a skill can be a few lines long.
Once it's written, put it in the right folder: see where skills are stored, and what to check if it doesn't show up.