SKILL.md format, with examples

SKILL.md is the file at the center of every Claude skill. It follows the open Agent Skills format, so the same file works in Claude Code, Claude.ai and other agents that support it. Here is everything that goes in one.

The smallest skill

A folder, and a SKILL.md inside it that starts with a YAML header:

---
name: release-notes
description: Writes release notes from a list of merged changes. Use when the user asks for release notes or a changelog.
---

# Release notes
1. Group the changes into New, Improved and Fixed.
2. Write one plain sentence per change.
3. Put breaking changes first.

Header fields

• name (required): up to 64 characters, lowercase letters, numbers and single hyphens. It can't start or end with a hyphen, and it should match the folder name.
• description (required): up to 1024 characters. What the skill does and when to use it.
• license (optional): a license name, or the name of a license file in the folder.
• compatibility (optional): up to 500 characters on what the skill needs, like a tool or network access. Most skills skip it.
• metadata (optional): your own key and value pairs, like an author or version.
• allowed-tools (optional, experimental): tools the skill may use without asking. Support varies by agent.

Writing the description

The description is what Claude reads to decide whether to use the skill, so make it specific. Name the job, then the moments it applies to, using words your requests would contain.

Folder layout

release-notes/
  SKILL.md        required
  scripts/        code the agent can run
  references/     longer docs it reads when needed
  assets/         templates, images, data files

Point to extra files with relative paths from SKILL.md, like references/style.md, and keep them one level deep.

How long it should be

The agent loads the whole SKILL.md when it uses the skill, so keep the main file under about 500 lines and move long reference material into separate files. Those load only when the task needs them.

A fuller example

---
name: pdf-forms
description: Fills in PDF forms from a spreadsheet row. Use when the user wants to fill, complete or batch-fill PDF forms.
license: MIT
metadata:
  author: your-name
  version: "1.0"
---

# PDF forms
## Steps
1. List the form's fields with scripts/fields.py.
2. Match each field to a spreadsheet column.
3. Ask before guessing a field that has no match.

## Details
See references/FIELDS.md for date and checkbox rules.

Next: install it in Claude Code, or read what Claude skills are from the start.