AiRobotNews 人工智能机器人技术网

怎么写 agent skill，怎么用 eval 测它：adherence 和 effect 两个分数

ROBOT@qwh 56 分钟阅读 Agent 工程
怎么写 agent skill，怎么用 eval 测它：adherence 和 effect 两个分数

这篇文章写给两类人：跑 coding agent、决定装不装或写不写某个指令文件的人；以及给市场或内部 skill 库签字的人——他们该问的问题，和前者是同一个。

读完能做的事：随便拿一个 skill，把它依赖的观点抽出来，用两个数字量一下 agent 跟不跟它、跟了有没有用，在这段文字进入你的 prompt 之前。文中数字都来自末尾列出的公开研究，外加一份在 Level 0 里逐字读完的公开 skill 文件，所以没有哪一步依赖你看不见的环境。

先读这段就够了

skill 是一个装着指令的文本文件，agent 在任务前或任务中读它。装上 skill 不会改动模型里的任何东西。模型只是上下文里多了些文字，它因为这段文字而表现不同——和你往 prompt 里粘任何一段别的文字没什么两样。

为什么会有 skill： 人希望 agent 每次都按某种特定方式做某类任务，又不想每次重新敲一遍指令。

问题在于： 现在公开市场里共享的这类文件超过一百万份，而共享格式只要求一个名字和一段描述，不要求测试。典型的 skill 是「写完觉得挺对 → 用几次 → 发出去」，没有测试、没有 eval、没有指标，于是它到底帮了忙、帮了倒忙，还是只花了 token，全是看法。而就算测过，也是在某个人的环境里测的。上下文因人而异：规则文件、同一个列表里的其他 skill、工具、代码仓库、把活交给 agent 的方式，全都不一样。在一个环境里测过，不等于在你的环境里测过。

一个 skill 应该这样被造出来：

  1. 一句话目标。 用了这个 skill 之后，什么必须变好，而且得是能测的东西。测不了就研究不了，那这个 skill 只是一段主观文字。
  2. 把观点列成点。 一份短清单，每个核心点说明 agent 必须做什么，并带上「为什么这会有用」的假设；次要的点同样处理。写不出假设的点，就是民间偏方。
  3. 点变成指令。 这一步把点转成 agent 要读的指令文本。文件里每一句都来自某个点；点是被共享和被评审的东西，文本只是交付形式。
  4. 指标。 一是 adherence：对着 agent 的动作日志，每个点一条检查。二是 effect：在真任务上、在 agent 看不到答案的前提下测——用隐藏检查，再给 agent 产出的每条东西打一个质量标签（以测试为例：critical / useful / nitpick / useless / harmful），由经过你手标校准的裁判来打；外加诚实度、成本、稳定性。看的是产出质量，不是产出数量。
  5. eval。 你的任务、你的上下文、你的模型。对照组：不装 skill、装 skill、装一段同样长度的无关文字。每组跑多次。
  6. 测量、判断、发布。 adherence 低就重写文字；adherence 高但 effect 平就扔掉这个观点。发布时把文字连同观点、eval 和结果一起发，每次模型更新后重跑。

一个外部 skill 在接近你的 prompt 之前，应该这样被验证：

  • 把指令拆成观点。读文本，抽出点，每个点配一个假设。抽不出来就停：里面没有可测的东西，装它只是买了一堆「服从」。
  • 写指标。每个点一条 adherence 检查，effect 用上面那些测法。
  • 造 eval。对照组同上，跑在你的任务、你的上下文、你的模型上——因为别人的测试没在这里跑过。
  • 测量并判断。按模型决定留、砍还是扔，模型或上下文变了就重来一遍。

重点： skill 有两种失败方式，而只看结果分不清是哪一种。要么 agent 没照文字做（文字不行），要么照做了但结果没变好（观点不行）。

对我们的意思： 每个 skill 都需要两个分数：一个是 adherence，一个是 effect。adherence 低，回去改措辞；adherence 高但 effect 平，回去改观点。

为什么重要： 只盯结果的团队，会因为措辞弱而重写掉好观点，也会因为措辞强而一直服从坏观点。

后面一节一节往下钻，每一层回答上一层留下的一个问题。

  • Level 0 · 整套方法在某个公开 skill 的一条指令上跑一遍
  • 第一部分：问题
  • Level 1 · skill 在起任何作用之前先花掉什么？
  • Level 2 · 有人测过共享的 skill 吗？
  • Level 3 · skill 能从模型 A 迁到模型 B、从环境 A 迁到环境 B 吗？
  • Level 4 · 为什么「我这能用」不是证据
  • 第二部分：方法
  • Level 5 · 这个 skill 是为了什么？
  • Level 6 · 它的观点是什么？
  • Level 7 · 怎么知道 agent 照做了？
  • Level 8 · 怎么知道照做有用？
  • Level 9 · eval 怎么跑？
  • Level 10 · 怎么判断、交付、维持？
  • 第三部分：用例
  • Level 11 · 示例 skill 走完整个方法
  • 最后 · 工具与做法、决策指南、参考文献

Level 0：整套方法在一条指令上跑一遍

这一层回答：真正跑起来的时候，测一个 skill 长什么样。

贯穿全文的例子。 用的 skill 是公开仓库 superpowers 里的 test-driven-development，它是给 coding agent 用的、星数最多的 skill 集合之一。读者需要的都在公开文件里，下面的数字可以自己重数：

  • 这个仓库有 15 个 skill 和一个会话钩子。钩子在每个会话开始时注入一份 492 词的「using-superpowers」文件，里面告诉 agent：只要有「哪怕 1% 的可能某个 skill 适用」，就「绝对必须调用该 skill」。
  • test-driven-development 是单个约 1,475 词的文件，另有一份约 1,310 词的配套文件讲怎么写出好测试，只要 agent 写测试就被要求去读。
  • 它的一句话描述说，适用于「任何功能开发或修 bug，在写实现代码之前」。它的第一条规则叫 Iron Law：「没有先失败的测试，就没有生产代码」。
  • 里面的代码示例是用 npm 跑的 TypeScript，而本文拿来测它的任务是 Python 仓库，所以示例和 agent 实际在写的语言永远对不上。

