SKILL.md Format Explained: Fields, Folder Layout and an Annotated Example

SKILL.md is the one required file in every Agent Skill folder. It holds YAML frontmatter with a name and description, then Markdown instructions the agent loads on activation. The rules come from the Agent Skills specification and Anthropic's documentation, checked on 2026-10-21.

We wrote the example below for this page. It is spec-valid and uses one reference file and one script.

---
name: reviewing-pull-requests                      # (1)
description: Reviews a pull request diff for bugs, missing tests and risky changes, then writes a prioritised comment list. Use when the user asks to review a PR, a diff or staged changes.   # (2)
license: Apache-2.0                                # (3)
compatibility: Requires git and Python 3.10+       # (4)
metadata:                                          # (5)
  author: example-team
  version: "1.2"
allowed-tools: Bash(git diff:*) Read               # (6)
---

# Reviewing pull requests                           

## Steps
1. Run `git diff main...HEAD` and read the changed files.
2. Check each change against [references/CHECKLIST.md](references/CHECKLIST.md).   
3. Run `scripts/find_untested.py` to list changed functions without tests.   
4. Write findings as: severity · file:line · problem · fix.

## Edge cases
- Stop and say so when the diff is empty.

reviewing-pull-requests/
├── SKILL.md
├── references/CHECKLIST.md
└── scripts/find_untested.py

Spec: 6 fields · 2 required · 64 / 1,024 / 500 characters.

What is a SKILL.md file?

A SKILL.md file is the one required file in every Agent Skill folder. It opens with YAML frontmatter holding a name and a description. Markdown instructions follow, and the agent reads them when the skill activates.

An Agent Skill is "a directory containing, at minimum, a SKILL.md file" (agentskills.io specification). The spec sets the format plainly. The file "must contain YAML frontmatter followed by Markdown content". The frontmatter is the block between two --- lines. Claude Code reads that block only when the opening --- is the file's first line (Claude Code docs).

Anthropic published the format as an open standard, now hosted at agentskills.io. Our concept guide covers what Agent Skills are, and the open standard.

SKILL.md, skill.md or skills.md: which spelling is right?

SKILL.md, in capitals, is the right spelling. The spec names the file SKILL.md throughout. Anthropic's Complete Guide is stricter. It says the file "Must be exactly SKILL.md (case-sensitive)" and lists "skill.md" as wrong (Complete Guide, PDF). Anthropic's Help Center article on custom skills writes "skill.md" in lower case throughout (Help Center). The two official sources conflict, so use SKILL.md and it passes both. "skills.md" is a different thing: a separate service, covered further down.

How does an agent load a SKILL.md?

An agent loads a SKILL.md in three levels, called progressive disclosure:

The spec gives these budgets, and the Claude platform docs use the same three levels (platform overview). Claude reads SKILL.md through bash. Scripts run through bash too, and only their output enters context. The choice between installed skills is its own topic: how Claude decides which skill to load.

Which agents and tools read SKILL.md?

Several agents read SKILL.md today. Three examples, each from its own docs:

• Claude reads it in the Claude apps, Claude Code and the Claude API (platform overview, "Where Skills work").
• VS Code looks in .agents/skills/ by default, per the agentskills.io quickstart.
• Microsoft Agent Framework loads SKILL.md directories as file-based skills (Microsoft Learn).

The full list of clients sits in the concept guide linked above.

What does a SKILL.md file look like?

A SKILL.md file looks like a short Markdown document under a YAML header. The header sits between two lines of three dashes and names the skill and its trigger. Headed instructions, examples and edge cases follow.

The annotated file at the top of this page is a full example. The header names the skill and says when to use it. The body then reads like a short runbook: a heading, numbered steps, and a list of edge cases. Links point to files the agent opens only when a step needs them. The smallest valid SKILL.md, from the spec, has two fields and no body:

---
name: skill-name
description: A description of what this skill does and when to use it.
---

Real skills sit between these two. Anthropic's Frontend Design skill, at commit 8a1541c, uses three frontmatter fields: name, description and license. Its folder holds 2 files: SKILL.md and a licence file. Our verdict on Anthropic's Frontend Design skill, reviewed on 2026-09-30, reads:

What frontmatter fields does a SKILL.md support?

The Agent Skills spec defines six SKILL.md frontmatter fields: name, description, license, compatibility, metadata and allowed-tools. Only name and description are required. Claude Code supports extra fields, such as context and model, that uploads reject.

Table A lists the six spec fields (agentskills.io specification):

