Skills come to MCP

At GuruSup we ran into an awkward boundary: part of the logic lived in our MCP server and part in our Assistant, which consumes that MCP. We wanted the Assistant to be just another client. But sharing tools wasn't enough to share the procedure.

A client can know the same tools and still not know what context to gather first, when to check something or how to read the result. Switching clients exposes what the protocol carries and what we had left out. An MCP should work the same, and perform about as well, no matter which client uses it.

Where should that manual live so it can travel with the tools?

Same tools, different path

Picture a typical request to an agent connected to our MCP: “Tell the support agent not to promise refunds without checking the order first.”

One client reads the current prompt first, finds the returns section and inserts the rule right after it. Then it rereads the prompt to confirm everything else is unchanged. Another writes a new prompt from scratch, rule included, and saves it in place of the old one: the rule gets in, but along the way a section disappears, or the new rule clashes with one that was already there. Both have access to the same server and both end up with an agent that answers. The difference is the path, and in the second case nobody notices until a customer complains:

We don't need identical answers. We need switching clients not to drop important steps or turn a small change into a blind rewrite.

It's worth separating two failures. If skipping the initial read makes the edit worse, guidance is missing. If skipping a validation allows a forbidden operation, an enforceable condition on the server is missing. A skill can help with the first; it shouldn't be the defense against the second.

The manual, concretely

For that task, a skill could contain this procedure:

---
name: edit-agent-prompt
description: Changes an agent's prompt without breaking what already works.
---
1. Read the current prompt before changing it.
2. For a small change, edit only the fragment; don't rewrite the whole prompt.
3. Use as an anchor a piece of text that appears only once.
4. After saving, reread and confirm nothing else changed.

The tool saves the change. The skill prescribes how to prepare it, what to touch and how to check nothing broke.

Writing it is the easy part. The hard part comes after:

• └Where does it live? On the MCP server, next to the tools it describes, or in every client that uses them?
• └How does it reach the model? Does the user install it, does the agent ask for it, or does the server offer it?
• └Who decides when to use it: the host?
• └And if I switch clients, does it come with me or stay behind?

The procedure should travel with the MCP. Whoever maintains the tools knows best how to use them. If every client keeps its own copy, we'll have as many versions as clients and none of them up to date. That doesn't mean the server decides when it's used: activating it will still be up to the client.

The rest of the article answers those questions in two steps: how different MCP servers solve it today with workarounds, and what changes with the new spec.

Weren't Resources and Prompts enough?

MCP already had pieces for passing knowledge along. The problem wasn't where to store text, but how to recognize it and consume it as a shared procedure.

• └Tools: describe and execute operations. A description can guide, but stuffing a cross-cutting manual in there duplicates context and makes it harder to maintain.
• └Resources: expose data and files. They could serve a SKILL.md, but there was no common convention to identify its bundle and discover it as a skill.
• └Prompts: offer invocable templates, usually picked by the user. That's not the same as automatically discovering a relevant procedure.
• └Server instructions: give guidance about the server. Putting every manual there throws away much of the benefit of loading them only when needed.

Back to the edit. A Resource can hold the prompt style guide; a Prompt, a template for requesting changes. The client still needs to know both belong to the same procedure and when to fetch them. Until now, every integration could invent that link.

The bytes could already travel. What was missing was a shared convention to find them and recognize their role.

That's why Resources don't go away with skills: they still carry files. The extension adds the specific contract for discovering procedures that use those files.

The workarounds tell the same story

The manual as a tool: Logfire and n8n

Logfire's MCP offers query_schema_reference to prepare queries and query_run to run them. Its reference even lists the functions models wrongly try to use and that its engine doesn't have.

n8n's official MCP follows a similar pattern: get_workflow_sdk_reference hands over building patterns and rules, and its docs recommend checking it first. You can fetch specific sections; get_workflow_best_practices adds guidance per technique.

We read both designs as the same strategy: retrieve knowledge first; operate after. Logfire provides context to query data; n8n also provides instructions to build workflows. Neither needs a skills extension to offer that knowledge on demand.