在一条指令上把方法走完。 拿文件里最有辨识度的那条指令：先写测试、跑一遍、看着它失败，再写代码。整套方法就用这一条演示。

  • 目标。 agent 改动代码时，改动必须通过它没见过的测试；且 agent 自己写的测试，在改动前必须失败、改动后必须通过。
  • 点与假设。 点：写代码之前先跑新测试并看着它失败。假设：一个从没被看见失败过的测试，可能是因为错误的原因通过的，所以「看着它失败」能删掉那些证明不了任何事的测试。
  • adherence 检查。 从命令日志里看：测试命令在测试文件写完之后、第一个源文件写出之前运行；退出码非零；失败信息点名的是新测试，而不是语法错误。是或否，不需要判断。
  • effect 检查。 跑完后先套任务的隐藏测试。再拿 agent 写的每一个测试，分别对「改动前的代码」和「几处人为植入的故障」运行，逐个打标签：critical / useful / nitpick / useless / harmful。一个永远不会失败的测试就是装饰。
  • 对照。 同样的任务各跑三次：不装 skill、装 skill、装一段同长度的无关文字。每次报告隐藏测试通过率、critical 测试占比、token、轮次、分钟数。
  • 判定规则。 adherence 高、且 critical 测试占比相对两个对照都上升，这个点留下，并把多花的 token 和轮次记在收益旁边。adherence 低，问题在措辞，这个点还没被测到。adherence 高但 critical 测试占比不动，这个点对这个模型就是不管用，再好听也不管用。

后面每一层都在拆解其中的一块。

从 Level 0 带走：

  • 一个 skill 是关于 agent 行为的假设，只是用文字写下来的。
  • 它需要两个分数：agent 做了没有，做了有没有用。
  • 两个分数都需要对照，而对照需要一个「长度控制」。

第一部分：问题

Level 1：skill 在起任何作用之前先花掉什么？

这一层回答：一个只是被「装上」的 skill，让 agent 付出了什么。

skill 在三个地方花 token。它的名字和描述躺在每一轮的 prompt 里，好让模型决定要不要打开它。它的正文在被打开时加载，之后一直留在对话里。还有些集合加了个钩子，每个会话开始就注入一个文件，不管有没有相关 skill。

列表是最容易被忘掉的那部分。 Claude Code 的文档说得很直白：「每一行都是持续发生的 token 成本」（Anthropic，《Claude Code》skill 文档）。在一台开发者机器上用内置的 skill-doctor 报告查了一遍：

  • 列表里有 89 个 skill，来自用户自己的文件夹、同步的云端 skill 和装好的插件。
  • 89 个里有 81 个从来没被调用过。
  • 被用过的 8 个，最近一次使用也在 37 天前。

列表存在的意义是让模型挑，但证据显示它大多不挑：

  • Vercel 报告说，在 56% 的 eval 用例里它的默认 skill 根本没被调用；装了 skill 得分 53%，和不给任何文档一样；加一行明确的「调用这个 skill」后升到 79%，常驻的文档索引则达到 100%（Vercel，2026，厂商自述，模型和用例数未披露）。涨分来自强行加载，不是来自 skill 的内容。
  • 一个独立复测用 Claude Sonnet 4.5 跑了 22 条 prompt：没有强制钩子时激活率 50% 到 55%，有钩子时 100%（Spence，2026）。同一个画面——原生的选择步骤只有大约一半的时候会触发。
  • 一个 5,400 用例、八模型的基准测了各模型到底多久加载一次 skill：按模型不同在 11.1% 到 72.1% 之间，而且在模型自己能解决的任务上和解决不了的任务上，加载频率差不多（Skill Retrieval Augmentation，arXiv 2604.24594）。作者说模型「不具备需求感知」：加载的决定不跟着「加载有没有用」走。
  • 池子越大挑得越差：选对的占比从只有 5 个 skill 时的 29.6%，掉到 100 个时的 3.3%（Demystifying Agent Skills，arXiv 2608.14036）。长列表不只花 token，还降低选对的概率。

钩子是另一笔隐形开销。 例子里那 492 个词，在用户还没敲任何字之前就落进了每个会话。那是一条加载策略，不是 skill，只有当它强制加载的 skill 足够好时才值这个钱。

重点： 列表是为了让模型挑 skill，而在厂商 eval、独立复测和八模型基准里，模型挑对的概率大约一半或更低。

对我们的意思： 要么在任务里点名 skill，要么用钩子或命名规则路由，要么接受一半的跑分其实是「没装 skill」的基线加上额外 token。

为什么重要： 任何一次不记录「正文有没有加载」的 effect 测量，测的都是一个混合体。

从 Level 1 带走：

  • 列表、正文、钩子是三笔独立的成本，按不同节奏付费。
  • 原生选择步骤大约一半时候触发，池子变大还会更差。
  • 测一个 skill 必须说明它是怎么被加载的，否则数字混了两种条件。

Level 2：有人测过共享的 skill 吗？

这一层回答：一个 skill 被公开时，有人查过它什么。

skill 的公开规范定义了文件夹结构、名字、描述和正文怎么加载（agentskills.io 的规范页）。它没有定义测试、eval 或质量门槛。我没找到任何统计说有多少共享 skill 带 eval。这个「没有」本身就是发现。

