SEP-2640: Skills Extension

​

Abstract

​

Motivation

• Fragmented distribution. A server and the skill that teaches an agent to use it are versioned, discovered, and installed separately. Users installing a server from a registry have no signal that a companion skill exists. (problem statement)
• Instruction size limits. Server instructions are delivered as the instructions field of the server/discover result and are practically bounded in size. Complex workflows — such as the 875-line mcpGraph skill — do not fit this model. (experimental findings)
• Inconsistent ad-hoc solutions. Absent a convention, several independent implementations have each invented their own skill:// URI structure, with diverging semantics for authority, path, and sub-resource addressing.

​

Specification

​

Dependencies

​

Skill Format

• 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).

​

Resource Mapping

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

• <skill-path> is a /-separated path of one or more segments locating the skill directory within the server’s skill namespace. It MAY be a single segment (git-workflow) or nested to arbitrary depth (acme/billing/refunds).
• <file-path> is the file’s path relative to the skill directory root, using / as the separator.

• A SKILL.md MAY appear in a descendant directory of a skill — skills can nest. See Nested skills.
• The final <skill-path> segment, being the skill name, MUST satisfy the Agent Skills specification’s naming rules. The first <skill-path> segment occupies the authority component and SHOULD be a valid reg-name per RFC 3986; any other prefix segments SHOULD be valid URI path segments; no further constraints are imposed on them.

​

Examples

​

Resource Metadata

• mimeType SHOULD be text/markdown.
• name SHOULD be set from the name field of the SKILL.md YAML frontmatter. By the path constraint above, this will equal the final segment of <skill-path>.
• description SHOULD be set from the description field of the SKILL.md YAML frontmatter.

​

Nested skills

• Nested content is supporting content. From the enclosing skill’s perspective, a nested skill’s directory and files are ordinary supporting files, and reading them is ordinary reading. A nested SKILL.md read this way is ordinary markdown: hosts MUST NOT act on its frontmatter.
• Activation requires fresh consent. Approval is per skill: approving a skill approves that skill alone and says nothing about skills nested within it. Activating a nested skill — loading it as a skill in its own right, whether through the host’s skill-loading machinery or by giving effect to its frontmatter — requires fresh, explicit user consent; approval of the enclosing skill does not substitute for it. Once activated, a nested skill is an ordinary skill: its frontmatter takes effect under the same rules as any other MCP-served skill, including the approval gate on allowed-tools.
• Publication is flat. A nested skill is published like any other: through its own skills/list entry, or by explicit reference. The listing remains flat — an entry for a nested skill is an ordinary entry whose uri happens to share a path prefix with the enclosing skill’s, and nothing in the listing marks nesting.

​

Discovery

​

Enumeration via skills/list

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "skills/list",
  "params": {}
}

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "skills": [
      {
        "uri": "skill://git-workflow/SKILL.md",
        "frontmatter": {
          "name": "git-workflow",
          "description": "Follow this team's Git conventions for branching and commits"
        },
        "resources": [
          {
            "uri": "skill://git-workflow/SKILL.md",
            "digest": "sha256:a1b2c3d4..."
          }
        ]
      },
      {
        "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:b2c3d4e5..."
          },
          {
            "uri": "skill://acme/billing/refunds/examples/email.md",
            "digest": "sha256:c3d4e5f6..."
          }
        ]
      },
      {
        "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..."
          },
          {
            "uri": "skill://pdf-processing/references/FORMS.md",
            "digest": "sha256:e6f7a8b9..."
          },
          {
            "uri": "skill://pdf-processing/scripts/extract.py",
            "digest": "sha256:f7a8b9c0..."
          },
          {
            "uri": "skill://pdf-processing/templates/invoice.md",
            "digest": "sha256:a8b9c0d1..."
          },
          {
            "uri": "skill://pdf-processing/templates/purchase-order.md",
            "digest": "sha256:b9c0d1e2..."
          },
          {
            "uri": "skill://pdf-processing/templates/regional/eu-invoice.md",
            "digest": "sha256:c0d1e2f3..."
          }
        ]
      }
    ]
  }
}

Names

Frontmatter

Skill URIs

Resources

