你真的会写 Skill 吗？Description 是触发器，而不是摘要（2/7）

写 skill 的最高杠杆点：description 是写给模型看的，而不是写给人看的

为什么先讲它

上一课我们建立了三层模型：元数据层（name + description）永远在线，是 agent 决定”要不要调用这个 skill”的唯一依据。这意味着一个残酷的事实：

Anthropic 的 Claude Code 团队在内部跑了几百个 skill 后，把这条写进了他们的经验总结，原话是：

注意这句话里视角的切换：description 的读者不是人类用户，而是模型。人类用户在界面上看到的是 display_name 和图标；而模型看到的却是 description——它拿着这段话去和用户的消息做语义匹配。写 description，我们实际上是在写一段”给模型的路由规则”。

好 description 的解剖

官方规范（agentskills.io）给了一对标准对照：

❌ Poor example（失败的例子）
description: Helps with PDFs.

# 翻译：帮忙处理 PDF。
→ 没有说清做什么，没有说清何时用
→ 模型匹配"帮我改一下这个 PDF"时，语义距离太远，不触发

✅ Good example（合格的例子）
description: Extracts text and tables from PDF files, fills PDF forms,
and merges multiple PDFs. Use when working with PDF documents or when
the user mentions PDFs, forms, or document extraction.

# 翻译：从 PDF 文件中提取文本和表格、填写 PDF 表单、合并多个 PDF。
# 当用户在处理 PDF 文档，或提到 PDF、表单、文档提取时使用。
→ 前半句：做什么（三个具体动作）
→ 后半句：何时用（含用户会说的关键词）

核心公式：description = 具体能力清单 + 触发场景 + 用户关键词。三个要点各司其职：

• 具体能力清单：动词开头，让模型判断”我的任务在它的能力范围内吗”
• 触发场景：当什么发生时使用，让模型判断”现在的情境对吗”
• 用户关键词：用户嘴里会说出的词，模型的匹配是语义层面的，关键词直接缩短语义距离

看一个公开的真实案例

以一个公开的 grill-me skill 为例，它的 description 是这样写的：

Interview the user relentlessly about a plan or design until reaching
shared understanding, resolving each branch of the decision tree.
Use when user wants to stress-test a plan, get grilled on their design,
or mentions "grill me".

# 翻译：围绕一个方案或设计不断追问用户，直到达成共识，把决策树的
# 每个分支都拆解清楚。当用户想压力测试一个方案、想被拷问自己的设计，
# 或提到"grill me"时使用。

对照公式检验：

• 能力清单（interview、resolve decision tree）✓
• 触发场景（想压力测试方案时）✓
• 关键词（”grill me”）✓

所以用户说”帮我拷问下这个方案”时它会准时出现——这不是运气，是 description 写对了。

一个进阶判断：边界声明

当我们的 skill 和别的 skill 触发域有重叠时，可以在 description 里显式划出边界。还有一种更彻底的做法：给 skill 配上 disable-model-invocation: true（禁止模型自动调用），让它完全不参与自动匹配，只能由用户手动触发。这是两种互不冲突的策略：

• 参与自动触发→ description 必须精确，宁可窄不可宽
• 只手动触发（/命令）→ description 可以更简略，将触发控制权完全交还给用户

检验一下

description = 具体能力清单（动词开头）
            + 触发场景（当什么发生时使用）
            + 用户关键词（用户嘴里会说出的词）

❌ Helps with X.   （帮助处理 X——无动作、无场景、无关键词）
✅ {动词} {对象} {产出}. 当 {场景} 时，
   或用户提到 "{关键词1}", "{关键词2}" 时使用。