Skills

Discover and read Agent Skills from MCP servers

ext-skills 仓库包含官方 Skills 扩展（io.modelcontextprotocol/skills）的已发布规范。SEP-2640 已定稿。

Skills Over MCP 工作组负责维护该扩展。SDK 与宿主支持仍在实现中；当前覆盖情况请参见客户端支持矩阵和实现列表。

modelcontextprotocol/ext-skills

Skills over MCP 的规范与文档。

Skills 扩展允许 MCP 服务端向客户端暴露工作流指令及其支持文件。客户端可以发现可用的技能、获取其元数据，并使用现有的 Resources 原语读取其内容。

一个技能是一个目录，其中包含一个 SKILL.md 文件和可选的支持文件，遵循 Agent Skills 规范。本扩展定义了通过 MCP 进行发现与获取的方式。

技能适用于组合多个工具或需要支持性参考资料的可复用工作流，例如代码审查或文档处理。通过 MCP 提供这些技能，可使指令与其所描述的服务保持在一起。客户端可以从元数据中发现可用的工作流，并仅在需要时加载指令和支持文件。

用户交互模型

宿主应用决定技能如何暴露给模型和用户。技能可以由模型根据其名称和描述进行选择，也可以由用户显式选择。本扩展不强制规定特定的用户交互模型。

通过 resources/read 读取 SKILL.md 本身并不会激活技能。要加载技能，宿主会将读取路由到其技能加载路径，该路径会验证内容并在加载到模型上下文之前应用任何所需的用户批准。

能力

支持 Skills 的服务端 MUST（必须）在 server/discover 中同时声明 resources 能力和 io.modelcontextprotocol/skills 扩展：

json

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

声明此扩展的服务端 MUST（必须）实现 skills/list 和 skills/get。技能文件通过 resources/read 提供。

可选的 directoryRead 设置表示支持 resources/directory/read，默认为 false。空的扩展对象表示支持但不支持目录读取。客户端仅在观察到服务端的声明后才发出 skills/list 和 skills/get。

NOTE

这些示例使用协议修订版 2026-07-28 或更高版本。为简洁起见，请求示例省略了 _meta。每个请求 MUST（必须）包含所需的请求元数据。

协议消息

列出技能

为发现可用技能，客户端发送 skills/list 请求。此操作支持分页和缓存。

请求：

json

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

响应：

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete",
    "skills": [
      {
        "uri": "skill://code-review/SKILL.md",
        "frontmatter": {
          "name": "code-review",
          "description": "Review code using the team's checklist."
        },
        "resources": [
          {
            "uri": "skill://code-review/SKILL.md",
            "digest": "sha256:d2489d6c182e8df9c178563ff9f2eac7998a0c1bb1278c52a7fd5306e4259160",
            "size": 149
          },
          {
            "uri": "skill://code-review/references/checklist.md",
            "digest": "sha256:dbab2de7bf7db9cc95cb6ce681c3690b26184db39f75b958a0287ca6d9e24e20",
            "size": 65
          }
        ]
      }
    ],
    "ttlMs": 300000,
    "cacheScope": "public"
  }
}

每个条目包含：

Field	Meaning
`uri`	技能 `SKILL.md` 的资源 URI。
`frontmatter`	所有 YAML frontmatter 字段，保持不变，包括 `name` 和 `description`。
`resources`	完整的文件清单，或对于生成的内容为 `"dynamic"`。

清单 MUST（必须）包含 SKILL.md 及每个支持文件，并带有每个文件的 URI、SHA-256 摘要和字节大小。skills/list 返回的每个条目都是完整的；客户端无需调用 skills/get 获取额外元数据。

当响应包含 nextCursor 时，客户端将其作为 params.cursor 传入以获取下一页。列表和获取结果 MUST（必须）包含 resultType: "complete"、ttlMs 和 cacheScope。缓存字段描述新鲜度和共享性；它们不提供内容完整性。

技能身份由来源服务端的身份和技能 URI 组成。名称只是标签，不保证唯一。宿主 MUST（必须）在注册表、批准和缓存中同时保留服务端身份和 URI。服务端 SHOULD（应该）使用 skill:// 方案，但 MAY（可以）使用其他方案。宿主 MUST NOT（不得）仅凭 URI 方案将资源识别为技能。

获取技能

