Black Friday 2026: more dev deals (DataCamp 60% off and more) See the deals

Skills Over MCP Explained: How Servers Ship Agent Skills

 Â· 15 min read  Â·

You install an MCP server. It gives your agent 40 tools. Then you go find the skill that teaches the agent how to use those tools, copy its folder into your agent’s skills directory, and hope it stays in sync with the server.

Skills over MCP gets rid of that copy step.

It’s an official MCP extension, defined in SEP-2640, that lets an MCP server serve agent skills itself. The host discovers them when it connects, shows you where they came from, and loads them on demand like any local skill.

I’ll go through the wire format, what servers and hosts each have to do, and who supports it right now. Then the security rules, which you should read before you click Allow on anything.

Quick refresher

If you need the background, start with these two:

  • What are agent skills? A Skill packages repeatable instructions, workflows, and reference material into a folder an AI agent can find and load when needed. The required file is SKILL.md.
  • What is MCP? MCP is a standard way for AI apps to connect to external tools, data, and systems.

In the skills post I put it this way: MCP gives the agent the kitchen, Skills give it the recipes. Until now you got the kitchen and the recipes from two different stores. This extension lets the kitchen ship with its own recipe binder.

What problem it solves

SEP-2640 lists three problems in its motivation section:

  1. Fragmented distribution. A server and the skill that teaches an agent to use it are versioned and installed separately. Installing a server from a registry gives you no signal that a companion skill exists.
  2. Server instructions are too small. MCP servers can already send an instructions string, but it is practically bounded in size. A real workflow skill with references and scripts doesn’t fit.
  3. Everyone invented their own skill://. Several projects had already started serving skills as MCP resources, each with a different URI layout. The SEP standardizes one.

What I like about the design is that it adds no new primitive. Skills ride on MCP’s existing Resources primitive, so each file in a skill directory becomes a resource. The skill format itself (frontmatter, naming rules, progressive disclosure) is delegated entirely to the Agent Skills specification. MCP only defines the transport.

Where the spec stands

A few dates and names, because older articles will confuse you otherwise:

  • SEP-2640 is Final. Its pull request merged on September 13, 2026. The SEP page itself says it is preserved as a historical record and points to the current spec.
  • The current spec lives in modelcontextprotocol/ext-skills, at specification/beta/skills.mdx. The extension is at the Beta stage, written against base protocol revision 2026-07-28. The old experimental-ext-skills repo URL redirects there.
  • The extension identifier is io.modelcontextprotocol/skills.
  • The Skills Over MCP Working Group maintains it.

One thing to watch for: earlier drafts used a well-known skill://index.json resource as the catalog. The Agentic AI Foundation’s June 2026 write-up describes that version. The final design replaced it with a skills/list method, and the WG’s rationale doc explains why: pagination, the base protocol’s list caching, and support implied by the capability declaration instead of probing a URI. If a tutorial tells you to read skill://index.json, it’s describing the old draft.

How it works on the wire

Four pieces: a URI layout, a capability declaration, two required methods, and one optional one. Everything else is plain resources/read.

The skill:// URI layout

Every file in a skill is a resource at:

skill://<skill-path>/<file-path>

<skill-path> can be one segment or nested, and its last segment must equal the skill’s name from its frontmatter. Anything before it is a prefix the server picks for organization. These are the spec’s own examples:

skill://git-workflow/SKILL.md
skill://pdf-processing/references/FORMS.md
skill://pdf-processing/scripts/extract.py
skill://acme/billing/refunds/SKILL.md
skill://acme/billing/refunds/examples/email.md

In skill://acme/billing/refunds/SKILL.md, the prefix is acme/billing and the skill name is refunds. You can recover the name from the URI without reading the file.

A few more rules:

  • The skill root is skill://acme/billing/refunds, with no trailing slash.
  • Relative links inside SKILL.md resolve against the skill’s root, exactly like on disk. references/GUIDE.md in the refunds skill becomes skill://acme/billing/refunds/references/GUIDE.md.
  • The spec says servers SHOULD use skill://. A server can still use its own scheme, like github://..., as long as the path still ends in the skill name and SKILL.md.
  • A URI scheme does not make something a skill. A host learns a resource is a skill from a skills/list entry or by confirming it with skills/get.

The capability declaration

A server opts in through the extensions field of its capabilities. This is the shape from the spec:

{
  "capabilities": {
    "resources": {},
    "extensions": {
      "io.modelcontextprotocol/skills": {
        "directoryRead": true
      }
    }
  }
}

Declaring the extension commits the server to skills/list and skills/get. It must also declare resources. directoryRead defaults to false and gates the optional directory method. An empty object means “supported, no optional features.”

