What Are Agent Skills? SKILL.md Explained

An agent skill is a folder with a file called SKILL.md in it. The file starts with a name and a one-line description, then has instructions in plain Markdown. Your AI agent (Claude Code, Codex, Cursor, VS Code and many others) reads the description all the time and the instructions only when a task matches it.

That is most of the idea. A skill teaches your agent how to do one kind of job the way you want it done: write a commit message in your team's format, review a pull request against a checklist, fill in a PDF form with a script you trust. This post covers what goes in the folder, why skills stay cheap until they are used, where each tool looks for them, how to install one, and how to write a small one of your own.

What is in a skill folder

The Agent Skills specification asks for one file. Everything else is optional:

commit-messages/
├── SKILL.md        required: metadata and instructions
├── scripts/        optional: code the agent can run
├── references/     optional: longer docs it reads when needed
└── assets/         optional: templates, data files, images

SKILL.md opens with YAML frontmatter. Two fields are required and four are optional:

Below the frontmatter is the body: the instructions, in whatever shape helps. Steps, examples of good output, edge cases to watch for. There are no required headings.

Some tools add fields of their own. Claude Code, for example, has disable-model-invocation for a skill you only ever want to start yourself. Its skills docs say those extras only work in Claude Code, and that a skill meant to travel should stick to the six fields above.

Why a skill costs almost nothing until it is used

Everything your agent reads takes up room in its context window, and a crowded context makes an agent slower, more expensive and easier to distract. Skills avoid that by loading in three steps, which the spec calls progressive disclosure:

1. Metadata. At startup, the agent loads the name and description of every installed skill. The spec puts this at about 100 tokens a skill.
2. Instructions. When a task matches a description, the agent reads that skill's whole SKILL.md body. The spec recommends keeping it under 5,000 tokens and 500 lines.
3. Resources. Files in scripts/, references/ or assets/ load only if the instructions point to them and the task needs them.

Pick a task below to see what ends up in the context window.

Two things follow from this. You can install a dozen skills without paying for a dozen sets of instructions on every message. And the description does all the work of getting a skill picked: if it does not say when to use the skill, in words close to how you would ask, the agent will not load it.

Which tools can use skills

Anthropic introduced skills in October 2025 and published the format as an open standard in December 2025. The agentskills.io site lists the tools that support it. Most AI coding tools you are likely to use are on that list, including Claude Code, Codex, Cursor, VS Code with GitHub Copilot, Gemini CLI, OpenCode and Goose.

The format is shared, but each tool looks in its own folders. This is where the main ones load skills from:

Several of them also read the shared .agents/skills/ folder, and VS Code reads .claude/skills/ too, so one copy can serve more than one tool. The Claude apps work differently: you upload a skill as a .zip in settings rather than putting it in a folder. Folder names change from time to time, so check the linked docs if one of these does not work.

How to install a skill

Installing a skill means copying its folder into one of those places.

The skills CLI fetches a skill from a GitHub repository and puts it in the right folder for the tools you pick:

npx skills add OWNER/REPO --skill SKILL-NAME

Or do it by hand: clone or download the repository, then copy the skill's folder (the one with SKILL.md in it) into your tool's skills folder, keeping the folder name.

Whichever you use, read the files first. A skill's instructions are followed by your agent, and its scripts run with the same access to your computer as you have. Our guide on checking a skill or MCP server before you install it takes about ten minutes and covers what to look for. Every skill in our agent skills list has already been through it, and its page gives install steps pinned to the exact version we read.

Write a tiny one

Here is a complete skill. Save it as .claude/skills/commit-messages/SKILL.md (or the folder for your tool) and it works:

---
name: commit-messages
description: Writes git commit messages in Conventional Commits style. Use when committing changes or when asked for a commit message.
---
 
1. Run `git diff --staged` and read the whole change.
2. Pick the type: feat, fix, docs, refactor, test or chore.
3. Write a subject line under 72 characters, in the imperative
   ("add", not "added"), with no full stop.
4. If the change needs explaining, add a blank line and a short body
   saying why it was made, not what the diff already shows.
5. Show the message and ask before committing.

A few things that make the difference between a skill that gets used and one that sits there:

• Write the description for the moment it should load. Say what it does and when to use it, with the words you would actually type. "Helps with git" is too vague to match anything.
• Keep the body short and move detail out. Long examples and reference tables can go in references/, with one line in the body saying when to read them. Keep those links one level deep from SKILL.md.
• Explain why, not only what. A rule with a reason attached is easier for the agent to apply to a case you did not think of.
• Check the frontmatter. The spec's skills-ref tool validates a folder with skills-ref validate ./commit-messages.

Three skills to start with

These are from our reviewed list. Each page says what the skill can touch and how to install it in the tool you use.

• Grill Me, by Matt Pocock. Before any code gets written, your agent questions your plan one round at a time and suggests an answer each time. Instructions only, no scripts.
• Frontend Design, by Anthropic. Makes your agent choose a visual direction before it writes UI code, so pages stop looking generated.
• Skill Creator, by Anthropic. The one above, for when you are ready to write your own.

Skills teach your agent how to work. They do not connect it to anything new. For access to GitHub, a browser or a database you need an MCP server, which what MCP is and how it works explains. If you are not sure which of the two you need, or where subagents fit, read skills vs MCP servers vs subagents.

Sources

All checked on 27 September 2026.

• Agent Skills, Specification and Overview
• Anthropic, Equipping agents for the real world with Agent Skills (October 2025, updated December 2025)
• Claude Code docs, Skills
• Codex docs, Build skills
• Cursor docs, Skills
• VS Code docs, Agent skills
• Gemini CLI docs, Skills
• Claude Help Center, Use skills in Claude
• Vercel Labs, skills CLI