写好 description

description 是整个 Skill 中最关键的一行字。它直接决定 Skill 是否会被加载——其它内容写得再好，触发不到都是零。

社区一致认同：写不好 description 是 Skill 失败的 #1 原因。本页把社区共识、Anthropic 官方建议、可复制的验证流程汇总到一起。

为什么 description 决定生死

复习一下 三层渐进加载：

• Level 1（启动时常驻）：name + description ≈ 100 tokens
• Level 2（命中时加载）：SKILL.md 正文 < 5,000 tokens
• Level 3（按需读取）：scripts/ / references/ / assets/

关键事实：agent 在做"是否触发该 Skill"的决定时，只能看到 Level 1 的 description。如果它从 description 里看不出"这件事归我管"，正文写得再精彩也无法被读到。

五大规则

1. 只说触发，不说过程
2. 第三人称 + 祈使句
3. 包含触发关键词与典型用户表述
4. 涵盖隐式触发
5. 要「略带强势」

下面逐条展开。

规则 1：只说触发，不说过程

这是 #1 重灾区。如果 description 把 "怎么做" 说了，agent 会以为不读正文也能完成，直接跳过加载 SKILL.md 正文。

# ❌ 讲了过程
description: >
  读取 PDF，使用 pypdf 提取文本，先检查加密，再生成 markdown。
  对加密 PDF 用 cryptography 库解密。
# Agent 想：你都告诉我步骤了，我直接照做就行，不用读正文。
# 结果：正文里那些边界处理、错误码映射、表格特殊格式 —— 全部没用上。

# ✅ 只说触发
description: >
  Use when the user needs to extract text or tables from PDF files,
  fill PDF forms, or merge multiple PDFs.
# Agent 想：用户问的是 PDF，归我管。我得读正文看具体怎么搞。

IMPORTANT

判别法：写完 description 后问自己「读完这段，agent 能直接动手吗？」能 → 说明你讲多了；不能，但他知道这归我管 → 完美。

规则 2：第三人称 + 祈使句

description 会被注入到 agent 的系统提示词里。视角不一致会让 agent 困惑：

示例	问题
I can help you process Excel files	第一人称——agent 不知道"I"是谁
You can use this to process Excel files	第二人称——agent 不知道"You"是它自己
Helps with Excel files	动词形式但模糊——什么帮助？
Processes Excel files and generates reports	✅ 第三人称、动词清晰
Use when the user uploads .xlsx files	✅ 祈使句，明确触发条件

规则 3：包含触发关键词与典型用户表述

agent 把用户消息与 description 做语义匹配。description 里如果完全不出现用户可能说的词，命中率就低。

# ❌ 关键词稀薄
description: 处理表格数据。

# ✅ 含领域术语 + 文件扩展名 + 中英双语关键词
description: >
  Use when the user works with spreadsheets — including Excel files
  (.xlsx, .xls), CSV files, or asks to "处理表格"、"做透视表"、"分析销售数据".
  Triggers on column-header phrases like "金额", "revenue", "customer".

TIP

触发关键词可以多语种、多种说法、含口语。用户不会按你预想的格式说话，描述要尽量"包住"他可能用的所有表达方式。

规则 4：涵盖隐式触发

很多时候用户不会直接点名领域。Skill 也要在这种"侧面"语境下被触发：

# ❌ 只能直接命中
description: Use when the user asks to process Excel files.
# 结果：用户说"老板发了个 xlsx 文件"——不命中（没说 Excel）

# ✅ 涵盖隐式表述
description: >
  Use when the user works with Excel/spreadsheet data — including
  cases where they don't explicitly mention "Excel" or "spreadsheet"
  (e.g., "my boss sent me this xlsx file", "请帮我看下这份销售数据",
  "make a chart from this data file").

Anthropic skill-creator 内部例子里有一句很经典的"用户口气样本"：

"ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage."

如果你的 description 能触发这种带错别字、口语、文件路径、上下文背景的真实表述，就基本及格了。

规则 5：要「略带强势」（pushy）

agent 默认懒触发——能用基础工具搞定的事不会调用 Skill。要让它意识到"这事归我管，必须用我"，description 应该主动声明它的能力边界：

# ❌ 太谦虚
description: Can help with PDF tasks if needed.

# ✅ 带"使命感"
description: >
  Always use this skill whenever PDF files are involved — including
  text extraction, form filling, merging, or visual layout analysis.
  Do not attempt to handle PDFs without this skill, even for simple cases.

WARNING

不要矫枉过正——「always use this skill」适合定位独占的 Skill。如果你的 Skill 只覆盖部分场景，越界声称会变成误触发。"pushy" 的尺度是对自己负责的范围内强势。

验证方法：LLM 隔离测试

写完 description 后，在动手写正文前，先做一次隔离测试——把 description 单独喂给一个全新的 LLM 对话，让它评估"在什么情况下会被触发"。

把以下提示词复制到一个新对话：

我正在写一个 Agent Skill，遵循 agentskills.io 规范。
Agent 会**仅根据下面的 YAML 元数据**决定是否加载这个 Skill。

请你判断：
1. 哪些用户输入会让 agent 加载它？
2. 哪些用户输入"看起来像但其实不该"加载它？
3. description 有什么模糊或冲突的地方？

YAML 元数据如下：

```yaml
name: my-skill
description: >
  ……（贴你的 description）
```

如果 LLM 给出的"会触发"列表与你的预期不符，说明 description 还要改。这一步比写正文更值得反复打磨。

验证方法：触发率评估

更系统的方法（来自 agentskills.io 官方推荐流程）：

第 1 步：建评估集

准备两个清单：

清单	目标	建议数量
should-trigger queries	应该触发的用户表述	10–20 条
should-not-trigger queries	看起来相关但不该触发的	5–10 条

queries 必须真实——含错别字、口语、文件路径、个人背景。不要写成"Format this data" / "Extract text from PDF" 这种抽象指令。

[
  { "query": "我刚才上传的那份 .pdf 有 200 页，能帮我提取所有表格吗？", "should_trigger": true },
  { "query": "ok so my boss sent me this xlsx file...", "should_trigger": false },
  // ...
]

第 2 步：跑触发率

每条 query 跑 3+ 次（agent 行为非确定性），算触发率：

期望	阈值	结论
should_trigger=true	触发率 > 0.5	✅ 通过
should_trigger=false	触发率 < 0.5	✅ 通过

20 条 × 3 次 = 60 次调用，可以稳定揭示问题。

第 3 步：迭代

没通过的 query 是黄金信息——它告诉你 description 哪里没说清。把失败 query 的关键表述补回 description，再跑一轮。

TIP

上述流程在 Anthropic skill-creator 中有现成实现，能自动生成测试样例并跑评估。详见下一页 工具与生态。

检查清单

写好 description 后，对照以下 checklist：

• [ ] 长度 ≤ 1024 字符
• [ ] 只描述何时触发，不描述如何执行
• [ ] 第三人称 + 祈使句（Use when... / Processes...）
• [ ] 含至少 3 个触发关键词
• [ ] 含至少 1 个隐式触发场景
• [ ] 没有 claude / anthropic 等保留词
• [ ] LLM 隔离测试结果与你的预期一致
• [ ] 至少跑过 5 条真实 query，触发行为符合预期

下一步

掌握了 description，你已经避开了 Skill 创作中 #1 的坑。接下来：

• 想把所有反模式一次性看清楚？→ 反模式与坑
• 想知道工具链怎么帮你自动化这一切？→ 工具与生态
• 想立刻写第一个？→ 快速开始