为 dotnet/skills 仓库的…

当需要新建或扩充 skill/agent 的 eval.yaml 评测规格、写刺激用例/评分器/评分细则、按统计功效确定评测规模或搭建测试夹具文件时使用。

适用场景

解决思路

1. Step 1 定位目标与测试目录：skill 用 `tests/<plugin>/<skill-name>/eval.yaml`，agent 用 `tests/<plugin>/agent.<agent-name>/eval.yaml`（`agent.` 前缀用于消歧）。
2. Step 1 确认目标确实存在于 `plugins/<plugin>/skills/<skill-name>/SKILL.md` 或 `plugins/<plugin>/agents/<agent-name>.agent.md`，并阅读其内容——不读就无法写出不过拟合的评分细则。
3. Step 1 agent eval 走 native SDK agent lane：Vally 0.14 无法注册自定义 agent，`agent.*` spec 不会走 skill experiment；评估工作流单独发现它们，用 `skill-validator evaluate` 运行目标 agent，再把证据适配进同一套带 schema 版本的结果与 dashboard 管线。distinct-stimulus 下限对 skill 与 agent eval 都适用。
4. Step 1 对设置了 `disable-model-invocation: true` 的 skill 要特别小心：模型无法调用它，该 skill 在面向模型的 skilled arm 中不存在，任何直接 eval 都是在比较两个完全相同的 arm；answer-content grader 不会在这两个 arm 之间产生差异。这类 skill 的诚实覆盖走依赖层——通过加载它的那些 skill 的 outcome eval，以及 plugin arm。例如 `filter-syntax` 由 `tests/dotnet-test/run-tests/eval.yaml` 中的 filtered-command 场景覆盖。
5. Step 2 用 Vally 格式写规格骨架：必须使用 `stimuli:` 和 `graders:`；`scenarios:` 与 `assertions:` 是 pre-Vally 格式，已不再被加载。骨架含 name、description、type、defaults（timeout、runs）、stimuli（name、prompt、environment.files、graders、rubric）。
6. Step 2 注意 `defaults:` 是替换 `config:`，不是合并：`config` 是同一块的废弃别名，同时声明两者时 vally 会抛错。现有 eval 若以 `config:` 开头，改设置时把它替换成单个 `defaults:` 块。否则失败是隐形的：job 退出码 0、没有任何 verdict，而 PR 评论会归咎于「瞬时基础设施问题」。
7. Step 3 在写内容前先按统计功效定规模：gate 给每个 distinct stimulus 一票；同一 stimulus 的重复运行折叠成一次多数方向投票，并作为可靠性证据保留。
8. Step 3 distinct stimuli 必须 ≥ 5，否则 verdict 为 `underpowered`——既不会通过也不会判为回归；dormancy 契约不计入这一下限。
9. Step 3 需要在 discordant（非平局）刺激票上做精确单侧符号检验且 p ≤ 0.05；平局不被丢弃，它们会压低 discordant 计数。参考表：discordant ≤ 4 → 无法通过，p ≥ 0.0625；5–7 → 仅允许零失败（5W/0L），p = 0.031；8 → 可承受一次失败（7W/1L），p = 0.035。
10. Step 3 恰好 5 个 stimulus 时一次平局就是致命的（只剩 4 张 discordant 票）；6 个时一次平局可承受；7 个时最多两次；一次失败都不可承受。5 只是资格下限，不是足够功效。
11. Step 3 按要检测的效应量与平局率定规模：80% power 对真实 90% 条件胜率只需 8 张 discordant 票；对 80% 需 18 张、70% 需 37 张、60% 需 158 张。
12. Step 3 `runs` 用于可靠性而非任务广度：Vally 建议 CI 用 3 次、nightly 用 5–10 次来计算 pass rate、pass@k、pass^k 和 flakiness；额外 runs 永远清不掉五刺激下限。
13. Step 3 不要在 `dotnet-skills.experiment.yaml` 里设置 `runs`：experiment 的 override 会覆盖每个 eval 自己的值，而不是把它当默认值。
14. Step 4 写刺激用例：Name 描述「测什么」而不是「怎么测」。
15. Step 4 Prompt 必须是自然的开发者请求，绝不提及 skill、agent 或其专属词汇——被提示词引导的 prompt 会抬高 overfit 分数并偏置 baseline。
16. Step 4 每个 stimulus 应区分 skill 的**不同**属性；五个 stimulus 覆盖同一属性只是算术，不是证据。
17. Step 4 给每个 stimulus 一个稳定且唯一的 `name`：Vally 按 `(stimulus name, trial index)` 配对比较轨迹，重名会让 slot 身份变得模糊。
18. Step 4 对任何会迁移或重写代码的 skill，加入一个 boundary / no-op stimulus，证明它对已经正确的输入不做改动。
19. Step 5 配置环境：`environment.files` 用 `src`（相对 eval.yaml 的路径）与 `dest`（agent 工作目录中的路径），可以传整个目录；`environment.commands` 中预期会失败的构建命令要加 `|| exit 0` 保护。
20. Step 5 不要在 skill eval 中设置 `environment.skills`：experiment 声明了 `vary: /environment/skills` 并自己提供值（baseline arm 为 `[]`，skilled arm 为 `plugins/<plugin>/skills/<skill>`），eval 里声明的值在每个 arm 都会被替换，且无法只给一个 arm 加 skill。
21. Step 5 `environment.skills` 只在 `agent.*` eval 中有意义：native agent lane 只在隔离的目标运行中加载这些条目，而 plugin run 加载生产 plugin 的完整 skill 面。照抄现有 agent eval（如 `tests/dotnet-test/agent.test-quality-auditor/eval.yaml`）的形状，不要凭记忆复现——本仓库的 spec 对这些条目的写法并不一致。agent eval 若缺少 `environment.skills`，就无法调用 agent 路由到的 skill。
22. Step 5 夹具规则：每个被引用的 fixture 都必须被 git 跟踪。`.gitignore`（如 `coverage*.xml`）曾静默吞掉已提交的 fixture，导致本地通过、CI setup 阶段失败；用 `git ls-files` 验证，而不是看工作树。
23. Step 5 每个 fixture 必须如 stimulus 所假设的那样表现：作为健康样本的必须能构建；故意损坏的必须只因该 stimulus 关注的原因失败，不得有其他原因。judge 会因为夹具作者引入的无关「既有构建问题」而惩罚 agent。
24. Step 5 每个 fixture 必须复现其 stimulus 名称所指的 bug；否则 baseline 得分很高，skill 无从加分。
25. Step 5 覆盖率夹具必须内部一致：Cobertura 报告声明的 `line-rate`、汇总总数（`lines-covered`/`lines-valid`）与 `<line>` 元素互相矛盾时，两个 arm 会读到不同真相，失败是夹具的错；引用该数字的 rubric 项或 prompt 必须在同一次变更中一起更新。
26. Step 5 不要接线重复夹具来抬高 `n`；改名留下的残留物只增加 trial，不增加证据。
27. Step 5 预期会失败但仍要产出产物的 setup 命令必须加守卫（`|| exit 0`），否则 vally 会丢弃该 trial。
28. Step 5 会剥离源码的 cleanup 命令必须跳过包含 `SKILL.md` 的目录——暂存的 skill 就在那里，删掉它只会中止 skilled arm。
29. Step 6 写评分器：grader 是对每个 arm 评估的硬性 pass/fail 检查。类型与必需 config 对应关系：`output-matches`/`output-not-matches` 需 `pattern`（对 agent 输出做 regex）；`output-contains`/`output-not-contains` 需 `substring`（输出中的字面文本）；`file-exists`/`file-not-exists` 需 `path`（对工作目录做 glob）；`file-contains`/`file-not-contains` 需 `path` 与 `value`（产出文件的内容）；`run-command` 需 `command`（以及可选的 `expected_exit_code`、`timeout`、`stdout_matches`，用于验证产出的代码真的能构建/运行）；`exit-success` 无需 config（agent 产出了非空输出）；`prompt` 无需 config（对 `rubric` 运行 LLM judge）。
30. Step 6 注意 `config` 缺失或缺少必需键的 grader 能正常解析但**什么都不强制**；常见原因是编辑时的缩进滑位，`check_eval_quality.py` 会拦下它。
31. Step 6 优先使用能被多种有效做法满足的宽泛 pattern，例如 `(root cause|primary error|underlying issue)`。
32. Step 6 如果 skill 强制了某种输出形状，就要对它断言：被要求输出决定性 `Recommendation:` 行的 skill 可能悄悄停止这么做，而 eval 仍然通过。
33. Step 6 用 `file-not-contains` / `file-not-exists` 证明 agent 避免了错误动作。
34. Step 7 写评分细则：rubric 项按成对方式评判（baseline vs skilled），overfitting judge 会把每一项分类为 outcome（是否达成正确结果——WHAT 而非 HOW，这是目标）、technique（是否使用了 skill 特有流程，应最小化）、vocabulary（是否使用了 skill 的术语，应避免）。
35. Step 7 测试结果而非方法，例如写 “Identified the root cause of the build failure”，而不是 “Replayed the binlog using `dotnet build /flp`”。
36. Step 7 接受任何有效做法。
37. Step 7 绝不按名字引用 skill，也绝不重用 `SKILL.md` 的措辞。
38. Step 7 绝不奖励「使用了 skill」——harness 会单独报告激活情况，这样做既测不到东西又会抬高 overfit 分数。
39. Step 7 不要测模型已经具备的知识，那不会带来 delta。
40. Step 7 保持每一项都可以被独立评估。
41. Step 7 不要奖励体量（测试数量、报告长度）；当两个 arm 都采取行动时 judge 会做对比。
42. Step 8 谨慎添加约束：`constraints` 支持 `expect_tools`、`reject_tools`、`reject_skills`。在**咨询性**问题上用 `expect_tools: [bash]` 会强制一次 restore 或 build，把回答变成超时且没有质量收益；只在任务确实需要工具时才要求工具。
43. Step 8 用 `reject_tools` 是保持只读 stimulus 只读的正确方式。
44. Step 9 添加 dormancy guard：它证明 skill 在表面上匹配它的离题请求上保持休眠。对每个真实的「when not to use」边界加一个：错误输入格式、超出范围的请求、不兼容的项目类型、错误的框架版本、前置条件缺失。
45. Step 9 dormancy guard 的 rubric 验证三件事：recognition（说明为何不适用）、restraint（无流程、无文件改动、无安装）、redirection（给出正确的下一步）。
46. Step 9 绝不要把 `expect_activation: false` 与 `constraints.reject_skills` 组合：那会强制 skilled arm 在无 skill 的情况下运行，harness 就无法观察目标 skill 是否劫持了该请求；比较结果仍会作为 report-only 证据可见，但不参与偏好投票，且意外的隔离激活会阻止通过。`expect_activation: false` **单独**使用是本仓库的约定。
47. Step 10 验证：运行 `dotnet run --project eng/skill-validator/src/SkillValidator.csproj -- check --plugin ./plugins/<plugin>`、`python eng/eval-quality/check_eval_quality.py`、`./eng/run-skill-evals.sh <plugin> <skill-name>`。
48. Step 10 对 agent eval 直接跑 native lane：`dotnet run --project eng/skill-validator/src/SkillValidator.csproj -- evaluate plugins/<plugin>/agents/<agent>.agent.md --tests-dir tests/<plugin> --runs 1 --verdict-warn-only`；CI 通过 `eng/vally-adapter/adapt-agent-results.mjs` 适配该结果，并应用与 skill 结果相同的 distinct-stimulus 符号检验政策。
49. Step 10 `check_eval_quality.py` 会拦截十一类会破坏结果的结构缺陷：缺失或未被跟踪的夹具、自相矛盾的覆盖率夹具、空的 grader config、带 `reject_skills` 的 dormancy guard、低于下限的 stimulus 数量、重复的 YAML 键或 stimulus 名，以及 `config:`/`defaults:` 冲突。不要把新 eval 加入 `eng/eval-quality/underpowered-allowlist.txt`——gate 会拒绝相对 base 分支新增的 allowlist 条目。
50. Step 10 正式运行时，提交一条包含 `/evaluate` 的 PR review，使其绑定到被评审的 commit。
51. 补充坑位：代码生成任务 timeout 设得太短会导致空输出、从而让每个 grader 都失败，用约 360s。
52. 补充坑位：编辑时遗留的重复 YAML 键会逐字段覆盖下一个 stimulus 字段，必须删掉多余块。
53. 补充坑位：agent eval 不能用 `./eng/run-skill-evals.sh` 运行，那个辅助脚本只支持 skill，请用 `skill-validator evaluate`。
54. 补充坑位：landing 一个恰好 5 个 stimulus 的 eval 很危险，一次平局就会让通过变得不可能；应按效应量与平局率定规模。
55. 补充坑位：靠提高 `runs` 来清掉下限是无效的——重复只测单个任务的可靠性，应增加 stimulus。

适用边界 · 注意事项

• 不要用于诊断失败或回归的 eval——那要用 `improve-skill-quality`。
• 不要用于修改 skill-validator 或评估工作流本身。
• 不要用于创建或编辑 `SKILL.md` 文件——那要用 `create-skill`。