研究者拿真任务测共享 skill 时发生了什么：

  • 把来自知名仓库的 31 个公开 skill 注入到每一次 prompt 里，在 50 个 web 项目、四个模型上跑。四个模型通过率都掉了，Claude Sonnet 4 在两次尝试下掉 4.2 个点，token 按模型不同涨了 72% 到 394%（Signal or Noise，arXiv 2608.23067）。
  • 那项研究里，只有 1% 的「skill × 项目」组合能在四个模型上都是正的。到处都帮得上的 skill 是例外。
  • 另一个覆盖 49 个公开软件工程 skill 的基准发现，49 个里有 39 个零收益，平均增益 1.2 个点，token 开销最高到 451%（SWE-Skills-Bench，arXiv 2603.15401）。三个 skill 造成最多 10 个点的伤害，作者把伤害追到「指导是按更老的库版本写的」。
  • 一项研究 307 个「skill 改变了结果」的案例，其中 182 个是没有收益的成本回退（Agent Skills Can Be Harmful，arXiv 2608.11888）。这些是被挑出来的失败案例，不是基础发生率，但形状一样：同样的结果，更高的账单。

安全是「没测过」的极端形态。 skill 是 agent 会读的文件，常常还是它会跑的脚本，所以共享一个 skill 就是共享代码：

  • 扫了 31,132 个市场 skill，26.1% 至少有一种漏洞模式，带脚本的 skill 中招概率是 2.12 倍（Agent Skills in the Wild，arXiv 2601.10338）。四分之一不是长尾。
  • 在 98,380 个被扫过的 skill 里，157 个被确认恶意，其中过半来自同一个行为者（Do Not Mention This to the User，arXiv 2602.06547，USENIX Security 2026）。把关的是研究者，不是平台。
  • 五个 skill 扫描产品在一次公开测试里被绕过，四个绕过里有三个用了不到一小时（Trail of Bits，经云安全联盟，2026）。扫描不等于评审。

重点： skill 格式定义的是文件怎么加载，不是它有没有用；共享 skill 的实测记录是：多数零收益，全都加账单，安全问题四分之一。

对我们的意思： 下载来的 skill 当成陌生人发来的 pull request：读它，有 eval 就跑，没有就自己写，通过在你自己模型上的测试之前，别放进受信任目录。

为什么重要： 安装这一步就是把文字塞进每一个任务，而这个格式对它没有任何检查。

从 Level 2 带走：

  • 公开只意味着格式合规，不意味着测过。
  • 共享 skill 的实测默认值是没收益加更多 token，实际伤害主要来自过时的指导。
  • 共享 skill 就是共享代码，扫描结果说明未评审代码的漏洞率。

Level 3：skill 能从模型 A 迁到模型 B、从环境 A 迁到环境 B 吗？

这一层回答：如果某个 skill 在一个模型、一个环境里测过，我们对它在别处知道什么。

skill 是一段 prompt，而 prompt 不会迁移。同样的文字在不同模型里产生不同行为，而且差别不是小修小补：

  • 同一个 skill 在同一个项目上，让 Claude Sonnet 4 涨了 33 个点，让 DeepSeek 和 Qwen 各掉 22 个点；跨所有配对，模型间增益的相关性大约是零（Signal or Noise，arXiv 2608.23067）。知道一个 skill 帮了某个模型，对下一个模型毫无信息量。
  • 用一套精选 skill，Claude Haiku 4.5 拿到 27.7%，不装 skill 时是 22.0%（SkillsBench，arXiv 2602.12670）。好的 skill 能让便宜模型压过贵模型——这正好说明增益必须按模型测，不能假设。

模型只是第一条轴。 skill 从不单独运行。它边上还有用户的规则文件、列表里的其他 skill、agent 手上的工具、所在的仓库，以及这个人把活交给 agent 的方式。每个人的上下文独一无二，收集和喂上下文的方式也各不相同，所以同一个 skill 在每种环境里遇到的都是不同的 prompt：

  • 在那项注入研究里，只有 1% 的「skill × 项目」组合在四个模型上都正收益（Signal or Noise，arXiv 2608.23067）。帮不帮忙取决于项目和模型的配对，而不是 skill 本身。
  • 在 Vercel 的报告里，skill 得分 53%，和不给文档一样，而常驻文档索引拿到 100%（Vercel，2026，厂商自述）。上下文里已经有什么、怎么进去的，比 skill 更能决定结果。

市场里的 skill 不带模型标签，也不带环境标签；规范里根本没有「在什么上测过」这个字段。别人测过的 skill，是在那个人的环境里测的，而那不是你的。

重点： skill 按模型按环境被接受，不是总体上被接受。同一个文件，在一个模型上是收益、在另一个上是损失；在一个环境里是收益、在你这里是损失。

对我们的意思： 一个 skill 的 eval 是矩阵里的一个格子。用它对应的模型、你的上下文、你的任务跑一遍，模型或上下文变了就再跑一遍。

为什么重要： 「我们测过」而不说「在哪个模型、哪个环境」，描述的不是你要跑的那个 skill。

从 Level 3 带走：

  • 同样的文字，换模型或换环境，符号可能反过来。
  • adherence 和 effect 都依赖模型，也依赖上下文里的其他一切。
  • 别人的测试再诚实，也是别人的环境。

Level 4：为什么「我这能用」不是证据

这一层回答：今天判断 skill 的方式错在哪。

一个凭感觉写的 skill，验收标准是作者用了几次之后的感受。那是单次运行、单个模型，没有基线、不算成本、不重复。这几个缺口各自藏着一个具体的错误：

  • 一项仔细的研究把某个 skill 库的增益量到 2.8 个点，但置信区间跨过了零（Demystifying Agent Skills，arXiv 2608.14036）。单次运行分不清 3 个点的增益和噪声；感觉更分不清 3 个点的增益和 3 个点的损失。
  • 伤害研究里那 307 个案例，62.6% 是成本回退而不是失败（Agent Skills Can Be Harmful，arXiv 2608.11888）。让 agent 更慢更贵、答案却一样的 skill，坐在椅子上感觉良好，只在账单上现身。
  • skill 确实起作用的地方，都有人量过。Anthropic 报告说，一个内部数据分析 agent 在按每个主题几十个用例写出并维护 skill 文件后，在其 eval 集上的准确率从 21% 升到 95% 以上（Anthropic，2026，厂商自述）。增益是跟着 eval 来的。
  • 好 skill 的机制是程序性的：在那项拆开看的研，65.7% 的收益来自把 agent 锚到一套流程，4.5% 来自新知识（Demystifying Agent Skills，arXiv 2608.14036）。skill 靠让 agent 按步骤走来起作用，所以它的步骤才是要检查的东西。

