Agent Skills: the open SKILL.md standard, explained

What are Agent Skills?

Agent Skills is an open format for packaging know-how so any AI agent can use it. A skill is a folder with a SKILL.md file inside. The file starts with a short YAML header (a name and a description) and continues with Markdown instructions. The folder can also carry scripts, reference documents and templates.

The format was developed by Anthropic for Claude and released as an open standard in December 2025. The specification lives at agentskills.io, and the standard is developed in the open on GitHub. Because it's a shared format, a skill you write for Claude also works in Codex, Cursor, GitHub Copilot and other agents that adopted it.

The SKILL.md format

Here is the smallest valid skill:

---
name: commit-message
description: Write a Conventional Commits message from the staged diff. Use
  when the user asks to commit or asks for a commit message.
---

1. Read the staged diff with git diff --staged.
2. Pick the type: feat, fix, docs, refactor, test or chore.
3. Write a subject under 72 characters, in the imperative.
4. If nothing is staged, say so and stop.

The header has two required fields and four optional ones, all defined in the specification:

The body has no required structure. The spec suggests step by step instructions, examples of inputs and outputs, and common edge cases. For a hands-on walkthrough, see how to write a SKILL.md.

Optional folders

Anything beyond SKILL.md is optional, but the spec recommends three conventional folders:

pdf-processing/
├── SKILL.md        required
├── scripts/        code the agent can run
├── references/     extra docs the agent reads when needed
└── assets/         templates, images, lookup tables

Link to these files from SKILL.md with relative paths, like references/REFERENCE.md, and keep references one level deep. An agent that has to follow a chain of links from file to file is more likely to miss something.

What is progressive disclosure?

Progressive disclosure means the agent loads a skill in stages, only as far as the task needs. It is the idea that makes skills practical.

1. Discovery. At startup the agent reads only each skill's name and description, roughly 100 tokens per skill.
2. Activation. When a task matches a description, the agent reads the full SKILL.md body. The spec recommends keeping that under 5,000 tokens and under 500 lines.
3. Execution. The agent follows the instructions, opening reference files or running scripts only when a step calls for them.

This is why you can keep many skills installed with little cost, and why the description matters so much. It is the only part the agent sees before it decides whether to load the rest.

Which tools support Agent Skills?

Claude Code, the Claude app and API, OpenAI Codex, Cursor, GitHub Copilot CLI and Gemini CLI all document Agent Skills support in their own docs. Support has spread fast, and each tool reads skills from slightly different folders:

Sources: Claude Code, Claude platform, Codex, Cursor, GitHub Copilot, Gemini CLI. Many more agents are listed by the open source skills installer, which supports OpenCode, Claude Code, Codex, Cursor "and 75 more".

Notice the pattern: .agents/skills/ is becoming the shared default, while Claude Code keeps its own .claude/skills/ folder.

Why one folder works across agents

A skill is portable for three reasons.

1. The required header is the same everywhere. Every tool needs a name and a description and reads Markdown instructions.
2. Extra fields are ignored, not rejected. Claude Code adds fields like disable-model-invocation, and Codex reads an optional agents/openai.yaml. Other agents skip what they don't understand, so one file can carry settings for several tools.
3. It's just files. A skill lives in Git like any other code, so you can review changes, share it in a repo and roll it back.

The things that don't carry over are worth knowing:

• Folder locations differ, as the table above shows.
• Tool names differ. A skill that says "use the Bash tool" is written for one agent. Describe the action ("run the tests") rather than a specific tool when you can.
• Runtimes differ. The Claude API runs skills with no network access; Claude Code has the same access as your terminal. A script that downloads something works in one and fails in the other.
• Product rules can be stricter than the spec. Claude, for example, also rejects skill names containing "claude" or "anthropic".

Install one skill into several agents

You can copy a skill folder into each agent's directory by hand. The faster way is the skills command from Vercel Labs, which reads a Git repo and installs skills into the right folder for each agent you pick. It needs Node.js 22.20 or later.

# see which skills a repo contains
npx skills add vercel-labs/agent-skills --list

# install one skill for Claude Code and Codex, for all projects
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a claude-code -a codex -g

# install every skill in a repo to all agents, without prompts
npx skills add https://github.com/<owner>/<repo>.git --all

By default it symlinks each agent's folder to one shared copy, so an update reaches every agent at once. Add --copy if your system doesn't support symlinks.

Check a skill against the spec

The standard ships a reference validator, skills-ref, that checks the header and naming rules:

skills-ref validate ./commit-message

Before you share a skill, also check the things a validator can't: does the description use words people actually type, are the steps numbered, and does missing input have a default or a question?

Keep your skills in one repo

Because skills are plain folders, the natural home for them is a Git repo you control. Kipt is built on that idea: it saves your prompts and skills as Markdown in a private GitHub repo you own. Promote to skill turns a saved prompt into a valid SKILL.md that follows the rules above, and every skill in the repo installs into Claude Code or Codex with one npx skills add command. If you just want to convert a single prompt, the free SKILL.md generator does it in your browser.

Wondering how skills fit next to tool servers? Read skills vs MCP.