Clients only call the skills methods after they see this declaration, so a client that doesn’t know about the extension just sees skill:// files as ordinary resources.

skills/list

This is how a host builds its catalog. The request, from the current spec (on protocol 2026-07-28, every request carries _meta):

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "skills/list",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {
        "name": "ExampleClient",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

The response, trimmed to two of the spec’s three example entries:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "resultType": "complete",
    "skills": [
      {
        "uri": "skill://acme/billing/refunds/SKILL.md",
        "frontmatter": {
          "name": "refunds",
          "description": "Process customer refund requests per company policy",
          "license": "Apache-2.0"
        },
        "resources": [
          {
            "uri": "skill://acme/billing/refunds/SKILL.md",
            "digest": "sha256:ae7bc7e45f44a6381977ef1f772cbad6e38d8ec78903ea7b87abb373815a8f89",
            "size": 175
          },
          {
            "uri": "skill://acme/billing/refunds/examples/email.md",
            "digest": "sha256:a724fa5ed3b9e39c0e731fe1f0e866eb46d23969af25ecf0d5f41982e3e36bea",
            "size": 58
          }
        ]
      },
      {
        "uri": "skill://reports/daily/SKILL.md",
        "frontmatter": {
          "name": "daily",
          "description": "Assemble today's operational report from live data"
        },
        "resources": "dynamic"
      }
    ],
    "ttlMs": 300000,
    "cacheScope": "public"
  }
}

Each entry is a full manifest of the skill:

  • frontmatter is the skill’s YAML frontmatter, verbatim, as JSON. Every field the author wrote.
  • resources lists every file in the skill with a SHA-256 digest and byte size.
  • A skill generated on the fly sets "resources": "dynamic" instead. That skill offers no integrity guarantee, and hosts may refuse to load it.
  • ttlMs and cacheScope are required on this protocol revision, same as tools/list.
  • Pagination works like the other list methods (cursor and nextCursor), and an entry is never split across pages.

A listing can be empty or partial. A server with a huge or generated catalog doesn’t have to enumerate it, and hosts must not treat an empty list as “no skills.”

skills/get

skills/get returns one entry by its SKILL.md URI, listed or not. Servers must answer for every skill they serve.

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "skills/get",
  "params": {
    "uri": "skill://pdf-processing/SKILL.md"
  }
}

The result is { "skill": { ... } } with the same uri, frontmatter, and resources shape as a list entry. Unknown URI? The server returns JSON-RPC error -32602. (That request is the SEP’s example; the current spec adds the same _meta block shown above.)

Hosts use it for two things: refreshing one skill after a digest mismatch, and verifying a skill URI that showed up somewhere other than the listing, such as server instructions or another skill.

resources/read and resources/directory/read

Reading a file is just the base protocol’s resources/read with the file’s URI. Nothing skill-specific.

The one new read method is resources/directory/read, available only when the server declared directoryRead: true. It exists because skills say things like “pick the right template from templates/,” and the agent needs an ls. It returns the direct children of a directory, with subdirectories marked mimeType: "inode/directory", and you call it again to go deeper.

Skills over MCP message flow: capability check, skills/list, user approval, resources/read of SKILL.md, then host-side verification

What a server author does

The work is smaller than the spec length suggests, because SDKs now do the bookkeeping (digests, sizes, frontmatter, the methods).

1. Lay out your skills folder

Same format as a local skill. Each folder with a SKILL.md is one skill, and other folders become the URI prefix:

skills/
├── git-workflow/
│   ├── SKILL.md
│   └── references/REVIEW.md
└── acme/billing/refunds/
    └── SKILL.md

The name in each SKILL.md must match its folder name. If you have never written one, how to write a good agent skill covers the content side.

2. Attach it to your server

With the official TypeScript SDK (v2.4.0 added the extension under ext/skills), this is the example from the SDK’s own guide:

import { McpServer } from '@modelcontextprotocol/server';
import { loadSkills } from '@modelcontextprotocol/server/ext/skills/node';

const skills = await loadSkills('./skills');

const server = new McpServer({ name: 'team-skills', version: '1.0.0' });
skills.attach(server);

That serves skills/list, skills/get, resources/directory/read, and the skill:// resources. The SDK keeps metadata only, reads files on request, and refuses to serve a file whose bytes no longer match the published digest. Call skills.reload() after you change files on disk. The SDK docs flag attach as experimental, so expect the wiring to shift.

Not on TypeScript? The WG’s implementations list tracks the other SDKs. As of November 20, 2026 it lists C#, Ruby, Rust (rmcp), and FastMCP as shipped, Python as merged but unreleased, and Go and Java as in progress.

3. Stay inside the rules

