experimental-ext-skills: Teaching MCP Servers to Ship the Manual
How the Skills Over MCP group is trying to make workflow instructions discoverable, portable, and light enough for agents to actually use.
- experimental-ext-skills argues that the missing layer in agent systems is not more tools, but a better way to ship the manual that explains how to use them.
- The repo’s hardest problem is discovery, because a skill can exist and still be ignored unless the server nudges the agent to read it first.
- Its design bias is pragmatic: reuse MCP resources and conventions before inventing a new protocol surface.
- Progressive disclosure is the real technical insight, because it keeps instruction sets small enough to survive long conversations.
The server has the tool. Why doesn’t the agent know the manual?
That is the odd little failure mode this repo is built around. MCP already gives an agent tools, but a tool description only says what exists, not how to chain those pieces into a useful workflow. The experimental findings in experimental findings are blunt about it: a skill can be present, correct, and still invisible unless the server explicitly points the model at it.
MCP servers give agents tools, but tools alone are insufficient for complex workflows — tool descriptions tell an agent what a tool does, not how to orchestrate multiple tools to achieve a goal. Skills bridge this gap.
Why the Skills Over MCP group exists
This repository is not an official spec, and that matters. It is an incubation space for the Skills Over MCP Interest Group, which is trying to answer a narrower question than most people expect: how should a server distribute the know-how that makes its tools actually usable? The repo stays honest about scope. It is for requirements gathering, pattern exploration, and proof-of-concepts, not for approving spec changes or mandating client behavior.
This Interest Group explores how "agent skills" (rich, structured instructions for agent workflows) can be discovered and consumed through MCP.
That framing makes the project feel less like a product and more like a standards lab. The interesting part is not the logo, the stars, or the repo count. It is the fact that several working groups are trying to agree on a way to distribute instructions without turning the protocol into a junk drawer.
The core idea: skills as context, not plugins
The repo’s philosophical move is simple and sharp. A skill is structured Markdown that tells an agent how to do a job, and MCP is used as the transport layer for that knowledge. In other words, the server does not just expose callable things. It ships the manual alongside them, and the manual can live as a resource the client reads on demand.
Why the group is leaning on resources and conventions
The repo spends real time weighing three paths. One is a first-class protocol primitive for skills. Another is registry metadata. The path it seems to prefer is the least glamorous one: treat skills as MCP resources, give them a `skill://` convention, and let existing client behavior do the rest. That choice reads as caution, but it is also a bet on ecosystem simplicity. Every new primitive increases the surface area that servers, clients, registries, and tutorials have to keep in sync.
| Approach | Discovery method | Update path | Context cost | Server author burden | Best fit |
|---|---|---|---|---|---|
| Tool-only server | The agent sees tools, but not the workflow manual. | Tool descriptions and prompts change separately. | Low at first, high in practice when the agent wanders. | Low, because there is no skill layer to maintain. | Simple one-step actions. |
| Skills as `skill://` resources | The server points the agent at a readable skill resource. | Update the resource with the server, ship one connection, and keep versions together. | Medium, but controllable with progressive disclosure. | Moderate, because the author writes structured Markdown and resource wiring. | Multi-step orchestration without protocol bloat. |
| First-class skills primitive | The protocol defines dedicated skill methods and objects. | Protocol and client implementations must evolve together. | Potentially efficient, but only if everyone adopts it. | High, because spec and implementation work both increase. | A future ecosystem that wants skills as a core native concept. |
The table is the real argument. The repo is not trying to win a purity contest. It is trying to keep the model of distribution small enough that people will actually ship it.
What the experiments revealed
The experiment log is where this repo stops sounding theoretical. One finding is context decay. Even when an agent reads a good skill, it can drift as the conversation grows, which is why the group keeps returning to progressive disclosure. Smaller chunks, loaded only when a branch is hit, are easier for the model to retain than a giant one-shot manual.
Another finding is that atomic distribution simplifies the whole stack. If the server, the skill, and the metadata travel together, you avoid the awkward coordination tax of separate repositories and separate release cycles. That is the quiet appeal of the `skill://` approach. It makes the skill ephemeral, addressable, and tightly coupled to the thing it teaches.
That is also why this repo feels pragmatic rather than ideological. It is not saying standards should never grow. It is saying the first useful answer may be a convention that makes the right behavior easy to discover and cheap to maintain.
What this means for the MCP ecosystem
The broader bet is that ecosystems do not need to standardize every layer at once. MCP already standardized how a server says, "I have tools." This repo is trying to standardize how a server says, "Here is the manual for using them." If that works, the win is not a new category of object. The win is a workflow that feels native without making the protocol heavier than it needs to be.
That is a good place to stop. The repo’s most interesting contribution is not a finished spec. It is a discipline: keep the manual close to the machine, make it discoverable, and only load as much as the conversation can carry.