Guide · Claude Code
What Are Agent Skills? SKILL.md, explained
An Agent Skill is a folder with a SKILL.md file that teaches an AI agent how to do a specific kind of work. The agent loads the skill when the task matches, then follows the instructions inside. Skills extend assistants such as Claude, Claude Code, Cursor, and Codex, and they follow an open standard so the same package can work across tools.
This guide explains what is actually inside a skill, how the loading mechanism keeps your context small, how skills differ from MCP servers, and how to choose one for real work instead of collecting a folder of packages you never use.
What an Agent Skill actually is
A skill is not a plugin and not a prompt. It is a written procedure: a short description that tells the agent when the skill applies, plus markdown instructions the agent reads only after deciding to use it. Anthropic documents this as the Agent Skills open standard, and Claude Code implements it with extra features such as invocation control and subagent execution.
The practical test for whether something should be a skill comes from Anthropic's own guidance: create one when you keep pasting the same instructions, checklist, or multi-step procedure into chat. If a chunk of your project instructions has grown into a procedure rather than a fact, it is a candidate for a skill.
The parts of a SKILL.md file
Every skill has a SKILL.md with two parts: YAML frontmatter between --- markers, and the markdown body that follows. The frontmatter tells the agent when to use the skill; the body tells it what to do.
| Field | Purpose |
|---|---|
| description | What the skill does and when to use it. The main signal the agent uses to load it automatically. |
| name | Command name shown in the menu. Defaults to the folder name. |
| when_to_use | Extra trigger phrases, appended to the description. |
| allowed-tools | Tools the skill may use without asking during that turn. A permission grant, not a sandbox. |
| disable-model-invocation | Set true for workflows you only want to trigger by hand. |
| model / effort | Optional overrides while the skill is active. |
Only description is recommended; every field is optional, and an unrecognized field is ignored without an error. The description matters most because the agent compares your request against it to decide whether to load the skill. Anthropic truncates the combined description and when-to-use text at 1,536 characters in the skill listing to limit context use.
How progressive disclosure keeps context small
The reason skills are useful is not that they hold more information than a prompt. It is that they hold information *later*. At startup the agent sees only each skill's name and description. The full body loads when the skill is used, and supporting files load only when the instructions reach them.
That order matters for cost. Once a skill loads, its content stays in context across later turns, so every line becomes a recurring token cost. The practical consequence for anyone choosing skills is the same as for authors: favor focused skills over sprawling ones, and prefer skills whose body states the procedure rather than narrating it. If you are optimizing a setup, the token optimization topic collects skills that target exactly this.
Skills vs MCP vs prompts vs hooks
These four are often confused because they all "extend" an agent, but they solve different problems. The Model Context Protocol is an open standard for connecting an AI application to external systems, such as data sources, tools, and workflows. A skill is context. A hook is an automatic action on an event. A prompt is a one-off instruction.
| You want to… | Use | Why |
|---|---|---|
| Reach an external system or data source | MCP server | It standardizes connections to tools and data the agent does not have. |
| Teach a repeatable procedure | Skill | It loads on demand and stays out of context until needed. |
| Enforce something on every event | Hook | It runs automatically rather than relying on the model to remember. |
| Give a one-off instruction | Prompt | No packaging, no reuse; fine for a single turn. |
Where skills live and how they load
For Claude Code, where you save a skill decides which sessions get it. A personal skill in ~/.claude/skills/ is available in all your projects; a project skill in .claude/skills/ ships with the repository so the whole team gets it; plugins and managed settings distribute skills across an organization. Claude Code also reads skills from parent and nested directories in a monorepo.
Agents that follow the open standard use comparable layouts, which is why a skill written for one tool often works in another. The Claude Code topic covers skills that support that specific working loop; the Cursor topic covers the same idea in a different editor.
How to choose a skill for real work
Most people over-install. The skills that help are the ones tied to work you repeat, not the ones with the best names. A short process beats a long list:
- Name the task you repeat. If you cannot point at the task, the skill will not change anything.
- Check what the skill actually covers, not what its title promises. Read the description and, when it matters, the body.
- Prefer one skill per stage of a workflow over a single skill that claims the whole pipeline.
- Note its dependencies. A skill that wraps a CLI, an API, or a model you do not have is dead weight.
- Treat the source as a trust signal. Read the skill's own instructions before you let it run.
That last point is not a formality. Installing a skill is a trust decision: a skill can propose commands, and an allowed-tools grant widens what runs without a prompt. The Beginners topic is a reasonable starting list if your main goal is to learn the format before adopting anything heavy, and the Developers topic is the right anchor once you are choosing by workflow stage.
SkillPicker organizes that choice by the work, not by popularity. Each topic page is a list of SKILL.md packages, ranked from observed search demand, and marked as reviewed for relevance rather than endorsed. Use this guide to understand the format, then use the topic index to find candidates.
Frequently asked questions
Are Agent Skills the same as MCP servers?
No. A skill is a written procedure the agent loads as context. An MCP server is a connection to an external system that exposes tools or data. Many workflows use both: MCP provides the capability, a skill provides the know-how.
Do skills cost tokens all the time?
No. Only the skill name and description sit in the listing. The body loads when the skill is used, so long reference material costs almost nothing until it is needed.
Where do I install a skill?
For Claude Code, personal skills live in ~/.claude/skills/<name>/SKILL.md and project skills in .claude/skills/<name>/SKILL.md. Other agents that follow the Agent Skills standard use comparable directories.
Reviewed, not endorsed.These guides explain how to compare skills. They are not a recommendation or a security guarantee. Read each skill's own SKILL.md before installing it. How this index works