1. Claude Skills 到底是什么从 Prompt 堆叠到渐进式披露Claude Skills 是 Anthropic 给 Claude 系列模型Claude 3.5 Sonnet、Claude 4 Opus 等加的一层「能力封装」机制。你可以把它理解成给模型准备的一份标准作业程序把某个任务需要的规则、模板、脚本、参考资料打包成一个文件夹模型在合适的时机自动读取并执行。它解决的核心问题不是「模型不够聪明」而是「每次都要把同样的上下文重新讲一遍」。我最早接触这套机制是在做代码审查 Agent 的时候。当时每次对话都要把公司的命名规范、日志格式、异常处理约定贴一遍Token 消耗大不说模型偶尔还会漏掉其中两条。后来把这些规则拆进一个 Skill 目录触发词命中后模型自己按需读取输出一致性明显好了很多。这就是 Skills 和传统 Prompt 工程最大的区别Prompt 是「一次性投喂」Skills 是「按需检索 渐进式披露」。所谓渐进式披露Progressive Disclosure指的是模型不会一次性把 Skill 里所有文件都塞进上下文而是先读元数据判断要不要用再读主指令文件最后在真正需要某个资源时才去读对应的子文件。这个设计直接决定了 Token 成本。一个 Skill 目录里可以放几十个参考文档但单次对话可能只加载其中一两个剩下的留在磁盘上不占上下文窗口。和 MCP 的关系也常被搞混。MCPModel Context Protocol解决的是「模型怎么连外部工具和数据源」偏通信协议层Skills 解决的是「模型怎么知道在什么场景下该做什么、按什么规范做」偏知识与流程封装层。两者是协同关系Skill 负责判断「现在该调用哪个工具、传什么参数」MCP 负责把这次调用真正发到外部服务。一个典型的 Agent 链路是用户提问 → Skill 触发 → 注入工作流指令 → 模型决定调用某工具 → 通过 MCP Server 执行 → 结果回填 → Skill 里的规则校验输出格式。适合用 Skills 的场景有几个共同特征任务重复性高、有明确的专业规范、输出格式要求稳定。代码审查、周报生成、品牌文案、数据清洗脚本生成都属于这一类。反过来一次性的开放问答、纯创意发散用 Skills 反而增加负担。下面这张表可以帮你快速判断判断维度适合用 Skill不适合用 Skill任务频率每天/每周重复一次性规范强度有硬性格式或规则自由发挥资源依赖需要模板/脚本/知识库纯模型推理输出一致性要求稳定可复现允许每次不同理解了这个定位后面的目录结构、注入时机、工具调用链路就都是围绕「怎么让渐进式披露真正生效」来展开的。2. TaoToken 前置准备把 Base URL、Key、Model ID 三件套配齐在动手写 Skill 之前得先有一个能稳定调用 Claude 的入口。Skill 的调试过程需要反复触发、观察注入结果、检查工具调用如果底层 API 不稳定排障会变成玄学。我实测下来用 TaoToken 作为统一接入层比较省心它兼容 Anthropic 的原生协议Claude Code、Cline、Codex 这类工具都能直接对接。先明确三件套这是后面所有配置的基础Base URLhttps://taotoken.net/apiAPI Key在控制台创建形如sk-开头的一串字符Model ID按需选择比如claude-sonnet-4-20250514这类具体版本号获取 Key 的入口在控制台的 API Keys 页面创建后记得立刻复制页面刷新后就不再完整显示。模型列表可以在模型对话页面里先试跑一次确认你要用的 Model ID 能正常返回再去配到工具里避免配置和模型可用性两个问题混在一起排查。如果你用的是 Claude Code配置方式是在项目或用户目录下写 settings 文件。这里给一份可直接复制的 JSON 片段路径按你的实际环境调整{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }注意ANTHROPIC_BASE_URL不要带末尾斜杠也不要自己拼/v1客户端会按协议补全。这一点踩过坑手动加了/v1之后请求路径变成/v1/v1/messages直接 404。如果你用的是 Cline 或类似的 VS Code 插件配置项名称会不一样但本质还是三件套。Cline 里选 Anthropic 兼容模式Base URL 填https://taotoken.net/apiAPI Key 填你的 KeyModel ID 手填具体版本。有些插件会去拉模型列表如果拉取失败直接手动输入 Model ID 即可不影响使用。Codex 的 auth.json 结构稍有不同它把凭证和模型分开存{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model: claude-sonnet-4-20250514 }三件套配好之后先用一个最小请求验证通路别急着上 Skill。验证命令curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 OK 两个字母}] }返回里能看到content数组且文本是 OK说明 Base URL、Key、Model ID 三件套全部生效。这一步过了再进入 Skill 目录的搭建排障边界会清晰很多。如果这一步就报 401问题在 Key报 model not found问题在 Model ID报连接失败问题在 Base URL 或网络出口。3. 可复制配置SKILL.md 模板与 MCP 服务注册Skill 的目录结构是整套机制的地基。一个最小可用的 Skill 长这样~/.claude/skills/code-review/ ├── SKILL.md ├── references/ │ └── style-guide.md └── scripts/ └── lint_check.pySKILL.md是入口模型最先读它。它由两部分组成顶部的 YAML frontmatter 和下面的 Markdown 正文。frontmatter 决定「什么时候触发」正文决定「触发后怎么做」。这份模板可以直接复制改--- name: code-review description: 对 Python 代码做规范化审查检查命名、日志、异常处理与类型注解 version: 1.0.0 triggers: - keyword: review code - keyword: 代码审查 - task_type: programming --- # 代码审查 Skill ## 工作流程 1. 读取用户提供的代码文件或代码块。 2. 对照 references/style-guide.md 中的规范逐条检查。 3. 对每个问题给出位置、问题描述、修改建议、严重级别。 4. 输出为 Markdown 表格按严重级别降序排列。 ## 输出格式 | 行号 | 问题 | 建议 | 级别 | | --- | --- | --- | --- | ## 约束 - 不要重写整份代码只给局部修改建议。 - 严重级别只允许blocker / major / minor。 - 如果代码没有明显问题明确回复「未发现规范问题」。frontmatter 里的triggers是渐进式披露的第一道闸门。模型先看这些关键词和任务类型命中才继续读正文。所以关键词要写得具体别用「代码」这种泛词否则任何编程对话都会触发反而干扰。references/目录放的是「按需读取」的资料。比如 style-guide.md 里写详细的命名规范、日志格式模型只有在真正执行审查时才会去读平时不占上下文。scripts/放可执行脚本模型可以通过工具调用运行它们比如跑一个 lint 检查拿结构化结果。接下来是 MCP 服务注册。Skill 负责决策MCP 负责执行。假设你有一个本地 MCP Server 提供 Git 操作能力注册配置写在 Claude Code 的 MCP 配置文件里{ mcpServers: { git-tools: { command: npx, args: [-y, modelcontextprotocol/server-git], env: { GIT_REPO_PATH: /your/project/path } } } }注册完成后Skill 的正文里就可以引用这个 MCP 提供的工具。比如在 code-review 的流程里加一步「调用 git-tools 获取本次 diff」模型在触发 Skill 后会通过 MCP 拿到变更内容再执行审查。这里的关键是 Skill 和 MCP 的职责边界Skill 说「去拿 diff 然后审查」MCP 提供「拿 diff」这个动作。不要把业务规则写进 MCP Server也不要把工具调用细节写死在 Skill 里否则两边都难维护。再给一个带工具调用的 Skill 片段展示怎么把 MCP 工具串进工作流## 工作流程 1. 调用 git-tools 的 get_diff 工具获取当前分支相对 main 的变更。 2. 对变更中的每个 Python 文件读取 references/style-guide.md。 3. 逐文件检查输出问题表格。 4. 如果 diff 为空回复「本次无代码变更」。这样一份配置下来Skill 目录、SKILL.md、MCP 注册三部分就齐了。路径要和实际环境一致~/.claude/skills/是默认扫描目录如果你改了位置需要在客户端配置里同步。4. 验证请求触发 Skill、观察注入、确认回退配置写完不代表生效得有一套验证动作清单。我一般分四步走触发、观察、回退、边界。第一步触发验证。在 Claude Code 里输入一句包含触发词的话比如「帮我 review code 这段 Python」然后看模型是否按 SKILL.md 里定义的表格格式输出。如果输出格式和模板一致说明 Skill 被加载了。如果还是自由发挥说明触发没命中回去检查 frontmatter 的 keyword 是否和输入匹配。第二步观察注入时机。这一步需要看日志或调试输出。Claude Code 在启动时如果加了调试参数会打印加载了哪些 Skill、注入了哪些文件。你可以通过观察「模型是先读了 SKILL.md 还是直接读了 references」来判断渐进式披露是否按预期工作。正常情况下第一轮只读 SKILL.md只有当流程走到「对照规范检查」时才会去读 style-guide.md。第三步回退验证。Skill 机制必须支持「不触发」的情况。故意输入一句不含触发词的话比如「今天天气怎么样」确认模型没有加载任何 Skill正常回答。如果这时候还去读 code-review 的规范说明触发条件写得太宽需要收紧。第四步边界验证。测试触发词出现在无关语境里会怎样。比如「我不需要 review code只想聊聊天」看模型是否能识别否定意图而不触发。这一步能暴露关键词匹配的粗糙之处必要时在 SKILL.md 正文里加一条「如果用户明确表示不需要审查则跳过」。验证过程中MCP 工具调用也要单独确认。可以在 Skill 流程里加一句临时日志或者直接问模型「你刚才调用了哪个工具」。如果模型说调用了 git-tools 的 get_diff但实际没拿到 diff 内容问题在 MCP Server 那一侧和 Skill 无关。一个完整的验证请求示例用 curl 模拟带 Skill 上下文的调用curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 1024, system: 你已加载 code-review Skill按 SKILL.md 的格式输出。, messages: [{role: user, content: review code: def f(x): return x1}] }返回里如果出现 Markdown 表格且列头是「行号/问题/建议/级别」说明 Skill 的格式约束生效了。这一步过了再回到 Claude Code 里做交互式验证两边结果一致就可以认为 Skill 接入完成。5. 常见报错排查401、local proxy failed、reading choices、OAuth调试 Skill 和 MCP 的过程中报错基本集中在几个固定位置。下面按真实遇到的顺序列出来对照排查。401 Unauthorized。这个最常见九成是 Key 的问题。先确认 Key 有没有复制完整有没有多余空格。然后确认请求头字段名对不对Anthropic 原生协议用x-api-key有些客户端用Authorization: Bearer两者不能混。如果你用的是 Claude Code检查 settings 里的ANTHROPIC_AUTH_TOKEN是否被环境变量覆盖了。还有一种情况是 Key 创建后没启用回控制台确认状态。local proxy failed。这个报错通常出现在客户端配置了本地代理端口但代理进程没起来或者端口被占用。排查顺序先确认 Base URL 是不是被错误地指向了localhost某个端口正确值应该是https://taotoken.net/api。如果确实需要本地转发确认转发进程在运行且转发目标写的是正确的 Base URL。这个报错和 Skill 本身无关是网络层问题先解决通路再谈 Skill。reading choices 相关报错。这类错误一般出现在响应解析阶段提示读取choices字段失败。原因是客户端按 OpenAI 的响应格式去解析但 Anthropic 协议返回的是content数组结构不一样。解决办法是确认客户端选的是 Anthropic 兼容模式而不是 OpenAI 模式。如果你在 Cline 里选了 OpenAI Compatible 却填了 Anthropic 的 Base URL就会出这个错。切回 Anthropic 模式即可。OAuth 相关报错。有些客户端默认走 OAuth 流程但 TaoToken 用的是 API Key 认证两者不匹配就会报 OAuth 失败。处理方式是在客户端里关掉 OAuth 选项改用 API Key 直填。Claude Code 的某些版本会尝试 OAuth 登录需要在配置里显式指定用 token 认证。如果报错信息里出现oauth字样先检查认证方式选对没有。Skill 不触发。这个不算报错但很常见。排查三步一看 frontmatter 的 triggers 是否和输入匹配二看 Skill 目录是否在扫描路径下三看 SKILL.md 的 frontmatter 格式是否正确YAML 对缩进敏感多一个空格都可能解析失败。可以用一个最小 Skill 只留 name 和 description 测试确认机制通了再加 triggers。MCP 工具调用无响应。Skill 触发了但工具没执行。先单独测 MCP Server 能不能起来命令行手动跑一次注册时的 command看有没有报错。然后确认 Skill 正文里引用的工具名和 MCP Server 暴露的工具名完全一致大小写敏感。最后看权限有些 MCP Server 需要额外的环境变量或路径权限。把这几类报错和对应的检查点整理成一张对照表排障时按行查报错关键词大概率原因检查动作401Key 错误或请求头不对核对 Key 与x-api-keylocal proxy failedBase URL 指向本地或代理未启动改回https://taotoken.net/apireading choices客户端按 OpenAI 格式解析切换 Anthropic 兼容模式OAuth认证方式不匹配关闭 OAuth改用 API KeySkill 不触发triggers 或目录问题检查 frontmatter 与扫描路径排障的核心原则是分层先确认 API 通路三件套再确认 Skill 加载目录与 frontmatter最后确认 MCP 执行Server 与工具名。一层一层过不要跳。6. 继续深入把 Skill 接进你的日常编码流Skill 配好、验证通过之后真正的价值在于把它接进日常流程。我现在的做法是每个项目根目录放一个.claude/skills/把项目特有的规范、模板、脚本都收进去跟着代码一起做版本控制。这样换机器或者团队协作时Skill 跟着仓库走不用重新配。如果你还在选长期用的编码方案Coding Plan 适合把 Skill、MCP、多轮 Agent 任务放在一起跑额度模型对高频调试更友好。需要先拿 Key 或者看接入文档的从 API Keys 页面进文档里有各客户端的完整配置示例。想先验证模型输出质量的模型对话页面可以直接试跑确认 Model ID 和响应格式符合预期再落到配置里。Skill 这套机制目前还在快速迭代Anthropic 的官方文档和社区 Gallery 会持续更新预置包。我的建议是先从一个小 Skill 开始比如只做「提交信息规范化」跑通触发、注入、回退全流程再逐步加 references 和 MCP 工具。一次堆太多文件排障成本会指数上升。等第一个 Skill 稳定运行一周你对渐进式披露的节奏就有手感了后面扩展会顺很多。