mcp-use Skills over MCP 实战:以 purchase-order 模板为例构建带策略与模板文件的 Agent Skill

原创2026-09-23 17:29:541,434 阅读
文章标签:人工智能AI AgentAgent 框架MCP 服务MCP Clients工具调用后端CLIWebSocket插件系统

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 publishes refunds and purchasing Agent 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.md or skill://purchasing/SKILL.md, read the relevant policy and template as MCP resources, then call refund-order or create-purchase-order as appropriate.

即:技能根文档通过 skill://<技能名>/SKILL.md 寻址,策略与模板作为普通 MCP 资源读取。其底层实现位于 skills/runtime.ts 的 registerSkillsRuntime 函数,该函数在一台 SDK server 上注册了以下几类能力:

  1. 资源注册(registerResource):遍历技能快照(snapshot)中的每个文件,将其注册为 MCP 资源,声明 title、mimeType,并在读取时返回 text(UTF-8 文本)或 blob(Base64 二进制)内容;
  2. skills/list 处理器:返回快照中全部技能条目(每个条目含 uri、frontmatter 与文件清单);
  3. skills/get 处理器:按 URI 精确获取单个技能,未知 URI 会抛出 INVALID_PARAMS 协议错误;
  4. 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 后,典型流程如下:

  1. 调用 skills/list 获取技能清单,得到 purchasing 与 refunds 两个技能;
  2. 通过 skills/get 读取 skill://purchasing/SKILL.md,解析 frontmatter 与正文指令;
  3. 按指令读取 references/approval-policy.md,确认采购需要经理审批;
  4. 与用户确认审批与数量后,调用 create-purchase-order 工具(传 sku 与正整数 quantity);
  5. 工具返回成功后,读取 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 技能是值得直接参考的最小可运行范式。

登录后查看全文
mcp-use