快读那段里说的两种失败模式就出在这里：要么 agent 服从了文字、没人查服从有没有用，要么它无视了文字、没人发现。只看结果分不清。

共享方式上还有个更深的问题。 人们共享文字，而应该共享观点。一个 skill 的观点是几条「做 X，因为这样 Y 会更好」式的陈述，读者几分钟就能判断几条。一千五百词的指令读不完也判断不了，所以只能靠感觉判断。有些共享 skill 仔细读根本没有观点：只有语气、紧迫感和格式规则。装这种东西买到的只是「服从」，最好是白花 token，最坏是扭曲行为。

重点： skill 是一个假设，通常没测过；在真测过共享 skill 的研究里，大多数没有收益。

对我们的意思： 把 skill 当观点来共享和评审：几个点，每个配一个理由；文字只是这些点的实现。没带 eval 的 skill 不接受。

为什么重要： 没有观点的文字无法被评估，只能被服从；而没有理由的服从，花 token，没有可测的好处。

从 Level 4 带走：

  • 一次运行、没有基线、不算成本：感觉看不见 3 个点的变化，也永远看不见账单。
  • skill 靠锚定一套流程起作用，所以流程才是要测的东西。
  • 共享观点；文字只是把它写下来的一种方式。

第二部分：方法

Level 5：这个 skill 是为了什么？

这一层回答：在写任何指令之前，第一句该写什么。

每个 skill 都从一句话开始：用了它之后，什么必须变好。这句话点的是一个可测的结果。测不了就研究不了，那这个 skill 就只能停留在今天大多数 skill 的状态：一段主观文字。后面写的每一条都拿它来对，动不了这句话的规则是风格，不是观点。

这句话不定价。 Level 2 的证据是 skill 经常让 token 账单翻倍，所以价格在 eval 里测，和收益并排报告；某一次「用准确率换 token」值不值，到时候拿着两个数字、针对那个任务决定。没人能事先定下这笔交易，假装能定只是把账单藏起来。

对本文的示例 skill，它的文字隐含的目标是：

agent 改动代码时，改动是对的（它没见过的测试通过，之前通过的东西没有失败），并且每个行为至少带一个 critical 测试（一个在改动前失败、检查的是任务要求的那个行为的测试）。

注意这句话做了什么：它把「做测试驱动开发」变成两件可测的事：隐藏测试通过，critical 测试存在。skill 里要求的任何东西，只要这两件事都不动，就不在目标里。

从 Level 5 带走：

  • 一句话，一个可测结果；测不了就是没研究。
  • 成本不在这句话里；它在 eval 里测，和收益并排报告。
  • 后面每一条规则都拿这句话来对。

Level 6：它的观点是什么？

这一层回答：怎么把一个 skill 变成一短串能测的东西。

一个 skill 的观点就是它的「点」。核心点是一条「agent 必须做什么」的陈述，配一个「为什么有用」的假设，写成可检验的断言：「做 X 会让结果 Y 更好，因为 Z」。清单要短到评审一分钟能读完。写不出假设的点是民间偏方，老实标注是唯一诚实的做法。次要点是同样形式的支撑规则，单独报告，文字需要瘦身时先砍它们。

点有三个来源，按可信度排序：

  • 基线里看到的失败。不带 skill 跑真任务，看哪里出问题，每个反复出现的失败写一个点。一项用 agent 自己的失败构建 playbook 的研究报告，正是这个循环让某个 agent 基准涨了 12.3%（Agentic Context Engineering，arXiv 2510.04618）。来自失败的点自带证据。
  • 测过的证据，来自公开研究或你之前跑的 eval。
  • 教条，也就是专家说这活该怎么干。教条点要写下来，配假设，并标注「未测」。本文的示例从头到尾都是教条。

对示例 skill，读文本能得到七个核心点。每条都引自或转述自该文件，假设则是文件自己声明或暗示的主张：

  • C1. 任何生产代码之前先写测试。 假设：先把期望行为说出来，测试才会抓住真 bug，而不是 agent 猜的那个。
  • C2. 跑测试并看着它因为正确的原因失败。 假设：没被看见失败过的测试可能是因错误原因通过，这一步删掉那些证明不了任何事的测试。
  • C3. 写最少量的代码让它通过，跑，看到它通过。 假设：少写投机代码，就少引入回归。
  • C4. 测试失败时改代码，绝不削弱测试。 假设：阻止 agent 靠删断言把红灯变绿。
  • C5. 声称完成前跑全量测试，并点名任何失败。 假设：抓住回归，逼出一份诚实的最终报告。
  • C6. 修 bug 从复现该 bug 的测试开始。 假设：这样修复针对的是真 bug，不是症状。
  • C7. 小循环，一次一个行为。 假设：失败被隔离，浪费的轮次更少。

次要点是测试质量规则：一个测试只测一个行为、不 mock 被测单元、每个新函数都要有测试、覆盖边界情况、只在绿了之后再重构、保持测试输出干净。

指令文本只从这些点写出来，别无其他： 文件里每一句都来自某个点，例子使用 agent 实际会遇到的语言和工具。文本是点的交付形式；点是共享和评审的对象。

文件里还有两样既不是核心也不是次要的东西。第一块是反驳 agent 自己借口的段落——一张合理化说辞表加一张红旗清单。它不是关于任务的指令，而是一个用来提高 C1 服从度的装置，假设是「预先堵住借口能让 agent 更常遵守 Iron Law」，只能被 adherence 那一族指标测到。第二样是会话钩子，一条加载策略，靠「有钩子 / 没钩子」对比来测。

