Grounding Skill Evals

grounding-skill-evals —— 怎么度量一个 cc-master skill

> 这是项目自用的 dev skill，不随插件分发。 它住在 .claude/skills/（给 cc-master 自己的贡献者用），不在 skills/（那是 ship 给插件用户的）。终端用户装 cc-master 永远看不到它——它只为度量本仓的 skill 而存在。

Overview

这个 skill 回答一个问题：「这个 skill 到底好不好，怎么用数据说话？」

它不写 skill 的 body（那是 cc-master-skillsmith），也不判断一个 skill 该不该存在（那是 curating-skill-portfolios）。它只管度量——给一个已经写出 body 的 skill 声明一份可消费的成功契约（J），接上本仓已有的三个 eval 脚本，并用三个借来的思想防止「自己骗自己说改好了」。

核心原则：度量先于迭代。 没有声明 J（成功 = 什么），评测就会逐 case 漂移、优化就会 reward-hack 碰巧在视野里的那个指标。没有 baseline、没有 holdout、没有改前预测，「我感觉改好了」就是在自欺。

> 本 skill 只借三个思想，不搬引擎。 成熟的 skill 评测 / 优化方法论有一整套重型机器（重型 J 不变量集、多字段机器可读裁决 schema、带自动搜索 + 多候选 filter 的优化引擎、Pareto 前沿追踪、统计显著性 / 方差分析预检）。本仓体量用不上，只借 baseline-must-fail / holdout split / predict-then-validate 三个判别力思想，落在纯 prose checklist + 现有脚本上。任何「补个搜索引擎 / 加个多字段裁决 schema」的冲动都是照搬过度工程（红线——过度工程的边界见本 skill 的 When NOT to use / OUT of scope 与设计宪法的「不做」段）。

When to use

• 刚给一个 skill 写完或改完 body，想要一份独立的成功度量再迭代。
• 要给本仓某个 skill 写 / 修轻量 J（分发 skill 用 .design/OBJECTIVE.md，dev-only skill 用 OBJECTIVE.md）。
• 改一个 skill 的 description 前后，想知道触发准确率（precision/recall/accuracy）有没有真的提升——跑 Track A。
• 改一个 skill 的纪律段 / 行为，想知道 with-skill vs without-skill 的行为差有没有真的拉开——跑 Track B。
• 怀疑 description 优化「过拟合到我脑子里那几个 query」——要 holdout split 验证。
• 改动前想立个可证伪的预测、改完比对——predict-then-validate 防自欺。

When NOT to use（明确反例 + 移交）

• 要写 / 改一个 skill 的 body（craft 诊断、命名锚、流程骨架、纪律段怎么写）→ cc-master-skillsmith。本 skill 度量 body，不生产 body。
• 要决定一个 skill 该不该建 / 该是 skill 还是 reference / 一组 skill 边界与重叠（portfolio 准入）→ curating-skill-portfolios。本 skill 假设 skill 已存在且值得度量；「值不值得存在」是上游问题。
• 要跑纯定性 pressure baseline（看纪律段在压力下被不被合理化绕过）→ 那是 cc-master-skillsmith 的 Iron Law 闭环。本 skill 的 baseline-must-fail 是它的定量延伸，不替代它。

轻量 J 入口（5 分钟，不是 5 小时）

J（objective function）= 这个 skill「成功 = 什么」的机器可读答案。分发 skill 落在 skills//.design/OBJECTIVE.md；dev-only skill（.claude/skills//）可保留根部 OBJECTIVE.md。本仓的 J 是轻量的：一句话 J_top + 一段 baseline_reference（没这 skill 的 agent 会怎样退化）+ 1-2 个不可回退的 strict_dims。就这么多——不要膨胀成重型 J 不变量集那种 schema。

最小入口（完整 schema、判据、正反例在 [references/objective-function.md](references/objective-function.md)）：

1. 写 J_top——一句话：这个 skill 让 agent 在什么上成功。不是 description（那是触发器），是成功的承重定义。
2. 写 baseline_reference.without_skill_floor——≤3 行：没有这个 skill 的默认 agent 会怎样做差。写得足够具体，让「这个 skill 打败它」是可判定的，不是口号。
3. 挑 1-2 个 strict_dims——不可回退的承重维度。不能全空（全空 = J 不约束任何东西，迭代可以丢掉一切还自称进步），也不能全锁（全锁 = 没有探索空间）。

> J ≠ description。 description 是触发期的消歧器（prose、流动、随版本演化）；J 是结构性承诺（声明一次、稳定、被 Track A/B 当锚消费）。两者职责分开——改 description 跑 Track A，改 J 是改成功定义本身。

接现有 Track A + Track B + codex 第二评委（不重造）

本仓已有三个 eval 脚本。本 skill 的纪律是接它们、读它们的判决，不是再造一套（怎么跑、怎么读判决的完整步骤在 [references/track-ab-discipline.md](references/track-ab-discipline.md)）：

