一、智能体是怎么相中技能的

先说清楚：它不会把所有技能的正文都读一遍再挑。那样上下文立刻就爆了。 实际发生的是这样一件事：系统把所有技能的「名字 + description」拼成一张清单， 连同你的请求一起交给模型，问它一句「这次该用哪个，或者都不用」。 模型看完清单，做出选择，然后系统才去磁盘上读那个技能的正文。 这个顺序很关键：description 是唯一的判断依据，正文在那一步还没登场。 所以描述写得含糊，正文写得再好也没用——它连被读到的机会都没有。 顺带说一句，这一步也解释了为什么技能多了会变慢、变贵：清单本身在涨。

二、为什么有时候会选错

选错有三种，成因完全不同。 第一种，都不选。你的请求和所有描述都不沾边，模型判断「没有合适的技能」，直接干。 这通常不是坏事，说明描述写得够专。但如果这个活明明有技能，那就是描述漏了触发词。 第二种，选错人。两个技能的描述都能沾上你的请求，模型挑了那个更「像」的。 这多半是因为其中一个描述写得太宽，什么都沾一点。 第三种，选多了。它同时用两个技能，各干一半，结果互相打架。 这一种最少见，但最难查——因为它看起来像是「技能写得不好」，其实是边界重叠。 三种错里，第一种要补触发词，第二种要收窄描述，第三种要在描述里写清「不适用」。

三、写好 description 的三个成分

一份合格的 description，三个成分缺一不可。 做什么：产出物是什么。「把会议转承稿整理成四段式纪要」。 什么输入：对方要给什么。「带说话人前缀、一行一句的转承稿」。 什么时候用：列触发词。「会议记录、录音转写、讨论稿、要待办」。 第三个成分是命中率的主要来源。人表达同一件事有很多说法，触发词就是把这些说法覆盖住。 长度上，四十到八十字比较合适。少于二十字多半太虚，超过一百五十字开始稀释。 还有一个可选项：写「不适用」。两个技能容易混的时候，这一句能救回来。 比如「本技能只处理中文稿，英文润色请用 polish-en」。

四、本章小结

第二章讲的是「技能为什么能起作用」，四篇各管一段。 六大要素定位置，四大进化说价值，上下文预算讲约束，description 讲入口。 四篇连起来是一条链： 技能占的是「经验」这一格，它的价值在按需加载，它的约束是上下文，它的入口是 description。 任何一环断了，技能就只是个躺在文件夹里的文本文件。 下一章往外走一步：从「看懂机制」转到「动手拆任务」——先想清楚这件事该不该做成技能。

五、动手 Demo：description 写得好不好，用三十条请求量一遍

这一段做一次小型评测：八个技能、三十条真实口吻的请求，两版 description 各跑一遍。 一版只写技能名，一版加上触发场景，比 top1 与 top3 的命中率。 最后再补一个反例：description 写得太全，会发生什么。

lib = [
    ('meeting-minutes',
     '把带说话人前缀的会议转承稿整理成四段式纪要，'
     '当用户给出会议记录、录音转写稿、讨论稿，要求整理成纪要或待办时使用'),
    # ...另外七个
]

for req, want in REQS:          # 三十条请求，每条标了该选谁
    top = pick(req, lib, 1)     # 按字面重合度排序（真机上是模型判断）
    hit += 1 if top[0][1] == want else 0

实跑输出：

--------------------------------------------------------------------
description 写得好不好，用三十条请求量一遍
--------------------------------------------------------------------


  ① 先看一个技能的两版 description
  --------------------------------------------------------------------
  差的：会议纪要技能
  好的：把带说话人前缀的会议转承稿整理成四段式纪要，当用户给出会议记录、录音转写稿、讨论稿，
  要求整理成纪要或待办时使用
  差的那版只说了「我叫什么」，好的那版说了「什么时候用我」。
  模型挑技能时看的正是后者：这一次的请求，像不像它描述的场合。

  ② 三十条请求，两版各跑一遍
  --------------------------------------------------------------------
| 写法 | top1 命中 | 命中率 | top3 命中 | 命中率 |
|---|---:|---:|---:|---:|
| 只写技能名 | 16/30 | 53% | 23/30 | 77% |
| 加上触发场景 | 21/30 | 70% | 24/30 | 80% |

  同一批请求、同一批技能，只改 description 的写法：
  top1 从 16/30 变成 21/30，top3 从 23/30 变成 24/30。
  top1 涨得多，top3 涨得少——说明触发场景主要是把对的技能从「前三」推到「第一」。
  ! 这是本沙箱用字面重合算的，不是模型判断。
  ! 能信的是方向：写清触发场景，命中率会上去。绝对值换套分词就变。

  ③ 哪几条还是选错
  --------------------------------------------------------------------
  三十条里有 9 条没中。前八条如下：