• When present, resources MUST be complete: it lists every file of the skill, each exactly once, including an entry matching the skill’s top-level uri — that entry carries the digest of SKILL.md itself.
• Each uri MUST be the skill’s SKILL.md or a file within the skill’s directory.
• Completeness extends to nested skills: from the enclosing skill’s perspective their files are supporting files (Nested skills), so the enclosing skill’s resources lists them too, and the same file may appear in both the enclosing and the nested skill’s entries. A change to a nested skill is therefore a change to the enclosing skill’s set.
• resources MAY be omitted only when a skill’s content is generated dynamically, such that stable digests cannot be published. A skill without resources offers no content integrity and cannot be content-bound (Security Implications). Hosts MAY decline to load such skills, and server authors SHOULD expect that some hosts will.

Integrity and verification

​

Retrieval via skills/get

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

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "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..."
        },
        {
          "uri": "skill://pdf-processing/references/FORMS.md",
          "digest": "sha256:e6f7a8b9..."
        },
        {
          "uri": "skill://pdf-processing/scripts/extract.py",
          "digest": "sha256:f7a8b9c0..."
        },
        {
          "uri": "skill://pdf-processing/templates/invoice.md",
          "digest": "sha256:a8b9c0d1..."
        },
        {
          "uri": "skill://pdf-processing/templates/purchase-order.md",
          "digest": "sha256:b9c0d1e2..."
        },
        {
          "uri": "skill://pdf-processing/templates/regional/eu-invoice.md",
          "digest": "sha256:c0d1e2f3..."
        }
      ]
    }
  }
}

• If the URI does not identify a skill the server serves, the server MUST return error -32602 (Invalid params) — the same code resources/read uses for unknown resources.
• A server MUST answer for every skill it serves, whether or not that skill appears in its skills/list result. A skill absent from a partial listing is still retrievable by URI.
• The result is a point-in-time snapshot, exactly as a listing entry is. Re-calling the method is how a host refreshes one skill’s digests without re-enumerating the catalog.
• A skill whose content is generated dynamically omits resources, per Resources, whether it is reached through skills/list or skills/get.
• The result carries no pagination cursor: a single entry is not a list. The entry is a snapshot of the skill as the server holds it at that moment; whether the result should also carry the base protocol’s caching attributes (ttlMs and cacheScope, per SEP-2549), as resources/read results do, is left open.

​

Pointer from Server Instructions

​

Capability Declaration

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

​

Reading

​

Directory Listing

​

Directory resources

​

resources/directory/read

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "resources/directory/read",
  "params": {
    "uri": "skill://pdf-processing/templates"
  }
}

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "resources": [
      {
        "uri": "skill://pdf-processing/templates/invoice.md",
        "name": "invoice.md",
        "mimeType": "text/markdown"
      },
      {
        "uri": "skill://pdf-processing/templates/purchase-order.md",
        "name": "purchase-order.md",
        "mimeType": "text/markdown"
      },
      {
        "uri": "skill://pdf-processing/templates/regional",
        "name": "regional",
        "mimeType": "inode/directory"
      }
    ]
  }
}

• The method applies only to directory resources. If the URI does not exist, or exists but is not a directory resource, the server MUST return error -32602 (Invalid params) — the same code resources/read uses for unknown resources.
• The result contains every direct child of the directory: files with their ordinary resource metadata, subdirectories listed as directory resources (mimeType: "inode/directory"). The listing is not recursive; clients descend by calling the method again on a child directory.
• An empty directory yields an empty resources array.
• Pagination mirrors resources/list: when the result includes nextCursor, the client passes it back as cursor to retrieve the next page.

​

Implementation Guidelines

​

Hosts: End-to-End Integration

{
  "name": "read_skill",
  "description": "Load a skill's SKILL.md into context.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "name": { "type": "string", "description": "The skill name" }
    },
    "required": ["name"]
  }
}

{
  "name": "read_resource",
  "description": "Read an MCP resource from a connected server.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "server": {
        "type": "string",
        "description": "Name of the connected MCP server"
      },
      "uri": { "type": "string", "description": "The resource URI" }
    },
    "required": ["server", "uri"]
  }
}

​

SDKs: Convenience Wrappers

@server.skill("git-workflow")                 # → skill://git-workflow/SKILL.md
def git_workflow():
    return Path("./skills/git-workflow")