If you roll your own instead of using an SDK, these are the server-side MUSTs and SHOULDs worth taping to your monitor:

  • Publish complete manifests: every file, each with its digest and size, computed from the bytes you actually serve.
  • Pass frontmatter through verbatim. Don’t curate it.
  • Answer skills/get for every skill you serve, even ones you leave out of the listing.
  • Keep each skill at or under 512 files and 16 MiB total. Hosts only have to support that much.
  • If you declare directoryRead, support it for every directory in your skill namespace.

You can still point the agent at a specific skill from your server’s instructions field. The URI is readable whether or not it shows up in a listing.

4. Verify before you ship

The MCP Inspector CLI has a --verify flag that runs the SEP-2640 conformance, digest, and frontmatter checks over everything your server lists, prints one JSON report per skill, and exits non-zero on a failure. Its README pitches it for gating CI:

mcp-inspector --cli <server> --method skills/list --verify

Swap in --method skills/get --uri <skill-uri> to check a single skill.

What a host or client does

Most of the spec’s MUSTs land on the host. My guess is that’s why hosts are shipping this more slowly than servers.

The flow the spec describes:

  1. Connect and check. If the server declares io.modelcontextprotocol/skills, call skills/list.
  2. Build a registry from the listing alone. Names and descriptions come from frontmatter. The host must not fetch any SKILL.md or supporting file at this stage. That’s progressive disclosure, applied across servers.
  3. Key everything on origin plus URI. Two servers can both serve skill://refunds/SKILL.md, and they are unrelated skills. The spec treats a name as a display label only.
  4. Show the model name, description, and origin. MCP skills sit in the same list as filesystem skills, tagged with the server they came from.
  5. Load on demand. When the model wants a skill, the host fetches SKILL.md with resources/read, checks the byte size and digest against the entry, parses the frontmatter, and compares it field by field with the listed frontmatter. Any mismatch means don’t load it.
  6. Read supporting files only from the manifest. While acting on a skill, a read of a file that isn’t in the entry’s resources counts as a verification failure.

The SEP sketches a host design with a read_skill tool and a read_resource tool, both taking a server and a uri. The SEP calls that section illustrative, so hosts can wire it however they like.

On the client side, the TypeScript SDK wraps the verification for you:

import { SkillsClient } from '@modelcontextprotocol/client/ext/skills';

const skills = new SkillsClient(client);
const { skills: entries } = await skills.list();

const git = entries.find(entry => entry.frontmatter.name === 'git-workflow')!;
const manifest = await skills.read(git);                       // size, digest, frontmatter checked
const review = await skills.read(git, 'references/REVIEW.md'); // resolved against the skill root

A failed check throws SkillVerificationError with a reason of unlisted, size, digest, or frontmatter.

Who supports it today

This changes week to week, so check the official extension client matrix and the WG’s implementations list before you rely on anything below. I only list a product here if its own docs, changelog, or repo says it supports the extension.

ProductRoleWhat its own source says
VS Code (GitHub Copilot)HostPreview in 1.146, enabled by default in 1.147. You approve a server’s skills the first time you connect; opt out with chat.agentHost.mcpSkills.enabled.
fast-agentHostUses skills/list and skills/get, downloads every manifest file, checks size and digest, then writes a local copy. Won’t install "dynamic" skills.
MCP InspectorDev toolCLI skill verification. The client matrix marks it Partial.
GitHub MCP ServerServerv2.2.0 (“The one with Skills”). The local server bundles workflow skills, off by default, enabled with --features=skills, filtered to the toolsets you enabled.
TypeScript SDKSDKv2.4.0 adds ext/skills for servers and clients.
C# SDKSDKMerged October 23, 2026.

Look at who’s missing, too:

  • Claude Code, Claude Desktop, and Cursor have no Skills mark on the client matrix. The SEP says Claude Code support was “prototyped internally at Anthropic; not yet public.”
  • ChatGPT is marked Partial on the matrix, but the matrix links to an “import skills” section that I couldn’t find on OpenAI’s current page, and the WG’s implementations list says skill import was rolled back in November 2026. Treat it as unsupported until OpenAI’s docs say otherwise.

Servers outnumber hosts. As of November 20, 2026, the implementations list has 49 server and gateway rows (28 marked beta) against 22 host rows. Of those hosts, 10 are beta, 2 partial, 1 draft, and 9 still planned or in progress.

Fetch live or snapshot at install?

The spec allows two host styles, and current hosts split between them.

Snapshot at install. fast-agent copies a served skill into a local managed directory after verifying every file, and records the server identity, URI, and manifest alongside it. You review the copy and it doesn’t change under you.

