Guide

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

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. Before this extension, agents loaded skills from folders on the machine. 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. 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.

{
  "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:

{
  "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. 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 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, with the URI, size and digest. It never records the content.

The 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 gives the full rules and explains the design choices.
  2. The Agent Skills specification defines the skill format.
  3. Consuming Skills describes Gatana’s tools and extension support.
  4. How to share skills across Claude Code, Codex and other agents covers skill folders, the registry and the sync hook.

FAQ

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.

All guides