Agent Skills设计与实现：用SKILL.md与MCP构建可复用AI Agent能力

1. 从一次技能误触说起Agent Skills 到底解决什么问题如果你正在做 AI Agent大概率遇到过这种场景给 Agent 塞了十几个工具结果它在该查天气的时候去调了数据库该写周报的时候触发了代码执行。问题不在模型笨而在于你给它的能力没有边界。Agent Skills 就是来解决这件事的——它把「一个 Agent 能做什么」拆成一个个独立、可描述、可加载的技能单元每个单元用一份 SKILL.md 定义语义边界再通过 MCP 把外部工具调用接进来。简单说Agent Skills 是一套让 AI Agent 能力可复用、可组合、可验证的工程化方案。它适合三类人一是正在从「写提示词」转向「搭能力系统」的 Agent 开发者二是需要把团队内部工具标准化接入 Agent 的工程团队三是想让自己的 Agent 在多个平台Claude Code、Cursor 等复用同一套技能定义的独立开发者。我试过把一套 PDF 处理技能从 Claude Code 迁移到另一个支持 MCP 的客户端只改了配置路径SKILL.md 一行没动就跑通了。这就是结构化技能封装的价值。下面我会从目录结构、SKILL.md 骨架、MCP 配置到本地验证给出一套可以直接复制的落地流程。2. 前置准备TaoToken 接入与技能运行环境在写第一个 Skill 之前你需要一个能稳定调用模型的入口。TaoToken 提供统一的 API 接入支持模型对话、Coding Plan 和 API Keys 管理适合作为 Agent 技能链路的模型底座。2.1 获取 API Key 与接入地址访问官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后进入控制台创建 API Key。API 基础地址为 https://taotoken.net/api不加 UTM。拿到 Key 后建议先写入环境变量避免硬编码到 SKILL.md 或脚本里export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api2.2 技能运行的最小依赖Agent Skills 本身是 Markdown 脚本的组合不依赖特定框架。但要让 MCP 工具调用跑起来你需要Node.js 18用于运行 MCP serverPython 3.10如果你的 Skill 包含 Python 脚本一个支持 MCP 的客户端Claude Code、Cursor 或自建 Agent 运行时如果你打算长期做编码类 Agent可以了解 Coding Plan它更适合高频调用场景如果只是验证模型对话链路直接用模型对话页面即可。3. 可复制配置目录结构、SKILL.md 骨架与 MCP 片段这一节是全文的核心。我会给出一个完整的「PDF 处理技能」示例你可以把 pdf 替换成自己的业务名。3.1 标准目录结构Agent Skills 的目录结构遵循约定优于配置的原则。目录名必须与 SKILL.md 中的 name 字段完全一致否则加载器找不到入口。skills/ └── pdf-toolkit/ ├── SKILL.md # 必需技能定义入口 ├── scripts/ # 可选可执行脚本 │ ├── pdf_rotate.py │ └── pdf_extract_table.py ├── references/ # 可选参考文档 │ └── pdf-format-spec.md └── assets/ # 可选静态资源 └── output-template.md项目级技能放在.agents/skills/下全局技能放在~/.taotoken/skills/下。加载优先级是项目级高于全局级这样你可以用项目级技能覆盖全局同名技能做调试。3.2 SKILL.md 骨架SKILL.md 采用 YAML Frontmatter Markdown 正文的格式。Frontmatter 里的 name 和 description 是始终加载的元数据层正文是按需加载的技能正文层。--- name: pdf-toolkit description: 当用户需要旋转 PDF、提取 PDF 表格或生成 PDF 摘要时使用。支持 90/180/270 度旋转和表格转 Markdown。 version: 1.0.0 compatibility: - claude-code - cursor - mcp-client --- # PDF 处理技能 ## 触发条件 ### 显式触发 - 关键词/pdf、/rotate-pdf、/extract-table - 用户明确提到「旋转 PDF」「提取表格」 ### 隐式触发 - 对话历史中出现 PDF 文件路径 旋转/表格/摘要意图 - 置信度阈值语义匹配度超过 0.85 时自动触发 ## 执行步骤 ### 旋转 PDF 1. 确认旋转角度为 90、180、270 之一 2. 调用 scripts/pdf_rotate.py传入文件路径和角度 3. 输出保存到 assets/output/rotated-timestamp.pdf 4. 返回文件路径和页数变化说明 ### 提取表格 1. 调用 scripts/pdf_extract_table.py 2. 检查返回表格是否为空 3. 转换为 Markdown 表格并附加来源页码 4. 保存到 assets/output/table-timestamp.md ## 异常处理 - 格式不支持返回 E001建议先转换 PDF 格式 - 识别失败返回 E002提示人工介入 - 超时15s返回 E003走降级路径只返回文本摘要 ## 评测指标 - 旋转准确率100%角度校验通过后执行 - 表格提取准确率≥95% - 响应时间简单操作 ≤3s复杂操作 ≤10s这里的关键是 description 字段。它决定了模型在什么时候加载这个技能。写得太宽会导致误触写得太窄会导致该触发时不触发。我的经验是把「用户会怎么说」和「技能能做什么」都写进去用逗号分隔多个触发场景。3.3 MCP 配置片段MCP 负责把 SKILL.md 里的脚本调用变成标准化的工具调用。下面是一个 MCP server 配置示例放在客户端的 mcp 配置文件中{ mcpServers: { pdf-toolkit: { command: python, args: [-m, mcp_server_pdf], env: { TAOTOKEN_API_KEY: ${TAOTOKEN_API_KEY}, TAOTOKEN_BASE_URL: https://taotoken.net/api, SKILL_ROOT: ./skills/pdf-toolkit } } } }对应的 MCP server 最小实现Python如下它把 SKILL.md 里声明的脚本暴露成工具from mcp.server import Server from mcp.types import Tool, TextContent import subprocess, json, os app Server(pdf-toolkit) SKILL_ROOT os.environ.get(SKILL_ROOT, ./skills/pdf-toolkit) app.list_tools() async def list_tools(): return [ Tool( namepdf_rotate, description旋转 PDF 文件支持 90/180/270 度, inputSchema{ type: object, properties: { file_path: {type: string}, angle: {type: integer, enum: [90, 180, 270]} }, required: [file_path, angle] } ) ] app.call_tool() async def call_tool(name: str, arguments: dict): if name pdf_rotate: script os.path.join(SKILL_ROOT, scripts, pdf_rotate.py) result subprocess.run( [python, script, arguments[file_path], str(arguments[angle])], capture_outputTrue, textTrue, timeout15 ) return [TextContent(typetext, textresult.stdout or result.stderr)]这段代码的作用是当模型决定调用 pdf_rotate 时MCP server 接收参数、执行脚本、把结果回传给模型。SKILL.md 负责「什么时候调」MCP 负责「怎么调」。4. 验证请求确认技能加载与调用链路生效配置写完后不要急着接业务。先用最小请求验证三件事技能是否被加载、触发是否准确、工具调用是否返回。4.1 验证技能加载在客户端启动后查看技能列表是否包含 pdf-toolkit。以命令行方式验证# 列出已加载技能 npx skills list --path ./skills # 预期输出 # pdf-toolkit v1.0.0 当用户需要旋转 PDF...如果列表为空检查目录名与 name 字段是否一致以及 SKILL.md 的 Frontmatter 是否以---开头和结尾。4.2 验证触发与调用发送一条明确触发请求帮我把 ./docs/report.pdf 旋转 90 度预期链路是模型匹配 description → 加载 SKILL.md 正文 → 调用 MCP 的 pdf_rotate 工具 → 脚本执行 → 返回文件路径。如果模型没有触发技能把 description 改得更贴近用户表达如果触发了但工具调用失败检查 MCP server 的 env 里 SKILL_ROOT 是否指向正确目录。4.3 验证模型对话链路如果你只想先确认模型侧能正常响应可以用模型对话页面发一条测试消息确认 API Key 和 base_url 配置无误。这一步能排除「是模型没响应还是技能没加载」的歧义。5. 本篇常见错排查5.1 技能不加载目录名与 name 不一致这是最高频的问题。加载器按目录名查找 SKILL.md如果目录叫 pdf-toolkit 但 name 写的是 pdf_toolkit就会静默跳过。统一用连字符小写。5.2 触发过于频繁description 写太宽比如 description 写成「处理文件相关任务」模型会把所有文件操作都往这个技能上靠。改成「当用户需要旋转 PDF 或提取 PDF 表格时使用」把边界收窄。5.3 MCP 调用超时脚本没有超时控制SKILL.md 里写了 15 秒降级但脚本本身没有 timeout会导致 MCP server 挂起。在 subprocess.run 里加 timeout 参数并在脚本内部也做分块处理。5.4 环境变量丢失MCP 配置里没透传MCP server 是独立进程不会自动继承 shell 的环境变量。必须在配置的 env 字段里显式声明 TAOTOKEN_API_KEY 和 TAOTOKEN_BASE_URL。5.5 跨平台路径问题用了绝对路径SKILL.md 和 MCP 配置里尽量用相对路径配合 SKILL_ROOT 环境变量解析。绝对路径在换机器后会直接失效。6. 下一步把技能接入你的实际工作流技能跑通后建议按这个顺序推进先把一个高频任务封装成 Skill验证触发和调用再把多个 Skill 组合成串行链路比如「提取表格 → 生成摘要 → 导出 Markdown」最后把技能目录纳入版本控制用项目级路径做灰度。如果你需要管理多个 API Key 或查看调用量去控制台如果要把技能接入编码类 Agent 做长期任务看 Coding Plan如果只是想先验证模型对技能描述的理解能力直接用模型对话试几条触发语句。接入文档里有 MCP 配置的完整字段说明遇到加载问题可以先对照检查。技能工程的本质是把「模型会做什么」变成「你定义了它能做什么」。SKILL.md 是契约MCP 是管道验证是保险丝。三者对齐Agent 的能力才真正可复用。