AI
Agent Skills Explained: The Other Half of the MCP Ecosystem Developers Are Missing
Agent Skills are SKILL.md folders that teach agents how your team works. How they differ from MCP, why progressive disclosure saves context, how to write one.
Agent Skills are folders containing a SKILL.md file — YAML frontmatter with a name and description, plus Markdown instructions and optional scripts — that teach an AI agent to perform a task the way your organisation wants it done. MCP and Agent Skills solve different problems: MCP is the pipe giving an agent access to your systems, Skills are the instructions giving it judgment once connected. They are complementary layers, not competing choices.
An MCP server exposes your Jira, your repo, your Postgres instance to an agent. Now watch it get the job wrong anyway: it opens a pull request, breaks your title convention, skips the rollback plan your team requires on anything touching payments. Every tool call succeeded. The agent had no idea how you work. That gap is what Skills fill.
What are Agent Skills, and how are they different from MCP?
Agent Skills are a lightweight, open format for packaging procedural knowledge that an AI agent loads on demand: a directory containing a required SKILL.md file, plus optional scripts/, references/ and assets/. The Model Context Protocol (MCP) is a separate open standard connecting agents to external systems. Skills describe procedure; MCP provides connectivity.
| Dimension | MCP | Agent Skills |
|---|---|---|
| Provides | Access to external systems | Procedural knowledge |
| Unit | A server exposing tools | A folder with SKILL.md |
| Idle context cost | Tool definitions stay loaded | ~100 tokens per Skill |
The analogy holds at the mechanism level: an MCP server is a running process speaking a wire protocol, a Skill is a Markdown file on disk. The connectivity layer has its own mechanics, covered in our companion piece on how MCP works under the hood.
How do Agent Skills work, and what is progressive disclosure?
Progressive disclosure is the mechanism by which an agent loads a Skill in three stages instead of all at once: at startup only each Skill’s name and description enter the context window (~100 tokens per Skill); when a task matches that description the agent reads the full SKILL.md body into context (recommended under 5,000 tokens); bundled files and scripts load only if the task actually requires them. Unused content costs nothing. The specification defines those three stages — discovery, activation, execution — but leaves the loading mechanism to each implementation.
| Level | What loads | When | Token cost |
|---|---|---|---|
| 1 — Metadata | name and description | Always, at startup | ~100 tokens per Skill |
| 2 — Instructions | The SKILL.md body | When a request matches the description | Under 5k tokens |
| 3 — Resources | Files in references/, scripts/ | Only when the task needs them | Nothing until accessed |
Level 3 carries the detail most explainers omit. Reference files load when read. Scripts do not. When the agent executes validate_pr.py, the source never enters the context window — only the output, so a 400-line script costs the twelve tokens of “Validation passed: 0 errors”. That asymmetry is a design instruction: anything deterministic and verbose belongs in a script, anything needing judgment belongs in the Markdown.
Why this matters: the context window is a budget, not a container
Every token competes with the actual task — cost on each turn of an agent loop, latency, and, least appreciated, accuracy: an agent reasoning over forty irrelevant tool definitions has a harder retrieval problem than one holding only what it needs. Because unused Skill content is free, fifty Skills cost roughly five thousand tokens at startup rather than fifty full instruction sets. Anthropic’s engineering write-up calls the context bundled into a skill “effectively unbounded.”
The trade-off: discovery depends entirely on the description. If it does not say when to use the Skill, in words resembling how a request gets phrased, the agent never triggers it — the Skill sits on disk, costs a hundred tokens, and never fires. That failure mode is a writing problem, not a code problem.
Can Agent Skills and MCP be used together?
Yes — in production they are normally used together, because they sit at different layers. A Skill can hold a workflow orchestrating calls to several MCP servers: MCP supplies the connection, the Skill supplies the sequence and the decision rules.
The “Skills or MCP” framing is the most common error here: Skills do not replace MCP, and MCP is not obsolete. Anthropic’s engineering documentation states that “Skills can complement Model Context Protocol (MCP) servers by teaching agents more complex workflows that involve external tools and software.” The governance record agrees: Anthropic donated MCP to the Linux Foundation’s Agentic AI Foundation on 9 December 2025 and published Agent Skills as an open standard nine days later.
Remove the Skill and the agent still has every tool, and works like a competent stranger; remove MCP and it knows your conventions exactly and cannot reach the repo. Where a runtime exposes MCP capability directly to application code, the picture changes again — our piece on native MCP bindings covers that pattern.
What is a real example of an Agent Skill that MCP alone could not handle?
An Agent Skill encodes how your organisation does something — a code-review standard, an API deprecation policy. An MCP server cannot supply this: it exposes capability rather than convention, letting an agent read a diff and post a comment while holding no opinion about what counts as a blocking finding. For a deprecation policy, MCP gives the agent the repo, the gateway’s traffic data and Jira — all real capability, none of it policy.
The illustrative SKILL.md below is my own worked example, not a quotation from vendor documentation or a real company’s repository:
---
name: api-deprecation
description: Applies the internal API deprecation policy when removing or
deprecating an HTTP endpoint in a Java or Node service. Use when a task
mentions deprecating, sunsetting or removing an API endpoint.
---
# API deprecation policy
## Before anything else
1. Get 30-day traffic for the endpoint from the gateway.
2. If external consumer traffic exceeds 1,000 req/day, STOP. Ask for
platform-team sign-off before proceeding. Do not open a PR.
## Required code changes
- Add a `Sunset` response header (RFC 8594 format).
- Annotate the handler: `@Deprecated` (Java) or JSDoc `@deprecated` (Node).
- Do NOT delete the handler. Removal happens two minor releases later.
## Required artifacts
- Jira ticket, `API-DEPRECATION` type, due date = sunset date.
- Migration note. See references/catalogue-format.md for fields.Three things there explain the Skills layer. The stop condition: no MCP tool exposes “our organisation requires sign-off above this threshold”. The negative instruction: Do NOT delete the handler suppresses what a competent agent does by default, and a tool schema has nowhere to say it. The deferred detail: references/catalogue-format.md loads only if the task reaches it.
Do developers need to learn to write Agent Skills?
Writing Agent Skills is a developer-level task, not a platform-team-only feature. In Claude Code a Skill is a directory at ~/.claude/skills/<name>/, or .claude/skills/<name>/ in a repo to share with your team — no upload, no API call, no admin involvement. The barrier is a Markdown file with two frontmatter fields.
Write them yourself when you own a service whose conventions the org keeps getting wrong; leave organisation-wide policy to a platform team. The security guidance is blunt — a Skill can direct an agent to execute code in ways that do not match its stated purpose, so use trusted sources only.
The skill behind the Skill is technical writing: whether an agent triggers it depends entirely on whether the description matches how requests are phrased. One caveat on portability: the core format is standardised, but allowed-tools is experimental and Claude Code adds fields outside the spec. Runtimes differ too — on the Claude API, Skills run sandboxed with no network access; in Claude Code they have the same access as any program on your machine. Our guide to AI skills for software engineers covers the wider picture.
Where this leaves your stack
Two layers, one system. MCP standardises how an agent reaches your tools; Skills standardise how it behaves once there. Both are open standards under multi-vendor governance, so the question is not which to adopt — it is which of your conventions exist only in people’s heads. Correct an agent the same way twice and that correction was a Skill you had not written.
Frequently asked questions
What are Agent Skills and how are they different from MCP?
Agent Skills are folders containing a SKILL.md file — YAML frontmatter with a required name and description, plus Markdown instructions and optional scripts and reference files — that give an AI agent procedural knowledge about how to perform a task. The Model Context Protocol (MCP) is a separate open standard that connects agents to external systems and tools. The difference is layer, not quality: MCP gives an agent access to your repo, database or ticketing system, while an Agent Skill tells it how your organisation wants that access used. Anthropic’s framing is that MCP connects Claude to data while Skills teach Claude what to do with that data.
What is progressive disclosure in Agent Skills?
Progressive disclosure is the three-stage loading mechanism Agent Skills use to limit context window consumption. At startup, only each Skill’s name and description load into context, costing roughly 100 tokens per Skill. When a request matches a Skill’s description, the agent reads the full SKILL.md body, recommended to stay under 5,000 tokens. Bundled reference files and scripts load only if the task needs them, and script source code never enters context at all — only the script’s output does. Unused Skill content costs nothing, so the expertise bundled into a Skill is effectively unbounded.
Can Agent Skills and MCP be used together?
Yes. Agent Skills and MCP are complementary layers and are normally used together in production agentic systems. A Skill can define a multi-step workflow that orchestrates calls to one or more MCP servers: MCP supplies the connection to systems like GitHub, Jira or a database, and the Skill supplies the sequence, standards and decision rules governing those calls. Anthropic’s engineering documentation states that Skills complement MCP servers by teaching agents more complex workflows involving external tools. Skills do not replace MCP, and MCP is not made obsolete by Skills.
What is an example of an Agent Skill that MCP alone could not handle?
An internal API deprecation policy is a clear example. MCP servers can give an agent access to the repository, the API gateway’s traffic data and the Jira instance, but they encode no opinion about policy — that deprecation requires two minor releases of overlap, that a Sunset header is mandatory, that endpoints above a traffic threshold need platform-team sign-off before the clock starts, or that the deprecated handler must not be deleted yet. Those rules are organisational convention, and an Agent Skill is where they are written down so the agent applies them consistently.
Do developers need to learn how to write Agent Skills?
Writing Agent Skills is a developer-level task rather than a platform-only feature. In Claude Code a Skill is a directory at ~/.claude/skills/ for personal use or .claude/skills/ inside a repository to share with a team, requiring no upload or admin involvement. Writing one means writing a Markdown file with two required YAML frontmatter fields, name and description, so the real competence involved is technical writing: whether the agent triggers the Skill depends entirely on how clearly the description states when it applies. Organisation-wide Skills with security or compliance implications are better owned by a platform team, since a Skill can direct an agent to execute code and should be audited like any dependency.