Claude 终极使用指南

主题

08.3 编写高触发率的 description ​

Skill 最常见的失败不是逻辑错，是"该触发时没触发"。根因几乎都在 description。

读完你能做什么：写出让 Claude 在正确场景可靠触发、错误场景不误触发的 description。

一、触发是怎么发生的 ​

回到机制：Claude 看到的是每个技能的 name + description（第 1 层，常驻上下文）。当你提出需求时，Claude 判断"这个需求和哪个技能的 description 匹配"，匹配上就调用。

text
你的需求  →  Claude 拿它和所有技能的 description 做语义匹配  →  匹配上就触发

因此 description 的本质是：一段描述"什么情况下该用这个技能"的触发条件。 它不是给人看的功能介绍，是给 Claude 看的匹配信号。

二、触发失败的三个根因 ​

根因 1：description 只说"是什么"，不说"何时用" ​

markdown
❌ description: 数据库迁移工具
   （Claude 知道它是什么，但不知道什么时候该用）

✅ description: 生成和执行数据库 schema 迁移。当用户需要修改表结构、
   添加字段、创建索引，或提到"迁移""migration""改表"时使用。

关键：description 里要包含触发场景和触发词。

根因 2：描述太窄或太宽 ​

markdown
❌ 太窄：description: 修复 UserService.java 第 45 行的空指针
   （只匹配一个极具体的情况，几乎永远触发不了）

❌ 太宽：description: 处理代码相关的任务
   （匹配一切，导致到处误触发）

✅ 适中：description: 诊断和修复 Java 空指针异常。当遇到 NullPointerException、
   或用户报告"空指针""NPE""XX 是 null"这类问题时使用。

根因 3：用词和用户的说法不一致 ​

markdown
❌ description: 执行持续集成流水线验证
   （用户会说"跑一下 CI""检查构建"，不会说"持续集成流水线验证"）

✅ description: 运行 CI 检查，包括测试、类型检查、lint。当用户说"跑 CI"
   "检查构建""提交前验证""能过 CI 吗"时使用。

技巧：想象用户实际会怎么描述这个需求，把那些说法（包括口语、缩写、同义词）放进 description。

三、description 的写法公式 ​

text
description: <这个技能做什么>。当<触发场景1>、<触发场景2>，
             或用户提到"<触发词1>""<触发词2>""<触发词3>"时使用。

三个组成部分：

部分作用例子
功能说清做什么"生成上线前检查报告"
触发场景描述适用情境"当用户准备发布、部署时"
触发词列出实际说法'提到"上线""发版""deploy"时'

四、正例集 ​

4.1 流程类技能 ​

markdown
---
name: incident-response
description: 引导生产事故的处理流程，包括止血、根因、复盘。当发生线上故障、
  用户报告"挂了""宕机""P0""incident""生产出问题"，或需要事故复盘时使用。
---

4.2 生成类技能 ​

markdown
---
name: adr-writer
description: 把一个技术决策整理成标准的架构决策记录（ADR）文档。当用户做出
  重要技术选型、说"记录这个决策""写个 ADR""为什么选 X 不选 Y"，
  或讨论结束需要沉淀决策时使用。
---

4.3 检查类技能 ​

markdown
---
name: security-checklist
description: 对代码执行安全检查清单，覆盖注入、鉴权、敏感信息泄露。当用户
  提到"安全审计""检查安全问题""有没有漏洞""security review"，
  或处理涉及认证、支付、用户数据的代码时使用。
---

4.4 领域专项技能 ​

markdown
---
name: sql-migration
description: 按本团队规范编写和审查数据库迁移脚本。当用户需要改表结构、
  加字段、建索引、写 migration，或提到"改数据库""加个字段""迁移脚本"时使用。
  本技能包含我们的迁移规范（向后兼容、可回滚、分批执行）。
---

五、避免误触发 ​

高触发率不等于"逮谁触发谁"。误触发同样有害 —— 它会在你不需要时插入无关流程。

5.1 用边界词划清范围 ​

markdown
description: 生成正式的对外文档（如 API 文档、用户手册）。
  仅用于面向外部的正式文档，不用于代码注释或内部笔记。

5.2 对有副作用的技能，禁用自动触发 ​

有副作用的技能（部署、提交、发消息）宁可不自动触发，用 disable-model-invocation: true 让它只能手动调：

markdown
---
name: deploy-prod
description: 部署到生产环境。仅通过 /deploy-prod 手动触发。
disable-model-invocation: true
---

这样即使 description 匹配了，Claude 也不会自作主张部署。

六、测试触发准确率 ​

写完 description 别急着用，测一测。

6.1 手动测试 ​

准备几组应该触发和不该触发的输入，逐个试：

text
应该触发：
- "帮我跑一下 CI"
- "提交前检查一下"
- "这个能过构建吗"

不该触发：
- "解释一下 CI/CD 是什么"（这是问概念，不是要跑）
- "帮我写个新功能"（无关）

对每个输入，观察 Claude 是否按预期触发/不触发。

6.2 用 skill-creator 评测 ​

Claude Code 的 skill-creator 技能能帮你系统地测试和优化 description 的触发准确率，包括方差分析：

text
> 用 skill-creator 帮我测试 sql-migration 这个技能的触发准确率，
  给我一组会误触发和漏触发的案例

七、迭代 description 的流程 ​

text
1. 写初版 description（功能 + 场景 + 触发词）
2. 准备"应触发"和"不应触发"两组测试输入
3. 逐个测试，记录：
   - 漏触发（应触发却没触发）→ description 太窄/缺触发词
   - 误触发（不应触发却触发）→ description 太宽/缺边界
4. 针对性调整：
   - 漏触发 → 补充触发场景和用户的实际说法
   - 误触发 → 加边界词，或禁用自动触发
5. 重测，直到两组都正确

八、一个改进前后的对比 ​

改进前（经常漏触发）：

markdown
---
name: perf-audit
description: 性能审计
---

改进后（触发可靠）：

markdown
---
name: perf-audit
description: 分析代码的性能问题，包括慢查询、N+1、不必要的循环、内存泄漏。
  当用户说"太慢了""性能问题""优化一下速度""为什么这么卡"，
  或处理明显涉及性能的代码（大数据量循环、数据库查询、频繁调用）时使用。
  不用于纯功能实现或代码风格问题。
---

改进点：

  • 说清了具体覆盖什么（慢查询、N+1...）
  • 列了用户的实际说法（"太慢了""这么卡"）
  • 加了触发场景（涉及性能的代码）
  • 加了边界（不用于功能/风格）

九、Checklist ​

写完 description 逐项检查：

text
□ 说清了这个技能"做什么"
□ 描述了"什么场景"该用它
□ 列出了用户可能的实际说法（口语、缩写、同义词）
□ 范围适中（不是只匹配一个具体情况，也不是匹配一切）
□ 如果有边界，用边界词划清了"不用于什么"
□ 有副作用的技能，考虑了是否该禁用自动触发
□ 用"应触发/不应触发"两组输入测试过

延伸阅读 ​

基于 VitePress 构建 · 内容采用原作者授权

© 2026 星创数学 XCMath