| 请求 | 该选的 | 选成了 | 分 |
|---|---|---|---:|
| 这篇稿子读着一股机器味，帮我改改 | polish | article-illustration | 0.00 |
| 月底了，把这个月做的事整理一下给老板看 | weekly-report | meeting-minutes | 0.06 |
| 公众号这篇要配三张图，风格统一一点 | article-illustration | polish | 0.07 |
| 明天要讲半小时，把这篇改成能讲的结构 | slide-outline | article-illustration | 0.00 |
| 帮我看看这个函数改得对不对 | code-review | polish | 0.08 |
| 写个周报，三段式那种 | weekly-report | meeting-minutes | 0.14 |
| 这个月的流水，帮我算算同比环比 | data-report | article-illustration | 0.00 |
| 这句话太啰嗦，删一删 | polish | article-illustration | 0.00 |

  表里那几条 0.00 的，是八个技能一个都没沾上，按名字退回占位。
  这种结果没有意义——不是选错了，是根本没得选。
  错的两类原因，都值得记下来。
  第一类：请求里根本没有描述里的词。
  「这篇稿子读着一股机器味」——描述里写的是「润色、去 AI 味、读起来别扭」，
  没有一个字能和「机器味」对上。人一眼懂，字面匹配不懂。
  第二类更隐蔽：两边同分，排序按名字定胜负。
  「写个周报，三段式那种」，周报技能中了「周报」，纪要技能中了「段式」，
  都是 1/7，分数打平；名字靠前的那个赢。
  ! 这就是字面匹配的天花板。真机上模型看语义，这两类错都能躲掉大半。

  ④ 好的 description 有三个成分
  --------------------------------------------------------------------
| 成分 | 例子 | 作用 |
|---|---|---|
| 做什么 | 把会议转承稿整理成四段式纪要 | 说清产出物 |
| 什么输入 | 带说话人前缀、一行一句 | 说清对方要给什么 |
| 什么时候用 | 会议记录、录音转写、讨论稿、要待办 | 列触发词 |

  三个成分写全，description 大概 40 到 80 字。少于 20 字多半太虚。
  ! 还有一个可选项：写「不适用」。当两个技能容易混时，这一句能救回来。

  ⑤ 一个反例：写得太全，反而抢活
  --------------------------------------------------------------------
| 请求 | 该选的 | 实际 top1 | 分 |
|---|---|---|---|
| 这份文档要发给国外同事，翻成英文 | translate | translate | 0.23 |
| 这段 diff 你审一下 | code-review | code-review | 0.20 |
| 帮我处理一下这段文字 | （说不清） | broad | 0.22 |

  两条说得清的请求，它一个都没抢走——具体需求会被具体描述接住。
  第三条「帮我处理一下这段文字」说不清，它全接了。
  所以宽描述的危害不在抢明确的活，在于把所有说不清的活都接过去。
  接过去之后给你一个什么都沾一点的泛泛结果，你还以为是自己没说清。
  ! description 的目标不是「覆盖面大」，是「只在该出现的时候出现」。

第一段先把两版描述摆出来：「会议纪要技能」对上一整句带触发场景的说明。 第二段是三十条请求的评测结果：只写技能名 top1 命中 16 条，加上触发场景 21 条。 top3 从 23 条变成 24 条——涨得少，说明触发场景主要是把对的技能从「前三」推到「第一」。 命中率 53% 到 70%。这个绝对值不高，因为本沙箱用的是字面重合，不是语义。 真机上模型看语义，两版都会更高；但「加了触发场景会更好」这个方向不会变。 第三段列出没中的九条，两类原因：请求里没有描述里的词，或者两边同分按名字定胜负。 表里那几条 0.00 的，是八个技能一个都没沾上，按名字退回占位——不是选错，是没得选。 第四段给出三个成分：做什么、什么输入、什么时候用。 第五段是反例：「各种文字工作」这种写法，两条说得清的请求它抢不走， 但那条说不清的「帮我处理一下这段文字」，它全接了。

30 秒实验

1. 把你每个技能的 description 单独抄出来一行，遮住技能名，看能不能猜出它干什么、什么时候用。
2. 拿你最近五次的真实请求，手动跑一遍「该选谁」，对不上的那条，就是描述要补的地方。
3. 给你最容易被抢活的那个技能，加一句「不适用」。

常见误区

1. description 写成技能名的扩写。 meeting-minutes 配「会议纪要技能」，等于什么都没说——这两个词本来就是名字里有的。
2. description 写得越长越全。长到什么都沾，就会在所有模糊请求上抢活，然后给你一个泛泛的结果。
3. 只在心里想着「它会懂的」。 技能被选中靠的是字面与语义的相似度，你脑子里的那层意思，不写下来就不存在。

第二章完。下一章从「看懂」转到「动手」：把一个任务拆开，判断它该不该做成技能。

• ☐ （本篇完，下一篇 3.1 先把任务拆开）

相关笔记

• 上下文与按需加载
• Claude Code 橙皮书 · 索引
• 🧩 Skill提效实战 · 索引