你的 Skill 不是写得不好,是该出场时沉默、不该出场时抢答——根子几乎都在 description 那几行。本文是聚合式实操课(系列第 4 课):把误触发/漏触发的三类根因、一套正反例改写骨架、一道全量重测门槛聚到一张流程里,不做工具横评。上节课:第3課:スクリプト付きスキルとセキュリティ監査管的是脚本权限,这节课只管一件事:触发器变准。文末给出今晚就能跑通的安装、配置、翻车与验收步骤。
はじめに
你需要:一个已能触发的 Claude Agent Skill;至少 5 段真实对话原话(成功/误触发/漏触发);能改 SKILL.md 并立刻重聊的环境。没有真实对话,别用想象案例。失败用例先于文案灵感——捞不到原话就停笔。
概念:description 是触发器,不是小作文
description 告诉路由何时该叫这个 Skill。堆「智能」「全面」「专业」几乎无助于触发。有效写法:任务动词 + 输入类型 + 正例边界 + 反例边界。当成搜索匹配词,不是品牌文案。
- 正例:用户在做什么、带着什么文件、要什么可观察结果
- 反例:看起来像但不该触发的邻近任务
- 禁区:需人工确认的高风险动作
把 description 想成路由器匹配规则。路由只关心:这句话像不像「该我上场」。形容词越多,匹配面越糊;边界词越多,误触发越少。改之前强制回答:任务动词?输入长什么样?何时必须触发?何时绝对不该触发?答不全就还没写完。
当用户要【任务动词】且输入是【文件/对话类型】时使用本 Skill。
正例:【口语原话 1】;【口语原话 2】。
反例:【邻近但不该触发的原话 1】;【原话 2】。
禁止:【需人工确认的高风险动作】。
正例必须用用户原话。漏触发常因口语不在词表——用户说「把这个表弄干净」,你写「执行数据清洗流水线」,路由对不上。手册进 reference/,description 只留触发边界;写到一屏以上就剪走。
三类根因各怎么改(拿表里的原话举例)
太宽 → 加反例,不删正例。「写一封催款邮件」被 doc-clean 抢走,是因为旧描述写着「各类文档处理」,邮件也算文档。正确动作是在反例里点名「写邮件、写通知」,而不是把正例删到只剩一句——删正例会立刻换来漏触发。
太窄太文言 → 把用户口语抄进正例。「帮我把合同转成可搜的」没触发,因为描述里只有「OCR 结构化抽取」。用户不会说 OCR,他们说「能搜」「弄干净」「转成文字」。把这三个说法原样写进正例,比再加十个专业术语管用。
关键词撞车 → 让邻近 Skill 互写反例。「审计一下这个脚本安不安全」同时含「脚本」和「文件」,两个 Skill 都觉得是自己的。只改一边不够:doc-clean 的反例写「审计/检查脚本」,script-audit 的正例写「这个脚本安不安全」,两边边界对齐,路由才有确定答案。
ステップバイステップの実践ガイド
- 建失败用例本:原话 / 实际触发了谁 / 期望触发谁。
- 误触发归类:太宽、关键词撞车、缺反例。
- 漏触发归类:太窄、太文言、口语不在词表。
- 按骨架改一版;正反例各至少两条。
- 用原失败对话重测,全过才合入。
失败用例本建议路径 skills/<name>/failures.md,表头四列:原话、实际触发、期望触发、根因归类。
| 原话 | 实际触发 | 期望触发 | 根因 |
|---|---|---|---|
| 帮我把合同转成可搜的 | 通用写作 | doc-clean | 漏触发/太文言 |
| 写一封催款邮件 | doc-clean | 误触发/太宽 | |
| 审计一下这个脚本安不安全 | doc-clean | script-audit | 关键词撞车 |
操作展开:① 导出当前 description 作「改前快照」;② 粘贴 ≥5 段真实原话;③ 逐条标实际/期望/根因;④ 按骨架改,删空形容词;⑤ 用原失败对话重聊,全部符合期望才合入。PR 门槛:误触发集 0;漏触发最多 1 条遗留且登记改期;无重测记录打回。

优先级:先砍误触发,再补漏触发。日常一出现失败就复制原话进 failures.md,不要等评测周。一周捞不到 5 条,说明还在用想象案例。
エラーと失敗(少なくとも3件)
翻车一:改完不重测——假进步。翻车二:用摘要代替原话——触发词对不上。翻车三:正例太满反例空白——邻近 Skill 抢触发。补丁:失败用例本进仓库;谁改谁贴重测结果。
- 翻车四:多人改同一 description 不锁——后合入覆盖前一次重测。补丁:标题带
[skill-desc]的独占 PR,合并前再跑全量失败用例。 - 翻车五:同义词大全堆正例——吞掉邻近 Skill 触发词。补丁:正例只留真实口语;同义词 ≤3 且各配反例。
- 翻车六:重测环境与生产路由不一致——本地单 Skill、线上十个抢触发。补丁:必须在全量 Skill 已加载环境重测。
第 3 课管脚本权限;本课管该不该出场。两门都过,才谈第 5 课 CI / 团队共享目录。团队公约可贴 CONTRIBUTING:改 description 附 failures.md;全量环境重测;误触发 0 容忍;漏触发遗留有改期。
今晚落地:安装、跑通、配置、翻车、验收