Live from the server. VS Code’s release notes describe the connected server providing skills to the model after a one-time consent prompt. They don’t mention a local install step.

The spec has rules for both. Approval is bound to the exact set of URIs and digests you approved, so if the server rotates a file, the old approval is revoked and the host must ask again. And if a host caches skill files on disk, that cache must sit outside every filesystem-skill discovery path, and anything loaded from it is still treated as MCP-origin content, even after a restart. A cached MCP skill never gets promoted to the trust level of a skill you wrote yourself.

Trust and security

Skill content is instructions sent to a model. That makes it a prompt-injection surface, and unlike a remote tool call, a skill can put server-authored scripts on your machine and tell the agent to run them. The spec says hosts must treat MCP-served skills as “a higher-risk surface than remote tool invocation.”

The host-side requirements that matter most:

  • Untrusted input. Skill content gets the same prompt-injection defenses as any server-provided text. Being connected doesn’t make a server authoritative.
  • Visible origin. The model must see which server a skill came from, and an MCP skill must never look identical to a local one.
  • No implicit execution. Running bundled scripts, hooks, or any command a skill asks for requires explicit per-skill user approval.
  • allowed-tools is ignored for MCP-origin skills unless you explicitly approve that grant for that skill. A remote server setting it is asking for elevated access on your machine.
  • No cross-server reads. A skill from server A can’t make the host read resources from server B without per-call approval naming both.
  • No silent shadowing. A malicious server can publish a skill called git-workflow to hijack your local one. Hosts must namespace by origin and must not let it replace or intercept your skill.
  • Nested skills need their own consent. Approving a skill doesn’t approve a SKILL.md nested inside it.

The rule people will misread is about digests. The SHA-256 values come from the same server as the content and aren’t signed. A match proves the bytes are what the listing promised. It says nothing about whether the server or any gateway in between is honest. fast-agent’s docs put it plainly: “Integrity is not trust.”

So my practical rule: treat a skills-enabled server like a package you’re about to install, not like an API you’re about to call. Read the skills before you approve them, especially anything with a scripts/ folder.

Open questions the spec doesn’t settle

The extension defines transport and host safety rules. Several things the WG and others have raised are still open:

  • Provenance and enterprise control. The AAIF post asks whether enterprise admins should be able to approve, block, or pin specific skills. The spec allows intermediaries to attach provenance annotations under their own _meta prefix but assigns them no meaning, and its digests are unsigned.
  • Overlapping skills. If a vendor’s server ships a refund-processing skill and your company has its own, which one wins? The spec forbids silent shadowing and requires disambiguation, but layering and precedence are up to hosts.
  • Will models use them? The AAIF post reports the WG’s early experiments found models often ignored available skills and went straight to tools. A server instruction telling the agent to read the skill first helped, but adherence dropped as context grew.
  • Packaging. The WG charter puts installable bundles (skills plus servers plus configuration as one artifact) out of scope.

Should you use it?

If you maintain an MCP server, yes, start now. If you already have a skill that explains your tools, serving it from the server is a few lines with the TypeScript SDK, and it versions with your code. Hosts that don’t support the extension just see ordinary resources, so you lose nothing.

If you’re a user, it depends on your client. VS Code users have it on by default as of 1.147, so read that consent prompt instead of clicking through it. Everyone else is mostly waiting on their host.

If you build a host, budget real time for the security section. Listing and reading are the easy part. The work is in origin tagging, content-bound approval, and cache isolation.

Skills Over MCP FAQ

What is Skills over MCP?

Skills over MCP is an official MCP extension, defined in SEP-2640, that lets an MCP server serve agent skills. Each file in a skill directory is exposed as an MCP resource, usually under a skill:// URI, and hosts discover skills with the skills/list method.

What is the capability identifier for the MCP Skills extension?

Servers declare io.modelcontextprotocol/skills in the extensions field of their capabilities. Declaring it commits the server to implementing skills/list and skills/get. An optional directoryRead setting adds resources/directory/read.

Is skill://index.json still part of the spec?

No. An earlier draft used a skill://index.json catalog resource. The final design replaced it with the skills/list method, which supports pagination and the same list caching as tools/list.

Does Claude Code support Skills over MCP?

Not publicly as of November 2026. SEP-2640 says Claude Code support was prototyped internally at Anthropic and not yet public, and the official client matrix shows no Skills support for Claude Code.

Are MCP-served skills safe to load?

Treat them as untrusted. The spec requires hosts to show where a skill came from, ignore allowed-tools without explicit approval, and get per-skill consent before running any code. Digests only prove the bytes match the listing, not that the server is trustworthy.

This page may contain affiliate links. Please see my affiliate disclaimer for more info.

Related Posts

View All Posts »