要通过 URI 获取技能条目，客户端发送 skills/get 请求。URI 可以由用户、另一个技能或服务端指令提供。

请求：

json

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "skills/get",
  "params": {
    "uri": "skill://code-review/SKILL.md"
  }
}

响应在 result.skill 下包含一个技能条目，其形状与 skills/list 中的条目相同，并带有 resultType: "complete"、ttlMs 和 cacheScope。客户端也可以使用此方法刷新现有条目。

服务端 MAY（可以）返回空或部分列表，但 MUST（必须）对其提供的每个技能响应 skills/get。宿主 MUST（必须）支持按 URI 加载，包括未出现在列表中的技能。

读取技能内容

要获取技能指令或支持文件，客户端发送 resources/read 请求。此示例从上面的列表中获取 SKILL.md。

请求：

json

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/read",
  "params": {
    "uri": "skill://code-review/SKILL.md"
  }
}

响应：

json

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "resultType": "complete",
    "contents": [
      {
        "uri": "skill://code-review/SKILL.md",
        "mimeType": "text/markdown",
        "text": "---\nname: code-review\ndescription: Review code using the team's checklist.\n---\n\n# Code review\n\nRead `references/checklist.md`, then review the diff.\n"
      }
    ],
    "ttlMs": 300000,
    "cacheScope": "public"
  }
}

SKILL.md 文件 MUST（必须）以包含 name 和 description 的 YAML frontmatter 开头。其父目录路径的最后一段 MUST（必须）与 name 匹配。

客户端相对于技能的根目录解析相对引用。在此示例中，references/checklist.md 解析为 skill://code-review/references/checklist.md。支持文件使用 resources/read 从同一服务端获取，其内容为：

markdown

# Review checklist

Check correctness, tests, and compatibility.

两个示例文件均以换行符结尾；其摘要和大小与清单匹配。宿主 MUST NOT（不得）在需要之前获取文件，包括在连接、列表或批准时。批准绑定到清单，无需获取文件。

读取目录

要列出目录的直接子项，客户端发送 resources/directory/read 请求。此方法为可选。除非服务端声明 directoryRead: true，否则客户端 MUST NOT（不得）调用它。

请求：

json

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "resources/directory/read",
  "params": {
    "uri": "skill://code-review/references"
  }
}

响应：

json

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "resultType": "complete",
    "resources": [
      {
        "uri": "skill://code-review/references/checklist.md",
        "name": "checklist.md",
        "mimeType": "text/markdown"
      }
    ]
  }
}

目录 URI 没有尾部斜杠。子目录使用 mimeType: "inode/directory"。客户端通过为子目录发出另一个请求来向下遍历。结果支持 cursor / nextCursor 分页，且仅包含直接子项。

对于具有清单的技能，宿主 MAY（可以）从该清单回答目录查询。目录读取也支持动态技能和其他资源树。宿主 MUST NOT（不得）将实时目录结果视为对保留清单的扩展，也不得将新列出的文件作为技能的一部分暴露。访问这些文件需要刷新条目并获得任何所需的用户批准。

消息流

此示例展示了在发现服务端能力之后，加载一个带有文件清单的技能。宿主的 MCP 客户端发送协议请求。技能选择和用户批准是宿主交互。

sequenceDiagram
    actor User
    participant Model
    participant Host
    participant Server

    opt Discover a catalog
        Host->>Server: skills/list
        Server-->>Host: Skill entries with frontmatter and manifests
        Host->>Model: Available skills and their origins
        Host->>User: Available skills and their origins
    end

    alt Model selects a skill
        Model->>Host: Load skill (server, URI)
    else User selects a skill
        User->>Host: Load skill (server, URI)
    end

    opt Host has only a URI
        Host->>Server: skills/get (URI)
        Server-->>Host: Skill entry or error
    end
    break Lookup failed
        Note over Host,Server: Stop loading (unknown skill: -32602)
    end
    Note over Host: Retain entry (server, URI)

    opt User approval required
        Host->>User: Request approval for this skill and manifest
        User-->>Host: Approve
    end

    Host->>Server: resources/read (SKILL.md URI)
    Server-->>Host: SKILL.md content
    Host->>Host: Verify byte size, digest, and frontmatter
    Host->>Model: Load verified instructions with server origin

    loop Supporting files requested while the skill is active
        Model->>Host: Read a supporting file
        Host->>Host: Resolve URI within the retained manifest
        Host->>Server: resources/read (file URI)
        Server-->>Host: File content
        Host->>Host: Verify byte size and digest
        Host->>Model: Verified content with server origin
    end

