What is inside a SKILL.md
Updated 13 November 2026. Based on the Agent Skills specification, read directly from agentskills.io on that date. Where an agent behaves differently from the specification, the agent wins; check its own documentation.
An agent skill is a folder. The only required file is SKILL.md: a short block of YAML at the top, then instructions in Markdown. Everything else is optional.
pdf-processing/
├── SKILL.md required: frontmatter, then instructions
├── scripts/ optional: code the agent can run
├── references/ optional: documentation loaded when needed
└── assets/ optional: templates, images, data filesThe frontmatter, field by field
Two fields are required.
| Field | Required | Rule in the specification |
|---|---|---|
| name | yes | 1 to 64 characters. Lowercase letters, digits and hyphens. Must not start or end with a hyphen, must not contain two hyphens in a row, and must match the folder’s name. |
| description | yes | 1 to 1024 characters. Should say both what the skill does and when to use it. |
| license | no | A license name, or the name of a bundled license file. |
| compatibility | no | 1 to 500 characters. Environment requirements such as the intended product, system packages or network access. |
| metadata | no | A map of text keys to text values, for anything the specification does not define. |
| allowed-tools | no | A space-separated string of pre-approved tools. Marked experimental; support varies between agents. |
A minimal file looks like this:
---
name: pdf-processing
description: Extracts text and tables from PDF files, fills forms and merges files. Use when working with PDFs.
---
# PDF processing
Step-by-step instructions go here.It is the part every agent reads for every installed skill, and it is how an agent decides whether a task needs the skill. “Helps with PDFs” tells it little; naming what the skill does and when to use it tells it much more.
What gets loaded, and when
The specification describes loading in three levels, so that a long list of skills does not fill the agent’s context:
- Metadata, the name and description of every skill, at startup. The specification puts this at about 100 tokens per skill.
- Instructions, the whole SKILL.md, when the agent decides a task matches. The specification recommends under 5000 tokens, and a file under 500 lines.
- Resources, the files in
scripts/,references/andassets/, only when the instructions point to them.
That is why long reference material belongs in separate files rather than in SKILL.md itself. See how much context a skill costs for measurements.
Pointing at other files
Refer to files with relative paths from the skill’s folder, for example references/REFERENCE.md or scripts/extract.py. The specification advises keeping references one level deep from SKILL.md and avoiding chains of files that point to more files.
Checking a skill
The specification’s own reference tool is skills-ref validate ./my-skill. The mdprev skill inspector does the same frontmatter checks in the browser, adds the estimated token cost and lists files that the instructions mention but the folder does not contain, and scripts worth reading before you install a skill.