1. 为什么你的 Skill 总是“该触发时不触发”如果你最近在 Claude Code 里攒了十几个 Skill大概率遇到过这种尴尬明明写好了SKILL.md描述也填了结果问一个完全对口的问题Claude 却像没看见这个技能一样直接用自己的原生能力回答了。更气人的是有时候它又在完全不相关的场景里突然把某个技能拉出来用输出一堆你根本没要的格式。这不是你的错觉也不是模型“变笨了”。核心原因在于Skill 的触发完全依赖 frontmatter 里的description字段而描述词的边界一旦模糊触发判断就会失准。描述写得太宽比如“用于处理文档相关任务”那任何跟文字沾边的请求它都想插一脚描述写得太窄比如“仅用于将 PDF 中第 3 页表格转为 CSV”那稍微换个说法它就装死。Claude Skill Creator 2.0 这次更新本质上就是把“写 Skill”从碰运气变成了可验证的工程流程。它给了你三样东西评测能力跑测试用例看通过率、A/B 基准测试对比加载技能和不加载技能的输出质量、描述词优化自动分析触发准确率并给出改写建议。再加上多智能体并行评测一次能跑 6 个独立智能体每个都在干净上下文里执行互不污染。这篇文章聚焦两件事SKILL.md 到底怎么写才规范frontmatter 里每个字段分别控制什么行为。我会给你可直接复制的模板、参数清单以及本地加载后验证触发和参数生效的完整操作步骤。适合已经在用 Claude Code、手上有一堆 Skill 但触发不稳定的人也适合刚准备写第一个 Skill 的新手。先明确一个概念Skill 不是提示词模板它是可测试、可版本管理的软件制品。你写进SKILL.md的每一行每次触发时都会被完整加载进上下文。所以文件越长开销越大字段越模糊触发越飘。下面从最基础的目录结构开始拆。2. SKILL.md 目录结构与 frontmatter 字段全解析一个标准的 Skill 目录长这样你可以直接照着建your-skill/ ├── SKILL.md # 必需技能主文件 ├── scripts/ # 可选放确定性校验脚本 │ └── validate.py └── references/ # 可选放详细文档和示例 └── api-notes.mdSKILL.md由两部分组成顶部的 YAML frontmatter和下面的 Markdown 正文。frontmatter 用---包裹字段决定“这个技能什么时候被唤醒、以什么身份执行”正文决定“唤醒之后具体怎么做”。先看一份可直接复制的最小可用模板--- name: code-reviewer description: 用于对 Python 代码进行结构化评审检查命名规范、异常处理和边界条件。当用户提交代码片段并要求评审、审查或找问题时触发。不用于简单语法问答或代码格式化。 version: 1.0.0 author: your-name agent: reviewer metadata: tags: - code-quality - python --- # 代码评审技能 ## 触发后执行步骤 1. 读取用户提交的代码片段确认语言为 Python。 2. 按以下维度逐项检查 - 命名是否符合 PEP 8 - 异常处理是否覆盖边界情况 - 是否存在未关闭的资源 3. 输出格式固定为三段问题列表、修改建议、示例代码。 ## 约束 - 只评审不直接重写整份代码。 - 如果代码少于 5 行提示用户提供更完整片段。现在逐个拆 frontmatter 字段。这张表是你写 Skill 时的对照清单字段是否必需作用常见取值/示例name必需技能唯一标识调用时用code-reviewerdescription必需触发判断的唯一依据一段包含触发场景排除条件的描述version推荐版本管理配合基准测试1.2.0author可选归属标记your-nameagent可选指定子代理执行隔离上下文reviewermetadata可选自定义键值对如标签tags: [code-quality]description是重中之重。它同时承担两个职责告诉 Claude“什么时候该用我”以及“什么时候别用我”。写法上建议三段式用途 触发场景 负触发器。负触发器就是明确排除条件比如上面模板里的“不用于简单语法问答或代码格式化”。这一句能挡掉大量误触发。agent字段值得单独说。当你写agent: reviewer时Claude 会为这个技能创建一个独立的子代理来执行上下文和主对话隔离。多智能体协作场景下这意味着评审技能不会把主对话的历史全带进去Token 消耗和干扰都更可控。如果你要做“生成→评审→格式整理”的流水线每个环节用不同 agent彼此接力而不是堆在一个上下文里。正文部分的原则是精简。经验值超过 5000 字性能开始明显下降控制在 500 行以内比较合理。详细文档、API 说明、只在特定场景才需要的内容全部丢到references/目录在正文里按需引用并说明“什么时候去读”。比如## 参考资料 当需要处理复杂表单坐标计算时读取 references/form-coords.md。这样 Claude 只在真正需要时才加载那部分内容平时不占上下文。还有一个容易被忽略的点不要在正文里写全局生效的指令比如“必须一直用列表回答”或“绝对不能用正式语气”。这类规则会和其他技能冲突。正确做法是收紧边界一个技能只解决一个具体问题需要组合时在正文里显式调用其他技能。3. 可复制配置多智能体协作的 SKILL.md 与 settings 片段多智能体协作的核心思路是把一个大流程拆成多个单一职责的 Skill每个用独立agent执行通过正文里的显式调用串起来。下面给你一套可直接复制的三件套配置包含 Base URL、Key、Model ID 的接入方式以及多技能协作的SKILL.md。先看接入配置。在 Claude Code 里你需要把模型服务指向兼容端点。配置文件通常放在项目根目录或用户配置目录格式如下以settings.json为例{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }三件套对应关系要记牢Base URL 填https://taotoken.net/apiKey 填你在控制台生成的密钥Model ID 填具体模型标识。缺任何一个请求都会失败。Key 的获取入口在控制台的 API Keys 页面模型对话入口可以用来先验证模型是否通。接下来是多智能体协作的 Skill 组合。假设你要做一条“内容生成→质量检查→格式整理”的流水线建三个目录pipeline/ ├── content-writer/ │ └── SKILL.md ├── writing-guard/ │ └── SKILL.md └── format-cleaner/ └── SKILL.mdcontent-writer/SKILL.md--- name: content-writer description: 用于根据大纲生成技术文章初稿。当用户提供大纲并要求撰写、扩写或生成正文时触发。不用于润色已有成稿或纯翻译任务。 version: 1.0.0 agent: writer --- # 内容生成技能 ## 执行步骤 1. 读取用户提供的大纲确认章节数量。 2. 逐节生成正文每节不少于 300 字。 3. 生成完成后调用 writing-guard 技能进行检查再返回结果。writing-guard/SKILL.md--- name: writing-guard description: 用于检查技术文章初稿的语气一致性和事实准确性。当其他技能或用户要求对草稿进行质量检查时触发。不用于从零生成内容。 version: 1.0.0 agent: guard --- # 质量检查技能 ## 执行步骤 1. 逐段检查语气是否统一标记突兀表达。 2. 检查技术术语使用是否一致。 3. 输出问题清单不直接改写原文。format-cleaner/SKILL.md--- name: format-cleaner description: 用于将检查通过的草稿整理为最终 Markdown 格式统一标题层级和代码块标注。当草稿通过质量检查后触发。不用于内容创作或事实核查。 version: 1.0.0 agent: cleaner --- # 格式整理技能 ## 执行步骤 1. 统一所有标题层级确保不跳级。 2. 为所有代码块补充语言标注。 3. 输出最终版本。注意每个技能的description都带了负触发器agent字段各不相同。这样在流水线执行时Claude 会为每个环节创建独立子代理上下文互不污染。content-writer正文里那句“调用 writing-guard 技能进行检查”就是显式的技能组合调用。如果你用 Codex 或 Cline 这类工具配置思路类似auth.json或 MCP 配置里同样要写全 Base URL、Key、Model ID 三件套。以auth.json为例{ baseUrl: https://taotoken.net/api, apiKey: sk-你的密钥, model: claude-sonnet-4-20250514 }配置写完后把技能目录放到 Claude Code 能识别的技能路径下重启生效。下一步就是验证触发和参数是否真的按你写的走。4. 验证请求确认触发生效与参数落地配置写完不代表生效必须跑验证。这一步很多人跳过结果线上出问题只能靠猜。下面给你一套可跟做的验证流程从触发测试到参数确认。第一步确认技能被正确加载。在 Claude Code 终端里执行插件市场添加和安装命令/plugin marketplace add anthropics/skills /plugin install document-skillsanthropic-agent-skills安装完成后重启 Claude Code。如果你之前装过先更新插件再重启。重启后用一条明确的触发语句测试使用 code-reviewer 技能评审这段 Python 代码 def f(x): return x/0如果技能被正确触发Claude 会按你SKILL.md里定义的输出格式返回三段式结果问题列表、修改建议、示例代码。如果它只是普通地回答“这里会除零错误”说明触发没生效问题多半出在description上。第二步验证负触发器是否起作用。发一条应该被排除的请求帮我看看 Python 里 list 和 tuple 有什么区别这条属于“简单语法问答”按你写的负触发器code-reviewer不应该被唤醒。如果它还是跳出来做评审说明负触发器写得不够明确需要回到description里加强排除条件。第三步验证agent字段是否真的隔离了上下文。在多智能体流水线里触发content-writer后观察它是否调用了writing-guard。你可以用 Skill Creator 的评测功能来量化使用 Skill Creator 对 content-writer 运行评估它会生成evals.json测试用例文件然后启动多个并行智能体。典型配置是 6 个智能体3 个带技能运行3 个不带技能作为基线。跑完后 Claude 会生成一个基于 HTML 的评估查看器在浏览器里并排展示“带技能”和“不带技能”的输出对比。第四步确认参数落地。检查评估报告里的通过率和失败项。如果agent字段没生效你会看到子代理没有独立创建所有执行都挤在主上下文里Token 消耗异常高。这时候回到SKILL.md确认agent字段拼写正确且没有和metadata里的键冲突。第五步做 A/B 基准测试确认技能没有拖后腿使用 Skill Creator 对 code-reviewer 进行基准测试它会用同一组输入分别在加载技能和不加载技能下运行然后由独立的评审智能体盲审裁决。结果出来后按这个决策原生 Claude 胜出就直接删技能技能略微领先就保留等下次模型更新后再测技能大幅领先就继续用。模型在进步你的技能可能在退化每次大版本更新后跑一遍这个测试几分钟就能避免长期用着悄悄降低输出质量的过时技能。验证通过后你才算真正完成了一个 Skill 的闭环。接下来是排障环节这些报错我基本都踩过。5. 常见报错排查401、local proxy failed 与触发失效排障这部分按报错现象来每条都给你原因和修法。先看最影响接入的几个。报错一401 Unauthorized。请求直接被拒通常是 Key 没填对或没生效。检查三件套Base URL 是否为https://taotoken.net/apiKey 是否从控制台 API Keys 页面正确复制注意前后不要有空格Model ID 是否拼写正确。如果用的是settings.json确认ANTHROPIC_API_KEY字段名没写错。改完后重启 Claude Code 再试。报错二local proxy failed。这个报错说明本地代理层没起来或端口冲突。先确认你的配置里没有残留的本地代理地址Base URL 应该直接指向服务端点不要经过额外的本地转发。如果你之前配过其他工具的代理设置检查环境变量里有没有冲突的HTTP_PROXY或HTTPS_PROXY有的话清掉再重启终端。报错三reading choices 相关解析失败。这类报错通常出现在响应格式不符合预期时根源往往是 Model ID 填了一个不支持当前接口协议的模型。确认你填的 Model ID 和服务端支持的列表一致。如果换了模型后出现先换回之前能用的 Model ID 验证再逐个排查。报错四OAuth 相关报错。如果你在配置里混用了 OAuth 流程和 API Key 流程会冲突。API 接入只需要 Key不需要走 OAuth。检查配置文件里有没有多余的 OAuth 字段删掉后只保留 Base URL、Key、Model ID 三件套。报错五技能该触发却不触发。这是最高频的问题不是接入错误而是description问题。用 Skill Creator 的描述词优化功能来定位使用 Skill Creator 优化 code-reviewer 的描述词它会用大量提示词做多场景压力测试验证技能在应触发请求中是否激活、在无关请求中是否保持静默然后自动重写描述逻辑。官方在自家技能上测试发现6 个技能中有 5 个触发准确率明显提升。优化后重新跑一遍触发测试确认。报错六技能触发太频繁不该用时也用。同样是描述问题但方向相反。加负触发器在description末尾补一句明确的排除条件比如“不要用于简单数据查询或一般问题仅用于完整报告生成流程”。记住三点描述太模糊容易误触发描述太严格很难触发负触发器的作用是在不缩小范围的前提下把不相关情况排除掉。报错七多技能同时启用后响应变慢。每次对话 Claude 都要把所有技能的描述加载进上下文来判断触发技能一多开销迅速累积。经验上超过 20 到 50 个技能性能开始明显下降。做法是只保留当前任务相关的技能其他按需启用而不是一直开着。不是技能越多越好而是让合适的技能在合适的时候出现。报错八多 MCP 工作流里调用顺序错乱。当一个技能需要调用多个服务时顺序和数据流必须写清楚。在SKILL.md里明确拆分 step1、step2、step3指定每一步的输出如何传给下一步并在关键节点加验证。顺序不清会导致调用链错位数据不明确会导致上下文传递出错缺少校验会让错误一路累积放大到最终结果。排障的核心逻辑是接入类报错查三件套触发类报错查description性能类报错查技能数量和文件长度。把这几类分开定位大部分问题几分钟就能解决。6. 从能跑到可靠把 Skill 当软件制品来管写到这里你已经有了完整的 SKILL.md 模板、frontmatter 字段清单、多智能体协作配置、验证流程和排障手册。最后说几个让技能从“能跑”变成“可靠”的实践。关键校验放进脚本。写在SKILL.md里的指令本质是交给 Claude 理解执行时有弹性。涉及必须稳定、不能出错的校验逻辑放进scripts/目录用 Python 或 Bash 写。脚本不做解释只执行通过就是通过不通过就是失败。在SKILL.md里调用它Claude 根据返回结果决定继续或中断。必填字段校验、数据格式检查、文件结构验证都适合这么做。你不一定自己写可以直接问 Claude“这个技能适合用脚本吗”它通常能帮你生成并整理好。用版本号串起测试记录。在 frontmatter 的metadata里加version字段。模型更新后重新跑基准测试、修改技能后对比前后效果、回头分析哪次改动带来提升都靠这个字段对齐。没有版本号测试结果就是一堆对不上号的记录。控制活跃技能数量保持 SKILL.md 精简。这两条前面提过但值得再强调。文件超过 5000 字性能明显下降控制在 500 行以内活跃技能超过 20 到 50 个响应变慢。详细内容放references/按需引用。每次模型大版本更新后跑一遍基准测试。这是最容易被忽略但回报最高的一步。模型在进步你的技能可能在退化。几分钟的测试能避免长期使用那些悄悄降低输出质量的过时技能。Anthropic 这次更新把技能开发从“写完就用”变成了覆盖测试、测量、优化的完整生命周期。技能不再只是提示词而是可测试、可验证的软件制品。你现在就可以从手头触发最不稳定的那个技能开始用 Skill Creator 跑一遍评测看看通过率和失败项然后定向修复。需要先接入的话API Keys 和接入文档在控制台和文档页都能找到想先验证模型是否通用模型对话入口发一条测试请求即可如果你要长期做编码和 Agent 流水线Coding Plan 会更合适。