# How Skills Over MCP Work: The Skills Extension (SEP-2640)

> SEP-2640 lets MCP servers publish Agent Skills alongside their tools. Each skill file is an MCP resource under skill://. Learn how hosts list and load skills, which safety checks they must make, which clients support the extension, and how a gateway serves skills.

Erik Jonsson Thorén, Founder, Gatana. Published 2026-11-18. Human-readable version: https://www.gatana.ai/guides/skills-over-mcp-sep-2640

Skills over MCP is the Skills extension of the Model Context Protocol (SEP-2640, identifier `io.modelcontextprotocol/skills`). A server publishes each skill file as an MCP resource under `skill://`. The host calls `skills/list` to find skills. It reads files with `resources/read` only when the model needs them, then checks each file against its listed SHA-256 digest. The extension is read-only.

## The problem it solves

A skill is a folder with a `SKILL.md` file and optional supporting files. The open format is documented at [agentskills.io](https://agentskills.io). Before this extension, agents loaded skills from [folders on the machine](https://www.gatana.ai/guides/share-skills-across-claude-code-and-codex). An MCP server had no standard way to supply a skill that teaches an agent to use its tools. The SEP identifies three problems:

- A server and its skill are installed and versioned separately. Installing a server does not tell the user that its skill exists.
- A server's `instructions` field is too small for a long workflow. The SEP gives a skill with 875 lines as an example.
- Several servers had defined their own `skill://` layouts with different rules.

The Skills Over MCP Working Group wrote [SEP-2640](https://modelcontextprotocol.io/seps/2640-skills-extension). It was created on 23 April 2026 and its status is Final. The Agent Skills specification still defines the file format. The SEP defines how MCP carries those files.

## A skill is a set of resources

Each skill file is one MCP resource. Its URI has the form `skill://<skill-path>/<file-path>`.

| Skill path | File | Resource URI |
| --- | --- | --- |
| `git-workflow` | `SKILL.md` | `skill://git-workflow/SKILL.md` |
| `pdf-processing` | `scripts/extract.py` | `skill://pdf-processing/scripts/extract.py` |
| `acme/billing/refunds` | `SKILL.md` | `skill://acme/billing/refunds/SKILL.md` |

Four rules apply:

- The last segment of the skill path must match the `name` in the `SKILL.md` frontmatter. The host can get the name from the URI alone.
- The server chooses any prefix segments before the name.
- A URI belongs to the server that serves it. Two servers can serve different skills at `skill://refunds/SKILL.md`. A host identifies each skill by both its server and URI.
- The URI scheme alone does not identify a skill. A server can use another scheme, such as `github://`. A resource is a skill when `skills/list` lists it or `skills/get` confirms it.

## The methods

A server declares the extension in its capabilities. It must also declare the `resources` capability.

```json
{
  "capabilities": {
    "extensions": {
      "io.modelcontextprotocol/skills": {
        "directoryRead": true
      }
    }
  }
}
```

| Method | What it does |
| --- | --- |
| `skills/list` | Returns the server's skills in pages. Required |
| `skills/get` | Returns one skill entry by its `SKILL.md` URI. Required. An unknown URI returns error `-32602` |
| `resources/read` | Returns the bytes of one file. This is the standard MCP method |
| `resources/directory/read` | Returns the direct children of a folder. Optional. The server declares it with `directoryRead: true` |

A list can be empty or incomplete. A server with a large or generated catalog can omit skills. A host must not treat an empty list as proof that the server has no skills. The host can still read an unlisted skill by its URI and get its entry with `skills/get`.

## Skill entries

`skills/list` and `skills/get` return entries. Each entry describes one skill:

```json
{
  "uri": "skill://pdf-processing/SKILL.md",
  "frontmatter": {
    "name": "pdf-processing",
    "description": "Extract, fill, and assemble PDF documents",
    "metadata": { "version": "2.1.0" }
  },
  "resources": [
    { "uri": "skill://pdf-processing/SKILL.md", "digest": "sha256:d5e6f7a8...", "size": 5120 },
    { "uri": "skill://pdf-processing/references/FORMS.md", "digest": "sha256:e6f7a8b9...", "size": 18433 },
    { "uri": "skill://pdf-processing/scripts/extract.py", "digest": "sha256:f7a8b9c0...", "size": 4096 }
  ]
}
```

- `frontmatter` contains all fields from the `SKILL.md` YAML frontmatter as JSON.
- `resources` lists every skill file, including `SKILL.md`, with its SHA-256 digest and size in bytes.
- A server that generates a skill for each request cannot provide digests. It sets `"resources": "dynamic"`. A host can refuse such a skill.

Each entry contains the information the host needs to show the skill, ask for user approval and later check its files. The host needs no separate call to get this information for each skill.

## How a host loads a skill

1. The host connects and finds the extension in the server's capabilities.
2. The host calls `skills/list` and adds each entry to its skill list alongside local skills. It does not read files yet.
3. The host gives the model each skill's name, description and source server.
4. The model decides that a skill applies. The host then reads the `SKILL.md` with `resources/read`.
5. The host checks the size and the digest against the entry. It also parses the frontmatter and compares it with the entry, field by field. If a check fails, the host does not use the content.
6. If `SKILL.md` refers to `references/FORMS.md`, the host resolves the path against the skill folder. It reads the file and checks its size and digest.

A check can fail because the skill changed on the server. The host then calls `skills/get` for a new entry. If the set of digests changed, the earlier user approval is no longer valid. The host must ask again.

In protocol version 2026-07-28 and later, list results also contain `ttlMs` and `cacheScope`. These fields tell the host how long it can cache the list and whether the list is specific to one user.

## Host safety rules

A skill contains instructions from a server that the model follows. The SEP rates skills as a higher risk than remote tool calls. A skill can cause the host to save files from the server and tell the model to run them. Hosts must follow these rules:

1. Treat skill content as untrusted input, like any other text from a server.
2. Tell the model which server supplied each skill. Do not present an MCP skill as a local skill.
3. Get user approval for a skill before running code that it requests. This includes its scripts and commands in its text.
4. Ignore the `allowed-tools` field unless the user approved it for that skill.
5. Tie user approval to the URIs and digests in the entry. A changed set needs new approval.
6. Do not let a skill from one server cause a read from another server.
7. Do not let a server skill replace a skill with the same name from another server or a local folder.
8. Keep cached skill files outside the folders where the host looks for local skills.

The digests are unsigned. The same server sends the digest and content, so a match proves only that they agree. The SEP says that a gateway or another intermediary can rewrite both. The user must still decide whether to trust the skill.

## Limits

| Limit | Value |
| --- | --- |
| Files per skill | 512, including `SKILL.md` |
| Total size per skill | 16 MiB |

Every host must accept a skill up to these limits. A server should not serve a larger one.

The extension does not support:

- **Writes.** A host can list and read skills. No method creates or changes one.
- **Archives.** An earlier draft let a server send a skill as one tar or ZIP file. The maintainers removed this option because every host would have to unpack remote files safely. A session now needs one read for each skill file it uses.

## Who supports it

The working group keeps a [list of implementations](https://github.com/modelcontextprotocol/ext-skills/blob/main/docs/implementations.md). On 18 November 2026, 15 of the 17 listed servers implemented the released extension. These included Hugging Face, Cloudflare, Outline, Salesforce B2C DX, n8n and Ansible AAP.

The TypeScript SDK added support in version 2.4.0 and FastMCP in version 4.1.2. The Python and C# SDKs had merged support but had not released it.

Fewer hosts supported the extension on the same date:

| Status | Hosts |
| --- | --- |
| Implemented | fast-agent, MCPJam Inspector, mcpc (Apify), vitehub, harness |
| Partial | MCP Inspector, ChatGPT plugins (a static skill copy made when a plugin is submitted), Microsoft Agent Framework |
| Open pull request | Goose, opencode, Hermes Agent, Cherry Studio, Agno, agentgateway |
| Requested | VS Code (GitHub Copilot) |

The [official client matrix](https://modelcontextprotocol.io/extensions/client-matrix) had no Skills entry for Claude Code, Claude Desktop or Cursor on that date. The SEP says that Anthropic built an internal prototype for Claude Code. It also lists prototypes for Codex and Gemini CLI.

Most agents therefore cannot read skills through the extension yet. Teams can also use skill folders on each machine or tools that list and return skills.

## How a gateway serves skills

A gateway connects agents to an organization's MCP servers. To the host, the gateway is one server. Connected servers can serve the same URI, so the gateway must give their skills distinct URIs.

Gatana serves skills from two sources on one connection:

| Source | URI | Who can read it |
| --- | --- | --- |
| The organization's skills registry | `skill://release-checklist/SKILL.md` | Users with read access to the skill |
| A connected MCP server | `skill://github.server/git-workflow/SKILL.md` | Users with access to the server |

A skill name cannot contain a dot, so `github.server` cannot match a registry skill name.

For skills from connected servers:

- Gatana fetches and stores a server's skill list when it refreshes that server's tools. It answers `skills/list` from this stored list.
- Gatana reads files from the server on request with the user's credentials. It does not store the files.
- Gatana changes only the URIs. File bytes pass through unchanged, so the host can still check the server's digests.
- Gatana does not serve skills with `"resources": "dynamic"`.
- A server maintainer can turn off its skills on the **Settings** tab. Its tools remain available.
- Gatana records each read in the [audit log](https://docs.gatana.ai/audit-logs/), with the URI, size and digest. It never records the content.

**The [tool firewall](https://docs.gatana.ai/tool-firewall/) checks tool calls. It does not check skill content.** A connected server that publishes skills supplies instructions to every agent with access to it. Review those skills before you keep them enabled.

## Hosts without the extension

For hosts without the extension, Gatana's built-in **Skills** server provides tools to read the same skills:

| Tool | What it does |
| --- | --- |
| `skills_list_skills` | Lists the organization's skills, followed by a block for each connected server with its skill URIs |
| `skills_get_skill` | Returns an organization skill by `name`, or a server skill file by `uri` |

For these tool calls, Gatana checks files for the host. It reads the file from the server and checks its size, digest and frontmatter against the entry. If a check fails, the tool returns an error without content. The response names the source server on the first line, so the model knows where the instructions came from.

Tell the agent to use these tools. Add this line to the project's `CLAUDE.md` or equivalent instruction file:

> At the start of a task, call `skills_list_skills` and follow any skill that applies.

## Where to go next

1. [SEP-2640](https://modelcontextprotocol.io/seps/2640-skills-extension) gives the full rules and explains the design choices.
2. The [Agent Skills specification](https://agentskills.io/specification) defines the skill format.
3. [Consuming Skills](https://docs.gatana.ai/skills-install/#skills-over-mcp) describes Gatana's tools and extension support.
4. [How to share skills across Claude Code, Codex and other agents](https://www.gatana.ai/guides/share-skills-across-claude-code-and-codex) covers skill folders, the registry and the sync hook.

## Questions, answered

### What is SEP-2640?

SEP-2640 defines the Skills extension for the Model Context Protocol. Its identifier is io.modelcontextprotocol/skills and its status is Final. It specifies how MCP servers serve Agent Skills as resources. The skills/list method lists skills. The skills/get method returns one skill by its URI.

### How does an MCP host find a server's skills?

The server declares the extension in its capabilities. The host then calls skills/list. Each entry contains the SKILL.md URI, all frontmatter fields as JSON, and a list of files with their SHA-256 digests and sizes. The host builds its skill list from these entries. It reads files only when the model needs them.

### Are skills from an MCP server safe to load?

Hosts must treat skill content as untrusted input and tell the model which server supplied it. They must get user approval for a skill before they run code that it requests or accept its allowed-tools field. A matching digest confirms that content agrees with the listing. It does not prove trust.

### Which clients support skills over MCP?

On 18 November 2026, the working group's list showed five hosts with support: fast-agent, MCPJam Inspector, mcpc from Apify, vitehub and harness. Goose, opencode, Hermes Agent, Cherry Studio and Agno had open pull requests. The official client matrix had no entry for Claude Code or Cursor. More servers than hosts support the extension.

### Can an agent create or change a skill through the extension?

No. The extension is read-only. It defines skills/list, skills/get and the optional resources/directory/read. Hosts read files with the standard resources/read method. None of these methods creates or changes skills. Servers must provide separate tools to save skills. Gatana's built-in Skills server has create and update tools.

### What does an MCP gateway do with the skills of the servers behind it?

To a host, a gateway is one server. It must keep each connected server's skills separate. Gatana adds the server slug to the URI: skill://github.server/git-workflow/SKILL.md. It serves a stored skill list and reads files from the server with the user's credentials. File bytes pass through unchanged, so the digests still match.
