Claude SKILL.md Format Explained
Updated September 17, 2026
The SKILL.md format has two parts: YAML frontmatter that tells Claude when to use the skill, and a Markdown body that tells it how. Two fields are required, four more are in the open specification, and Claude Code understands a further set that no other surface accepts. This page lists every field with its limits, as published in the Agent Skills specification and Anthropic's documentation.
The short answer
A valid SKILL.md starts on line one with three dashes, has a name and a description, closes the frontmatter with three dashes, and then contains Markdown. The name must match the folder. Everything else is optional, and the safest file uses only the six fields the specification defines, because those are the ones every surface accepts.
The two required fields
| Field | Constraints | Notes |
|---|---|---|
| name | 1 to 64 characters; lowercase a-z, 0-9, hyphens; no leading, trailing, or consecutive hyphens; must match the parent folder name | Anthropic also forbids XML tags and the reserved words “anthropic” and “claude”. Claude Code reserves “synced” for account-synced skills |
| description | 1 to 1024 characters; non-empty; no XML tags | Says what the skill does and when to use it, in third person. This is what Claude matches requests against |
The four optional fields in the specification
| Field | Type and limit | Purpose |
|---|---|---|
| license | Short string | A licence name or the name of a bundled licence file |
| compatibility | 1 to 500 characters | Environment needs: intended product, system packages, network access. Most skills do not need it |
| metadata | Map of string keys to string values | Free-form data for tooling, such as author or version. Use distinctive key names to avoid clashes |
| allowed-tools | Space-separated string | Tools pre-approved for the skill, for example Bash(git:*) Read. Marked experimental; support varies by agent |
Fields only Claude Code understands
Claude Code reads an extra set of fields that control how a skill runs inside it. They are useful there and fatal elsewhere: Anthropic's Claude Code documentation states that any field outside the six above causes a hard error when the file is uploaded to claude.ai or the Skills API, or packaged with the reference packaging script.
| Field | What it does in Claude Code |
|---|---|
| when_to_use | Extra trigger context appended to the description for auto-invocation |
| argument-hint | Autocomplete hint shown after the slash command, such as [issue-number] |
| arguments | Named positional arguments substituted as $name in the body |
| disable-model-invocation | Only you can invoke it; Claude never loads it on its own |
| user-invocable | Set to false to hide it from the slash menu; only Claude can load it |
| disallowed-tools | Removes tools from Claude's pool while the skill is active |
| model, effort | Override the session's model or effort for this skill |
| context, agent, background | Run the skill in a forked subagent, choose its type, and whether to wait |
| hooks | Register hooks when the skill is invoked |
| paths | Glob patterns; the skill auto-loads only when editing matching files |
| shell | bash or powershell for injected commands |
The body
After the closing dashes, the specification places no format restrictions on the body. It recommends step-by-step instructions, examples of inputs and outputs, and common edge cases, and it advises keeping SKILL.md under 500 lines, moving long reference material into separate files that the body links to with relative paths. How to structure a SKILL.md file covers that layout; how to write a SKILL.md file covers the wording.
Common format errors
- Uppercase or spaces in the name. PDF-Processing and pdf processing are both invalid; pdf-processing is valid.
- Folder does not match name. The specification requires them to be identical.
- A reserved word. claude-tools and anthropic-helper are rejected.
- Frontmatter not on line one. A blank line or a comment before the first three dashes means there is no frontmatter.
- A Claude Code-only field in a file meant for claude.ai. Remove it, or keep two versions.
- First-person description. Not a format error, but Anthropic warns it hurts discovery.
The SKILL.md Generator checks a file against all of the rules above as you edit it, and flags the Claude Code-only fields separately so you can decide whether they belong. The checks confirm structure, not quality: whether the instructions are good is a matter for testing the skill.
Common questions
- Which SKILL.md fields are required?
- Two: name and description. The specification marks everything else optional. Claude Code will even load a file with only a description, using the folder name as the name, but the specification and every upload path expect both.
- What characters can a skill name contain?
- Lowercase letters a to z, digits 0 to 9, and hyphens, up to 64 characters, with no hyphen at the start or end and no two in a row. Anthropic additionally rejects names containing “anthropic” or “claude”.
- Can I add my own fields to the frontmatter?
- Put them inside metadata, which is a map of string keys to string values defined for exactly that purpose. A top-level custom field is rejected by claude.ai and the Skills API.
- Is allowed-tools safe to use?
- The specification marks it experimental and says support varies. In Claude Code it pre-approves the listed tools for the turn in which the skill is invoked, and the approval clears on your next message.
- Does the body have to use specific headings?
- No. There are no body format rules. Headings for steps, examples, and edge cases are conventions that make the skill easier for Claude and for you to navigate.
Try it yourself
These live under Developer tools, alongside the rest of the claude skills & skill.md guides on the guides page.