02 技能评估方法论

02 技能评估方法论

学习目标

• 理解 skill-creator 中的并行对比实验设计
• 掌握 benchmark.json 的统计解读方法
• 分析 eval-viewer 的双标签可视化架构
• 学习描述优化的自动评估循环

前置知识

本章涉及技能评估方法的通用原理，建议先阅读：

• 技能评估方法论

下文假设你已理解上述概念，直接聚焦 skill-creator 技能的具体实现。

---

项目实践

skill-creator 的并行实验架构

skill-creator 是 Anthropic Skills 仓库中最复杂的技能（~485 行），它本身就是一套完整的评估框架。其核心设计：

关键设计决策：

1. 同一 turn 并行启动：with_skill 和 baseline 在同一个消息中同时派生子代理，消除时间偏差。
2. timing.json 即时捕获：子代理完成的通知中包含 total_tokens 和 duration_ms，必须立即保存——这是唯一的机会。
3. 基线选择灵活：新技能用无技能作为基线，改进技能用旧版本快照作为基线。

benchmark.json 的严格 Schema

skill-creator/references/schemas.md 定义了精确的 JSON 结构。关键约束：

• 配置名必须是 "with_skill" 和 "without_skill"（viewer 依赖这些字符串做分组和颜色编码）
• pass_rate、time_seconds、tokens 必须嵌套在 result 对象下，不能放在 run 的顶层
• run_summary 中每个配置必须包含 mean 和 stddev

如果 schema 不符合，eval-viewer 会显示空值或零值——这是一个实际踩过的坑。

eval-viewer 的双标签架构

eval-viewer（eval-viewer/generate_review.py）是一个独立的 Python HTTP 服务器，提供：

Outputs 标签：

• 逐测试用例并排对比
• 文件渲染（PDF 直接显示，代码语法高亮）
• 自动保存的人工反馈文本框
• 迭代 2+ 时显示上一轮的输出和反馈

Benchmark 标签：

• 统计汇总（mean ± stddev + delta）
• 分析师观察（非判别性断言、高方差测试、时间-质量权衡）

无显示环境适配：

• Cowork/无显示器环境使用 --static <output_path> 生成独立 HTML 文件
• 反馈通过 feedback.json 文件下载，而非服务器提交

---

问题与规避

timing.json 数据丢失

问题：子代理完成的通知中的 total_tokens 和 duration_ms 只在通知瞬间可用。

规避策略：skill-creator 明确要求在收到通知时立即写入 timing.json，不等待所有子代理完成再批量处理。

grading.json 字段名必须精确

问题：viewer 期望 text、passed、evidence 字段名。如果 grader 使用了 name/met/details 等变体，viewer 无法解析。

规避策略：使用 skill-creator 自带的 grader 子代理（agents/grader.md），它会输出正确的字段名。

非判别性断言浪费计算资源

问题：如果某个断言在两个配置下都 100% 通过，它不区分技能价值，但仍然消耗了执行和评分的计算资源。

规避策略：benchmark.json 的 notes 字段会自动标记这些断言。分析师建议移除或增加更细粒度检查。

---

设计取舍

为什么用子代理并行对比而非单 Agent 依次执行？

优势：

• 两个版本在同一 turn 内独立执行，避免上下文偏差
• 总执行时间 = max(with_skill, baseline)，而非 sum
• 更真实的对比（每个子代理都是”干净的”Claude）

代价：

• 需要 subagent 支持（Claude.ai 不支持）
• Token 消耗翻倍

替代方案：依次执行（更便宜但有上下文偏差）。在 Claude.ai 上 skill-creator 自动降级为依次执行模式。

为什么描述优化用 60/40 训练/测试分割？

优势：防止描述在训练集上过拟合。始终用测试集得分选择最优描述。 代价：需要更多的评估查询（20 条最小）。 Anthropic 的教训：他们明确指出”选测试集得分而非训练集得分”——这是实际踩过的坑。

---

参考来源

• Anthropic Skills 仓库：skills/skill-creator/SKILL.md
• JSON Schema 规范：skills/skill-creator/references/schemas.md
• agentskills.io 规范：https://agentskills.io/specification