@server.skill("acme/billing/refunds")         # → skill://acme/billing/refunds/SKILL.md
def refunds():
    return Path("./skills/refunds")

skills = await client.list_skills()               # calls skills/list, paginating; may be empty
entry = await client.get_skill(
    "skill://acme/billing/refunds/SKILL.md")      # calls skills/get, listed or not
content = await client.read_skill_uri(
    "skill://acme/billing/refunds/SKILL.md")      # wraps resources/read, works regardless of enumeration
entries = await client.read_directory(
    "skill://pdf-processing/templates")           # wraps resources/directory/read

​

Rationale

​

Why Resources Instead of a New Primitive?

​

Why skill://<path>/<file> With an Explicit SKILL.md?

• It directly mirrors the Agent Skills specification’s directory model. A skill is a directory; its URI space should look like one.
• SKILL.md being explicit means supporting files are siblings at the same level, with no special casing for “the skill URI” versus “a file in the skill.”
• Hosts implementing both filesystem and MCP skills can use one path-resolution codepath.

​

Why Allow a Path Prefix But Constrain the Final Segment?

​

Why May the Listing Be Empty or Partial?

​

Why skills/get Alongside skills/list?

​

Why a Method Instead of a Well-Known Index Resource?

​

Why Delegate the Format to agentskills.io?

​

Why a Directory Read Method?

​

Why Verbatim Frontmatter in the Listing?

​

Why Per-File Digests Instead of a Single Skill Digest?

​

Backward Compatibility

​

Security Implications

• Skill content is untrusted input. Hosts MUST treat MCP-served skill content as untrusted model input, subject to the same prompt-injection defenses applied to any server-provided text. A server being connected does not make its skill content authoritative.
• Origin MUST be visible to the model. Hosts MUST tag MCP-served skill content with its originating server identity at the point it enters model context and MUST NOT present an MCP-served skill to the model as indistinguishable from a local filesystem skill. The model, not the host, decides whether to follow a skill’s instructions. Withholding origin from it makes the untrusted-input requirement above unenforceable at the layer that acts on it.
• Skills introduce host-side surfaces that tools do not. Unlike a remote tool call, an MCP-served skill can place server-authored bytes on the host filesystem and direct the model to execute them with host-side tools. Hosts MUST treat MCP-served skills as a higher-risk surface than remote tool invocation.
• No implicit local execution. Hosts MUST NOT allow MCP-served skill content to cause host-side code execution without explicit per-skill user approval. This covers (a) declarative fields the host parses (hooks, frontmatter scripts) and (b) instructions in the skill body that direct the model to invoke any host code-execution tool, whether to run a script bundled in the skill or to run an arbitrary command the skill specifies. Hosts MUST ignore or approval-gate (a), and MUST apply the same approval gate to code-execution tool calls issued while the model is acting on an MCP-served skill.
• Origin-scoped resource reads. A model-callable resource-read surface (such as the read_resource pattern in Hosts: End-to-End Integration) is a cross-server confused-deputy vector when driven by untrusted skill content. Hosts MUST bind such reads to the skill’s originating server: a skill served by server A MUST NOT cause a resources/read against server B. Hosts MUST identify servers by a host-assigned label, not the server’s self-reported serverInfo.name. Any cross-origin read MUST be gated behind explicit per-call user approval naming both servers.
• Name collisions are an impersonation surface. Skill names are not unique across origins, and a malicious server can publish a skill under the name of a popular one — another server’s, or the user’s own local skill — counting on the host resolving its way. Hosts MUST resolve skill names within a per-origin namespace, identifying servers by a host-assigned label, not the self-reported serverInfo.name; MUST NOT let an MCP-served skill silently shadow, replace, or intercept invocations of a same-named skill from any other origin, including the host’s filesystem skills; and SHOULD surface collisions to the user. A name binds to whatever bytes its origin currently serves — it carries no authorship or endorsement. Intermediaries MAY attach provenance or verification annotations via _meta under their own reverse-domain prefix — not the io.modelcontextprotocol.skills/ prefix reserved for this extension (Resource Metadata); this extension assigns such annotations no semantics.
• No implicit permission grants. Hosts MUST NOT honor frontmatter fields that widen the model’s tool or filesystem permissions when the skill arrives over MCP. In particular, the Agent Skills allowed-tools field, which a filesystem-sourced skill uses to declare the tools available while it runs, MUST be ignored for MCP-origin skills unless the user has explicitly approved that grant for that skill. A remote server populating allowed-tools is requesting elevated access on the host, not declaring a property of its own environment. Approval of a skill never extends to the frontmatter of any other SKILL.md within its file space: a nested skill’s allowed-tools has no effect unless that nested skill is itself activated under its own approval (Nested skills).
• Skills are data, not directives. Hosts MUST NOT treat skill resources as higher-authority than other context. Explicit user policy governs whether a skill is loaded at all.
• Nested skill consent. Approval is per skill: approving a skill does not approve skills nested within it. Activating a nested SKILL.md requires fresh, explicit user consent, per Nested skills. Silently promoting a file of an approved skill to an active skill would let a server ride new instructions and permission requests in on a prior approval.
• Provenance and inspection. Hosts SHOULD indicate which server a skill originates from when presenting it, SHOULD let users inspect a skill’s content before it is loaded into model context, and MAY gate loading behind per-skill or per-server user approval.
• Digests are not a security boundary. Listing digests are unsigned and come from the same server as the content. They confirm consistency between the listing and what was fetched, as described in Integrity and verification, but they cannot establish trust in the content, defend against the server itself, or detect an intermediary that rewrites both together.
• Content-bound approval. When a host persists any per-skill user approval, it MUST be bound to the entry’s resources set — every uri and digest — observed at the moment of approval. If a subsequent entry for that skill — from skills/list or skills/get — advertises a different set, whether a file was rotated, added, or removed, the host MUST treat the prior approval as revoked and re-prompt before loading or executing. A host need not poll for changes. While it holds the approved entry, content that has moved fails verification when read; and if it does fetch a fresh entry, the rule above revokes the approval. Neither path lets moved content through under the old approval. A skill published without resources cannot be content-bound: hosts MAY decline to load it, and MUST NOT treat a persisted approval as covering whatever content the server currently serves. Digest verification (Integrity and verification) defends the approval after it is granted - it cannot establish that the content was trustworthy when the user approved it, because the server authors both the listing and the body.
• Cache isolation and durable origin. Hosts that cache MCP-served skill content on disk MUST do so in a location excluded from every filesystem-skill discovery path, and MUST treat content loaded from that location as having arrived over MCP for all purposes of the no-implicit-local-execution rule above, including after host restart and after the originating server is disconnected. Cached bytes do not graduate to filesystem-skill trust by residing locally. Hosts SHOULD remove a server’s cached skill content when the user removes that server.

