What is a SKILL.md file?
SKILL.md is the one required file in an agent skill. It holds YAML frontmatter, which tells the agent when to use the skill, followed by Markdown instructions that the agent reads once it decides to use it. The Agent Skills specification defines the format, and Claude Code, Codex and Cursor all read it. If you are new to the idea, start with what Claude skills are.
A minimal SKILL.md example
The specification’s smallest valid file is two frontmatter lines. A useful one adds a body:
---
name: summarize-changes
description: The SKILL.md file format explained: required name and description, every frontmatter field, a minimal example and what to check before you install.
---
# Summarize changes
1. Run `git diff HEAD` and read the output.
2. Summarize the changes in two or three bullet points.
3. List risks: missing error handling, hardcoded values, tests that need updating.
4. If the diff is empty, say there are no uncommitted changes.Save it as .claude/skills/summarize-changes/SKILL.md for one project, or in ~/.claude/skills/summarize-changes/ for all of them. The folder name should match name.
SKILL.md frontmatter fields
The open specification defines six fields. Only the first two are required.
| Field | Required | Rules |
|---|---|---|
name | Yes | 1 to 64 characters. Lowercase letters, numbers and hyphens. No leading, trailing or double hyphens. Must match the folder name. |
description | Yes | 1 to 1024 characters. Says what the skill does and when to use it. |
license | No | A license name or the name of a bundled license file. |
compatibility | No | Up to 500 characters on environment needs, such as required tools or network access. |
metadata | No | Free-form key-value pairs for your own tooling. |
allowed-tools | No | Space-separated tools the skill may use without asking. Marked experimental, and support varies by agent. |
The description is the field that matters most. The agent matches your request against it to decide whether to load the skill, so write it the way a user would phrase the task. Compare the specification’s own examples: “Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents” works, while “Helps with PDFs” does not.
Anthropic’s Agent Skills overview adds two limits for Claude: name cannot contain XML tags or the reserved words anthropic and claude, and description cannot contain XML tags.
Extra fields in Claude Code
Claude Code treats every field as optional (the name defaults to the folder name, and only description is recommended) and adds its own. The ones you will meet most often:
| Field | What it does |
|---|---|
when_to_use | Extra trigger phrases, appended to description. |
argument-hint | Autocomplete hint such as [issue-number]. |
disable-model-invocation | true stops Claude from loading the skill by itself; you run it with /name. |
user-invocable | false hides it from the / menu so only Claude calls it. |
allowed-tools | Tools Claude may use without asking while the skill runs. It does not restrict which tools exist. |
context and agent | context: fork runs the skill in a subagent of the type named by agent. |
model and effort | Override the model or effort level while the skill is active. |
hooks | Hooks registered when the skill is invoked and kept for the session. |
paths | Glob patterns that limit automatic activation to matching files. |
The combined description and when_to_use text is cut at 1,536 characters in Claude Code’s skill listing, so put the main use case first. Unknown fields are ignored in Claude Code, but outside it (claude.ai uploads and the Skills API) only name, description, license, compatibility, metadata and allowed-tools are accepted, and other keys cause an error. If you plan to publish a skill for several surfaces, stick to the six standard fields.
Other agents add their own. Cursor reads paths, disable-model-invocation, icon and color, and Codex takes optional settings such as invocation policy from an agents/openai.yaml file beside SKILL.md. See each agent on our platforms page.
The body: instructions, strings and shell commands
Below the frontmatter, the body is ordinary Markdown with no required structure. The specification suggests step-by-step instructions, examples of inputs and outputs, and common edge cases.
Claude Code also expands a few things before Claude sees the text: $ARGUMENTS for what you typed after /name, ${CLAUDE_SKILL_DIR} for the skill’s own folder, and !`command` lines whose shell output replaces the placeholder. That last feature runs code on your machine, so read those lines in any skill you did not write.
Folder layout and file size
A skill can bundle more than SKILL.md:
skill-name/
├── SKILL.md
├── scripts/ executable code
├── references/ documents loaded when needed
└── assets/ templates, images, dataKeep SKILL.md under 500 lines and under about 5,000 tokens, and move detail into reference files that SKILL.md links to with relative paths, one level deep. The agent loads only the name and description at startup, the body when the skill triggers, and other files when it reads them. Scripts run without their source entering the context.
Common mistakes
- Name and folder differ. The specification requires the name to match the parent directory.
- A vague description. Fix it first when a skill never triggers.
- Broken YAML. Claude Code then loads the body with empty metadata.
/skill-namestill works, but Claude cannot match your request to the description. Run with--debugto see the parse error. - Rules that must always hold. A skill is guidance Claude applies with judgment. Put hard rules in a hook.
- Everything in one file. A 2,000-line
SKILL.mdcosts context on every use.
What to check in a SKILL.md before installing
The frontmatter tells you a lot about risk. Look at allowed-tools for pre-approved shell access, hooks for code registered on tool events, context: fork for work handed to a subagent, and the body for !`command` lines or instructions to fetch a URL. A skill that reads rules from a remote file at run time, like web-design-guidelines, can change behavior without any change to the file you reviewed.
We record these facts for every skill; see how in the security checks and our methodology. For well-formed SKILL.md files you can copy from, browse Claude skills examples.