SKILL.md: The Claude Skill File Format
A SKILL.md is the file that defines a skill for Claude. It starts with YAML frontmatter that holds a name and a description, followed by Markdown instructions that Claude reads when it uses the skill. This page covers the fields Claude Code reads, the rules a valid file follows, and an example.
The structure of a SKILL.md
Each skill is a folder that holds a SKILL.md file, plus optional scripts and reference files. In Claude Code, personal skills live in ~/.claude/skills/<name>/SKILL.md and project skills in .claude/skills/<name>/SKILL.md.
The file has two parts. The frontmatter, between two --- lines at the top, is YAML that tells Claude what the skill is and when to use it. Below it, the body is ordinary Markdown: the steps, rules, and examples Claude follows once it loads the skill. Here is a short, complete example:
---
name: review-pr
description: Review a pull request for correctness and style. Use when the user asks for a code review.
allowed-tools: Bash(gh pr diff:*)
---
# Review a pull request
Read the diff, then report findings from most to least severe.
1. Run `gh pr diff`.
2. Read each changed file in full.
3. List each finding with its file and line.Frontmatter fields Claude Code reads
name is the skill's identifier and the command that runs it, such as /review-pr. description says what the skill does and when to use it; Claude reads it to decide when to load the skill. when_to_use adds more guidance on when to use it.
allowed-tools lists tools Claude can use without asking for permission during the turn that invokes the skill. disable-model-invocation: true makes the skill run only when you type its command, and user-invocable: false means only Claude can invoke the skill. argument-hint shows the expected arguments in autocomplete.
model and effort set the model and the effort level while the skill runs, and context: fork runs the skill in a separate subagent. Claude Code ignores keys it does not know, so a misspelled key has no effect and no error.
Rules and recommendations for a SKILL.md
The Agent Skills specification sets the name rules: 1 to 64 lowercase letters, numbers, and single hyphens, with no hyphen at the start or end, matching the folder name. It also requires a description of at most 1,024 characters. Claude Code is less strict: every field is optional, and it uses the first line of the body when the description is missing. Claude Code shows the first 1,536 characters of the description and when_to_use together.
The Claude Code docs recommend keeping the body under 500 lines. Move long reference material into separate files in the skill folder and link to them from SKILL.md, so Claude reads them only when it needs them. Boolean keys take true or false.
Edit and check a SKILL.md in Prettify
Paste a SKILL.md above, or click Try an example, and open it in the Preview. The frontmatter shows as a Properties card where you edit name, description, allowed-tools, and other keys field by field, and the instructions render as a document you can type in.
A YAML error in the frontmatter shows with its line, for free. Skill Check, a Pro feature with one free try per day, tests the file against every rule on this page. The Claude Skill Validator page explains what it checks.
Frequently asked questions
What is a SKILL.md file?
It is the file that defines a Claude skill. YAML frontmatter at the top gives the skill a name and a description, and the Markdown body below holds the instructions Claude follows when it uses the skill.
Which fields are required?
The Agent Skills specification requires name and description. In Claude Code every field is optional: it falls back to the folder name when name is missing and to the first line of the body when description is missing. Claude reads the description to decide when to use the skill, so always write one.
How long can the description be?
The Agent Skills specification allows up to 1,024 characters. Claude Code shows the first 1,536 characters of the description and when_to_use together, so put the most important words first.
How long can the body be?
The Claude Code docs recommend keeping it under 500 lines. Put long reference material in separate files in the skill folder and link to them from SKILL.md, so Claude reads them only when it needs them.
Where does a SKILL.md go?
In a folder named for the skill. For Claude Code, that is ~/.claude/skills/<name>/SKILL.md for a personal skill, or .claude/skills/<name>/SKILL.md inside a project.
How do I check a SKILL.md?
Open it in Prettify. YAML errors in the frontmatter show for free, and Skill Check (Pro, with one free try per day) tests the name, the description, the keys, and the body length.