Skills: teach an agent a procedure once, reuse it everywhere
How SKILL.md works, every frontmatter field Claude Code reads, where skills live, which tools read the open Agent Skills format today, how to write descriptions that trigger, and how to test a skill. Three complete skills to copy.
On this page
A skill is a folder that teaches an agent one procedure: your PR checklist, your incident template, your migration review. You write it once as a SKILL.md file, and the agent loads it only when a task needs it. The same folder works in Claude Code, claude.ai, the Claude API, Codex, GitHub Copilot, Cursor and Gemini CLI, because they all read the open Agent Skills format.
What it is#
A skill is a directory with a SKILL.md file at its root. The file starts with YAML frontmatter, at minimum a name and a description, followed by Markdown instructions. The folder can also hold scripts/ the agent runs, references/ it reads when needed, and assets/ such as templates.
markdown
---
name: api-conventions
description: REST API conventions for this codebase. Use when adding or changing an API endpoint.
---
- Use kebab-case for URL paths and camelCase for JSON fields.
- Every list endpoint is paginated with `cursor` and `limit`.
- Errors return `{ "error": { "code", "message" } }` with a 4xx or 5xx status.Skills load in three stages, which is why you can install dozens without filling the context window.
- Metadata, always loaded. The
nameanddescriptionof every skill go into the agent's context at startup, about 100 tokens each. The agent matches your request against the descriptions. - Instructions, loaded when triggered. When a task matches, the agent reads the full
SKILL.md. The open spec recommends keeping it under 5,000 tokens and 500 lines. - Resources, loaded as needed. Reference files enter context only when the agent reads them. Scripts run, and only their output enters context, never their code.
In Claude Code you can also run a skill yourself by typing /skill-name. Custom commands in .claude/commands/ still work, and a skill with the same name wins.
When to use it#
Write a skill when you notice one of these:
- You paste the same instructions, checklist or multi-step procedure into chat for the third time.
- A section of
CLAUDE.mdhas grown from a fact into a procedure. - The team has a format the agent keeps getting wrong: a postmortem template, a release note style, a review checklist.
- A task needs a script or reference file the agent should use the same way every time.
Pick a different building block when the job is different.
| You need | Use |
|---|---|
| Facts the agent needs in every session, such as build commands | CLAUDE.md or AGENTS.md |
A rule that must hold every time, such as never editing .env | A hook or a permission rule |
| A side task with a lot of output kept out of your conversation | A subagent |
| Live data or actions in another system, such as Jira or a database | An MCP server |
| Several skills, agents and hooks shipped to a team as one install | A plugin |
Skip the skill for a one-off task, and never put credentials in one: a skill is plain text that anyone with the folder can read.
Where skills work today#
The format is an open standard published at agentskills.io. Its list of supported clients names 46 products as of October 2026. These are the ones most teams use, with the folders each one reads, taken from each vendor's docs.
| Tool | Project folders | Personal folders |
|---|---|---|
| Claude Code | .claude/skills/ | ~/.claude/skills/ |
| claude.ai and Claude Desktop | Upload a ZIP in Customize, then Skills | Same, per account |
| Claude API | Upload with the Skills API, use in the container parameter | Shared across the workspace |
| OpenAI Codex and ChatGPT desktop | .agents/skills/ from the current folder up to the repo root | ~/.agents/skills/ |
| GitHub Copilot (cloud agent, code review, CLI, IDEs) | .github/skills/, .claude/skills/, .agents/skills/ | ~/.copilot/skills/, ~/.agents/skills/ |
| VS Code agent mode | .github/skills/, .claude/skills/, .agents/skills/ | ~/.copilot/skills/, ~/.claude/skills/, ~/.agents/skills/ |
| Cursor | .agents/skills/, .cursor/skills/, and for compatibility .claude/skills/, .codex/skills/ | ~/.agents/skills/, ~/.cursor/skills/, ~/.claude/skills/, ~/.codex/skills/ |
| Gemini CLI | .gemini/skills/ or .agents/skills/ | ~/.gemini/skills/ or ~/.agents/skills/ |
Claude Code does not read .agents/skills/. To share one skill across tools, keep it in .claude/skills/<name>/, which Claude Code, Copilot, VS Code and Cursor all read, and add a symlink at .agents/skills/<name> for Codex and Gemini CLI. Codex documents that it follows symlinked skill folders. Use only the six fields in the open spec when a skill must work everywhere. The members section below marks which fields are Claude Code extensions.
Set it up step by step
Members only below this line
Get the rest of this guide free
What you get on this page:
- 3 skills
Also in the members part
- Write descriptions that trigger
- Test a skill
- Three complete skills
- Patterns that work
- Mistakes to avoid
- Exercises
Sources
Checked against these on 13 Oct 2026.
- Extend Claude with skills (Claude Code docs) (opens in a new tab)code.claude.com
- Agent Skills specification (opens in a new tab)agentskills.io
- Agent Skills supported clients (opens in a new tab)agentskills.io
- Optimizing skill descriptions (agentskills.io) (opens in a new tab)agentskills.io
- Agent Skills overview (Claude Platform docs) (opens in a new tab)platform.claude.com
- Using Agent Skills with the API (opens in a new tab)platform.claude.com
- Use skills in Claude (Claude Help Center) (opens in a new tab)support.claude.com
- Build skills (OpenAI Codex and ChatGPT) (opens in a new tab)developers.openai.com
- About agent skills (GitHub Copilot) (opens in a new tab)docs.github.com
- Use Agent Skills in VS Code (opens in a new tab)code.visualstudio.com
- Agent Skills (Cursor docs) (opens in a new tab)cursor.com
- Agent Skills (Gemini CLI docs) (opens in a new tab)geminicli.com