Open editor
Guide

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 files

The frontmatter, field by field

Two fields are required.

FieldRequiredRule in the specification
nameyes1 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.
descriptionyes1 to 1024 characters. Should say both what the skill does and when to use it.
licensenoA license name, or the name of a bundled license file.
compatibilityno1 to 500 characters. Environment requirements such as the intended product, system packages or network access.
metadatanoA map of text keys to text values, for anything the specification does not define.
allowed-toolsnoA 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.
WHY THE DESCRIPTION MATTERS

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:

  1. Metadata, the name and description of every skill, at startup. The specification puts this at about 100 tokens per skill.
  2. Instructions, the whole SKILL.md, when the agent decides a task matches. The specification recommends under 5000 tokens, and a file under 500 lines.
  3. Resources, the files in scripts/, references/ and assets/, 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.