What Is an Agent Skill? SKILL.md Explained

A skill is a packaged piece of know-how an agent can pick up when it needs it. The open specification calls Agent Skills "a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows".

At minimum a skill is one folder with one file, SKILL.md. Everything else is optional:

my-skill/
├── SKILL.md      # required: front matter + instructions
├── scripts/      # optional: code the agent can run
├── references/   # optional: documents it reads when needed
└── assets/       # optional: templates, images, data

The difference from a prompt is when it's used. Anthropic's docs put it this way: "Unlike prompts (conversation-level instructions for one-off tasks), Skills load on demand, so you don't have to repeat the same guidance across conversations." You write the instructions once, and the agent reaches for them whenever a request matches.

Two fields are required: name and description. The description does most of the work, because it's what the agent matches your request against to decide whether to load the skill.

Anthropic adds two limits for Claude: the name can't contain XML tags or the reserved words "anthropic" or "claude". Claude Code also accepts its own extra fields, such as disable-model-invocation (only you can start the skill), user-invocable (hide it from the / menu) and context: fork (run it in a subagent). Outside Claude Code, in claude.ai uploads and the Skills API, only the six standard fields are accepted.

Write the description as two halves: what the skill does, then when to use it. The specification's good example: "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." Its poor example is "Helps with PDFs."

Agents load a skill in stages, so an installed skill costs almost nothing until it's used. Only the front matter is read up front; the instructions and files follow when a task calls for them.

This is why the specification says to "keep your main SKILL.md under 500 lines" and move detail into separate files, linked one level deep. A skill can carry a long reference document, and the agent opens it only when the step it's on needs it. Scripts are cheaper still: Anthropic's docs note that when Claude runs a bundled script, "the script code itself never enters context", only its output.

Claude Code reads skills from the file system: ~/.claude/skills for every project on your machine, or .claude/skills inside a project. Each skill is a folder with a SKILL.md at its root.

• Personal: ~/.claude/skills/<skill-name>/SKILL.md loads in all your projects.
• Project: .claude/skills/<skill-name>/SKILL.md loads in that repository. Commit it and your team gets it too.
• Plugin: <plugin>/skills/<skill-name>/SKILL.md, run as /plugin-name:skill-name wherever the plugin is enabled.

Claude uses a skill when it's relevant, or you can start one yourself by typing /skill-name. In the skill list, the description (with the optional when_to_use text) is cut at 1,536 characters, so put the main use case first.

Skills don't sync between Claude's products. On claude.ai you upload a skill as a zip in Settings > Features (Pro, Max, Team and Enterprise plans, with code execution on); on the Claude API you upload it through the Skills API; Claude Code reads its folders. Each copy is managed separately.

Many. Anthropic developed the format and released it as an open standard, and other agents now read the same SKILL.md folders. Each tool's own documentation confirms the folders below.

Two folders do most of the sharing. A skill in .claude/skills is found by Claude Code, Cursor and VS Code; one in .agents/skills is found by Codex, Cursor and VS Code. The agentskills.io site keeps a showcase of further clients.

Codex's docs say its skills "build on the open agent skills standard"; Cursor's say "Agent Skills is an open standard for extending AI agents"; VS Code's call it "an open standard" that works across Copilot's agents.

A working skill can be a dozen lines: front matter, then plain instructions. This one keeps release notes consistent:

---
name: release-notes
description: Write release notes from the commits since the last tag. Use when the user asks for release notes, a changelog entry or a summary of what shipped.
---

# Release notes

1. List commits since the last tag with `git log $(git describe --tags --abbrev=0)..HEAD --oneline`.
2. Group them under Added, Changed and Fixed. Skip merge commits and chores.
3. Write one plain sentence per change, from the user's point of view.
4. Show the draft and ask before writing it to CHANGELOG.md.

1. 1Make a folder whose name matches the name field, here release-notes.
2. 2Write the description as what it does plus when to use it.
3. 3Keep the body to the steps; move long reference material into separate files and link them.
4. 4Check it with the specification's validator: skills-ref validate ./release-notes.
5. 5Ask for release notes and confirm the agent picks the skill up.

Only install skills you trust. Anthropic's docs warn that a skill can direct the agent to run code or call tools, so read every file in a skill from an unknown source before using it, the same way you'd treat installing software.

A design kit is a skill whose job is to apply one design to your project. A Livery kit has the standard shape: a SKILL.md with a name such as livery-linear-app and a description that names the site and says to use the kit only when you ask to copy that site or apply its design, so the agent doesn't restyle your app unasked.

The SKILL.md body is the process: audit the project, report the gap for each area, ask which areas to apply, then commit one area at a time. The design itself sits in files the agent reads only when its step needs them: tokens.json (colours by role, type scale, spacing, radii), rules.md, components.md, layout.md and motion.md, all measured from the live site rather than written by a model. That is progressive disclosure applied to a design system.

Because it's the standard format, the same kit works beyond Claude Code: one paste installs it under .claude/skills, and for Codex, Cursor or Windsurf you unzip it into the project and point the agent at SKILL.md.