已知 URI 可以在不列出列表的情况下加载。skills/list 返回的条目可以复用；否则，宿主调用 skills/get。未列出的技能可能仍然存在，但未知 URI 会返回 -32602（Invalid params）并停止加载。所有技能读取都使用来源服务端。

如果查找失败、批准被拒绝或验证失败，宿主不会加载或使用该内容。从已更改的清单中恢复需要刷新条目并再次获得任何所需的批准，如下所述。

完整性与验证

在操作技能期间，宿主保留用于加载它的条目。此期间至少持续到该技能的 SKILL.md 离开模型上下文。对于具有清单的技能，宿主 MUST（必须）：

将文件读取限制在保留清单中的 URI。
在使用前验证每个文件的原始字节大小和 SHA-256 摘要。
解析 SKILL.md frontmatter 并将其与条目的 frontmatter 逐字段比较。

宿主 MUST NOT（不得）使用验证失败的内容。要从过时元数据中恢复，宿主使用 skills/get 刷新条目。持久化的批准 MUST（必须）绑定到完整的文件 URI 和摘要集合。文件发生更改、添加或删除会撤销该批准；宿主 MUST（必须）在加载或执行之前再次获得批准。

宿主 SHOULD（应该）按需缓存已验证的内容。磁盘缓存 MUST（必须）要么防止模型、其工具或其他用户的修改并保持文件不可变，要么在每次访问时验证缓存的字节。宿主 MUST（必须）将缓存文件排除在文件系统技能发现路径之外，并保留其 MCP 来源，包括在重启之后。

NOTE

摘要建立的是与服务端清单的一致性，而非对其内容的信任。对于没有稳定摘要的生成内容，条目使用 "resources": "dynamic"。宿主 MAY（可以）拒绝这些技能。如果接受，宿主 MUST（必须）仍然验证 frontmatter，且 MUST NOT（不得）将持久化的批准视为覆盖任意未来内容。

实现要求

服务端

服务端 MUST（必须）：

提供有效的 Agent Skills 并实现所声明的方法，包括基础 Resources 支持。
保留所有 frontmatter 字段，并发布根据所提供字节计算出的完整清单，除非该技能的资源被声明为 "dynamic"。
支持独立于列表的直接查找。每个技能条目是原子的；其清单 MUST NOT（不得）跨页拆分。
在声明 directoryRead: true 时，支持所提供技能命名空间中的每个目录。

服务端 SHOULD NOT（不应）超过每个技能 512 个文件或 16 MiB，包括 SKILL.md。宿主 MUST（必须）支持达到这些限制的技能，并 MAY（可以）支持更大的技能。

安全考虑

宿主 MUST（必须）：

防止同名技能相互静默替换。
用来源服务端标记已加载的内容，并使用宿主分配的标签将资源读取绑定到该服务端。跨服务端读取需要显式的逐调用批准，并指明两个服务端。
将技能内容视为不可信输入。宿主侧代码执行和诸如 allowed-tools 之类的权限授予需要显式的逐技能用户批准。
在激活嵌套技能之前获得新的用户同意。将其 SKILL.md 作为支持内容读取不会激活它或其 frontmatter。

完整的批准、来源和缓存规则请参见安全要求。

错误处理

Condition	Handling
未知技能/文件，或无效的目录 URI	JSON-RPC `-32602`（Invalid params）。
服务端内部故障	JSON-RPC `-32603`（Internal error）。
摘要、大小、frontmatter 或清单不匹配	宿主拒绝内容并刷新条目。

验证失败是宿主侧的情况，而非协议错误。它们按完整性与验证中所述处理。

客户端支持

Skills 支持情况及实现文档链接请参见客户端矩阵。

规范

完整规范位于 ext-skills 仓库。开发由 Skills Over MCP 工作组协调。

Skills

用户交互模型

能力

协议消息

列出技能

获取技能

读取技能内容

读取目录

消息流

完整性与验证

实现要求

服务端

安全考虑

错误处理

客户端支持

规范

友情链接