What Is an AI Agent Skill? SKILL.md Explained
An agent skill is a folder with a SKILL.md file that an AI agent reads only when a task calls for it. How skills load, how they differ from prompts and MCP servers.
What is an AI agent skill? It is a folder that packages instructions, and optionally scripts and reference files, for one kind of task, with a SKILL.md file at its center. The agent sees only the skill's name and description until a request matches, then loads the full instructions. That keeps your context window clear while still letting the agent know how to do many specialized jobs.
The format was introduced by Anthropic and is documented in its Agent Skills overview. This post explains how a skill is built, how it loads, how it differs from things it is often confused with, and what to watch for before installing one.
What is inside a skill
Every skill requires a SKILL.md file with YAML frontmatter containing a name and a description. The body holds the instructions. Anything else, such as extra markdown files or scripts, is optional.
---
name: release-notes
description: Write customer-facing release notes from a list of merged changes. Use when the user asks for release notes, a changelog entry, or an update summary.
---
# Release notes
## Steps
1. Group changes into Added, Changed, Fixed.
2. Write each item as one sentence a customer would understand.
3. Leave out internal refactors unless they change behavior.
## Style
- Plain words, present tense, no marketing language.
- Link to docs only if the URL was provided.
For tone examples, read examples.md.The documentation sets rules on the fields. The name is limited to 64 characters of lowercase letters, numbers and hyphens, and the description must be non-empty, up to 1024 characters. The description is the important one: it must say both what the skill does and when to use it, because the agent matches your request against it.
How a skill loads: three levels
The documentation describes progressive disclosure, where information loads in stages instead of all at once.
Level | When it loads | What the docs say it costs |
|---|---|---|
1. Metadata | At startup, always | About 100 tokens per skill, name and description only |
2. Instructions | When a request matches the description | SKILL.md body, under 5k tokens |
3. Resources and code | Only when the instructions reference them | Nothing until accessed, and script code does not enter context, only its output |
This is why you can install many skills without a penalty: until one triggers, only its short description sits in the context window. The idea connects to the broader discipline in what is context engineering.
Skill vs prompt vs MCP server vs fine-tuning
Thing | What it is | Best for | Weak at |
|---|---|---|---|
Skill | A folder of instructions, scripts and references loaded on demand | Repeatable procedures and house style | Live access to outside systems |
System prompt | Instructions sent with every conversation | Short rules that always apply | Anything long, since it costs context every time |
MCP server | A connection that lets an agent call outside tools and data | Reaching a database, calendar or API | Teaching a procedure or style |
Fine-tuning | Changing the model's weights with training data | Deep, stable behavior changes at scale | Quick edits, and anything that changes weekly |
A skill and an MCP server often work together: the server gives the agent access to your issue tracker, and the skill tells it how your team writes release notes from those issues. For the protocol side, see what is the Model Context Protocol.
Where skills live
In Claude Code, according to the docs, skills are filesystem-based: personal ones in a skills folder under your home directory's .claude directory, and project ones in a .claude/skills folder inside the repository. Skills for the API, claude.ai and Claude Code are managed separately and do not sync across surfaces. If you work with several, check where each one is installed.
Security: treat a skill like installed software
A skill can include instructions and executable code, which is exactly why the documentation warns to use skills only from trusted sources, those you created yourself or obtained from Anthropic. It says a malicious skill can direct the agent to invoke tools or run code in ways that do not match its stated purpose, and that skills which fetch external content carry added risk.
Read every file in a skill before installing it, including scripts.
Be wary of skills that make network calls you cannot explain.
Prefer skills you wrote or that come from a source you already trust.
Re-check a skill after it updates, just as you would a dependency.
Writing a good one
Start with the description, since that is what triggers it. Write what it does and the phrases a user would say. Keep the body short and procedural, and move detail into separate reference files so it loads only when needed. Test with a few real requests, including ones that should not trigger the skill.
Skills sit on top of the machinery described in what is an AI coding agent and what is an agent harness. For the whole category of tools, start at the AI coding tools guide.
FAQ
What is a SKILL.md file?
The required file in a skill folder. It has YAML frontmatter with a name and description, followed by the instructions the agent follows when the skill is triggered.
How is a skill different from a prompt?
A prompt is instructions for one conversation. A skill is stored, reusable, and loaded on demand when a request matches its description.
Do skills work with every AI model?
The format is documented by Anthropic for its products. Whether another tool supports the same folder layout depends on that tool, so check its documentation.
Can a skill run code?
Yes. A skill can bundle scripts that the agent runs, and only the script's output enters the context. That also makes it important to audit any skill you did not write.
How did this land?
About the author
Senior Editor, AI & Product
Cecilia leads the Swarmz editorial desk. She has spent a decade turning complex AI and product topics into writing people actually finish, and she owns the blog's quality bar.