The limit is shared: offering a manual and recommending it doesn't guarantee the client reads it or follows the procedure. A manual you have to ask for is a manual you can skip asking for. It means pushing the model to fetch the manual first and crossing your fingers 🤞, although this strategy works pretty well with current models.

Brain: the catalog up front, the manual on demand

In Gurusup Brain we combine an initial usage contract, the full catalog of authorized skills with their descriptions, and fetching their content on demand. What's deferred is each skill's manual, not the catalog.

On top of that, our public plugin ships the MCP together with an entry skill that says to call init first, follow the server's contract and answer based on evidence.

That's how we combine two workarounds: guidance through tools and a skill installed with the plugin. The instruction to read first still depends on the client; it's not an execution barrier.

The lesson wasn't “everything should become a skill”. We also need high-level operations so each client doesn't have to rebuild long chains. A good contract cuts unnecessary decisions; a good procedure explains the ones that remain.

Plugins bundle the pieces, but only on your machine

MongoDB distributes its MCP server through plugins for several agents and separately publishes its official Agent Skills. That's another answer: deliver MCP and skills through channels the host already understands.

It lets you ship capability and manual together, but installation and activation stay tied to each client's ecosystem. It solves a real need without, on its own, creating a contract between any server and any host. A plugin gets the manual to your disk, not to your client's chat.

The CLI, a third channel

Several companies don't choose between MCP and skills: they add a CLI. It plays three different roles.

Installing the server and the manual. Context7 sets up its MCP in each agent with ctx7 setup. Vercel publishes add-mcp, which detects installed agents and registers its server in all of them. WorkOS does it with workos mcp install. The CLI knows where each host keeps its config; the protocol doesn't.

Doing what the MCP can't. A remote server can't see your disk or your project. WorkOS's skill has a section on choosing the surface: the MCP to manage account resources, and the CLI for bootstrapping, local config and diagnostics, with an agent mode that returns JSON. Vercel bridges both worlds from within the protocol: a separate endpoint exposes use_vercel_cli, a tool that runs nothing and only points the model to CLI commands and their --help. And when a call fails, the error itself includes a cliFallback object with the equivalent CLI command, its help and its limitations; its tool descriptions announce it too.

Carrying the procedure. Vercel publishes CLI Workflows: end-to-end walkthroughs, like debugging 500 errors, rolling back a deployment or setting up a domain, with the command sequence and the reasoning between steps, written for agents. It's a procedure manual, but for the CLI, and it lives in the docs.

Vercel combines five channels for one goal: an MCP with over two hundred tools, a plugin, installable skills, a CLI with workflows for agents and indexes like llms.txt. It's another way to carry the procedure outside MCP, and one more reason to standardize it inside.

Two halves of the same problem

Comparing these servers, a pattern shows up. They all respond to the same constraint, that not everything fits in context, but they tackle different halves of the problem:

• └Capabilities: what the agent can do.
• └Procedure: how to do it well.

WorkOS is the most radical case of the first half. Its MCP doesn't expose one tool per operation: it offers an index the agent queries to discover each operation and its parameters, plus two generic tools to run them, one for queries and one for mutations. The catalog looks derived from its own API and, inside the server, the manual is reference only: one line and some parameters per operation, no server instructions, resources or prompts. Its docs sum up the bet: “The agent discovers the right operations and runs them for you”. But setting up a customer's SSO touches several operations (create the organization, add its domains, register its admins and send them the setup link), and the index doesn't say in what order or what to check in between. Loading fewer tools isn't the same as carrying the procedure to combine them.

WorkOS does have that procedure, but outside the protocol: its workos/skills repo publishes a skill with workflows like onboarding an organization, packaged as plugins for Claude Code, Codex and Cursor.

Logfire, n8n and Context7 tackle the second half with reference tools. Brain covers both: a high-level operation for capabilities and a skills catalog for the procedure.