重点： 观点才是 skill。它们是共享、评审、评估的对象；文字只是把它们写下来的一种方式。

对我们的意思： 装 skill 之前先抽点。能写出七句各自带假设的话，你就有东西可测；一句都抽不出来就停，文件里没有可评估的东西。

为什么重要： 评审者可以不同意一个点。而一千五百词的指令，在点被抽出来之前，没什么可不同意的。

从 Level 6 带走：

  • 一短串核心点，每条带可检验假设；次要点单独报告。
  • 来自基线失败的点，优先级高于教条。
  • 说服性文字和加载钩子是另一类点，要有自己的测试。

Level 7：怎么知道 agent 照做了？

这一层回答：不靠人逐个读记录，怎么测 adherence。

adherence 是第一族指标：agent 有没有照每个点说的做。它从 harness 日志打分，也就是一次运行里 agent 干了什么——写过的每个文件、跑过的每条命令及其退出码和输出、最后发出的消息。coding agent 的无头模式把它打成事件流，skill 工具上的钩子记录正文有没有、在什么时候被加载。

每个点一个判分器，判分器是代码里的规则，不是判断。 对例子来说：

  • C1 先测后写。任务里第一次写测试文件早于第一次写源文件，算达成。
  • C2 看它失败。测试命令在写测试之后、写第一个源文件之前运行，退出码非零，输出点名的是新测试而不是导入或语法错误，算达成。
  • C3 看它通过。源文件写出后跑测试命令，退出码为零，算达成。
  • C4 绝不削弱测试。agent 最终的测试文件对「改动前的代码」仍然失败，且测试跑红之后没被删掉，算达成。
  • C5 完成前跑全量。最后一个源文件写完之后跑了整套测试，且最终消息提到那一次跑出的任何失败，算达成。
  • C6 先复现 bug。在修 bug 的任务上，第一次写源文件之前就存在一个对原代码失败的测试，算达成。
  • C7 小循环。记为「写—跑」交替的次数，以及每次测试运行之间的源文件改动数。

一次运行的 adherence 分数，是「适用的核心点里达成的占比」。次要点有自己的占比，会报告，但不进头条。会话钩子的判分更简单：正文加载了吗，在第几轮加载的。

三个限制，免得指标被误读：

  • adherence 测的是服从，不是收益。满分只说明文字作为文字起作用了，别的什么都不说明。
  • 代码判分器看得到动作，看不到意图。一个跑完测试却无视输出的 agent，按字面也满足 C2；抓住它的是 C4 的判分器——它检查最终测试在旧代码上是否仍然失败。点要作为一组来判分，原因就在这里。
  • 激活属于 adherence 的一部分。没加载的 skill 在每个点上都拿零分，而这个零必须一直可见，不能被平均掉。

从 Level 7 带走：

  • 每个点一个代码判分器，跑在动作日志上。
  • 分数是达成点的占比，外加一个「加载了没有」的标记。
  • 高 adherence 证明文字有效，不证明观点有效。

Level 8：怎么知道照做有用？

这一层回答：怎么测 effect，让它奖励好测试而不是多测试，又怎么把它和点对应回去。

effect 是第二族指标：结果有没有变好。省事的做法是数数——写了多少测试、过了多少、覆盖多少行。对一个「测试先行」的 skill 来说这是错的，有研究说明了为什么。一项对 SWE-bench Verified 上 agent 轨迹的分析发现：agent 解出来的任务和失败的任务，写测试的频率一样；agent 更常用 print 语句而不是断言来检查值；提示四个模型多写或少写测试，结果都不变（Rethinking the Value of Agent-Generated Tests，arXiv 2602.07900）。数测试测的是努力，不是收益。覆盖率也不更好：一项针对模型生成测试套件的复现研究发现，一旦被测代码本身有 bug，覆盖率和变异分数就不可靠（arXiv 2607.22880），而修 bug 时代码正好是这种状态。再看超过 6,000 个由模型写出的错误程序：生成的测试经常执行到了那行错误代码，却依然通过，因为断言没检查真正出错的那个东西（arXiv 2609.09315）。

所以 effect 要从另一个方向搭。 先在没有 skill 介入的情况下，定下「对你团队来说什么是一个好测试」。然后拿这个定义，一次一个测试，去给 agent 写的每个测试打分。这是测试先行工作的验收框架：它定义靶子，而 skill 是试图打中靶子的一次尝试，「不装 skill」也是。

框架有三部分。

  • 基准真相。 任务的隐藏测试（agent 从没见过）加上原有测试套件。它们决定一切：隐藏测试没通过的那次运行，没有 effect 可谈。它们本身不够，因为固定的测试集可以通过，而部分预期行为根本没实现（GTDD，arXiv 2610.02952）。
  • 每个测试一个标签。 agent 写的每个测试都从固定集合里拿一个标签。Critical：在改动前的代码上失败，检查的是任务针对的那个行为。Useful：检查该行为的边界或错误路径，是评审者会要求的那种。Nitpick：检查了某件真实但不重要的事，或者重复了另一个测试。Useless：不可能失败——没有断言、断言在 mock 上、打印一个值，或者只是复述实现。Harmful：把错误行为钉死，或者被改到通过为止。
  • 先有证据，再下判断。 标签锚定在运行上，不锚定在阅读上。每个测试都对「改动前的代码」和改动行上植入的几处小故障执行。全部通过的测试不可能 critical 或 useful，不管它叫什么名字，直接归 useless。只有对那些东西失败过的测试才轮到裁判，裁判读测试和任务文本，分出 critical / useful / nitpick。

裁判是一个带评分规则的模型，要像任何裁判一样被校准：团队里有人手工标一批样本，量一致性，改规则直到一致性够可信。在那之前，标签只是看法。

每次运行报告什么。 每个标签下的测试占比，以及一个头条：任务的行为里有多少个至少带一个 critical 测试。「质量优先于数量」意味着：两个 critical 测试的运行，赢过十五个测试里只有一个 critical 的运行。旁边还要报：诚实度（agent 有没有声称完成、隐藏测试同不同意）、成本（轮次、token、分钟和钱，与不装 skill 的那次比）、稳定性（每个任务多次运行，第一次和三次内的通过率，成本的分散度）。

