Skills Over MCP

* Angie Jones VP of Developer Experience, Agentic AI Foundation ---------------------------------------- I’m a big fan and user of both MCP and Agent Skills, so when I learned there’s a Skills Over MCP working group (WG) that’s looking into integrating Skills with MCP, I had no choice but to lurk. THE PROBLEM Think about any product you’ve ever used… software or not. Most come with some sort of instruction manual that helps you figure out how to use it. For developer products, that’s usually in the form of docs, tutorials, examples, and maybe troubleshooting guides. Companies that do this well are often praised for their attention to Developer Experience. But now we’re asking our agents to become users of products on our behalf. We give them an MCP server that essentially provides a list of tool names and descriptions and expect them to figure it out without flailing or messing up. This is horrible Agent Experience. So, the working group is exploring how to go about providing instructional content to agents alongside related MCP servers. Of course, Skills already solve the problem of teaching an agent how to do something in a way that avoids context bloat. The standard utilizes progressive disclosure techniques to help the agent find a given skill when it needs it without filling the context window with all of the nitty gritty details when it doesn’t. This immediately made me think back to when the Playwright CLI dropped earlier this year. The CLI itself was hot, but the team also shipped a Playwright CLI skill. If you installed the CLI and the skill, your agent now had everything it needed to nail tasks without guessing about the shape and structure of the CLI’s commands and arguments. Which was amazing considering this was a brand new product and thus not in the LLM’s training data. This makes a very happy agent and therefore a very happy human as there are quicker sessions, fewer errors, and lower token spend. But there still remained a bit of separation. The CLI and the skill need to be installed and maintained separately, as they are two different things. This isn’t exactly shipping the manual with the product. So, the premise that the Skills Over MCP WG is exploring is what if we found a way to ship MCP servers with accompanying skills. That should give the agent the tools it needs to execute but also the operational knowledge it needs to do it efficiently. Essentially, ship the manual with the product. THE PROPOSED SOLUTION As opposed to adding yet another primitive to the protocol (which the WG did consider originally), they are looking to expose Skills as content through the existing Resources primitive. Resources are read-only pieces of data that lets the agents connect to external documents, databases, etc. They are essentially a read-only book that the agent can use to learn new facts. So, perfect for Skills! The proposal is SEP-2640: Skills Extension with extension identifier: io.modelcontextprotocol/skills Given the shape of a Skill: my-skill/ ├── SKILL.md ├── scripts/ │ └── helper.py ├── references/ │ └── workflow.md ├── assets/ │ └── template.md └── examples/ └── example.md That Skill package could be served as a collection of resources using a skill:// URI scheme. skill://my-skill/SKILL.md skill://my-skill/scripts/helper.py skill://my-skill/references/workflow.md skill://my-skill/assets/template.md skill://my-skill/examples/example.md The great thing about this approach is that MCP doesn’t need to understand what a skill is. As far as the protocol is concerned, these are just resources. The skill format itself remains owned by the Agent Skills specification. A server isn’t limited to exposing a single skill. It might expose dozens (or even hundreds) of them. For example, the Stripe MCP server could easily bundle the following skills skill://subscription-management/SKILL.md skill://refund-processing/SKILL.md skill://payment-disputes/SKILL.md skill://billing-investigation/SKILL.md That immediately creates a discovery problem. We don’t want the agent reading every skill from every connected server just to figure out what’s available. To solve that, the proposal defines a well-known resource as the server’s optional skill catalog: skill://index.json Rather than loading every SKILL.md, a host can read the index file and get lightweight metadata (e.g. name, description, location) about the available skills. This respects the discovery technique introduced by the Agent Skills spec. { "skills": [ { "url": "skill://refund-processing/SKILL.md", "frontmatter": { "name": "refund-processing", "description": "Use this skill when issuing refunds, handling partial refunds, or investigating refund status." } }, { "url": "skill://payment-disputes/SKILL.md", "frontmatter": { "name": "payment-disputes", "description": "Use this skill when investigating chargebacks, gathering evidence, or responding to disputes." } } ] } Then for servers with even more skills, they can use a template as opposed to listing every single skill: { "type": "mcp-resource-template", "description": "Stripe product area skill", "url": "skill://stripe/{product_area}/{skill_name}/SKILL.md" } HOW CLIENTS ARE EXPECTED TO CONSUME SKILLS Imagine you’ve connected the GitHub MCP server to goose, an MCP client. The moment that connection is established, goose checks whether the server supports io.modelcontextprotocol/skills. If it does, goose reads skill://index.json and gets back a lightweight catalog (e.g. skill names, descriptions, and URIs). That catalog goes into context, but not the full skill content. So the model knows the skills exist, not what’s in them. Then when a user asks goose to review a pull request, the model sees “pr-review” in the catalog along with its description, recognizes it is relevant, and calls read_resource to fetch skill://github/pr-review/SKILL.md. The model reads the skill, follows any references it needs, and starts pulling in supporting files on demand. This flow is progressive disclosure in practice with small metadata upfront, then full instructions only when needed. SOME OPEN QUESTIONS This is still active work, and there are plenty of questions left to answer. Will clients add support for Resources? This whole approach depends on clients actually implementing the Resources feature; many which currently do not. If Skills over MCP takes off, clients will need to treat resource discovery/reading as part of the normal agent workflow. Will models actually use the skills? The host is responsible for surfacing the skill catalog to the model, but surfacing alone isn’t enough. The WG’s early experiments found that models often ignored available skills and tried to use tools directly, sometimes failing before eventually finding the skill. This defeats the purpose of even providing a skill if the agent will still fumble anyway. The WG found that adding a server instruction telling the agent to read the skill first helped, but even then adherence starts declining as context grows. How much of that burden falls on the host, the client, or the skill author is still being worked out. How does trust work? While a skill is “just instructions”, instructions change agent behavior in meaningful ways. If an MCP server exposes a skill, should the host trust it automatically? Should users see where a skill came from? Should enterprise admins be able to approve, block, or pin specific skills? How do overlapping skills get handled? Imagine a Stripe MCP server ships a general refund-processing skill that explains how Stripe refunds work, but your company also has an internal refund-processing skill with its own policies on when your company allows refunds, who needs approval, and what notes to leave. Hosts will need a way to handle layering, precedence, or at least source visibility. HOW TO GET INVOLVED If this sounds interesting, the Working Group is actively discussing these ideas, building prototypes, and looking for feedback. The work is still evolving, so now is a great time to jump in and help shape it. You can find the Skills Over MCP WG on GitHub as well as in the MCP Discord server.