SEP-2640 standardizes only the second half. It's the one WorkOS solves with a separate plugin and the one everyone else solved their own way. With the extension, that manual could travel with the server instead of depending on each host installing the right plugin.

The objection: wasn't describing the tools well enough?

It's the obvious question. If the agent already reads each tool's description, why not put the procedure there? Well-written descriptions help, and some servers make full use of them: many Vercel tools announce in their own description the CLI command to fall back on if the call fails. But they have three limits.

The host decides how much gets read. By default, Claude Code cuts server instructions and the description of each tool that loads upfront at 4,096 characters, and at 16,384 if the tool is loaded through tool search. And with tool search on, at session start it only loads tool names and server instructions. If the rule “read the prompt before editing it” sits at the end of a long description, the model may never see it.

A procedure doesn't belong to a single tool. Setting up a customer's SSO in WorkOS chains four operations. In which one's description do you write the order? Repeating it in all of them multiplies context and guarantees the copies drift apart.

You pay for it even when you don't use it. A description travels in every session that loads the tool, whether the procedure is needed or not. Logfire and n8n didn't solve it with longer descriptions, but with a reference tool that's only read when needed.

The description guides one call; the procedure explains how to combine them. You need both.

MCP didn't want to be a package manager

The original proposal, SEP-2076, wanted skills as a first-class primitive. At the June 24 core maintainers meeting the vote was postponed: bundled files, permissions, scripts and the fear of turning MCP into a package manager. A week later, the Working Group narrowed the scope: each file is still a Resource and the extension only handles discovery and identity.

Agreeing on how to deliver a manual doesn't require agreeing on how to install packages or run remote code.

SEP-2640 delivers the manual, it doesn't enforce it

SEP-2640, with Final status, defines an extension, not a new core primitive:

• └skills/list discovers entries and metadata.
• └skills/get fetches a skill's entry by URI: its metadata and the digests of its files.
• └resources/read retrieves instructions and supporting files.
• └resources/directory/read lets you browse directories if supported; it's optional.

With the editing example, in theory the host would list edit-agent-prompt, could load it when it sees a change request, and only then call the tool that saves the prompt. The full flow would be:

Digests verify that the bytes match the skill's entry, not that the author is trustworthy. Identity combines origin and URI; the skill:// prefix alone doesn't make something a skill.

There may be scripts among the files. Carrying them doesn't authorize running them: the host needs policies and sandboxing.

Discovering, loading, activating, following and executing are different steps. The extension doesn't guarantee that a skill is activated before every tool, or that the model follows all its instructions.

The manual advises; the server guarantees

A skill doesn't enforce anything: the model may not load it, or load it and skip a step. With the prompt edit, that means a worse change, but not a disaster, because our server validates every edit before saving it. WorkOS does the same with deletions: the first attempt never deletes anything, because the server requires a separate confirmation.

If skipping an instruction breaks security, consistency or business logic, it can't live only in Markdown.

Workaround today; contract tomorrow

We started with a question: where should the manual live so it travels with the tools? Today there's no right answer; every organization settles it differently. Logfire and n8n put it in a reference tool, Brain in init, WorkOS in a plugin and Vercel in its CLI. All of that works, but they're workarounds: private agreements between a server and the clients that know how to read them. Switch clients and the manual can get lost along the way.

A contract is something else: an agreement any client understands without knowing you. That's what SEP-2640 proposes for the procedure. And the earlier point still holds: what can't fail isn't negotiated in any manual; the server guarantees it.

So where are we? The spec has been final since September 2026 and the Python SDK already has the code merged, but the clients that matter don't use it yet: neither Claude nor Codex asks a server for skills/list today. As soon as Claude and Codex officially support it, I'll be among the first to try it.

Fran, GuruSup's CTO, covers the other side in “Your harness remembers mistakes the model no longer makes” (in Spanish): when the model learns something, part of the harness we built around it becomes unnecessary. Standards work the same way. The day the protocol adopts this pattern, our workaround will expire, and that'll be good news.

One open question for anyone maintaining an MCP: where does your manual live today, and what got lost the last time you switched clients?