| 设施 | 脚本 | 量什么 | 何时跑 | |---|---|---|---| | Track A —— 触发准确率 | scripts/eval-trigger.sh | description 在 should-trigger + near-miss query 上的 precision/recall/accuracy | 任何 description 改动前后各一遍比 accuracy | | Track B —— 编排纪律 benchmark | scripts/eval-benchmark.sh | with-skill vs without-skill 的行为断言，各 3 run 看 mean±stddev | behavioral 改动（纪律段 / 流程）前后 | | codex 第二评委 | scripts/codex-review.sh [--base ] | 非-Claude 端点对同一 diff / transcript 出 approve | needs-attention | grader 后跑，分歧 = 高信号 |

generator ≠ judge（红线级，呼应 cc-master「端点验收 / gate-green ≠ passed」）： 生产 body 的 actor 和评判的 actor 必须分离。同家族评委给同家族产出打分，pass-rate 虚高约 33%。所以 Track B 的 grader 后必须跑 codex 当第二评委——它是非-Claude 端点，与 Claude 产出/评判家族分离。codex approve + 非空 + 已读 diff → 信；needs-attention / 空 review / OAuth 过期 → 按未通过处理（silent-pass-through guard，不静默放行）。

> scripts/ 不进 hooks/（红线 1 / ADR-006，ship-anywhere）： 这三个脚本都依赖 uv + Python 3.12 + claude/codex CLI，只许进 scripts/（带外手动 / 编排调用），绝不进 hooks/（hook 只允许 bash + node/JS——Claude Code 保证存在的 runtime；uv/python/claude/codex 不在其中）。将来本 skill 若要补新工具脚本，同样只进 scripts/。

只借的三个思想（baseline-must-fail / holdout / predict-then-validate）

这三个是本 skill 的判别力内核——都是思想，不是引擎（完整配方 + 正反例在 [references/anti-overfit-lite.md](references/anti-overfit-lite.md)）：

1. baseline-must-fail——每个 eval case 必须在「没有该 skill」时可证失败。两臂都过的 case = 零证据（它没区分有没有 skill）。所以先跑 baseline 臂（without-skill），确认它真的失败，再跑 with-skill 臂——否则正向证据会先入为主。cc-master 的 pressure baseline 已是它的定性版；这里是定量延伸。

1. holdout split——把 should-trigger / near-miss query 分成 train / holdout 两组（默认 70/30）。只在 train 上调 description，用 holdout 验证。 train 上好、holdout 上崩 = 过拟合到了那组 query（你优化的是「背答案」不是「会判别」）。

1. predict-then-validate——改 description / 纪律前，先写下预测的 delta（「我预期 accuracy 从 X 升到 Y / 这条 case 会从 fail 翻成 pass」），改后比对实测。预测对 = 你真的理解了机制；预测频繁错 = 你在碰运气 + 把噪声当真有效。结构性改动（删一段、加一条硬规则）预测准；纯 prose 措辞策略改动预测准度骤降——准度本身就是信号。

baseline-must-fail 的强模型天花板（本仓 dogfood 观测）

当一个有能力的模型在单次决策里能自推出纪律选项，RED 不会失守——这不证明 skill 无价值，而是说该 skill 的价值在一致性（每次都对，含弱模型 / compaction 后退化的 context）、触发（想起来要用）、更硬的边界，而非翻转一次 fresh 强模型的高压决策。此时判据①的诚实证据 =「GREEN 守住 + 精准引用 skill 段落 + 内容经独立审查判对 + 文档化这道天花板」，而非伪造一个 RED 失败（加压到崩只证明『够压能压垮任何 agent』，是假证据）。

> 这是本仓真实 dogfood 观测——本会话三轮鉴别性 baseline 都未能让强模型 RED 失守，不是凭空规则。强模型 RED 不失守时，不要为了凑一个「baseline 可败」而加压到崩；那制造的是噪声，不是判别力。

Quick Reference

| 你要做 | 用什么 | 去读 | |---|---|---| | 给一个 skill 声明 / 修 J | 写 .design/OBJECTIVE.md 或 dev-only 根部 OBJECTIVE.md（Jtop + baselinereference + strict_dims） | [references/objective-function.md](references/objective-function.md) | | 改了 description，量触发准确率 | scripts/eval-trigger.sh （前后各一遍比 accuracy） | [references/track-ab-discipline.md](references/track-ab-discipline.md) | | 改了纪律段 / 行为，量行为差 | scripts/eval-benchmark.sh（各 3 run，mean±stddev） | [references/track-ab-discipline.md](references/track-ab-discipline.md) | | 拿非-Claude 端点二审 | scripts/codex-review.sh（generator≠judge） | [references/track-ab-discipline.md](references/track-ab-discipline.md) | | 定演化节奏（description 高频 / body 低频）、找回滚锚 | 评估成本分层 + git 谱系（每次演化独立 commit） | [references/track-ab-discipline.md](references/track-ab-discipline.md) §7 | | 防 description 过拟合 | holdout split（train/holdout 70/30） | [references/anti-overfit-lite.md](references/anti-overfit-lite.md) | | 防自欺（碰巧当有效） | predict-then-validate（改前写预测、改后比对） | [references/anti-overfit-lite.md](references/anti-overfit-lite.md) | | 保证 case 有判别力 | baseline-must-fail（两臂都过的 case 零证据） | [references/anti-overfit-lite.md](references/anti-overfit-lite.md) |