安装:一个文件,两分钟
不用装任何新工具。在 Skill 目录下建 failures.md,四列表头一次写死,随 description 一起进仓库:
printf '| 原话 | 实际触发 | 期望触发 | 根因 |\n|---|---|---|---|\n' > skills/<name>/failures.md
git add skills/<name>/failures.md
同时把当前 description 复制一份到 PR 草稿里当「改前快照」。没有快照,事后说不清到底是哪一句改好的。团队多人共用同一个 Skill 时,再约定一条:改描述的 PR 标题统一带 [skill-desc] 前缀,同一时间只开一个,免得后合入的把前一次重测结果悄悄覆盖掉。
跑通:先让失败可复现
翻最近两周的对话,把「跳错技能」和「该出场却沉默」的句子原样贴进表里,至少 3 条,标上实际触发、期望触发、根因(太宽 / 太窄太文言 / 关键词撞车)。然后开一个新会话,逐句重贴,确认这些失败今天还能复现——复现不了的先划掉,别为已经消失的问题改文案。
用 Claude Code 的话,历史会话以 JSONL 存在 ~/.claude/projects/ 下,可以直接搜关键词捞原话,比凭记忆复述准得多:
grep -l '合同\|扫描件\|可搜' ~/.claude/projects/*/*.jsonl | head
捞出来的句子只截用户那一句,不要连同上下文整段贴——重测时你也只会贴这一句。
配置:只动一个字段
按上面的骨架改 SKILL.md 的 description:任务动词 + 输入类型,正例、反例各至少两条且全部来自原话,再加一行禁区。一轮只做一种动作——要么改动词,要么加反例——否则重测过了也说不清是哪一处起的作用。超出一屏的说明挪进 reference/。
描述里有冒号、引号这类字符时,用 YAML 折叠写法,避免 frontmatter 解析失败导致整个 Skill 不加载:
---
name: doc-clean
description: >-
用户要把 PDF、扫描件、合同清洗成可搜索文本时使用。
正例:把合同转成可搜的;这堆扫描件弄成能搜的。
反例:写邮件、写通知、审计或检查脚本、翻译。
禁止:删除或覆盖原文件。
---
翻车:改了却像没改
- 旧会话里重测:Skill 元数据通常在会话开始时载入,改完 SKILL.md 还在老窗口里聊,测到的是旧描述。每轮改完都开新会话。
- frontmatter 写坏了:冒号没折叠、缩进错一格,Skill 直接不加载,表现成「全部漏触发」。先确认它出现在可用技能列表里,再测触发。
- 测试时点名 Skill:用户不会先喊技能名,点名测试会系统性高估触发率。全程只贴原话。
- 含糊话被抢答也算过:「帮我处理一下这个文件」落到专用 Skill,一律记为误触发,补反例后重测。
验收:三条线,缺一不合
- 误触发集 0 条;漏触发最多遗留 1 条,且在 failures.md 写明负责人与改期日期。
- failures.md 里每条原话都有本轮重测勾选,PR 附改前/改后 diff 和正反例对照。
- 合入后 48 小时内同类误触发再现,就开热修,优先加反例,不往正例堆同义词。
评审人不用读懂整个 Skill,只问四句:任务动词能不能被观察到?输入类型写清了没有?正例是不是用户原话?反例有没有覆盖最近抢过触发的邻近技能?任何一句答得含糊,当场打回改,不接受「合并后再补」。PR 描述按三行写:改前触发问题、改后正反例各几条、全量环境重测结果,审阅者一分钟就能看懂边界。
团队节奏也别太重:周一把上周新冒出的失败原话补进表里,周三集中改写和重测,周五花十五分钟合并重复根因、给遗留漏触发排改期。一周新增不到五条原话,说明大家还在凭想象改文案,那一周就别合入任何描述变更。
本地可先跑一句自检,未勾选的行一目了然:
grep -n '\[ \]' skills/<name>/failures.md && echo '还有未通过,禁止合入'
交付物只认两样:改过的 description,和更新后的 failures.md。时间只够改一个 Skill,就改最近两周误触发最多的那个。
次回の予告
第 5 课:把 Skill 接到真实仓库 CI / 团队共享目录。
本シリーズの目次
- 第1課:30分で、自動的にトリガーされる最初のClaude Agent Skillを作成する
- 第2課:Skillに参照を追加する/「まず計画文書を作成してから実行する」という検証ループ
- 第3課:スクリプト付きスキルとセキュリティ監査
- 第 4 课:用真实失败用例迭代 description(本文)
- 第 5 课:把 Skill 接到真实仓库 CI / 团队共享目录(预告)


评论列表 (0条):
加载更多评论 読み込み中...