What is SKILL.md

SKILL.md is a markdown file that tells an AI agent how to do one specific job. It lives inside a directory, and that directory is the skill. The file opens with YAML frontmatter carrying two required fields, name and description, followed by instructions in plain markdown. An agent loads only the description at startup and reads the rest when a task matches.

That is the whole format. The rest of this page is the detail behind it.

The directory

A skill is a folder. The only file it must contain is SKILL.md.

Three sibling directories are conventional. scripts/ holds executable code. references/ holds documentation the agent reads on demand. assets/ holds templates, images, and data files.

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

None of the three are required. A skill that is one file is a valid skill.

The frontmatter

Two fields are required. Four are optional.

Field	Required	Constraint
name	Yes	1 to 64 characters. Lowercase a-z, 0-9, and hyphens. No leading or trailing hyphen, no --. Must match the parent directory name.
description	Yes	1 to 1024 characters. Says what the skill does and when to use it.
license	No	A license name, or a reference to a bundled license file.
compatibility	No	Max 500 characters. Environment requirements.
metadata	No	A map of string keys to string values.
allowed-tools	No	Space-separated list of pre-approved tools. Experimental.

The gotcha is in the name row. It must match the parent directory name. A folder called Acme-Design-System cannot hold a skill named acme-design-system. Validation fails, and the folder name is not fixable from inside the file.

The description

This is the field that matters. Everything else is plumbing.

At startup an agent loads the name and description of every installed skill. Nothing else. The description is the only evidence it has when it decides whether to open your file. Write it badly and the skill is installed, valid, and never read.

The spec makes the point with two versions of the same skill.

Poor:

description: Helps with PDFs.

Good:

description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

The second one does three things. It names the actions. It names the trigger condition. It includes the words a user is likely to type.

The same failure in a design system reads like this.

Poor:

description: Our design system.

Good:

description: Component rules, tokens, and layout patterns for the Acme design system. Use when building or reviewing Acme UI, choosing colours or spacing, or when the user mentions Acme components, tokens, or brand.

You have 1024 characters. Most people use forty. Spend them on the words a person types when they need this skill.

The loading model

Agents load skills progressively, in three stages. The spec gives its own numbers for the first two.

Discovery, around 100 tokens. The name and description fields, loaded at startup for every installed skill.

Activation, under 5000 tokens recommended. The full SKILL.md body, loaded only once the agent decides the skill is relevant.

Execution, as needed. Files under scripts/, references/, and assets/, loaded only when the instructions call for them.

This is why a hundred installed skills cost so little to keep around. A hundred descriptions is a few thousand tokens. The bodies stay on disk until something needs them.

It is also why the description carries the whole load. It is the only part of your skill that competes for attention.

The example

A real one, short enough to copy.

---
name: acme-design-system
description: Component rules, tokens, and layout patterns for the Acme design system. Use when building or reviewing Acme UI, choosing colours or spacing, or when the user mentions Acme components, tokens, or brand.
license: MIT
---

# Acme design system

## Tokens

Colour, spacing, and radius values live in `references/tokens.md`. Read that
file before writing any style.

## Components

Use an existing component from `references/components.md` if one covers the
case. Do not build a new button, input, or card.

## Rules

1. Spacing comes from the 4px scale. No arbitrary pixel values.
2. Body text is 16px minimum. Never below.
3. Every interactive element carries a visible focus state.

## Checking your work

Run `scripts/lint-tokens.sh` against any file you changed.

Note what the body does not do. It does not paste the token table into the instructions. It points at a file and says when to read it.

The limits

Three pieces of practical guidance sit in the spec, and all three exist to protect context.

Keep SKILL.md under 500 lines. Past that, move detail into references/.

Keep file references one level deep. A file that points at a file that points at a file makes the agent burn context walking the chain.

Validate before you ship:

skills-ref validate ./my-skill

That checks the frontmatter and the naming conventions. It will not tell you whether the description is any good.

The origin

The format was originally developed by Anthropic and released as an open standard. Support is now broad, including Claude Code, Cursor, VS Code, GitHub Copilot, Gemini CLI, Codex, OpenCode, and Goose.

The specification page does not carry a publication date. I am not going to invent one.

Design systems

Nothing in the format is design-specific. It is a general packaging standard for procedural knowledge, and PDF processing is the spec's own worked example.

It happens to fit design systems well. A design system is already rules plus references plus assets, written down. The work is deciding which rules survive the translation, not converting the file.

I used this format for skill-kit, 577 files across 9 categories. The formatting was the fast part. The curation was not.

If you want the fuller picture of how this fits with DESIGN.md and the rest, start at agent-ready design systems. If you want to see what I do with it, that is there too.

A skill is a folder with a good description on top. Most of the work is in that one line.