Claude Code reads 14 more fields of its own (Claude Code docs). They are when_to_use, argument-hint, arguments, disable-model-invocation, user-invocable and disallowed-tools. The rest are model, effort, context, agent, background, hooks, paths and shell. Claude Code accepts metadata, license and compatibility too, but does not act on them.

These extras break portability. Claude.ai uploads, the Skills API and Anthropic's package_skill.py accept only the six spec fields. Any other key fails with "Unexpected key(s) in SKILL.md frontmatter". The ALLOWED_PROPERTIES list in quick_validate.py holds the same six keys.

Name and description rules

Claude's platform adds two rules (platform overview). Neither field can contain XML tags. name cannot contain the reserved words "anthropic" or "claude". Anthropic's best practices ask for descriptions in the third person.

The spec gives its own examples. pdf-processing is a valid name. PDF-Processing, -pdf and pdf--processing are invalid. Its good description starts "Extracts text and tables from PDF files, fills PDF forms". Its poor example reads "Helps with PDFs."

Official sources disagree on three points:

• Description length: the spec and platform docs allow 1,024 characters. The Help Center lists 200 characters. A description under 200 characters satisfies both.
• Name format: the Help Center example name is "Brand Guidelines", with capitals and a space. The spec and the Complete Guide require kebab-case, such as brand-guidelines.
• Required fields: the spec requires both fields. Claude Code treats every field as optional and defaults name to the folder name.

In Claude Code, the combined description and when_to_use text is cut at 1,536 characters in the skill listing. Wording matters for selection, which is why the description decides triggering.

The allowed-tools field

The spec defines allowed-tools as a space-separated, experimental list, as in Bash(git:*) Bash(jq:*) Read. In Claude Code, it pre-approves the listed tools for the turn that invokes the skill. It does not restrict other tools. Workspace trust does not gate it. Broad pre-approvals are one reason a verdict's safety grade drops to C, under how safety grades are assigned.

Claude Code-only fields

Arguments: $ARGUMENTS and argument-hint

Claude Code substitutes arguments into the body. $ARGUMENTS takes everything typed after the command. $ARGUMENTS[N] and $N take one argument by index, and $name takes a named one. argument-hint shows in autocomplete. With no placeholder in the body, Claude Code appends ARGUMENTS: <value>. A body reading "Fix GitHub issue $ARGUMENTS" turns /fix-issue 123 into "Fix GitHub issue 123".

What goes in the SKILL.md body?

The SKILL.md body is what goes in after the frontmatter: the instructions an agent follows once the skill activates. The spec recommends steps, input and output examples, and edge cases. It recommends under 500 lines and 5,000 tokens.

The spec says "There are no format restrictions" and recommends three kinds of content:

1. Step-by-step instructions
2. Examples of inputs and outputs
3. Common edge cases

Size matters because the whole body loads on activation. The spec, Claude Code docs and Anthropic's best practices all name 500 lines. The units differ on the second limit. The spec says under 5,000 tokens for the body. Anthropic's Complete Guide says "Keep SKILL.md under 5,000 words".

Claude Code keeps the body in context once it loads and does not re-read it. After compaction, it keeps the first 5,000 tokens of each re-attached skill. All re-attached skills share a 25,000-token budget (Claude Code docs). Put critical rules near the top.

Claude Code supports two body features that other surfaces ignore. !`command` runs a shell command and inserts its output first. ${CLAUDE_SKILL_DIR} resolves to the skill's own folder. Neither runs in claude.ai chat or through the API.

How is a skill folder around SKILL.md laid out?

A skill folder around SKILL.md is laid out with SKILL.md at its root and three optional folders. Scripts hold code, references hold documents loaded on demand, and assets hold templates and data.

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

SKILL.md links to these files by relative path, one level deep (spec). The spec sets a convention for each folder. Scripts are self-contained or document their dependencies, and they print helpful error messages. Python, Bash and JavaScript are the common languages. Reference files stay short and focused, because agents load them on demand. Assets hold templates, images and data files. Anthropic's Complete Guide adds two rules. Folder names use kebab-case, and no README.md goes inside the skill folder.

Every verdict on this site starts from these files. What a folder contains affects its safety grade:

Scripts are the part to read first; see what to check in bundled scripts. Each skill's own breakdown sits in every skill we've scanned, file by file.

scripts/, references/ and assets/

The spec's folder names are conventions. The PDF skill keeps reference files beside SKILL.md, outside a references/ folder.

Where does the skill folder go?

The spec does not mandate a location; it defines only what goes inside the folder. Three locations are common:

