Agent Skills
An agent can only hold so much in its prompt — the text instructions and information it's given before it starts working — before most of it becomes noise for any single task. A skill solves that by living outside the prompt until it's actually needed. When it's needed, the agent loads it. When it's not, it stays out of the way.
Put simply: a skill is a packaged set of instructions for doing one kind of task well, that an agent picks up only when that task comes up.
How an agent finds the right skill
Loading every skill's full instructions all the time would defeat the purpose — that's the same context-bloat problem skills exist to solve. Instead, the agent sees only a short description of each available skill up front. When a task matches one, the agent loads that skill's full instructions. Anthropic calls this progressive disclosure, and it goes one level further still: a skill can also bundle reference files and scripts that stay untouched until the task actually needs them. A reference file only costs context once the agent reads it. A script costs even less — the agent runs it and only its result enters context, never the script's own code.
How this site's pages get written
This site's own content gets written using exactly this pattern. A skill called write-concept-page holds the full process for authoring a page on this site. How to structure it, what markup to use, how to fact-check it, how to review it before it ships — all of it. That skill sits unloaded most of the time. Its one-line description is the only thing visible by default. The moment a page actually needs writing, its full instructions load and get followed. The result is the page you're reading right now.
Skill vs. tool
| Skill | Tool | |
|---|---|---|
| What it is | Instructions | A function the agent can call |
| What it does | Tells the agent how to approach a task | Actually does something — search, read a file, run code |
| Relationship | Often uses several tools along the way | Doesn't replace skills; skills call tools, not the other way around |
When to create one
When a task comes up often enough that re-explaining how to do it well gets wasteful. And when the instructions are detailed enough that keeping them permanently in the prompt would waste space on every other task that doesn't need them.
When not to bother
For a one-off task, or something simple enough to just ask for directly. Packaging a five-word instruction into a skill adds overhead for no benefit — the whole point of a skill is saving effort on something that gets repeated.
In this guide
FAQ
What happens if two available skills' descriptions both seem to match the same request?
The agent picks whichever description is the closer match — which is exactly why a skill's description needs to say clearly when to use it, not just what it does. A vague or overlapping description makes the wrong skill getting picked more likely.