Common Mistakes

• 自检即完成。 「我自己看了一遍 transcript，感觉行为对了」不是判决。自检不算完成——要独立端点判决（Track A 的数字 / Track B 的 grader + codex 第二评委）。「looks fine」从来不构成 passed。违背这条字面就是违背精神：你没法用「我读了一遍很有信心」绕过「跑了 eval 拿到数字」——有信心 ≠ 有证据。
• baseline 不会败也照用。 一个两臂（有/无 skill）都过的 case 证明不了任何东西——它对「这 skill 有没有用」零判别力。baseline 必须可败：每个 case 必须在 without-skill 臂可证失败，否则它不该进 eval set（reject-and-surface，别静默留着凑数）。违背这条字面就是违背精神：「这个 case 虽然两臂都过，但它测的是另一个维度」——那它就该去那个维度的 baseline-fail case set，不是留在这里冒充判别力。
• 同家族自己给自己打分。 用 Claude 产出、又用 Claude 评判，pass-rate 虚高约 33%。generator ≠ judge——Track B 必须跑 codex 第二评委，分歧才是高信号。
• 只看 train 不看 holdout。 在你脑子里那几个 query 上把 description 调到满分，holdout 上崩盘——这是过拟合，不是改进。永远留 holdout。
• 改前不预测。 改完跑 eval，数字变好了就宣布胜利——分不清是真有效还是噪声。改前写预测的 delta，比对了才知道。
• 把 J 写成 description 的复读。 J 是成功度量（被 eval 当锚消费），description 是触发器。J 复读 description = 没有可消费的成功契约。
• 想给本仓补个自动搜索优化引擎 / 多维优化前沿 / 多字段裁决 schema。 那是重型方法论的引擎，本仓体量是 overkill。只借思想，落在 prose + 现有脚本上。

Red Flags —— STOP，你在自欺

• 宣布「这 skill 改好了」但没有跑 Track A/B 拿到数字——只有「我感觉」。
• 用的 eval case 没有一个在 without-skill 时会失败——它们对「有没有用」零判别力。
• Track B 只用了 Claude grader，没跑 codex 第二评委。
• description 在 train query 上很好，从没在 holdout 上验证过。
• 改 description / 纪律之前没写任何预测，改完直接看数字喊好。
• 想往 hooks/ 里塞依赖 uv/claude/codex 的 eval 脚本（红线 1）。
• 想给本仓搭带自动搜索 + 多候选 filter 的优化引擎 / 多维优化前沿 / 统计显著性预检 / 多字段机器可读裁决 schema。

以上任一 = 停。先声明 J、接现有脚本拿数字、留 holdout、改前预测。自检不算完成，要独立端点判决。

Pointers

• references/objective-function.md——轻量 J 写法 + .design/OBJECTIVE.md / OBJECTIVE.md 的 schema（§5.4）+ J_top / baseline_reference / strict_dims 怎么填的判据与正反例。
• references/track-ab-discipline.md——怎么跑现有三脚本（eval-trigger / eval-benchmark / codex-review）+ 怎么读判决 + generator≠judge（codex 当第二评委）+ 演化频率分层（评估成本决定节奏，含 Track A 信号死亡时的降级路径）与 git 当谱系/回滚锚。
• references/anti-overfit-lite.md——holdout split + predict-then-validate + baseline-must-fail 的完整配方与正反例。
• cc-master-skillsmith——写 body（craft 诊断 + 4 类内容 + pressure baseline）。本 skill 度量它产出的 body。
• curating-skill-portfolios——portfolio 准入（要不要建 / skill vs reference / 重叠）。本 skill 假设 skill 已存在。
• design_docs/eval/README.md + design_docs/eval/track-b-benchmark.md——本仓 eval 机制的权威用法 / 依赖 / 天花板。
• skill-creator——官方 skill，用来 scaffold 文件 / 优化 description / 跑 eval 的工具。
• AGENTS.md §8——本仓 eval 机制（Track A + Track B）的仓级 SSOT。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nemori-ai
• Source: nemori-ai/cc-master
• License: MIT

Install and usage instructions live in the source repository linked above.