SKILL.md — The Agent Skills Format

SKILL.md is an open standard for packaging reusable capabilities that AI coding agents can discover and activate on demand. Created by Anthropic and standardized at agentskills.io, the format is supported by 27+ AI agents including Claude Code, Cursor, Codex, Gemini CLI, and VS Code.

What problem does it solve?

Without skills, you repeat the same complex prompts every time you want an agent to do something specific — generate a PDF, build a design system, write Playwright tests. SKILL.md packages those instructions once so any compatible agent can pick them up automatically. Skills are loaded on demand, so they don’t bloat your agent’s context window.

How it works

A skill is a folder containing a SKILL.md file with YAML frontmatter and markdown instructions. At minimum, a skill needs a name and description.

---

name: pdf-processing

description: Extract text and tables from PDF files,

merge documents, fill forms, and convert to images.

license: MIT

compatibility:

- Claude Code

- Cursor

allowed-tools: Bash(python:*) Read Write

---

# PDF Processing

When the user asks you to work with PDF files, follow

these instructions...

Frontmatter fields

Field	Required	Description
name	Yes	Unique identifier. Max 64 chars, lowercase letters, numbers, hyphens.
description	Yes	What the skill does and when to activate it. Max 1024 chars.
license	No	SPDX license identifier or reference to a license file.
compatibility	No	List of compatible agents and environment requirements.
metadata	No	Arbitrary key-value pairs (author, version, tags).
allowed-tools	No	Space-delimited list of pre-approved tools for the agent.

Progressive disclosure

Skills use a three-phase loading model to keep context windows efficient:

Discovery — Agent reads only the name and description (~100 tokens)
Activation — When a task matches, the full SKILL.md is loaded (<5000 tokens)
Execution — Agent follows instructions, loading referenced files as needed

Who supports it

The SKILL.md format is supported by Claude Code, Cursor, OpenAI Codex, Gemini CLI, VS Code, GitHub Copilot, Amp, Roo Code, Goose, Windsurf, Continue, and many more. The full list of compatible agents is maintained at agentskills.io.

Related specs

AGENTS.md — project-level context (loaded every prompt, not on demand)
CLAUDE.md — Claude-specific project rules
MCP — for connecting agents to external tools and services

Official Specification

The full SKILL.md specification is maintained at agentskills.io.

Read the full specification