团队的 Skill 库长到十几个以后，最烦人的问题通常不是 Skill 不会写，而是它在错误的时候出现，或该出现时装死。有人问“看下最近的改动”，发布 Skill 跳出来跑一整套构建；有人明确说“发到 staging”，agent 却只给一段建议。两种情况都会让人慢慢放弃自动触发，最后每次都手动贴流程，Skill 也就成了摆设。

把这件事换个角度看会清楚很多：description 不是介绍文案，它是路由规则。Claude Code 用 description 判断何时加载 Skill；Skill 的目录名则是可直接调用的命令。[1] Agent Skills 规范也把 name 和 description 放在第一层发现信息里，完整 SKILL.md 只在任务匹配后才加载。[2] 所以 description 写得含糊，不是文案差一点，而是在给调度器喂一个模糊分类器。

先把“触发”当成可测行为#

我会为每个关键 Skill 建一个很小的测试表，至少各放五条正例和反例。正例是它必须接住的真实说法，不写“我要发布”这种教科书句子，而写同事真的会发的消息：把当前分支部署到预发，别推生产、合并前帮我跑发布检查。反例同样重要：这次发布流程哪里会失败？ 可能只是咨询，不该启动命令；修一下 staging 的按钮 也不等于允许部署。

测试的目标不是追求每次都自动调用。高成本、有副作用的 Skill 宁可漏一次，也别误跑一次，保留显式 /release-check 作为逃生门。纯只读的排查 Skill 可以放宽一些。把风险等级写进测试表，你才不会拿“触发率”这个漂亮但没用的数字，掩盖一次错误部署的代价。

description 要写边界，不要堆关键词#

差的写法是：处理发布、部署、CI 和版本相关工作。 它看似覆盖全面，实际上会把“解释 CI 红了”也吸进去。好一点的写法是：仅在用户明确要求执行部署或发布前检查时使用；运行构建和验证，不推送、不部署生产。 前半句给触发条件，后半句写能力边界。官方同样建议 description 说明 Skill 做什么、何时使用；过宽会误触发，太窄又会漏掉合理请求。[1][2]

别把每个同义词都塞进 description。模型不靠机械关键词匹配，长描述还会让所有 Skill 的启动目录变胖。规范建议把详细指令留在激活后的主体，并把大参考资料拆到按需读取的文件中。[2] 真正需要覆盖的表达差异，应该沉到测试集：每发现一次漏触发，就补一条用户原话；每发生一次误触发，也别只改描述，先补反例把事故钉住。

快速上手：30 分钟做第一轮路由测试#

先选一个最常被手动调用、风险又可控的 Skill，例如 release-check。在它旁边建一份测试表：

# .claude/skills/release-check/trigger-cases.yml
should_trigger:
  - "把当前分支部署到预发，别碰生产"
  - "合并前跑一次发布检查"
  - "请执行 release-check，输出构建结果"
should_not_trigger:
  - "发布流程失败时怎么排查？"
  - "修复预发环境的登录按钮"
  - "解释这段 CI 日志"

然后把 description 收紧到能区分两组话的程度：

---
name: release-check
description: 执行发布前构建与验证。仅在用户明确要求发布前检查、部署或直接调用 release-check 时使用；不推送代码，不部署生产。
---

逐条把 case 放进一个干净会话，打开客户端的执行日志或工具调用记录，记下“是否加载了 SKILL.md”。每次只改 description 的一个意思，再重跑整组 case。不要在同一轮里既换描述又改 Skill 正文，否则你不知道到底是路由出了问题，还是执行流程让 agent 临时改了主意。

表格里再加三列就够用了：本次是否触发、结果是否符合预期、备注。备注不要写“感觉不太对”，要存完整原话、所用客户端版本、Skill 的提交号，以及是否有人在提示里显式点名。这样下次改动后，才能区分模型行为波动、客户端升级和描述回归。对触发结果没有自动化观测能力的工具，也可以先让两个人各自跑一遍同一组 case；结果不一致时先固定环境，再讨论措辞。这里求的是可比较的样本，不是假装得到绝对确定性。

把误触发变成回归用例#

这套表最有价值的时刻，是一次真实事故之后。比如 agent 因为“检查部署状态”启动了发布 Skill，就把那句原始请求加入 should_not_trigger；如果用户说“上线前确认一下”却没有命中，就加入 should_trigger。两周后你会得到一份属于自己团队的口语语料，比从网上抄十条关键词实在得多。

Skill 库不是规则越多越聪明。真正可靠的库会把路由当作产品接口维护：每个 Skill 有清楚的入口、边界和一组会失败的测试。这样 agent 偶尔理解错了，也能留下可修复的痕迹，而不是让下一位同事继续猜它什么时候会出手。

Sources#

[1] https://docs.anthropic.com/en/docs/claude-code/skills — Extend Claude with skills - Claude Code Docs [2] https://agentskills.io/specification — Agent Skills Specification