每一部分的理由：

  • 没有隐藏检查，agent 就是在给自己的作业打分。
  • 没有逐测试标签，skill 靠产出更多测试就能赢，而上面那项轨迹研究说更多测试并不能解决更多任务。
  • 没有对植入故障的那次运行，裁判是按测试读起来的样子打分。有位实践者的解析器覆盖率 100%、变异分数 61%（Mutation Testing for Agent-Written Code，awesome-testing.com，2026 年 8 月）：读着漂亮、检查很少的测试，靠读是发现不了的。
  • 不算成本，伤害研究里那 62.6% 的伤害就看不见，因为那是成本而不是失败（Agent Skills Can Be Harmful，arXiv 2608.11888）。
  • 不重复，3 个点的变化就是噪声：那个 2.8 点、置信区间跨过零的库级增益（Demystifying Agent Skills，arXiv 2608.14036），就是单次评估在有人算出区间之后的模样。

这个框架还回流到 Level 6。 基线的标签分布就是你要写的点的清单：如果不装 skill 的运行产出一堆因为只打印不断言而无效的测试，那么点就是「断言，不要打印」，而它来自被测到的失败，不是来自教条。

归因把两族指标接起来。 在 skill 组内跨任务，把每个点的 adherence 和 critical 测试数做相关。被遵守却不推动任何东西的点，是删除候选；很少被遵守、可一旦被遵守就和 critical 测试相关的点，是第一个该重写的。

消融来确认。 删掉一个点的文字，其他不动，两族指标都重跑。如果这个点的 adherence 掉了而 effect 没掉，这个点去掉；如果 effect 掉了，这个点留下，词再少也留。

两种失败模式到这里变成判定规则：

  • adherence 低：问题在文字。改措辞，不改观点，重跑。
  • adherence 高、effect 相对基线持平：对这个模型来说问题在观点。删掉这个点，或标注未测。
  • adherence 高、effect 上升：如果这笔成本你接受、且收益摆在眼前，就留下，并把两个数字和 skill 一起记录；否则先砍次要点再测一次。

重点： 「什么是一个好测试」的定义要在看任何 skill 之前写好，而且永不提及任何 skill。skill 是拿你的定义在打分，不是拿它自己的承诺；没有 skill 的基线也一样。

对我们的意思： 先把评分规则、植入故障和裁判校准做好。然后每个组，包括「不装 skill」，都拿到同样的逐测试标签，「skill 有没有帮忙」就变成「critical 测试的占比有没有涨，代价我们认不认」。

为什么重要： 没有「好」的定义，任何让 agent 多写测试的 skill 都显得更好，而公开的轨迹研究说这恰恰是没用的事。

从 Level 8 带走：

  • 对「测试先行」的 skill，effect 是逐测试标签，锚定在对旧代码和植入故障的运行上，再由校准过的裁判来读。
  • 头条是「有多少行为带 critical 测试」，旁边是诚实度、成本、稳定性。
  • 框架是在没有 skill 的条件下定义的；归因和消融把它接回具体的点。

Level 9：eval 怎么跑？

这一层回答：实验本身长什么样，得多大。

eval 集是真任务加隐藏基准真相，几十个。Anthropic 报告说每个主题用几十个 eval 用例（Anthropic，2026，厂商自述）。任务更少、又不重复的话，区间会覆盖掉公开研究报告的那种量级的效应——Level 4 里那个 2.8 点、置信区间跨零的增益就是例子。

对 coding skill 来说，自然的来源是「模型训练截止之后收集的真实仓库任务」基准：每条有题目陈述、修好前失败修好后通过的隐藏测试、以及仓库原有测试（SWE-bench-Live，arXiv 2505.23419；SWE-rebench，arXiv 2505.20411）。agent 永远看不到隐藏测试。

对照组，每一组都显式调用，免得 Level 1 的激活问题污染 effect 测量：

  • 基线。 不装 skill。它的失败就是你写 skill 时那些点的来源。
  • skill， 按读者会安装的样子。
  • 只有正文， 不带会话钩子（如果该集合有钩子）。这一组和上一组的差，就是钩子的价钱。
  • 另一种同样能达成目标的流程。 对测试先行的 skill，最明显的替代是「先写代码、后写测试，再验证这些测试在旧代码上失败」。如果这组和 skill 打平，真正起作用的观点是「验证你的测试」，不是「先写测试」。
  • 长度控制。 一段合理但无关的文字，token 数与 skill 相同。光是额外文字就能改变行为：在注入研究里，等长的无关 skill 让两个模型分别掉了 3.3 和 3.5 个点（Signal or Noise，arXiv 2608.23067）。没有这一组，损失可能是长度造成的，收益可能是「更多 token」造成的，两者都没说到观点。

运行规则： 每次运行用全新会话；每个任务每组至少两次，通常三次，好有分散度可报；每次运行都留 harness 日志；一切按模型分开，模型版本变了那一行重跑。

预算是组数 × 任务数 × 运行次数： 二十个任务、五组、三次，就是 300 次运行。第一次跑之前先定一个钱的 ceiling，因为 skill eval 的成本本身就是关于这个 skill 的一个值得知道的数字。

重点： 长度控制是最容易省掉的一组，而它正是分开「这些观点有用」和「随便加点文字都会这样」的那一组。

对我们的意思： 把对照加上，哪怕觉得傻。一个赢了基线却输给自己长度控制的 skill，里面没有模型用得上的观点。

为什么重要： 公开的 skill 损失大多是长度损失，所以没和自己长度比过的 skill，是在被放水评分。

从 Level 9 带走：

  • 几十个真任务、隐藏检查、显式调用。
  • 基线、skill、替代流程、长度控制；三次运行；按模型分行。
  • 预算是组数 × 任务数 × 运行次数，先定上限。

