MCP and Agent Skills solve different problems. The Model Context Protocol connects an agent to outside systems: an MCP server exposes tools, data and prompt templates, and the agent calls them. An Agent Skill is a folder with a SKILL.md file of instructions, plus optional scripts and reference files, that teaches the agent how to carry out a particular kind of work. Claude Code's documentation puts it in one line: MCP connects Claude to external services, and skills extend what Claude knows, including how to use those services well.
Most real setups use both: MCP for access, a skill for the procedure, and a hook for any rule that must hold every single time. Since SEP-2640 reached final status in 2026, MCP servers can also distribute skills through the protocol itself. In production, the part that decides success is how a skill gets activated, because the model picks it by reading its description, and that choice needs testing in both directions.
Here is the case we use in our harness playbook. A support team has a twelve-page procedure for investigating duplicate charges, and an engineer turns it into a skill. It tells the agent which records to fetch, how to tell a duplicate capture from a renewal, what evidence to keep, and when to escalate.
The demo is excellent. The agent stops improvising billing logic and produces cleaner investigation packets.
Then three things happen. A chargeback case uses the phrase "charged twice", so the skill activates on a case that a different legal process owns. The policy reference inside the skill is one version behind the policy service. And a helper script asks for the general payments credential, because that was the easiest way to make the example work.
The instructions were sensible, and the deployment was unsafe anyway. The difference between those two sentences is most of what this comparison is about.
What MCP is in 2026
MCP is a protocol between a host application, such as Claude Code, and servers that offer capabilities. The specification defines three things a server can offer: tools, which are functions the model can execute; resources, which are context and data; and prompts, which are templated messages and workflows for users.
The current revision, dated 28 July 2026, made the protocol stateless. The connection handshake is gone, every request carries its own protocol version and client capabilities, and a new server/discover call lets a client ask a server what it supports. For people running servers, there is no longer a protocol session to keep pinned to one machine.
The specification is direct about risk. It says tools represent arbitrary code execution and must be treated with caution. Tool descriptions should be considered untrusted unless they come from a trusted server, and hosts must get explicit user consent before invoking a tool. Our MCP security checklist turns that into controls.
In Claude Code, MCP is cheap until it is used. The context table in its documentation shows that only tool names load at session start, with full schemas fetched on demand through tool search.
What an Agent Skill is
Anthropic released Agent Skills as an open standard in December 2025, with the specification at agentskills.io. A skill is a directory with one required file, SKILL.md, whose frontmatter carries a name and a description, followed by the instructions themselves.
refund-investigation/
SKILL.md # required: frontmatter + instructions
scripts/ # optional: code the agent can run
references/ # optional: docs loaded when needed
assets/ # optional: templates, data files---
name: refund-investigation
description: Investigate a suspected duplicate card
charge on a single order. Use when a customer
reports being charged twice for the same order.
Do not use for chargebacks or disputed renewals.
---
1. Fetch the order and every capture for it.
2. Compare capture IDs, amounts and timestamps.
...The specification sets hard limits on the frontmatter. The name is at most 64 characters of lowercase letters, numbers and hyphens, and must match the folder name. The description is at most 1,024 characters and has to say what the skill does and when to use it.
Loading happens in three stages, which the standard calls progressive disclosure. The name and description, around 100 tokens per skill, load at startup for every installed skill. The body, recommended to stay under 5,000 tokens and 500 lines, loads when the skill activates. Scripts and reference files load only when the instructions call for them.
Agent Skills vs MCP, side by side
| MCP | Agent Skill | |
|---|---|---|
| What it carries | access to a system: tools, data, prompts | a procedure: instructions, references, scripts |
| Form | a protocol between a host and a server | a folder with a SKILL.md file |
| Where the code runs | on the server, wherever it is hosted | bundled scripts run where the agent runs |
| How it gets used | the model calls a tool | the model matches the description, or you invoke it by name |
| Context cost in Claude Code | tool names at start, schemas when used | description on every request, body when used |
| Typical examples | Slack, a database, a browser | a review checklist, a deploy procedure, an API style guide |
| Typical failure | a poisoned or over-privileged tool | activating on the wrong task, or missing the right one |
The last row is where the two really differ. An MCP failure usually involves what a tool is allowed to do. A skill failure usually involves when it decides to apply, which is a quieter problem and much easier to ship without noticing.
Most setups need both, plus a hook
Claude Code's documentation has a tidy example. A Slack MCP server gives the agent the ability to post messages, and a /post-to-slack skill carries your team's formatting rules, so the server supplies access and the skill supplies judgement about using it.
The third mechanism is the one people forget. The same documentation says an instruction like "never edit .env" in a skill or in CLAUDE.md is a request, and that a PreToolUse hook that blocks the edit is enforcement. Anything that must hold every time belongs in a hook, because a skill is read and interpreted by the model and its outcome can vary.
| What you need | Use |
|---|---|
| Read or write data in another system | an MCP server |
| A repeatable way of doing a task, with judgement in it | a skill |
| Both of the above for the same service | an MCP server plus a skill about using it |
| A rule that must never be broken | a hook, or a permission in the tool itself |
| A deterministic action after an event, such as formatting on save | a hook |
Skills are also, quite literally, text files. That is a large part of their appeal. The same argument we made about companies in A Company in 2030 Might Run on Text Files applies to agents, which read procedures far better than they read dashboards.
Skills now travel over MCP too
The two standards have started to meet. SEP-2640, created in April 2026 and now final, defines an official MCP extension, io.modelcontextprotocol/skills, that lets a server publish skills alongside its tools.
A server that supports it declares the extension, answers skills/list and skills/get, and serves the files through the existing resources mechanism, with addresses such as skill://acme/billing/refunds/SKILL.md. The skills follow the agentskills.io format, so the content is identical whichever way it arrives.
Two details in the extension matter for safety. Reading a SKILL.md over MCP does not activate it: the host routes it through its own skill-loading path, which verifies the content and applies any required user approval. And host support is still being implemented, so check your client before designing around it.
The practical effect is that the team that owns a service can ship the procedure for using it with the server itself. The billing team publishes the billing tools and the refund skill together, versioned together, which goes a long way toward preventing the stale policy reference from the opening case.
The model chooses the skill, and that is the risk
Ordinary software calls a function by a name the programmer chose. Skill-enabled agents work differently: the host shows the model a list of names and descriptions, the model interprets the task, and a skill is either loaded or ignored.
That makes the description part of the behaviour. Widening "duplicate card charges" to "all billing problems" changes which tasks the skill touches before anyone has read a line of the body. So does a name that collides with a trusted internal skill, or a description written to sound more urgent than its neighbours.
This is measurable. A May 2026 preprint on a public skill registry found that changes confined to SKILL.md text could manipulate which skills were surfaced and selected, with short text triggers reaching up to an 86% pairwise win rate in discovery. The exact numbers belong to that registry and setup. The lesson travels: review a description change the way you review a code change.
Progressive disclosure saves context, and it is easy to mistake for a safety control. A compact skill can still ask for a destructive tool, and a reference file loaded on demand can still contain an injected instruction. The standard's allowed-tools field is marked experimental, with support varying between agents, so permissions belong in the host's configuration and in the tools themselves.
Test activation in both directions
A skill that never activates is useless, and one that activates on the wrong task is dangerous. The agentskills.io guide on optimising descriptions gives a workable method: about 20 realistic prompts, half that should trigger the skill and half that should not.
The negative half is where the value is. The guide recommends near misses, prompts that share words with the skill and need something else, which is exactly the chargeback case from the opening. Because model behaviour varies between runs, it suggests running each prompt three times and counting a prompt as triggered when it activates the skill in more than half of the runs.
[
{"q": "Customer says order 4471 was charged twice",
"should": true},
{"q": "Two identical captures on one invoice, check",
"should": true},
{"q": "Chargeback filed: customer was charged twice",
"should": false},
{"q": "Annual renewal charged again, customer upset",
"should": false}
]Record whether the skill loaded on each run, from your agent's logs or transcript, and score the set with a few lines of plain Python.
import json
def score(cases, runs, threshold=0.5):
"""runs maps each query to a list of booleans:
did the skill load on that run?"""
tp = fp = fn = tn = 0
for c in cases:
r = runs[c["q"]]
hit = sum(r) / len(r) > threshold
if c["should"] and hit: tp += 1
elif c["should"]: fn += 1
elif hit: fp += 1
else: tn += 1
return {"missed": fn, "false_activations": fp,
"recall": tp / max(tp + fn, 1)}
cases = json.load(open("activation_cases.json"))
runs = json.load(open("activation_runs.json"))
print(score(cases, runs))Report false activations separately from recall, because they trade against each other. A broad description raises recall and false activations together. For a formatting skill that is a fair trade; for a skill that influences payments or a legal response, a single false activation on a near miss should block the release.
More skills can make the agent worse
Curated skills genuinely help. SkillsBench, in its latest version, ran 87 tasks across 18 model and harness configurations. Curated skills raised the average pass rate from 33.9% to 50.5%, with gains between 4.1 and 25.7 points depending on the configuration.
The same study found that focused skills with at most three modules beat larger or exhaustive bundles. Claude Code's documentation makes the related practical point that every added feature consumes context and adds noise, so skills may stop triggering correctly as the set grows.
So treat the catalogue as something with a carrying cost. Every installed skill adds a description to every request, a chance of colliding with a neighbour, and an owner who has to keep it current. In Claude Code, disable-model-invocation: true keeps a skill's description out of context entirely, so it runs only when someone invokes it by name, which suits procedures that should never start on their own.
A few budgets keep this honest: a cap on discoverable skills per task area, a rule that two skills with overlapping descriptions cannot both be enabled until someone decides which wins, and zero skills without a named owner.
Ship a skill like a release
The fix for the opening case was never a better prompt. It was treating the skill as a small piece of software, with an owner, a version, a declared scope, tests and a way to withdraw it. We keep that in a release file next to SKILL.md. This is our own convention, outside the standard, and the standard's free-form metadata field can carry the same keys if you prefer one file.
skill: refund-investigation
version: 4.2.0
owner: payments-support
activates_on: duplicate capture, one order
never_on: [chargeback, disputed renewal]
requires:
mcp: [[email protected]]
policy: refund-policy@2026-10
tools_requested: [billing.read]
tests:
activation: activation_cases.json
false_activation_max: 0
review: metadata changes need owner approval
retire_when: billing@3 shipsEach line answers a question someone will eventually ask in an incident. Who owns this, which policy version did it assume, which tools did it need, what was it qualified on, and what replaces it.
Three neighbours to this piece. What a harness is places skills, tools and hooks inside the system around the model. The MCP security checklist covers the access side. And Claude Code with Ollama shows why context budgets get tight fast when the model runs on your own machine.
What I'd do
Start from the procedure, then pick the mechanism. Put access in MCP servers with the narrowest permissions that work. Put the way your team does a task in a skill, with a description that names both when to use it and when to leave it alone. Put every rule that must never break in a hook or a tool permission. Before any skill reaches other people, write ten prompts that should trigger it and ten near misses that should not, run them three times each, and keep the file with the skill so the next description change gets the same test. The procedures themselves are the asset here, and we teach operators to keep them as a living document in their AI Operating System before any agent touches them. If you are building agents that use MCP in production, Engineering Foundations covers tool use through MCP and evaluation-first development, and the Engineering Series carries it through to governance and reliability.
FAQ
What is the difference between Agent Skills and MCP?
MCP is a protocol that connects an agent to external systems through servers that offer tools, data and prompts. An Agent Skill is a folder with a SKILL.md file that teaches the agent how to do a task, with optional scripts and references. MCP gives the agent access, and a skill gives it a procedure for using that access well.
Should I use Agent Skills or MCP?
Use MCP when the agent needs to read or change data in another system, and a skill when it needs a repeatable way of doing a task. Many setups use both for the same service, and any rule that must hold every time belongs in a hook or a tool permission instead of either.
Can Agent Skills replace MCP?
Partly. A skill can bundle a script that calls an API directly, which works for simple cases, but authentication, permissions and auditing then live inside a script on the agent's machine. MCP keeps the connection and its credentials in a server that can be secured, shared and monitored on its own.
Can MCP servers provide skills?
Yes. SEP-2640 defines the official io.modelcontextprotocol/skills extension, now final, which lets a server list skills and serve their files through MCP resources in the agentskills.io format. Host support is still being rolled out, so check your client.
How do Agent Skills load into the context window?
In three stages. Each skill's name and description, around 100 tokens, load at startup; the SKILL.md body, recommended under 5,000 tokens, loads when the skill activates; scripts and reference files load only when the instructions call for them.
Are Agent Skills safe to install?
Treat them like code from the same source. A skill can run scripts, request tools and change which tasks the agent applies it to through its description alone, and research on public skill registries has shown description-only manipulation of discovery and selection. Review the description as carefully as the scripts, and install from sources you would trust with code.
The duplicate-charge skill in the opening was good writing that had never been treated as software. Version it, test when it fires and when it stays quiet, and let a hook hold the line on anything that matters.
MCP gives an agent reach. A skill gives it a way of working, and that way of working deserves an owner.
Charafeddine MouzouniOctober 31, 2026
