给 Agent Skill 写 description 不再靠猜：触发率量化 + 自动修复闭环

一个扎心的问题

你花了半天写了一个完美的 Agent Skill：步骤清晰、防护栏齐全、还附赠脚本。

然后用户说"发个xhs"，agent 理都没理它。

问题大概率不在你的流程写得多烂，而在 description ------agent 决定加载哪个 skill 时，看到的只有每个 skill 的 name + description 这一行。这一行没写中用户的说法，后面几千字的精心指令根本没机会被读到。

更糟的是，这件事完全没有反馈：你不会收到任何"未触发"的报错。

我写了两个版本的同一个 skill（小红书文案改写）：一个 description 只有一句话（朴素版），一个把用户真实说法都嵌了进去（优化版）。然后用 10 条用例（6 条该触发、4 条相邻但不该触发）、再放 6 个竞品 skill 同场抢路由，拿 8 个模型分别当"路由器"测了一遍：

两个结论：

1. 强模型会原谅烂文案，弱模型不会。 如果你的 agent 跑在小模型上（成本考虑很多人就是这么干的），description 质量直接决定 skill 的生死。

2. 剩下的失败是真信号。 所有模型没触发的那条用例（"帮我把这个产品介绍改成种草文案"），都被一个 description 有重叠的竞品 skill（product-copy-generator）抢走了。这是 skill 边界问题，不量化一下根本发现不了。

（原始数据在仓库 results/ 目录，可复现）

一个 Python CLI，五个命令：

复制代码

pip install skill-inspect

test 的用例就是一个 YAML，像单元测试一样声明式：

yaml 复制代码

cases:
  - input: "帮我把这篇笔记改成小红书风格"
    expect: trigger
  - input: "帮我写公众号推文"
    expect: no_trigger   # 相邻需求，必须不触发

跑一次成本不到一分钱（gpt-4o-mini），支持 DeepSeek / Kimi / 本地模型任何兼容接口。

光测量还不够------我让它自己修：

bash 复制代码

skilldoctor improve ./my-skill --with ./competitor-skill

每一轮：跑测试 → 把没触发的说法交给 LLM → 改写 description → 用全部用例重新评分 （包括 no_trigger 护栏，防止靠堆关键词骗分）→ 直到全过或达到轮数上限。确认没问题再加 --write 写回 SKILL.md。

实测朴素版小红书 skill：baseline 67% → 一轮改写后 100%，误触率 0% 。

推理模型全报 0% 触发率，吓得我以为发现了什么大问题------结果是 deepseek-v4-flash / kimi-k2.5 这类推理模型把 20 个 token 的输出预算全花在隐式思考上了，回答一个字没吐出来。现在默认预算 1024，截断自动 4096 重试。
macOS 终端把输出重定向到文件就崩（C locale 下 stdout 变 ascii，rich 打印中文直接 UnicodeEncodeError）。现在 CLI 启动强制 UTF-8。

模拟路由 ≠ 真实 agent 行为。这个工具是用来迭代 description 的，不是保证线上表现的。和 skillcheck（静态校验）、skillbench（端到端评估）是互补关系。

如果你也在写 Agent Skill，欢迎试用、提 issue。觉得有用的话，一个 star 就是最大的支持 🙏