1. 从 MCP 到 Agent Skills为什么光有接口还不够如果你最近在 AI 开发者圈子里刷到过 Agent Skills 这个词大概率会同时看到两个疑问它和 MCP 到底什么关系是不是又一个换皮概念我先把结论放前面——Agent Skills 不是来取代 MCP 的它解决的是另一个维度的问题MCP 让 Agent 能连上外部工具而 Agent Skills 让 Agent 知道在什么场景下、按什么流程、用哪些工具把事情做对。打个比方。MCP 像电脑的 USB 接口负责把鼠标、键盘、打印机接进来解决的是能不能连的问题。但接上打印机之后怎么排版、用什么纸张、双面还是单面这些操作知识 USB 接口本身不管。Agent Skills 就是那本操作手册它用结构化的方式告诉 Agent遇到这类任务时先做什么、再做什么、参考哪些资料、调用哪些脚本。这套标准由 Anthropic 维护并开源核心载体是一个叫 SKILL.md 的文件。它的形式非常轻——就是一个文件夹加一个 Markdown 文件不需要跑服务、不需要部署进程。Claude 系列原生支持Cursor、Google、OpenAI 的生态也在快速跟进。对开发者来说这意味着你写的技能可以跨平台迁移而不是绑死在某个厂商的私有格式上。这篇文章面向想快速理解 SKILL.md 与 MCP 协作机制的开发者。我会先拆清楚概念边界然后给出一份可以直接复制的 SKILL.md 骨架和 MCP 配置文件示例最后带你在 Claude 类工具里接入 TaoToken 的统一 Key/API 通道把概念到配置这一步真正跑通。全程给命令、给参数、给排错思路你跟着敲就行。2. 前置准备TaoToken 统一 Key 与 API 通道在动手写 SKILL.md 之前先把模型调用这条链路打通。因为无论你的技能写得多漂亮最终执行时还是要落到模型请求上。如果你同时用 Claude、Cursor 或者自建的 Agent 框架每个平台各配一套 Key 会很乱。TaoToken 提供的是统一 Key/API 通道一个 Key 走多个模型配置一次就能在多个工具里复用。你需要准备的东西不多一个 TaoToken 账号注册入口在官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content登录后在控制台生成 API Key地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite记下 API 基地址https://taotoken.net/api这个地址不加 UTM 参数直接用于代码里的 base_url这里有个容易踩的坑很多人把控制台地址和 API 地址搞混。控制台是给你在浏览器里管理 Key、看用量用的API 地址是写进代码或配置文件里的请求端点。两者不是一回事。你在代码里填的应该是 https://taotoken.net/api而不是带一堆参数的网页地址。拿到 Key 之后建议先别急着写技能用最简单的方式验证一下通道是否通。你可以打开模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 直接发一句话测试确认 Key 有效、模型能正常返回。这一步花不了一分钟但能帮你排除掉后面 80% 的配置写了但没反应的问题。如果你打算长期做编码类 Agent 或者跑自动化任务可以关注一下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite它更适合高频调用的场景。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite遇到参数不确定的时候翻一下比瞎试快。3. 可复制配置SKILL.md 骨架与 MCP 配置示例3.1 SKILL.md 的目录结构与元数据一个标准的技能就是一个文件夹结构长这样my-skill/ ├── SKILL.md # 核心元数据 指令 ├── scripts/ # 可选可执行脚本 ├── references/ # 可选领域文档、API 手册 └── assets/ # 可选模板、静态资源SKILL.md 的头部必须是 YAML Frontmatter用三个短横线包起来。这是 Agent 在发现阶段唯一会读的部分所以 name 和 description 要写得精准它决定了 Agent 能不能在正确的时机匹配到这个技能。下面是一份可以直接拿去改的骨架我以接口文档生成这个场景为例--- name: api-doc-generator description: 根据代码或接口定义生成结构化 API 文档支持 OpenAPI 与 Markdown 输出 version: 1.0.0 author: your-team --- # 接口文档生成技能 ## 技能概述 帮助智能体从源码或接口描述中提取端点信息生成规范文档。 ## 何时使用此技能 当用户提出以下需求时激活 - 根据代码生成 API 文档 - 把接口定义转成 Markdown 或 OpenAPI - 补全缺失的参数说明 ## 前置要求 - 确认环境中已安装 pyyaml - 源码文件可读且未加密 - 若需调用模型补全描述确认 API Key 已配置 ## 操作步骤 ### 1. 扫描接口定义 运行脚本提取端点 bash python scripts/scan_endpoints.py --src ./src --out endpoints.json2. 生成文档python scripts/gen_doc.py --input endpoints.json --format markdown --out API.md3. 补全描述对于缺失的字段说明参考references/field-conventions.md 必要时调用模型接口补全接口配置见assets/model-config.json。常见问题处理解析失败检查源码是否为动态生成动态端点需手动补充字段缺失参考 references 中的约定文档编码问题统一使用 UTF-8输出格式MarkdownAPI.mdOpenAPIopenapi.yaml参考信息references/field-conventions.md- 字段命名约定references/openapi-spec.md- OpenAPI 规范摘要注意几个细节。第一Frontmatter 里的 description 要包含触发关键词比如生成 API 文档OpenAPI这样 Agent 匹配时才不会漏。第二正文里的脚本调用要写清楚完整命令和参数别只写运行脚本——Agent 需要的是可执行的具体指令。第三references 和 assets 的引用用相对路径保持技能文件夹的自包含性。 ### 3.2 MCP 配置文件示例 MCP 负责连接外部工具Skills 负责编排流程。两者配合时你需要在 MCP 配置里声明可用的工具服务。以常见的配置文件格式为例 json { mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, ./workspace] }, fetch: { command: npx, args: [-y, modelcontextprotocol/server-fetch] } } }这段配置声明了两个 MCP 服务filesystem 让 Agent 能读写工作目录fetch 让它能抓取网络内容。你的 SKILL.md 里就可以写使用 filesystem 工具读取 references 目录把 MCP 提供的工具和技能里的流程串起来。关键点在于MCP 配置解决有哪些工具可用SKILL.md 解决什么时候用、怎么组合用。一个数据分析技能可以指导 Agent 先通过 MCP 从数据库取数再套用技能内置的统计逻辑最后用 MCP 的文件工具写出报告。这就是两者互补的实际形态。3.3 渐进式披露为什么技能多了也不卡Agent Skills 有个核心机制叫渐进式披露分三个阶段发现阶段Agent 启动时只扫描所有 SKILL.md 的 Frontmatter读 name、description、version。这时候上下文里只有一张轻量索引表几百个技能也就几千 token。激活阶段用户提出任务后Agent 根据 description 匹配技能匹配上了才完整读取该技能的 SKILL.md 正文。执行阶段正文里引用的 references 文档、scripts 脚本都是用到才加载。比如只有处理扫描件时才去读 OCR 指南。这个机制的价值在于上下文管理。如果一次性把所有技能的完整指令塞进去上下文会溢出关键信息被淹没推理成本还高。渐进式披露把初始负载压到极低实际执行时只加载必要内容。这也是为什么一个 Agent 能挂几十上百个技能而不明显变慢。4. 验证请求把技能和模型通道跑通配置写完了得验证。分两步走先验证模型通道再验证技能加载。4.1 验证 TaoToken 通道用 curl 发一个最小请求确认 Key 和端点都对curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_API_KEY \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回复 ok}], max_tokens: 16 }如果返回里能看到正常的 message 内容说明通道没问题。如果报 401检查 Key 是否复制完整、有没有多余空格如果报 404检查 base_url 是不是写成了带参数的网页地址。4.2 验证技能加载把技能文件夹放到 Agent 的技能目录下然后发一个能触发 description 关键词的请求。比如你的技能 description 里写了生成 API 文档就发一句帮我根据 src 目录生成 API 文档。观察 Agent 的行为它应该先识别出需要 api-doc-generator 技能然后按 SKILL.md 里的步骤执行。如果它没匹配到多半是 description 写得不够具体或者技能目录路径不对。4.3 在 Claude 类工具中接入如果你用的是 Claude Code 这类工具接入 TaoToken 的方式是配置环境变量或配置文件。以环境变量为例export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYYOUR_API_KEY设置完之后重启工具让它读取新的配置。然后跑一个简单任务验证比如让它读一个文件并总结。能正常返回就说明通道接上了。更详细的接入参数可以参考接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite不同工具的配置字段名可能略有差异。5. 本篇常见错排查5.1 技能不触发最常见的原因是 description 太泛。写处理文档不如写从 PDF 提取文本和表格、填写表单、合并文档。Agent 靠 description 做语义匹配关键词越具体命中率越高。另外检查技能文件夹是否放在正确的扫描路径下有些工具要求技能放在特定目录。5.2 脚本执行报错SKILL.md 里写的脚本命令路径是相对于技能文件夹的。如果你写python scripts/xxx.py但实际执行时工作目录不对就会找不到文件。建议在脚本调用前先确认工作目录或者在 SKILL.md 里写明在技能根目录下执行。5.3 模型请求 401 或超时401 基本都是 Key 问题复制不全、过期、或者用了错误的端点。超时则可能是网络或端点配置问题确认 base_url 是 https://taotoken.net/api 而不是其他地址。如果用了代理类工具注意不要引入额外的转发层直接用统一通道最省事。5.4 上下文被撑爆如果你发现 Agent 响应变慢或者开始丢信息检查是不是某个技能的 SKILL.md 正文写得太长或者 references 被一次性全加载了。渐进式披露的前提是你把详细内容放在 references 里正文只留索引和步骤。正文超过几百行就该拆分了。5.5 MCP 服务起不来MCP 配置里的 command 和 args 要和你本地环境匹配。比如用 npx 启动的服务确认 Node 环境已装。路径参数用相对路径时注意它是相对于 MCP 客户端的工作目录不是相对于配置文件。起不来的时候先手动在终端跑一遍 command看报什么错。6. 把技能变成可复用资产Agent Skills 真正有意思的地方是它把怎么做事这件事变成了可以像 Markdown 文件一样分享的东西。你团队里某个同学摸索出一套代码审计流程写成 SKILL.md其他人直接放进技能目录就能用不需要重新调提示词。这种零成本分发是 MCP 服务做不到的——MCP 要部署、要维护进程而技能就是纯文本加脚本。我的建议是从一个小技能开始别一上来就搞大而全的。先挑一个你每天重复做的任务比如根据 commit 生成 changelog或者检查配置文件格式写成 SKILL.md跑通再逐步加 references 和 scripts。跑通之后你会发现真正花时间的不是写技能而是想清楚流程的每一步——而这恰恰是 Agent 最需要你教它的部分。模型通道这边统一用 TaoToken 的 Key 能省掉多平台来回切换的麻烦。需要验证模型效果就去模型对话页面试长期跑编码任务就上 Coding Plan接入细节翻文档。把通道和技能两件事都理顺你的 Agent 才算真正从能连工具进化到会做事。