Claude Code's docs list no .agents/skills/ location, checked 2026-10-21. The full table, with plugin and nested paths, explains where Claude Code looks for skills.

What is a .skill file?

A .skill file is a packaged Agent Skill: a ZIP archive of one skill folder. Anthropic's package_skill.py script writes it for sharing. Unzip it, or rename it to .zip, to read the SKILL.md inside.

Anthropic's packager describes itself as a tool that "Creates a distributable .skill file of a skill folder". It writes {skill_name}.skill with Python's zipfile module. The script ships inside Anthropic's skill-creator. A .skill file holds no new format. No ".skill to .md" conversion is needed, because the Markdown file already sits inside the archive. For claude.ai, the Help Center documents uploads as a ZIP with the skill folder at its root.

To open a .skill file:

1. Rename it from .skill to .zip, or open it with any unzip tool.
2. Extract the archive.
3. Open the SKILL.md inside the extracted folder.

Packaging is a rare use of skill-creator. Our verdict cites pull requests #1681, #1900 and #1796 on packaging and validation. Issue #1467 notes that quick_validate.py imports PyYAML, which is not declared anywhere. The verdict notes that the package_skill.py usage path is wrong (#904). Details sit in our verdict on Anthropic's skill-creator:

Is SKILL.md the same as skills.md, skill.md or AGENTS.md?

No, SKILL.md is not the same as skills.md, skill.md or AGENTS.md. SKILL.md is the required file inside an Agent Skill folder. The skills.md service runs skills remotely for credits, and AGENTS.md is project context.

This table separates SKILL.md from six similar names:

The skills.md service sums itself up in one line:

Your agent finds the skill, runs it on skills.md and the files come back

It lists 300+ curated skills and charges credits per run. The skillsmd.dev site calls itself "The Open Agent Skills Registry".

GitBook defines a docs-site skill.md as "structured technical documentation written specifically for AI agents" (GitBook). That post does not cite the agentskills.io spec.

AGENTS.md is sent with every prompt and works best under 150 lines, per Red Hat Developer. Anthropic Academy notes that CLAUDE.md loads into every conversation. A SKILL.md body, by contrast, loads only when its skill activates.

That is the whole file. Before you write one, start from a template and check it.

Where can you get a SKILL.md template?

You can get the simplest SKILL.md template from Anthropic's anthropics/skills repository on GitHub. It holds a name line, a description line and an empty instructions section. Copy the folder, rename it, and write your steps.

Anthropic's template/SKILL.md reads, in full:

---
name: template-skill
description: Replace with description of the skill and when Claude should use it.
---

# Insert instructions below

The spec's two-field minimum, shown earlier, is the same shape. Rename the folder to match the new name. The tutorial walks through how to create an Agent Skill from a template.

How do you check that a SKILL.md is valid?

You check that a SKILL.md is valid with the spec's validator: skills-ref validate ./my-skill tests frontmatter and naming rules. Claude Code's claude plugin validate finds frontmatter that fails to parse.

Three commands cover the checks:

skills-ref validate ./my-skill                 # spec rules (agentskills.io)
claude plugin validate ~/.claude/skills        # YAML parse errors (Claude Code v2.1.233 or later)
python scripts/quick_validate.py ./my-skill    # Anthropic's six-key check (skill-creator)

Anthropic's quick_validate.py checks the six allowed keys and the 64 and 1,024-character limits. Broken YAML is harder to spot in Claude Code. The skill loads with empty metadata, so /skill-name still works. Auto-triggering fails, because Claude has no description to match. For other causes, see why a skill isn't triggering.

Common questions

Can you add comments to a SKILL.md?

Yes: # comments are valid YAML, and the spec's own examples use them. Claude reads the raw file, so every comment costs tokens (platform overview).

Are skills just Markdown files?

No. The core is one Markdown file, but a skill is a folder (spec).

Can a SKILL.md use XML tags?

Yes, in the body, because the spec sets no format restrictions there. Claude's platform forbids XML tags in name and description.

How do you version a skill?

The spec has no version field, so use metadata with a version key. The Complete Guide says "Update version in metadata"; track changes in git.

How do you declare dependencies?

Use compatibility for environment needs and list packages in the instructions (spec, best practices). The Help Center names a dependencies field, but Claude Code's docs say uploads reject non-spec keys.

Is SKILL.md JSON?

No. The header is YAML and the body is Markdown (spec).

Where can you see real SKILL.md examples?

Anthropic's anthropics/skills repository on GitHub holds many. Our verdict pages show each reviewed skill's files.

Part of the Agent Skills guide.