SKILL.md format reference

A skill is a folder containing a SKILL.md file: a YAML header (the frontmatter) followed by instructions in Markdown. This page summarizes the format defined by the Agent Skills specification and the fields Claude Code adds.

Minimal example

---
name: pr-review
description: Reviews a pull request and flags bugs, missing tests and readability problems. Use when the user asks for a code review or mentions a PR.
---

# Pull request review

1. Read the full diff.
2. List the risks, most serious first.
3. Suggest a fix for each one.

The file must start with the --- line. The folder that holds it must have the same name as the name field.

Fields in the specification

These fields are shared by every agent that follows the specification.

Naming rules

The name field accepts only lowercase letters, digits and hyphens. It must not start or end with a hyphen, must not contain two hyphens in a row, and must match the parent folder name. Valid: pdf-processing, code-review. Invalid: PDF-Processing, -pdf, pdf--processing.

Writing the description

It is the only part the agent reads when deciding whether to load the skill. Say what the skill does and when to use it, in the words you would use in a request. "Helps with PDFs" is too vague; "Extracts text and tables from PDFs, fills forms. Use when the user mentions PDFs" works. See also how skills get triggered.

Fields Claude Code adds

In Claude Code every field is optional, and fields it does not know are ignored. Beyond the specification, it recognizes among others:

• when_to_use: extra trigger context, appended to the description. Together they are truncated at 1,536 characters in the skill listing.
• argument-hint and arguments: autocomplete help and named arguments for a skill called with /name.
• disable-model-invocation: when true, Claude does not load the skill on its own; you run it by hand.
• user-invocable: when false, the skill disappears from the / menu but Claude can still load it.
• disallowed-tools, model, effort: restrict tools, pick the model or the effort level for the current turn.
• context: fork and agent: run the skill in a subagent.
• paths: file patterns; the skill loads only when Claude works on matching files.
• hooks and shell: hooks tied to the skill, and the shell (bash or powershell) for inline commands.

If name is omitted, the folder name becomes the command. If description is omitted, the first non-empty line of the body stands in. license and compatibility are accepted but have no effect. These Claude Code fields are not portable: on claude.ai and through the Skills API, only the specification's fields go through.

Folder structure

my-skill/
├── SKILL.md
├── references/
├── assets/
└── scripts/

• SKILL.md: required.
• references/: detailed documentation, read on demand (for example REFERENCE.md). Keep files short and focused.
• assets/: templates, images, data files.
• scripts/: executable code. The specification allows it, but PalateKit catalog resources ship none; see skill safety.

Point to each file from SKILL.md with a path relative to the skill root, such as references/REFERENCE.md, so the agent knows when to open it. Stay one level deep.

Size and progressive loading

Agents load a skill in three steps:

1. Metadata (about 100 tokens): the name and description of every skill, at startup.
2. Instructions (under 5,000 tokens recommended): the body of SKILL.md, when the skill is activated.
3. Resources: files in references/, assets/ or scripts/, only when the task needs them.

Keep SKILL.md under 500 lines and move the detail into separate files. An installed skill therefore weighs very little until it is used.

Validate and install

The specification repository provides the skills-ref tool: skills-ref validate ./my-skill checks the frontmatter and the naming rules. To put the folder in your agent, see installing your first resource and the skills catalog.