​

Reference Implementation

• TypeScript SDK convenience wrappers (@server.skill(), client.listSkills(), client.readSkillUri()): experimental-ext-skills#71

• gemini-cli: olaservo/gemini-cli#1
• fast-agent: olaservo/fast-agent#1
• goose: olaservo/goose#1
• codex: olaservo/codex#1
• Claude Code: prototyped internally at Anthropic; not yet public

• GitHub MCP Server: github/github-mcp-server#2360

​

Appendix: Deferred Features

​

Archive Distribution

• Unpacking is an attack surface disproportionate to the benefit. Safely extracting an archive supplied by a remote server means defending against decompression bombs, path traversal, links resolving outside the skill directory, case- and Unicode-normalization collisions that silently overwrite SKILL.md, setuid and setgid bits, and non-regular file entries such as device nodes. Every host would have to implement that checklist correctly, and a host that got any item wrong would be exploitable by any server it connects to. Serving a skill as individually addressable resources has no comparable surface.
• Two ways to serve one skill is a compatibility hazard. Archives were a second encoding of content the protocol could already express. Hosts would have to support both forms to be certain of reading any skill, and a skill offered only as an archive would be unreadable to a host that implemented individual-file reads alone. A single retrieval form keeps the compatibility floor flat: any conforming host can read any conforming skill.

​

References

• Agent Skills specification
• SEP-2549: TTL for list results
• SEP-2076: Agent Skills as first-class primitive (alternative approach)
• Skills Over MCP Working Group charter
• Decision Log — Working Group decisions and rationale
• Experimental Findings — results from implementations (WIP)
• Related Work — survey of existing skill-serving implementations
• Skill _meta Keys — _meta key conventions for skill resources
• RFC 3986: URIs