Skills Delivered Over MCP: Why Progressive Disclosure Is the Missing Piece of Both Standards

Two standards showed up in the last year that most people file under different problems. Anthropic's Agent Skills gave us SKILL.md, a format for packaging what an agent should know. The Model Context Protocol gave us a wire format for what an agent can call. Skills are usually described as files on disk. MCP is usually described as servers on the network. They look like they solve unrelated things.

They do not. They solve two halves of the same thing, and the interesting move is to run one on top of the other. The thesis of this post is simple: the next useful shape is skills delivered over MCP, and the reason it works is that both standards are really about the same underlying idea. One of them just implements it and the other one forgot to.

The two halves

Start with what each standard is actually good at.

SKILL.md solved knowledge packaging. A skill is a folder with a markdown file that carries a name, a one-line description, and a body of instructions. The format's real contribution is not the file, it is the loading discipline around it, called progressive disclosure. Anthropic describes it as three stages: discovery, where the agent sees only each skill's name and description; activation, where a matching task pulls the full SKILL.md body into context; and execution, where the agent optionally reads bundled reference files or runs bundled scripts as the work demands. The point of the design is that the agent pays context cost in proportion to what the task needs. A hundred skills can sit in the catalog for the price of a hundred one-line descriptions, and the ten-thousand-word reference only loads when someone actually reaches for it.

MCP solved capability transport. A server publishes tools with typed inputs, any compliant harness discovers them, and calls them the same way regardless of who wrote the server. That uniformity is genuinely valuable. It is the reason a single harness can talk to a database, a calendar, and an image model without three bespoke integrations. But MCP's discovery model is flat. The classic pattern is tools/list, which returns every tool a server offers, each with its full JSON schema, all at once, before the agent has done anything. Connect a handful of rich servers and the tool definitions alone can run into tens of thousands of tokens sitting in context on every single request, most of it describing tools this particular task will never touch.

So one standard is disciplined about context and vague about transport, and the other is excellent at transport and profligate with context. That asymmetry is the whole opportunity.

The combination

Picture an MCP server whose tools are not a flat menu but a skill directory expressed as three tools:

• list_skills returns the cheap index. Names, one-line descriptions, nothing else. This is the discovery stage, delivered over the wire.
• get_skill takes a slug and returns that skill's body plus a manifest of its bundled files. This is activation.
• get_skill_file takes a slug and a path and returns one reference file on demand. This is execution.

That is progressive disclosure, rebuilt on MCP's transport. The agent pays for the index, then for one body, then for the specific files it needs, in exactly the escalating way it would if the skills lived on its own disk. The difference is that the skills no longer have to live on its own disk. They can be served from anywhere, versioned like an API, updated centrally, access-controlled, and shared across every agent and every machine that holds a key. You get the context economics of local skills with the distribution model of a web service.

The reason this is not a hack is that MCP already contains the primitive it needs. A tool can return a manifest of resources instead of a wall of content, and the agent can choose to fetch them. Nobody was forcing the flat tools/list dump. It was just the obvious first thing to build, the same way the obvious first thing to do with a new skill is to paste everything into one file.

Why this is where things are already heading

This is not a prediction so much as a reading of what has already shipped.

Skills themselves went multi-file. The public skills repository and the entries in Claude's own directory are not single files. They are folders with SKILL.md at the root and reference/, scripts/, and assets/ alongside it. Anthropic's guidance is explicit: when a SKILL.md gets unwieldy, split the detail into separate files and point at them, so rarely-used paths only cost tokens when they are actually taken. The moment a skill is a directory rather than a document, "serve it over a protocol" stops being exotic and becomes an obvious packaging question.

Anthropic ships an mcp-builder skill, which is a skill about building MCP servers. The two standards are already being composed in the official tooling; the vocabulary of one is used to teach the other. Anthropic's own framing puts it well: MCP is the professional kitchen with the equipment and ingredients, and skills are the recipes. Recipes are worth distributing, and the kitchen is how you distribute them.

And the harness makers are converging on the same context discipline from the tools side. Look at how modern agent harnesses handle large tool sets: instead of loading every tool schema up front, they expose a search or deferred-loading step. The agent gets a lightweight list of tool names, then fetches the full schema for a tool only when it decides to use it. That is progressive disclosure applied to tools rather than to knowledge. It is the exact same idea arriving from the opposite direction. When both the skill people and the tool people independently rediscover "show the index first, load the body on demand," that is not a coincidence. That is the shape of the problem.

What we built

We run this on our own site. developersdigest.tech exposes an MCP endpoint at /api/mcp, served over streamable HTTP, authenticated with a dd_live_ API key sent as a bearer token. Point any MCP-capable harness at the URL, give it the key, and the tool suite shows up. The connection story has its own write-up in Point Your Agent at Developers Digest; this post is about the shape of the library tools specifically.

