MCP Skills Extension

Appearance

Overview ​

The Model Context Protocol (MCP) Skills extension allows servers to publish skills alongside the tools, resources, and prompts they already serve. A skill is a directory of files, minimally a SKILL.md, that provides structured workflow instructions to an agent. Skills are addressed by the URI of their SKILL.md and may be read directly whether or not the server enumerates them.

Skills are useful for shipping the instructions for using a server together with the server itself, for workflows too large to fit in server instructions, and for orchestration that spans several tools or servers.

Extension Identifier ​

This extension is identified as: io.modelcontextprotocol/skills.

Capability Negotiation ​

Servers declare support for this extension in the extensions field of their capabilities in server/discover:

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

One extension-specific setting is defined:

SettingTypeDefaultMeaning
directoryReadbooleanfalseThe server implements resources/directory/read.

An empty object indicates support for the extension with no optional features.

  • A server that declares this extension MUST implement skills/list and skills/get.
  • A server that additionally declares directoryRead: true MUST implement resources/directory/read.
  • Clients MUST NOT call resources/directory/read against a server that has not declared directoryRead: true.
  • This extension depends only on the base protocol's Resources primitive. Skill files are served through resources/read, and the base Resources specification requires any server that supports resources to declare the resources capability. A server declaring this extension therefore MUST also declare the resources capability.

Clients issue skills/list and skills/get only after observing the server's declaration. To a client that does not implement this extension, skill:// resources are ordinary resources.

Skill Format ​

A skill served over MCP MUST conform to the Agent Skills specification. In particular:

  • A skill is a directory. Its skill name is the value of the name field in its SKILL.md frontmatter.
  • Every skill MUST contain a SKILL.md file at its root.
  • SKILL.md MUST begin with YAML frontmatter containing at minimum the name and description fields as defined by the Agent Skills specification.
  • A skill MAY contain additional files and subdirectories (references, scripts, examples, assets).

This extension does not redefine, constrain, or extend the skill format. Future revisions of the Agent Skills specification apply automatically. In the event that the Agent Skills specification changes in a backwards incompatible way, clients MUST honor any backwards compatibility mechanisms provided by the Agent Skills specification and SHOULD continue to support the Agent Skills specification as it existed prior to any incompatible change.

Listing Skills ​

A server declaring this extension MUST implement the skills/list method, which returns entries for the skills it serves. This operation supports pagination.

Getting a Skill ​

A server declaring this extension MUST implement the skills/get method, which returns the entry for a single skill named by the URI of its SKILL.md.

Reading Skill Content ​

Skill files are read via the standard resources/read method. No skill-specific read semantics are defined.

Reading a SKILL.md via resources/read does not by itself activate the skill. resources/read is transport. It returns bytes to whatever asked for them, whether a generic resource-reading tool, a resource browser, or a user inspecting the server. A skill is activated only by the host's own skill-loading path, which verifies the content against the skill's entry (Integrity and Verification), applies any required user approval (Security Considerations), and opens the window in which the host is acting on the skill.

  • Hosts MUST NOT treat a resources/read of a SKILL.md that arrives by any other route as a load. Such a read grants no approval, opens no acting window, and confers no standing on the skill's supporting files.
  • Content obtained that way is ordinary resource content, and a host that returns it to the model SHOULD do so as it would any other resource read, not as a loaded skill.
  • A host that wants such a read to load the skill routes it through the skill-loading path instead.

Relative References ​

Internal references within a skill (for example, SKILL.md linking to references/GUIDE.md) are relative paths, as in the filesystem form of the Agent Skills specification. A client resolves a relative reference against the skill's root, as a filesystem path would resolve. For example, references/GUIDE.md in skill://acme/billing/refunds/SKILL.md resolves to skill://acme/billing/refunds/references/GUIDE.md. The skill's root is the directory containing SKILL.md, not the scheme root. When skills nest, each SKILL.md's references resolve against its own directory, so a relative reference in a nested skill's SKILL.md resolves against the nested skill's root regardless of how the file was reached.

Reading Directories ​

A skill's instructions frequently reference a directory rather than a file, for example "pick the appropriate template from templates/" or "run the matching script in scripts/". To act on this, the agent must learn what the directory contains. resources/list enumerates the server's entire resource space rather than a subtree, and servers with large or generated catalogs may not implement meaningful global listing at all. This extension therefore defines the resources/directory/read method, gated behind the directoryRead capability setting.

Integrity and Verification ​

Digests are SHA-256 hashes of a file's raw bytes, formatted as sha256:{hex} where {hex} is 64 lowercase hexadecimal characters. Each SkillResource in a skill's resources carries the digest of the file at its uri.

For verification requirements and the skill-loading lifecycle, see Integrity and Verification.

Learn More ​