1. 为什么你的 Prompt 越写越长效果却越来越飘如果你已经能熟练写 Prompt但每次遇到同类任务还是要把那套流程重新描述一遍问题通常不在“提示词不够长”而在于缺少一层可复用的封装。Skills 就是干这个的它把“某类任务怎么做才专业”固化成一个标准文件夹让 Claude 在合适的时候自动加载、按流程执行。SKILL.md 是这套机制的核心文件MCP 则负责把外部工具能力接进来两者配合才能跑通端到端的 Agent 工作流。先说清楚它适合谁经常用 Claude 做代码审查、文档生成、数据校验、接口联调的开发者团队里希望把“老员工的经验”沉淀成文件而不是口口相传的人以及已经在用 MCP 接工具、但发现每次调用都不稳定的同学。这三类人用 Skills 收益最明显。传统 Prompt 的痛点很具体每次重复描述流程结果稳定性依赖临场发挥长上下文白白烧 token多人协作时风格难以统一。Skills 的优势对应着来一次定义反复复用自动触发和手动调用都支持渐进式加载只在需要时读取详细说明团队可共享、可版本化、可持续迭代。这里有个容易混淆的分工我用一句话帮你记住Rules 约束“行为与偏好”比如语气、格式、禁忌MCP 提供“能力接口”比如 API、数据库、第三方系统Skills 定义“怎么把能力用对、用顺、用稳定”。打个比方MCP 是厨房和设备Skills 是菜谱和出品标准。只有设备没有菜谱出品全靠厨师心情只有菜谱没有设备菜谱再好也做不出菜。我试过把一套代码审查流程从 Prompt 迁移到 Skill最直观的变化是以前每次要贴 300 字流程说明现在只需要说“帮我审查这段 Python”Skill 自动触发输出格式和检查项完全一致。下面从目录结构开始一步步把 SKILL.md 写出来再接到 MCP 工具上最后用 TaoToken 的统一通道做一次端到端验证。2. SKILL.md 目录规范与渐进式加载机制详解官方推荐的 Skill 结构分最小可用和完整两种。最小可用只有一个文件my-skill/ └── SKILL.md完整推荐结构长这样my-skill/ ├── SKILL.md # 必需入口文件 ├── scripts/ # 可选可执行脚本 ├── references/ # 可选参考文档 └── assets/ # 可选模板与素材理解这套结构的关键是“渐进式加载”的三层机制。第一层是 Frontmatter 层常驻加载只读取 name、description 等识别信息用来判断这个 Skill 该不该被触发。第二层是 SKILL.md 正文层按需加载当任务相关时才把详细流程读进来。第三层是目录资源层只有正文里明确引用到 references/ 或 scripts/ 时才会去读取。这个设计解决了“强能力”和“省 token”之间的矛盾。你不需要把所有细节都塞进常驻上下文而是让模型先看到“有这么个技能”需要时再展开。类比一下Frontmatter 像书的封面和目录正文像章节摘要references 像附录只有真要查细节时才翻。description 字段决定触发率这是官方指南反复强调的点。高质量描述公式是做什么 何时用 用户会怎么说触发短语。看几个对比# 好例子包含用户语言触发词 description: 管理 Linear 冲刺规划与任务创建。用于用户提到sprint 规划、创建任务、项目排期时。 # 坏例子过泛 description: 帮助处理项目。 # 坏例子纯技术无用户语言 description: 实现层次化 Project 实体关系模型。必填字段只有两个name 和 description。name 必须 kebab-case也就是小写字母、数字、连字符的组合。description 建议写清触发场景最长 1024 字符。可选字段包括 license、compatibility、metadata、allowed-tools。有几条官方限制必须记住踩了会直接导致加载失败文件名必须是 SKILL.md大小写敏感不要在 skill 文件夹里放 README.md说明文档放 references/ 或仓库根目录name 不能包含保留前缀比如 claude、anthropicFrontmatter 中禁止使用尖括号。什么时候该把内容拆到 references/ 和 scripts/规则太多就放 references/.md需要确定性校验就放 scripts/.py输出模板固定就放 assets/*.md。SKILL.md 本身保持“短而清晰”详细内容拆出去。引用写法很直接在处理 API 分页前先参考 references/api-patterns.md。 如需校验输入数据执行 python scripts/validate.py --input {filename}。这样模型读到正文时知道去哪里找细节而不是把所有细节都背在常驻上下文里。3. 可复制 SKILL.md 模板与 MCP 工具编排配置先给一份可以直接抄的 SKILL.md 模板覆盖 Frontmatter、使用时机、执行步骤、错误处理、参考引用五个部分--- name: python-naming-standard description: 统一 Python 内部函数命名规范。用于用户要求编写、重构、审查 Python 代码时。 metadata: author: your-name version: 1.0.0 --- # Python 内部命名规范 ## 使用时机 - 用户要求写/改/审查 Python 代码 - 涉及内部辅助函数命名一致性 ## 执行步骤 1. 识别内部辅助函数 2. 检查是否以 _internal_ 前缀命名 3. 若不符合给出最小改动建议 4. 输出修改建议与原因 ## 错误处理 - 若项目已有明确命名规范优先遵循项目规范并说明冲突点 ## 参考 - 命名示例见 references/naming-examples.md这份模板的要点description 里带了“编写、重构、审查 Python 代码”这些用户会说的词触发率高执行步骤编号清晰关键步骤前置错误处理明确避免模型自由发挥。接下来是 MCP 工具编排。Skills 负责“怎么用”MCP 负责“能调用什么”。在 Claude Code 里配置 MCP 服务器通常改 settings 文件。下面是一份可复制的配置片段路径按你的实际环境调整{ mcpServers: { taotoken-tools: { command: npx, args: [-y, taotoken/mcp-server], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: sk-your-key-here, TAOTOKEN_MODEL: claude-sonnet-4-20250514 } } } }如果你用的是 Cline 或 Claude Code 的 MCP 配置三件套必须写全Base URL、Key、Model ID。Base URL 填https://taotoken.net/apiKey 从控制台生成Model ID 按你实际使用的模型填。缺任何一个都会在调用时报鉴权或模型找不到的错。在 SKILL.md 里引用 MCP 工具时写法要明确工具名和参数## 执行步骤 1. 调用 taotoken-tools.search_docs 检索接口文档参数 query 为任务关键词 2. 根据返回结果生成代码 3. 调用 taotoken-tools.validate_schema 校验输出结构这里有个坑工具名大小写敏感写错了会报 tool not found。建议把校验逻辑写成脚本放 scripts/ 里减少语言歧义。比如# scripts/validate.py import json import sys def validate(payload): required [name, description] missing [k for k in required if k not in payload] if missing: print(fmissing fields: {missing}) sys.exit(1) print(ok) if __name__ __main__: with open(sys.argv[1]) as f: validate(json.load(f))这样 Skill 正文里只需要写“执行python scripts/validate.py --input {filename}”确定性交给脚本模型不用猜。4. 一次技能加载与调用的端到端验证配置写完了得验证它真的能跑通。验证分三步触发测试、功能测试、性能对比。触发测试先看 Skill 会不会被自动加载。应该触发的场景直接表述“帮我审查这段 Python 代码”以及同义改写“看看这个函数命名规不规范”。不该触发的场景无关任务比如“今天天气怎么样”。如果该触发没触发回去改 description补上用户会说的触发短语。功能测试看三件事输出是否正确、工具调用是否成功、异常分支是否可恢复。这里用 TaoToken 的统一通道做一次实际请求。先确认环境变量export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEYsk-your-key-here然后用 curl 发一次请求验证模型通道是否通curl -s $TAOTOKEN_BASE_URL/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 256, messages: [ {role: user, content: 用一句话说明 SKILL.md 的作用} ] }成功的话会返回一段 JSONchoices 或 content 字段里有模型输出。如果返回 401说明 Key 不对或没带上如果返回 model not found说明 Model ID 写错了。这一步通了说明 TaoToken 的 Key 和 API 通道没问题接下来把 Skill 挂上去。在 Claude Code 里加载 Skill把 skill 文件夹放到项目约定目录然后在对话里说“帮我审查这段 Python 代码”。观察是否自动触发。触发后看它有没有按 SKILL.md 里的步骤走识别内部函数、检查前缀、给建议、说明原因。如果步骤跳了说明正文写得太啰嗦关键步骤埋太深把流程编号前置。性能对比用/status看往返轮次和 token 消耗。和“无 Skill”相比稳定触发后往返轮次应该减少失败调用应该下降。一个实用标准先打磨一个最难任务直到稳定再扩展测试集。别一上来写十个 Skill先把一个跑顺。验证通过后你可以把这套流程固化成团队资产。Skill 文件进版本库MCP 配置进 settingsKey 走 TaoToken 统一管理换模型或换工具时只改配置不改 Skill。5. 常见报错排查401、local proxy failed、reading choices、OAuth排障这部分按真实报错来对。下面四个是接入 Skills MCP 时最常撞上的。401 Unauthorized。表现是请求直接被拒返回体里带 401。原因通常是 Key 没带、Key 过期、或者 Base URL 和 Key 不匹配。排查顺序先确认环境变量TAOTOKEN_API_KEY有值再确认请求头里带了x-api-key最后确认 Base URL 是https://taotoken.net/api而不是别的地址。如果用的是 MCP 配置检查 env 块里三个字段是否齐全。local proxy failed。表现是 MCP 工具调用时报本地代理失败。原因一般是 MCP server 启动命令写错或者 npx 拉包失败。排查手动在终端跑一遍npx -y taotoken/mcp-server看能不能起来起不来就是网络或包名问题能起来但 Claude 里报错就是 settings 里的 command 或 args 路径不对。注意不要在任何配置里写代理相关的东西走正常网络即可。reading choices 报错。表现是解析响应时读不到 choices 字段。原因通常是请求发到了不兼容的端点或者响应格式和预期不符。排查确认你调的是/v1/messages而不是 OpenAI 风格的/v1/chat/completions两者响应结构不同。如果你用的是兼容层确认 Model ID 和端点匹配。OAuth 相关报错。表现是鉴权流程卡住或 token 刷新失败。原因通常是本地缓存了旧的凭证。排查清理本地凭证缓存重新走一次授权如果用的是 API Key 模式确认没有混用 OAuth 配置。Claude Code 的 auth.json 里如果同时有 OAuth 和 API Key 字段可能冲突建议只保留一种。把这几类错误和对应动作整理成一张对照表排障时直接查报错关键词常见原因处理动作401 UnauthorizedKey 缺失/过期/不匹配检查环境变量与请求头确认 Base URLlocal proxy failedMCP server 启动失败手动跑启动命令检查 settings 路径reading choices端点或响应格式不符确认调用/v1/messages核对 Model IDOAuth 失败凭证缓存冲突清理缓存只保留一种鉴权方式排障时优先看日志里的第一行错误那通常是最接近根因的。后面的堆栈往往是连锁反应。6. 把 Skill 沉淀成团队 SOP 的落地建议写 Skill 的本质不是堆指令而是沉淀团队的 SOP。这句话值得贴在显示器上。你写的每一份 SKILL.md都是在把“老员工脑子里的经验”变成“新员工能直接用的文件”。落地时有几个实用建议。第一description 用用户语言写别用技术黑话触发率靠它。第二SKILL.md 正文保持短超过一屏的内容拆到 references/。第三需要确定性校验的逻辑写成脚本放 scripts/别让模型猜。第四MCP 配置里的 Base URL、Key、Model ID 三件套写全缺一个就报错。第五先跑通一个最难任务再扩展。如果你还没开始可以从最小可用结构起步一个文件夹一个 SKILL.md先解决你每周重复三次的那个任务。跑顺了再加 scripts 和 references。需要统一 Key 和 API 通道的话可以去 TaoToken 控制台生成 Key接入文档里有各客户端的配置示例想先验证模型输出用模型对话页面直接试长期做编码和 Agent 的话Coding Plan 更适合持续调用。把 Skill 文件进版本库配置进 settingsKey 走统一管理这套组合跑起来你的 Agent 工作流才算真正可维护。 
长河君 · 2026/10/17 1:42:13 · 阅读 1.2k 一文快速精通 Skills：从 SKILL.md 到 MCP 的落地实践，建议收藏！
1. 为什么你的 Prompt 越写越长效果却越来越飘如果你已经能熟练写 Prompt但每次遇到同类任务还是要把那套流程重新描述一遍问题通常不在“提示词不够长”而在于缺少一层可复用的封装。Skills 就是干这个的它把“某类任务怎么做才专业”固化成一个标准文件夹让 Claude 在合适的时候自动加载、按流程执行。SKILL.md 是这套机制的核心文件MCP 则负责把外部工具能力接进来两者配合才能跑通端到端的 Agent 工作流。先说清楚它适合谁经常用 Claude 做代码审查、文档生成、数据校验、接口联调的开发者团队里希望把“老员工的经验”沉淀成文件而不是口口相传的人以及已经在用 MCP 接工具、但发现每次调用都不稳定的同学。这三类人用 Skills 收益最明显。传统 Prompt 的痛点很具体每次重复描述流程结果稳定性依赖临场发挥长上下文白白烧 token多人协作时风格难以统一。Skills 的优势对应着来一次定义反复复用自动触发和手动调用都支持渐进式加载只在需要时读取详细说明团队可共享、可版本化、可持续迭代。这里有个容易混淆的分工我用一句话帮你记住Rules 约束“行为与偏好”比如语气、格式、禁忌MCP 提供“能力接口”比如 API、数据库、第三方系统Skills 定义“怎么把能力用对、用顺、用稳定”。打个比方MCP 是厨房和设备Skills 是菜谱和出品标准。只有设备没有菜谱出品全靠厨师心情只有菜谱没有设备菜谱再好也做不出菜。我试过把一套代码审查流程从 Prompt 迁移到 Skill最直观的变化是以前每次要贴 300 字流程说明现在只需要说“帮我审查这段 Python”Skill 自动触发输出格式和检查项完全一致。下面从目录结构开始一步步把 SKILL.md 写出来再接到 MCP 工具上最后用 TaoToken 的统一通道做一次端到端验证。2. SKILL.md 目录规范与渐进式加载机制详解官方推荐的 Skill 结构分最小可用和完整两种。最小可用只有一个文件my-skill/ └── SKILL.md完整推荐结构长这样my-skill/ ├── SKILL.md # 必需入口文件 ├── scripts/ # 可选可执行脚本 ├── references/ # 可选参考文档 └── assets/ # 可选模板与素材理解这套结构的关键是“渐进式加载”的三层机制。第一层是 Frontmatter 层常驻加载只读取 name、description 等识别信息用来判断这个 Skill 该不该被触发。第二层是 SKILL.md 正文层按需加载当任务相关时才把详细流程读进来。第三层是目录资源层只有正文里明确引用到 references/ 或 scripts/ 时才会去读取。这个设计解决了“强能力”和“省 token”之间的矛盾。你不需要把所有细节都塞进常驻上下文而是让模型先看到“有这么个技能”需要时再展开。类比一下Frontmatter 像书的封面和目录正文像章节摘要references 像附录只有真要查细节时才翻。description 字段决定触发率这是官方指南反复强调的点。高质量描述公式是做什么 何时用 用户会怎么说触发短语。看几个对比# 好例子包含用户语言触发词 description: 管理 Linear 冲刺规划与任务创建。用于用户提到sprint 规划、创建任务、项目排期时。 # 坏例子过泛 description: 帮助处理项目。 # 坏例子纯技术无用户语言 description: 实现层次化 Project 实体关系模型。必填字段只有两个name 和 description。name 必须 kebab-case也就是小写字母、数字、连字符的组合。description 建议写清触发场景最长 1024 字符。可选字段包括 license、compatibility、metadata、allowed-tools。有几条官方限制必须记住踩了会直接导致加载失败文件名必须是 SKILL.md大小写敏感不要在 skill 文件夹里放 README.md说明文档放 references/ 或仓库根目录name 不能包含保留前缀比如 claude、anthropicFrontmatter 中禁止使用尖括号。什么时候该把内容拆到 references/ 和 scripts/规则太多就放 references/.md需要确定性校验就放 scripts/.py输出模板固定就放 assets/*.md。SKILL.md 本身保持“短而清晰”详细内容拆出去。引用写法很直接在处理 API 分页前先参考 references/api-patterns.md。 如需校验输入数据执行 python scripts/validate.py --input {filename}。这样模型读到正文时知道去哪里找细节而不是把所有细节都背在常驻上下文里。3. 可复制 SKILL.md 模板与 MCP 工具编排配置先给一份可以直接抄的 SKILL.md 模板覆盖 Frontmatter、使用时机、执行步骤、错误处理、参考引用五个部分--- name: python-naming-standard description: 统一 Python 内部函数命名规范。用于用户要求编写、重构、审查 Python 代码时。 metadata: author: your-name version: 1.0.0 --- # Python 内部命名规范 ## 使用时机 - 用户要求写/改/审查 Python 代码 - 涉及内部辅助函数命名一致性 ## 执行步骤 1. 识别内部辅助函数 2. 检查是否以 _internal_ 前缀命名 3. 若不符合给出最小改动建议 4. 输出修改建议与原因 ## 错误处理 - 若项目已有明确命名规范优先遵循项目规范并说明冲突点 ## 参考 - 命名示例见 references/naming-examples.md这份模板的要点description 里带了“编写、重构、审查 Python 代码”这些用户会说的词触发率高执行步骤编号清晰关键步骤前置错误处理明确避免模型自由发挥。接下来是 MCP 工具编排。Skills 负责“怎么用”MCP 负责“能调用什么”。在 Claude Code 里配置 MCP 服务器通常改 settings 文件。下面是一份可复制的配置片段路径按你的实际环境调整{ mcpServers: { taotoken-tools: { command: npx, args: [-y, taotoken/mcp-server], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: sk-your-key-here, TAOTOKEN_MODEL: claude-sonnet-4-20250514 } } } }如果你用的是 Cline 或 Claude Code 的 MCP 配置三件套必须写全Base URL、Key、Model ID。Base URL 填https://taotoken.net/apiKey 从控制台生成Model ID 按你实际使用的模型填。缺任何一个都会在调用时报鉴权或模型找不到的错。在 SKILL.md 里引用 MCP 工具时写法要明确工具名和参数## 执行步骤 1. 调用 taotoken-tools.search_docs 检索接口文档参数 query 为任务关键词 2. 根据返回结果生成代码 3. 调用 taotoken-tools.validate_schema 校验输出结构这里有个坑工具名大小写敏感写错了会报 tool not found。建议把校验逻辑写成脚本放 scripts/ 里减少语言歧义。比如# scripts/validate.py import json import sys def validate(payload): required [name, description] missing [k for k in required if k not in payload] if missing: print(fmissing fields: {missing}) sys.exit(1) print(ok) if __name__ __main__: with open(sys.argv[1]) as f: validate(json.load(f))这样 Skill 正文里只需要写“执行python scripts/validate.py --input {filename}”确定性交给脚本模型不用猜。4. 一次技能加载与调用的端到端验证配置写完了得验证它真的能跑通。验证分三步触发测试、功能测试、性能对比。触发测试先看 Skill 会不会被自动加载。应该触发的场景直接表述“帮我审查这段 Python 代码”以及同义改写“看看这个函数命名规不规范”。不该触发的场景无关任务比如“今天天气怎么样”。如果该触发没触发回去改 description补上用户会说的触发短语。功能测试看三件事输出是否正确、工具调用是否成功、异常分支是否可恢复。这里用 TaoToken 的统一通道做一次实际请求。先确认环境变量export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEYsk-your-key-here然后用 curl 发一次请求验证模型通道是否通curl -s $TAOTOKEN_BASE_URL/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 256, messages: [ {role: user, content: 用一句话说明 SKILL.md 的作用} ] }成功的话会返回一段 JSONchoices 或 content 字段里有模型输出。如果返回 401说明 Key 不对或没带上如果返回 model not found说明 Model ID 写错了。这一步通了说明 TaoToken 的 Key 和 API 通道没问题接下来把 Skill 挂上去。在 Claude Code 里加载 Skill把 skill 文件夹放到项目约定目录然后在对话里说“帮我审查这段 Python 代码”。观察是否自动触发。触发后看它有没有按 SKILL.md 里的步骤走识别内部函数、检查前缀、给建议、说明原因。如果步骤跳了说明正文写得太啰嗦关键步骤埋太深把流程编号前置。性能对比用/status看往返轮次和 token 消耗。和“无 Skill”相比稳定触发后往返轮次应该减少失败调用应该下降。一个实用标准先打磨一个最难任务直到稳定再扩展测试集。别一上来写十个 Skill先把一个跑顺。验证通过后你可以把这套流程固化成团队资产。Skill 文件进版本库MCP 配置进 settingsKey 走 TaoToken 统一管理换模型或换工具时只改配置不改 Skill。5. 常见报错排查401、local proxy failed、reading choices、OAuth排障这部分按真实报错来对。下面四个是接入 Skills MCP 时最常撞上的。401 Unauthorized。表现是请求直接被拒返回体里带 401。原因通常是 Key 没带、Key 过期、或者 Base URL 和 Key 不匹配。排查顺序先确认环境变量TAOTOKEN_API_KEY有值再确认请求头里带了x-api-key最后确认 Base URL 是https://taotoken.net/api而不是别的地址。如果用的是 MCP 配置检查 env 块里三个字段是否齐全。local proxy failed。表现是 MCP 工具调用时报本地代理失败。原因一般是 MCP server 启动命令写错或者 npx 拉包失败。排查手动在终端跑一遍npx -y taotoken/mcp-server看能不能起来起不来就是网络或包名问题能起来但 Claude 里报错就是 settings 里的 command 或 args 路径不对。注意不要在任何配置里写代理相关的东西走正常网络即可。reading choices 报错。表现是解析响应时读不到 choices 字段。原因通常是请求发到了不兼容的端点或者响应格式和预期不符。排查确认你调的是/v1/messages而不是 OpenAI 风格的/v1/chat/completions两者响应结构不同。如果你用的是兼容层确认 Model ID 和端点匹配。OAuth 相关报错。表现是鉴权流程卡住或 token 刷新失败。原因通常是本地缓存了旧的凭证。排查清理本地凭证缓存重新走一次授权如果用的是 API Key 模式确认没有混用 OAuth 配置。Claude Code 的 auth.json 里如果同时有 OAuth 和 API Key 字段可能冲突建议只保留一种。把这几类错误和对应动作整理成一张对照表排障时直接查报错关键词常见原因处理动作401 UnauthorizedKey 缺失/过期/不匹配检查环境变量与请求头确认 Base URLlocal proxy failedMCP server 启动失败手动跑启动命令检查 settings 路径reading choices端点或响应格式不符确认调用/v1/messages核对 Model IDOAuth 失败凭证缓存冲突清理缓存只保留一种鉴权方式排障时优先看日志里的第一行错误那通常是最接近根因的。后面的堆栈往往是连锁反应。6. 把 Skill 沉淀成团队 SOP 的落地建议写 Skill 的本质不是堆指令而是沉淀团队的 SOP。这句话值得贴在显示器上。你写的每一份 SKILL.md都是在把“老员工脑子里的经验”变成“新员工能直接用的文件”。落地时有几个实用建议。第一description 用用户语言写别用技术黑话触发率靠它。第二SKILL.md 正文保持短超过一屏的内容拆到 references/。第三需要确定性校验的逻辑写成脚本放 scripts/别让模型猜。第四MCP 配置里的 Base URL、Key、Model ID 三件套写全缺一个就报错。第五先跑通一个最难任务再扩展。如果你还没开始可以从最小可用结构起步一个文件夹一个 SKILL.md先解决你每周重复三次的那个任务。跑顺了再加 scripts 和 references。需要统一 Key 和 API 通道的话可以去 TaoToken 控制台生成 Key接入文档里有各客户端的配置示例想先验证模型输出用模型对话页面直接试长期做编码和 Agent 的话Coding Plan 更适合持续调用。把 Skill 文件进版本库配置进 settingsKey 走统一管理这套组合跑起来你的 Agent 工作流才算真正可维护。