mcp-use Skills over MCP 实战:以 purchase-order 模板为例构建带策略与模板文件的 Agent Skill
mcp-use Skills over MCP 实战:以 purchase-order 模板为例构建带策略与模板文件的 Agent Skill
导读
本篇文章聚焦 mcp-use(TypeScript 服务端)内置的 Skills over MCP 机制,以仓库中的 skills-over-mcp 示例为核心案例,深入讲解一个完整的 Agent Skill 是如何由 SKILL.md、策略参考文档(references)与输出模板(templates)三类文件构成,并被 MCP 客户端发现、读取和执行的。读完本文,你将掌握 Skill 目录的约定结构、skill:// 资源 URI 的寻址方式、pnpm dev 启动后的验证流程,以及 mcp-use 服务端在 runtime.ts 中如何把技能注册为 MCP 协议资源与请求处理器。
一、示例全景:一个自动发现 skills/ 目录的 MCP 服务端
在仓库 libraries/typescript/packages/server/examples/skills-over-mcp 目录下,mcp-use 提供了一个名为 skills-over-mcp 的最小示例。它的 README.md 明确指出:
This server automatically discovers the adjacent
skills/directory and publishesrefundsandpurchasingAgent Skills alongside their tools.
也就是说,只要在服务端源码旁放置一个 skills/ 目录,mcp-use 就会自动发现它,并把其中定义的 Agent Skill 与工具一起发布,无需任何额外注册代码。整个示例目录结构如下:
examples/skills-over-mcp/
├── README.md
├── package.json
├── src/
│ └── index.ts # 定义三个 MCP 工具的服务端入口
└── skills/
├── purchasing/
│ ├── SKILL.md # 采购技能入口:技能元信息 + 操作指引
│ ├── references/
│ │ └── approval-policy.md # 策略参考:审批规则
│ └── templates/
│ └── purchase-order.md # 输出模板:采购订单确认
└── refunds/
├── SKILL.md
├── references/
│ └── policy.md
└── templates/
└── confirmation.md
其中 src/index.ts 只做了一件事:创建一个 MCPServer 实例并注册 refund-order、create-purchase-order、get-order-status 三个工具,代码注释里明确写着“The adjacent skills/ directory is discovered automatically by mcp-use.”。技能相关的全部逻辑都不在服务端代码里,而在于 skills/ 目录的文件组织。
一个技能的三类文件分工
从 purchasing 与 refunds 两个技能可以归纳出 Agent Skill 的标准构成:
| 文件 | 作用 | 由谁消费 |
|---|---|---|
SKILL.md |
技能入口,含 YAML frontmatter(name/description)与操作指引 |
Skill 感知的宿主(Host)通过 skill:// 读取 |
references/*.md |
策略、规则等背景知识,供 Agent 在执行前查阅 | 宿主作为 MCP 资源按需读取 |
templates/*.md |
输出模板,规范 Agent 的最终回复格式 | 宿主作为 MCP 资源读取后套用 |
这种“入口 + 策略 + 模板”的组织方式,让技能指令与业务策略解耦:策略可以频繁更新而无需改动代码,模板则保证 Agent 面向用户的输出稳定一致。
二、聚焦 purchasing 技能:从审批策略到订单模板
本文的关联文档 purchase-order.md 是 purchasing 技能的输出模板。它位于 skills/purchasing/templates/ 目录,全文如下:
# Purchase order confirmation
Your purchase order has been created. Purchasing will confirm the expected
delivery date with the supplier.
这份模板虽然简短,却在技能流程中承担明确的职责:当 create-purchase-order 工具成功执行后,Agent 应使用该模板向用户输出确认信息,告知订单已创建、采购部门将与供应商确认预计交付日期。
SKILL.md:技能的“操作手册”
模板由 SKILL.md 引用,后者定义了技能的使用流程:
---
name: purchasing
description: Create approved purchase orders with the create-purchase-order tool
---
# Purchasing
Before creating a purchase order, read the
<a href="https://link.gitcode.com/i/ce91903d888e3111e76247cfeec67ea8" target="_blank">approval policy</a>. When the purchase is
approved, call `create-purchase-order` with the SKU and requested quantity.
Use <a href="https://link.gitcode.com/i/dce019fa694a5039e91360eababb2c11" target="_blank">the order template</a> when confirming the
purchase.
从源码结构看,SKILL.md 的 frontmatter(name 与 description)会被解析并作为技能元信息对外暴露,正文则是给 Agent 的指令:先读审批策略 → 确认已审批 → 调用工具 → 用模板确认。注意其中的链接均为技能内部相对路径,指向同目录下的 references/ 与 templates/,宿主在读取 SKILL.md 后可以顺着这些引用继续读取策略与模板资源。
审批策略:执行前的强制前置条件
approval-policy.md 内容如下:
# Purchase approval policy
Purchases require manager approval before a purchase order is created. Ask for
clarification when approval is missing or the requested quantity is unknown.
它定义了采购业务的硬性约束:创建采购订单前必须获得经理审批;当审批缺失或数量未知时,Agent 应向用户澄清,而不是直接调用工具。这正是 Skills over MCP 相对于纯工具注册的核心价值——工具只声明“能做什么”(create-purchase-order),而技能通过策略文件告诉 Agent“什么时候该做、做之前要检查什么”。
配套工具:create-purchase-order 的参数契约
SKILL.md 要求调用 create-purchase-order 并传入 SKU 与数量,对应的工具定义在 src/index.ts:
server.tool(
{
name: "create-purchase-order",
description: "Create an approved purchase order.",
inputSchema: z.object({
sku: z.string(),
quantity: z.number().int().positive(),
}),
},
async ({ sku, quantity }) => ({
content: [
{
type: "text",
text: `Created a purchase order for ${quantity} × ${sku}.`,
},
],
})
);
工具入参通过 zod 校验:sku 为字符串,quantity 必须是正整数。这与 SKILL.md 中“数量未知时请求澄清”的指令互为印证——schema 从类型层面拦截非法调用,策略文件则约束业务前置条件,二者叠加构成完整的执行边界。
三、Skill 如何暴露给宿主:skill:// 资源与协议处理器
README.md 给出了技能在运行时的暴露方式:
A Skills-capable host can list
skill://refunds/SKILL.mdorskill://purchasing/SKILL.md, read the relevant policy and template as MCP resources, then callrefund-orderorcreate-purchase-orderas appropriate.
即:技能根文档通过 skill://<技能名>/SKILL.md 寻址,策略与模板作为普通 MCP 资源读取。其底层实现位于 skills/runtime.ts 的 registerSkillsRuntime 函数,该函数在一台 SDK server 上注册了以下几类能力:
- 资源注册(registerResource):遍历技能快照(snapshot)中的每个文件,将其注册为 MCP 资源,声明
title、mimeType,并在读取时返回text(UTF-8 文本)或blob(Base64 二进制)内容; skills/list处理器:返回快照中全部技能条目(每个条目含uri、frontmatter 与文件清单);skills/get处理器:按 URI 精确获取单个技能,未知 URI 会抛出INVALID_PARAMS协议错误;resources/directory/read处理器:支持按目录读取资源列表,子资源会按 URI 排序返回,目录项以inode/directory标识,实现对skill://purchasing/这类目录的浏览。
而“发现 skills 目录”的机制在 skills/types.ts 中有明确约定:SkillsOptions 提供了 directory 配置项,默认值为 "skills",即相对于项目根目录的 skills 目录。快照结构 SkillsSnapshot 包含三类数据:按 URI 排序的技能条目(skills)、去重后的资源内容(resources)、以及包含空目录在内的目录资源(directories)。每个文件还会计算 SHA-256 摘要(digest),便于宿主校验内容一致性。
四、端到端运行与验证
1. 启动服务端
在示例目录下执行:
pnpm dev
该命令由 package.json 中的 "dev": "mcp-use dev" 定义。服务启动后监听 http://localhost:3000/mcp,mcp-use 的 dev/build/start 命令会自动加载 skills/ 目录并接管 HTTP 监听,无需手写监听逻辑。示例要求 Node.js 版本 >=22.22.2。
2. 宿主侧的完整消费链路
一个支持 Skills 的 MCP 宿主连接到 http://localhost:3000/mcp 后,典型流程如下:
- 调用
skills/list获取技能清单,得到purchasing与refunds两个技能; - 通过
skills/get读取skill://purchasing/SKILL.md,解析 frontmatter 与正文指令; - 按指令读取
references/approval-policy.md,确认采购需要经理审批; - 与用户确认审批与数量后,调用
create-purchase-order工具(传sku与正整数quantity); - 工具返回成功后,读取
templates/purchase-order.md模板,向用户输出确认信息。
这一链路正是 Skills over MCP 的设计意图:让 Agent 在调用工具前先“学会”业务规则,在调用后按统一模板输出,从而把隐性的业务约束显性化、可审计化。
3. 自动验证
示例同时提供:
pnpm verify
对应 "verify": "node ../verify-examples.mjs --example=skills-over-mcp",用于自动化校验示例的行为是否符合预期。
五、模板文件的自定义与最佳实践
结合 purchasing 与 refunds 两个技能,可以总结出编写模板文件(templates/*.md)的要点:
- 职责单一:模板只描述“确认/结果类”输出,例如采购订单已创建、退款已处理(见 refunds/templates/confirmation.md,其中还明确了退款到账的 5–10 个工作日时效);
- 保持中性语气:模板面向最终用户,语言应简洁、确定,避免出现条件分支或不确定表述,如本模板中的“Purchasing will confirm the expected delivery date with the supplier”;
- 在 SKILL.md 中显式引用:只有被
SKILL.md引用的模板才会被 Agent 感知,引用采用技能内部相对路径(如templates/purchase-order.md); - 策略与模板分离:审批规则放在
references/,输出格式放在templates/,便于各自独立维护与演进; - 文本即资源:模板以纯 Markdown 文本形式暴露为 MCP 资源,mcp-use 会为其计算 SHA-256 摘要并在快照中按 URI 排序,保证内容可校验、可追踪。
六、小结
从一份仅两句话的采购订单确认模板出发,我们完整还原了 mcp-use 中 Agent Skill 的运作机制:skills/ 目录被服务端自动发现,SKILL.md 充当操作手册,references/ 提供策略依据,templates/ 规范输出格式,三者通过 skill:// URI 与 skills/list、skills/get、resources/directory/read 协议处理器暴露给宿主。源码实现集中在 skills/runtime.ts 与 skills/types.ts,相关约定在 skills-over-mcp 示例 README 中有权威说明。如果你正在为自己的 MCP 服务端引入“工具 + 指令 + 策略 + 模板”的完整技能体系,purchasing 技能是值得直接参考的最小可运行范式。