The skill library is exposed exactly as the pattern above. The catalog you can browse by hand at /library is the same catalog an agent reaches through the tools. list_skills returns the index, get_skill returns a body plus manifest, and files come down individually. A discovery call looks like this:

{
  "method": "tools/call",
  "params": {
    "name": "list_skills",
    "arguments": { "query": "changelog" }
  }
}

and comes back as a lean index, one line per skill, no bodies:

{
  "skills": [
    {
      "slug": "release-notes",
      "description": "Turn a merged PR list into customer-facing release notes."
    }
  ]
}

Only when the agent commits to a skill does it spend context on the body:

{
  "method": "tools/call",
  "params": {
    "name": "get_skill",
    "arguments": { "slug": "release-notes" }
  }
}

which returns the full SKILL.md ready to save to .claude/skills/release-notes/SKILL.md, plus a manifest naming the reference files the agent can pull later with get_skill_file. The full endpoint reference lives at /docs/api. The design goal was that a skill authored for the disk and a skill served over the wire are the same artifact. You should be able to move one to the other without rewriting it.

How to write a SKILL.md that survives this

The pattern only pays off if the skills are authored for it. A good SKILL.md over MCP looks like a good SKILL.md on disk, because the loading model is identical. Three habits matter.

Write the description like it is the only thing the agent will read, because at discovery time it is. It should say when to reach for this skill, in the user's words, not what the skill contains in yours. "Use when generating customer-facing release notes from merged PRs" beats "Release notes utilities."

Keep the body lean and make it point outward with when-to-read guidance. Do not inline the full API table or the edge-case catalog. Reference the file and tell the agent the condition under which it should open it: "For the full field-by-field schema, read reference/fields.md only when a field is ambiguous." The agent then loads depth on the specific branch it took, not on all of them.

Split mutually exclusive paths into separate files. If the skill handles three formats and any given run touches one, three files cost less than one file, because the agent pulls only the branch it is on.

The anti-patterns are the mirror image. Do not dump every reference file into one get_skill response; that throws away the entire benefit and turns activation back into the flat dump you were trying to escape. And do not build the fifty-tool flat server, where every schema loads before the agent has decided anything. Fifty tools behind a three-tool skill directory is almost always the better trade.

What this means for teams

Follow this one step past the public catalog and you arrive somewhere useful. A private skill server becomes the internal wiki for your agents. Not a wiki humans read and agents ignore, but a versioned, access-controlled library that every agent in the org discovers the same way, loads on demand, and never has to have copied onto its disk. Your deployment runbook, your incident-response steps, your house style for commit messages, your API conventions, each is a skill, each is one row in an index until the moment an agent needs it, each updated in one place. When you fix the runbook, every agent has the fix on its next get_skill call. No redeploy, no re-paste, no drift between what the fleet knows and what is true.

That is the version of this I care about, because it is what makes a fleet coherent. When we ran a fleet of agents for a day to rebuild this site, the thing that held the day together was shared, verifiable context that every agent could reach on the same terms. Skills over MCP is the standardized, distributable form of exactly that. Two standards each solved one half. The combination is the interesting part, and it is already being built in the open, one manifest at a time.

FAQ

What is the difference between an Agent Skill and an MCP tool? An Agent Skill is packaged knowledge: a SKILL.md file with instructions, plus optional reference files and scripts, loaded through progressive disclosure. An MCP tool is a callable capability with a typed input schema, exposed by a server over a wire protocol. Skills tell an agent how to do something; tools let it act. They compose cleanly, and you can even deliver skills through MCP tools, which is the pattern this post is about.

What is progressive disclosure in this context? It is loading information in stages so the agent pays context cost only for what a task actually needs. First the agent sees short descriptions, then it pulls the full body of the one skill it chose, then it reads specific reference files on demand. It keeps a large library cheap to hold in context, because most of it stays unread until the moment it is relevant.

Why not just list every tool with MCP's standard discovery? Flat discovery returns every tool's full schema up front, which can consume tens of thousands of tokens per request describing tools the current task will never call. Expressing a large capability set as a small skill directory, index first and bodies on demand, gives you the same reach at a fraction of the standing context cost.

Can I use this pattern with harnesses other than Claude Code? Yes. The point of MCP is that any compliant client discovers and calls tools the same way, so a skill directory exposed as list_skills, get_skill, and get_skill_file works from any MCP-capable harness. The skills themselves are plain SKILL.md markdown, which is an open format, so nothing about the pattern is tied to a single client.

How do I try the one running on this site? Point an MCP-capable harness at the /api/mcp endpoint with a dd_live_ API key, then call the library tools. You can browse the same skill catalog by hand at /library, and the full endpoint reference is at /docs/api.