微软发布MCP Skills扩展规范SEP-2640详解
Delivering Agent Skills Over MCP
面向Agent开发者的硬核工程指南，完整拆解了MCP Skills扩展的底层通信协议与数据流，直接指导技能分发架构落地。
Getting a skill working with one agent is a useful start. Sharing it with other agents raises a different question: where should that skill live?
让一个智能体（agent）能够使用某项技能是一个有用的起点。与其他智能体共享该技能则引出了另一个问题：这项技能应该存放在哪里？
You could give each agent its own copy. But when the skill changes, those copies need updating.
你可以为每个智能体提供其各自的副本。但当技能发生变更时，这些副本都需要进行更新。
The official Skills extension for Model Context Protocol (MCP) provides a standard way to make skills available from a server, so compatible agents can find and load them when needed.
Model Context Protocol (MCP) 的官方 Skills 扩展提供了一种标准方式，使技能可从服务器提供，以便兼容的智能体在需要时查找并加载它们。
Let's look at what happens across that connection, then where Microsoft Foundry fits in.
让我们先看看通过该连接会发生什么，然后再看 Microsoft Foundry 在其中扮演的角色。
What the extension adds
该扩展增加了什么
MCP already gives agents access to content from servers through resources. The Skills extension builds on that. It adds a way to ask which skills a server offers and get the details needed to load them.
MCP 已经允许智能体通过资源从服务器访问内容。Skills 扩展在此基础上进行了构建。它增加了一种询问服务器提供哪些技能并获取加载所需详细信息的方法。
It doesn't change the skill format, and it doesn't run a skill on the server. The application running your agent, called the host, still decides how to offer skills to the user or model and load the selected instructions.
它不改变技能格式，也不在服务器上运行技能。运行你智能体的应用程序（称为宿主 host）仍然决定如何向用户或模型提供技能以及如何加载所选指令。
Both the server and the host need the right support. Being able to call an MCP tool isn't enough to discover and load remote skills. A custom tool that returns skill text isn't, by itself, an implementation of this extension either.
服务器和宿主都需要适当的支持。仅仅能够调用 MCP 工具不足以发现和加载远程技能。仅返回技能文本的自定义工具本身也不是该扩展的实现。
The extension is identified as io.modelcontextprotocol/skills. Its proposal, SEP-2640, has reached Final status. Client support is still developing, so a published specification doesn't mean every MCP host supports it yet.
该扩展的标识符为 io.modelcontextprotocol/skills。其提案 SEP-2640 已达到最终状态（Final）。客户端支持仍在发展中，因此已发布的规范并不意味着所有 MCP 宿主都支持它。
How an agent gets a skill
智能体如何获取技能
The basic sequence is straightforward: find out what's available, select a skill, and read the content needed to use it. The host's MCP client handles the requests to the server.
基本流程很简单：找出可用内容、选择一项技能，并读取使用该技能所需的内容。宿主的 MCP 客户端负责向服务器发送请求。
We'll follow the case where the server provides a file list, called a manifest. It includes each file's address, size, and a SHA-256 digest: a fingerprint used to check that the file received matches what the server listed.
我们将遵循服务器提供文件列表（称为清单 manifest）的情况。清单包含每个文件的地址、大小以及 SHA-256 摘要：一种用于检查接收到的文件是否与服务器列出的内容匹配的指纹。
The examples below use a generic example-skill with two files. They illustrate the official message shapes, not a captured server session. They use protocol revision 2026-07-28 and include its required request metadata. The _meta block tells the server which protocol version and client capabilities apply to each request, including the client's Skills extension support. Both sides must declare support. Use a client and server that support this revision. The Foundry examples later follow its separately documented path.
以下示例使用一个名为 example-skill 的通用技能，其中包含两个文件。它们说明了官方的消息结构，而非捕获的服务器会话。它们使用协议修订版 2026-07-28，并包含其必需的请求元数据。_meta 块告诉服务器适用于每个请求的协议版本和客户端能力，包括客户端对 Skills 扩展的支持情况。双方都必须声明支持。请使用支持此修订版的客户端和服务器。后面的 Foundry 示例将遵循其单独记录的路径。
These examples show JSON-RPC message bodies, not complete HTTP requests. For Streamable HTTP, POST each message to the server's MCP endpoint with Content-Type: application/json, Accept: application/json, text/event-stream, and MCP-Protocol-Version: 2026-07-28 headers. Also set Mcp-Method to the body's method, such as skills/list. For resources/read, set Mcp-Name to the requested URI, such as skill://example-skill/SKILL.md. The mirrored values must match the body. See the HTTP header requirements.
这些示例展示了 JSON-RPC 消息体，而非完整的 HTTP 请求。对于 Streamable HTTP，请将每条消息 POST 到服务器的 MCP 端点，并设置 Content-Type: application/json、Accept: application/json, text/event-stream 以及 MCP-Protocol-Version: 2026-07-28 头信息。同时，将 Mcp-Method 设置为消息体的方法名，例如 skills/list。对于 resources/read，将 Mcp-Name 设置为请求的 URI，例如 skill://example-skill/SKILL.md。镜像值必须与消息体匹配。请参阅 HTTP 头要求。
Find out what's available
了解有哪些可用内容
First, the server declares that it supports resources and the Skills extension. This is the relevant fragment of its server/discover response:
首先，服务器声明它支持资源（resources）和 Skills 扩展。这是其 server/discover 响应的相关片段：
{
"capabilities": {
"resources": {},
"extensions": {
"io.modelcontextprotocol/skills": {}
}
}
}The empty extension object means skills are supported, but optional directory reading isn't enabled. The client can now ask for the available skills:
空的扩展对象表示支持技能（skills），但未启用可选的目录读取功能。客户端现在可以查询可用的技能：
{
"jsonrpc": "2.0",
"id": 1,
"method": "skills/list",
"params": {
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": {
"extensions": {
"io.modelcontextprotocol/skills": {}
}
},
"io.modelcontextprotocol/clientInfo": {
"name": "example-client",
"version": "1.0.0"
}
}
}
}Here is a response containing one skill:
以下是一个包含一个技能的响应：
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"resultType": "complete",
"skills": [
{
"uri": "skill://example-skill/SKILL.md",
"frontmatter": {
"name": "example-skill",
"description": "An example skill for this article."
},
"resources": [
{
"uri": "skill://example-skill/SKILL.md",
"digest": "sha256:d2069d0f3682fea0d69e62247386e950e9ad958bab5b186b456dc1fb8266e312",
"size": 138
},
{
"uri": "skill://example-skill/references/notes.md",
"digest": "sha256:e76b3033746e3c5d8cc970b21b15ce40f868e6902c065521a1abf373f4a19c85",
"size": 58
}
]
}
],
"ttlMs": 300000,
"cacheScope": "public"
}
}The resources array is the manifest. It lists both files, but doesn't contain their text. The host can show the skill's name and description without fetching either file. size counts bytes, not characters. The cache fields describe how long the result stays fresh and whether it can be shared. They aren't trust checks, and public here is a choice for this illustrative server, not a recommendation for private skill content.
resources 数组是清单（manifest）。它列出了两个文件，但不包含它们的文本内容。主机无需获取任一文件即可显示技能的名称和描述。size 统计的是字节数而非字符数。cache 字段描述了结果保持新鲜的时间以及是否可共享。它们不是信任检查，这里的 public 是该示例服务器的选择，而非针对私有技能内容的建议。
resultType: "complete" means this request completed, not that the server's entire catalog is in the response. If it includes nextCursor, pass that value as params.cursor on the next skills/list request. Each skill's manifest stays whole on one page.
resultType: "complete" 表示此请求已完成，并不意味着服务器的整个目录都在响应中。如果响应中包含 nextCursor，请将该值作为 params.cursor 在下一个 skills/list 请求中传递。每个技能的清单都完整地位于一页中。
The user or model can then select a relevant skill. The host keeps track of which server it came from and its address, known as a URI.
然后，用户或模型可以选择一个相关的技能。主机记录该技能来自哪个服务器及其地址，即 URI。
Read and load the instructions
读取并加载指令
After any required approval, the host uses resources/read to get the selected skill's instructions. It checks them against the details from the listing before adding them to the agent's context, the information available to the model.
在任何必需的审批之后，主机使用 resources/read 来获取所选技能的指令。在将其添加到代理的上下文（即模型可用的信息）之前，主机会根据列表中的详细信息对其进行核对。
The request uses the instruction URI from the listing:
该请求使用列表中的指令 URI：
{
"jsonrpc": "2.0",
"id": 2,
"method": "resources/read",
"params": {
"uri": "skill://example-skill/SKILL.md",
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": {
"extensions": {
"io.modelcontextprotocol/skills": {}
}
},
"io.modelcontextprotocol/clientInfo": {
"name": "example-client",
"version": "1.0.0"
}
}
}
}This time, the response contains the actual file text:
这次，响应包含了实际的文本内容：
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"resultType": "complete",
"contents": [
{
"uri": "skill://example-skill/SKILL.md",
"mimeType": "text/markdown",
"text": "---\nname: example-skill\ndescription: An example skill for this article.\n---\n\nRead references/notes.md when additional guidance is needed.\n"
}
],
"ttlMs": 300000,
"cacheScope": "public"
}
}The \n sequences represent line breaks in the file. Encoding the decoded text as UTF-8 produces 138 bytes. Computing SHA-256 over those bytes produces the digest shown in the first manifest entry. The fingerprint covers the file bytes, not the surrounding JSON response.
\n 序列代表文件中的换行符。将解码后的文本编码为 UTF-8 会产生 138 个字节。对这些字节计算 SHA-256 会得到第一个清单条目中显示的摘要。指纹覆盖的是文件字节，而非周围的 JSON 响应。
Reading the file and loading the skill are different steps. An MCP resource browser could read the same file to display it to a person. That doesn't make the skill active. The host must handle the checks and approvals that come with loading it for the agent.
读取文件和加载技能是两个不同的步骤。MCP 资源浏览器可以读取同一文件以向用户展示它。这并不会使该技能处于激活状态。主机必须处理加载供代理使用时所带来的检查和审批流程。
Get supporting files when needed
按需获取支持文件
If the agent needs a reference or another supporting file, the host reads it from the same server using resources/read. It checks that the file is in the saved manifest and that its contents match before using it.
如果代理需要参考信息或其他支持文件，主机将通过 resources/read 从同一服务器读取该文件。在使用之前，它会检查该文件是否存在于已保存的清单中，并且其内容是否匹配。
For our example, the relative reference resolves to the second URI in the manifest. When that file is needed, the client sends:
在我们的示例中，相对引用解析为清单中的第二个 URI。当需要该文件时，客户端发送：
更进一步：量化金融体系
看懂新闻只是起点——沿量化金融路径，把它变成能交付的工程能力