Level 10：怎么判断、交付、维持？

这一层回答：数字出来之后做什么，之后每个月又做什么。

判定规则是 Level 8 那一条，对着两个对照同时用。只有同时满足才接受：相对基线、相对长度控制，effect 都变好；多出来的成本你接受、并且收益摆在眼前；adherence 能解释这个 effect。否则 adherence 低就重写文字，adherence 高而 effect 平就删点，然后重跑。每个版本都连同数字一起留档。

一个 skill 交付时是四件东西的捆绑包： 文字、带假设的点、eval 集、以及标明模型和版本的跑分表。少于这些，就只是一个附了说法的文件。

这个包必须重跑，因为 adherence 会漂移，而且没人会通知你：

  • Anthropic 报告说，当底层数据变了而 skill 文件没动时，一个月内准确率会从约 95% 漂到约 65%（Anthropic，2026，厂商自述）。文字没变，底下的世界变了。
  • 那个 49 个 skill 的基准里，造成最多 10 个点伤害的三个 skill，伤害来自「指导对应的是更老的库版本」（SWE-Skills-Bench，arXiv 2603.15401）。过时也是一种错。
  • 能长期工作的 agent 自写 skill 系统，每次改写都有测试闸门：一个报告说加闸门后分数从 52.3% 升到 66.0%（Memento-Skills，arXiv 2603.18743），另一个报告说没有闸门会掉 6.2 到 11.5 个点（Meta-Context Engineering，arXiv 2607.16621）。

所以节奏是： 每次模型更新后重跑，每次 skill 提到的工具或库有重大变化后重跑，其余按日历。

对已有的 skill，同样的步骤照走，只是入口改成文本而不是目标。 写出这个 skill 隐含的目标，抽出它的点并各配一个假设，把说服性文字和任何加载钩子标成另一类点。如果一个点都抽不出来，停——没有可评估的东西，这个 skill 不该被安装。否则就建 eval、跑各组、按模型给结论：留、砍、扔。

要发布就发布整个包。

重点： skill 永远不会「完成」；它是按模型、按日期被接受的，而这个接受会过期。

对我们的意思： eval 集才是资产。文字可替换，点比较稳，数字有保质期。

为什么重要： 一个月从 95% 漂到 65%，就是把 skill 当成「做完了」的公开代价。

从 Level 10 带走：

  • 对两个对照都通过才接受，成本写在收益旁边，adherence 能解释 effect。
  • 文字、点、eval、结果一起交付。
  • 模型或依赖一变就重跑；已有的 skill 从它的文字进入同一个循环。

第三部分：用例

Level 11：示例 skill 走完整个方法

这一层回答：对 test-driven-development 这个 skill，完整设计长什么样，数字怎么读。

目标。 就是 Level 5 那句：改动正确，并由 agent 自己的测试证明。

点。 Level 6 的七个核心点 C1 到 C7、六条次要的测试质量规则、作为 adherence 装置的说服块、作为加载策略的会话钩子。

判分器。 Level 7 的七个代码检查跑在 harness 日志上，加一个「加载了没有」标记，再加 Level 8 的 effect 度量：隐藏测试、逐测试质量标签（锚定在对旧代码和植入故障的运行上）、诚实度、成本、稳定性。

任务。 二十个真实 Python 仓库任务，取自模型训练截止后刷新的基准：12 个修 bug、8 个做功能。每条都有隐藏测试、小于 150 行的标准补丁、两分钟内跑完的测试套件。留修 bug 是因为 C6 只在这类任务上适用；留功能是因为 C1 和 C7 在新行为上表现最明显。

对照组。

  • P0 基线。 什么都没有。
  • P1 按安装状态的 skill。 插件加会话钩子，任务文本里点名这个 skill。
  • P2 只有正文。 不带钩子。P1 减 P2 就是钩子的价钱和效果。
  • P3 替代方案。 先写代码、后写测试，再验证测试在旧代码上失败。P3 对 P1，问的是这个观点究竟是「测试先行」还是「验证你的测试」。
  • P4 从 P0 的失败里写出来的 skill。 点来自基线在这些任务上真实犯的错，可能与那七条教条点不同。
  • P5 经消融精简后的 P4。 只留推动 effect 的点。
  • P6 按需投递的精简版。 不在列表里、不注入；只告诉 agent 一条能打印它的命令。同样的文字，零足迹，所以 P6 对 P5 就是列表的价钱。
  • P7 长度控制。 合理但无关的文字，token 数与 P2 相同。

P0、P1、P5 每个任务跑三次，其余两次；P4 的点在十个任务的子集上做消融；P0、P1、P5 那一行在一个更便宜的第二个模型上再跑一遍：总计约 600 次运行，第一次之前先定钱的上限。

数字怎么读。 读法是第一次运行之前就定好的，这样结果没法事后被辩论成想要的样子：

  • P1 adherence 低：这段文字在这个模型上不工作，名声再大也没用。观点的事还一无所知。
  • P1 adherence 高，结果和 critical 测试占比不优于 P0：agent 确实做了测试驱动开发，代码并没有因此更好。这七个点是这个模型不需要的教条。
  • P1 优于 P0 但不优于 P7：涨的是额外 token，不是观点。
  • P1 和 P3 打平：先写测试不是关键观点，验证测试才是。这个 skill 可以丢掉它的 Iron Law。
  • P2 等于 P1：钩子白花钱。P2 差于 P1：钩子是正文被遵守的唯一原因，那说的其实是这段文字。
  • P5 用更少的点等于 P1，或 P6 在没有列表的情况下等于 P5：同样的效果，不必付 Level 1 那笔每轮成本。
  • 任何一组的增益都跟它的 token 和轮次一起读；多赢一个点却把账单翻三倍，就照实报告。

设计是读者今天就能拿走的。 它产出的数字属于跑它的那个模型和那个月，不是这个文件的属性。

