TL;DR
An agent skill is a folder containing a SKILL.md file, metadata plus instructions, that an agent loads on demand instead of keeping in context from the first turn. The mechanism that matters is progressive disclosure: the agent holds only a skill's name and description until a task actually calls for it, then loads the full instructions, then any bundled scripts or references. That is the whole trick, and it is also the whole reason skills belong in this series: they are a context engineering decision, ordering, compression, just-in-time loading, packaged as a folder.
Skills, MCP servers, and a longer system prompt all solve overlapping problems. This post draws the line between them, walks through building one, and covers the failure mode nobody writes about: a skill so vaguely described the agent never picks it.
Building specialized agents that need domain expertise on demand? We package AI agent capabilities as skills, MCP tools, or plain context, whichever costs the least tokens for the job, and ship the ones that actually get triggered.
Key Takeaways
- A skill is a folder with a required
SKILL.mdfile (name and description at minimum) plus optionalscripts/,references/, andassets/directories. - Progressive disclosure loads in three stages: discovery (metadata only), activation (full instructions), execution (bundled code or files). Most of a skill's content never enters context unless the task calls for it.
- Skills, MCP servers, and system prompts solve different problems. Skills package a repeatable procedure; MCP exposes live tools and data; a system prompt holds what every single turn needs.
- A skill with a vague description is a skill that never activates. The description is a routing decision, not documentation.
- The format was released by Anthropic as an open standard in October 2025 and has since been adopted across multiple agent products, not just Claude.
What is an agent skill, exactly?
An agent skill is a lightweight, open-format package, a folder holding a SKILL.md file plus optional scripts, reference documents, and templates, that gives an agent specialized knowledge or a repeatable workflow it loads only when relevant.
my-skill/
├── SKILL.md # required: name, description, instructions
├── scripts/ # optional: executable code
├── references/ # optional: deeper documentation
└── assets/ # optional: templates, static files
SKILL.md needs a name and description at minimum, the two fields the agent reads before deciding whether the skill is relevant at all, followed by the actual procedural instructions. Everything else in the folder is optional and stays unloaded until the instructions reference it.
How does progressive disclosure actually save context?
This is the part generic write-ups skip, and it is the reason this post exists on a site built around what context costs. Progressive disclosure loads a skill in three stages, and each stage costs a different number of tokens.
Discovery. At startup, the agent reads only the name and description of every available skill, a line or two each. An agent holding fifty skills pays for fifty short summaries, not fifty full procedures.
Activation. When a task matches a skill's description, the agent reads the full SKILL.md into its active context. This is where the real instructions land, and it happens only for the skill that matched, not the other forty-nine.
Execution. The agent follows the loaded instructions, optionally running bundled scripts or pulling in reference files, paying for those tokens only if the procedure actually needs them.
Skill, MCP server, or system prompt: which one do you need?
The three overlap enough to cause real confusion, and the official docs for each tend to explain their own mechanism without drawing the line to the other two.
A system prompt holds what every single turn genuinely needs, identity, constraints, tone. It is always in context, which is exactly why it should stay small. A skill holds a procedure the agent needs sometimes, not always, packaged so it costs nothing until the moment it matches. An MCP server holds live capability, current data, an action that changes external state, something no static file can provide because the answer is different every time it is called. The comparison post in this series works through when MCP earns its complexity against a plain API; the short version for skills is that MCP is for live access, skills are for repeatable know-how.
| System prompt | Skill | MCP server | |
|---|---|---|---|
| When it loads | Every turn, always | On demand, when matched | On demand, when a tool is called |
| What it holds | Identity, constraints, tone | A packaged procedure, plus optional scripts | Live data or actions on external systems |
| Cost shape | Fixed, paid every call | Paid once per activation | Paid per tool call, plus the round trip |
| Right for | What every task needs | A repeatable workflow with variable relevance | Anything that changes between calls |
| Wrong for | Anything task-specific | Live data that changes between runs | Static procedural knowledge |
A skill that calls an MCP tool mid-procedure is a common and correct pattern, not a conflict. The skill packages the "how"; the MCP server supplies the "what's true right now."
Building your first skill
Start from the structure, not the prose. A minimal SKILL.md:
---
name: pdf-form-filler
description: Fill and validate PDF form fields from structured data. Use when the user provides a PDF form and data to populate it with.
---
## Instructions
1. Read the PDF's form fields with the extraction script.
2. Map the provided data to matching field names.
3. Validate required fields are non-empty before writing.
4. Run `scripts/fill_form.py` with the mapped data.
5. Confirm the output PDF's fields match the input data.
The description is doing more work than it looks like it is. It is not a summary for a human reader, it is the routing signal the agent uses to decide, from a list of dozens, whether this skill is relevant to the current task. A vague one, "helps with PDFs", competes for attention with every other PDF-adjacent skill and often loses. A specific one, naming the exact action and the trigger condition, activates reliably because nothing else matches as precisely.
Activating and testing a skill correctly
Activation is not manual selection, it is the agent matching a task against every available skill's description and choosing the closest fit. That means testing a skill means testing the description, not just the instructions.
Run the target task with the skill installed and confirm three things: the skill activates on the phrasing you expect, it does not activate on adjacent tasks it should not claim, and the instructions execute correctly once loaded. The second check catches more real bugs than the first. A description broad enough to over-trigger pulls the wrong procedure into unrelated tasks, silently, because nothing errors, the agent just followed instructions that did not apply.
When a skill is just a README with ambitions
Not every packaged folder earns the name. The failure pattern is consistent: instructions written as prose explanation instead of executable steps, no way to verify the agent actually did the task correctly, and a description too generic to ever win the activation match. The result loads correctly and does nothing, because an agent reading paragraphs about a process is not the same as an agent following a checklist with a verification step at the end.
The fix is structural, not longer writing. Steps, not paragraphs. A verification step the agent can actually check, not "make sure it looks right." And a description specific enough that it activates for the task it was built for and stays silent for everything else.
Frequently asked questions
What are Claude skills?
Claude skills, more broadly called agent skills, are folders containing a SKILL.md file with metadata and instructions, plus optional scripts and reference files. Claude loads a skill's name and description at startup and only pulls the full instructions into context when a task matches, keeping many skills available at a small constant cost.
How do I properly activate a Claude Code skill?
Activation is automatic, not manual: the agent matches the current task against every available skill's description and loads the closest match. If a skill is not activating, the fix is almost always the description, make it specific about both the action and the trigger condition, rather than the instructions themselves.
How do I build a skill in Claude?
Create a folder with a SKILL.md file containing a name, a specific description, and numbered instructions. Add scripts/, references/, or assets/ only if the procedure needs executable code, deeper documentation, or templates. Test by running the target task and confirming the skill activates on the right phrasing and not on adjacent ones.
Are agent skills the same as MCP servers?
No. A skill packages a repeatable procedure that loads on demand; an MCP server exposes live tools and data that change between calls. A skill's steps can call an MCP server mid-procedure, which is a normal pattern, not overlap. Use MCP for anything that must be current at call time and skills for static, repeatable know-how.
What goes in a SKILL.md file?
At minimum, a name and a description, the two fields the agent uses to decide whether the skill matches a task before loading anything else. Below that, numbered instructions the agent follows once activated, plus optional references to bundled scripts, documentation, or templates in the same folder.