从 Level 11 带走：

  • 一个目标、十一个标注过的点、十二个判分器、八组对照、每个对比一条读法。
  • 读法在运行之前写好。
  • 数字按模型按日期；设计可复用。

现有工具与做法

按方法里的每一块，列出今天有什么，只陈述观察到的情况，不做推荐。

  • 无头 agent 运行。 作用：产出 harness 日志。给你：每次运行里每个工具调用、文件写入、命令和 token 数的事件流。限制：格式各家不同，判分器每个 runner 写一次。
  • claude plugin eval。 作用：在新会话里对插件跑一组用例。给你：每个用例重复运行、带/不带插件的消融模式并报告逐用例差值、确定性判分器（正则、用了某工具、文件存在）加一个模型裁判、按模型分行的 flag、以及美元成本。限制：方差要自己从逐次分数算（Anthropic，《Claude Code》plugin eval 文档）。
  • skill 使用报告。 作用：看装了哪些 skill 真被用过。给你：每个 skill 的调用次数和最近使用时间。限制：被用过也可能是损失。
  • 实时编程基准。 作用：带隐藏测试的任务来源。给你：模型训练截止后收集的真实仓库任务，附 fail-to-pass 和 pass-to-pass 测试（SWE-bench-Live，arXiv 2505.23419；SWE-rebench，arXiv 2505.20411）。限制：偏 Python，环境搭建要花功夫。
  • 长度对齐对照。 作用：把观点和 token 分开。给你：判断是否单靠长度就推动了结果的那一组。限制：对照文字必须合理且无关，否则测的是别的东西。
  • 变异工具与测试裁判。 作用：把逐测试质量标签锚到证据上。给你：变异工具植入的故障，然后一个带评分规则的模型裁判处理活下来的测试。限制：代码本身有 bug 时覆盖率和变异分数不可靠（arXiv 2607.22880），而裁判在用手标校准之前只是看法。
  • skill 扫描器。 作用：抓共享 skill 里已知的坏模式。给你：在一个带标签集合上报告 86.7% 精确率、82.5% 召回率（Agent Skills in the Wild，arXiv 2601.10338）。限制：公开测试里五个产品被不到一小时绕过；扫描不是评审。
  • 按需指令库。 作用：用之前零足迹。给你：纯文本文件，靠告诉 agent 一条命令来打印，prompt 里没有列表。限制：我没找到公开研究测过 agent 多久能自己找对文件。

决策指南

  • 该不该装这个共享 skill？ 先抽它的点。然后查：抽不出点就不装；抽得出点，就在你的几十个任务上跑基线、skill 和长度控制，读那一对分数。
  • 该不该为这个任务写 skill？ 先跑基线，读失败。然后查：失败重复出现，点就是那些失败；不重复，你需要的是一份更好的任务描述，不是 skill。
  • 我的 skill adherence 高但结果平。 用消融，一次一个点。然后查：只留「删掉它 effect 会掉」的点，其余是教条。
  • 我的 skill adherence 低。 重写措辞、缩短、把触发条件放到第一行、让例子对上 agent 的语言。然后查：只重跑 adherence，文字被遵守之前别动点。
  • skill 有用但贵太多。 先砍次要点和说服性文字。然后查：在更少的词数下 effect 必须守住，否则这是一笔真实的交易，得有人拿着两个数字来定。
  • skill 让 agent 写更多测试。 给每个测试打标签，锚定在对旧代码和植入故障的运行上。然后查：只看 critical 测试的数量，因为公开的轨迹研究发现测试数量并不对应任务是否被解决。
  • skill 在几十个的列表里。 在任务里点名它，或用规则路由。然后查：加载了没有的标记；没被点名的 skill 大约一半的时候才加载。
  • 我们换模型了。 重跑那一行。然后查：先看 adherence，因为它会悄悄漂移。
  • 有人问某个 skill「管不管用」。 反问模型、版本、基线、对照。然后查：缺任何一个，答案就是「没测过」。

要点

  1. skill 是上下文里的文字。模型里什么都没变，关于长 prompt 的所有已知结论在它加载那一刻就适用。
  2. 装了和用了是两回事。一台机器上 89 个列表里的 skill 有 81 个从没被调用；公开 eval 里模型大约一半的时候才会打开一个 skill。
  3. 公开只意味着格式合规。规范里没有测试，共享 skill 的实测默认值是没收益加更多 token。
  4. 公开测试里 token 涨了 72% 到 451%，而一段等长的无关文字对结果的影响和 skill 差不多。
  5. 扫过的市场 skill 里四分之一有漏洞模式，扫描器被不到一小时绕过。共享 skill 就是陌生人给的代码。
  6. skill 按模型按环境被接受。同一个文件在一个模型上高 33 个点、在另一个上低 22 个点；每个人的上下文、规则、工具和仓库都会把同一个 skill 变成不同的 prompt。
  7. 「我这能用」是一次没有基线、不算成本的运行。它看不见 3 个点的变化，也永远看不见账单。
  8. 共享观点，不共享文字。skill 的点能被判断，它的一千五百词只能被感觉。抽不出点的 skill 无法评估，只能服从。
  9. 从一句话开始：什么必须变好，写成可测的。测不了就是没研究，没研究就是主观文字。
  10. 一短串核心点，每条带可检验假设。来自基线失败的点优先于教条。
  11. 两族指标：adherence 按点从 harness 日志打分；effect 在带隐藏检查的真任务上打分，agent 产出的每条东西给一个质量标签。成对读。
  12. 结论来自这一对：adherence 低就改文字；adherence 高而 effect 平就扔掉观点。
  13. 永远跑长度控制。赢了基线却输给自己长度的 skill，里面没有能用的观点。
  14. 文字、点、eval、结果一起交付，模型一变就重跑。没人这么做的时候，一个月里准确率从 95% 掉到 65%。
  15. 设计可复用；数字会过期。

参考文献

资料来源

#Agent Skill#eval#adherence#测试驱动开发#Prompt 工程