Skill评估工具

解决什么问题

写 Agent Skill 时常见困境：改了指令、调了 prompt，却无法判断这次改动让技能变好还是变差；感觉“输出应该没问题”，但没覆盖边界情况（比如畸形输入、歧义指令）；新旧版本对比靠主观印象，缺客观数据支撑。根源是没有量化评估闭环——没用真实用例、可验证断言和对比实验检验技能的实际价值。

核心机制与流程

本技能用评估驱动迭代（eval-driven iteration）破局，核心动作是对比实验：对同一用例，分别跑「加载技能（with_skill）」和「不加载/用旧版（without_skill）」，通过通过率、token、耗时的 delta 量化质量提升与成本变化。

流程分 8 步循环：

1. 设计用例：在 evals/evals.json 写真实 prompt（含边界用例），配 expected（成功标准）和可选 input_files，起步 2-3 个；
2. 双配置运行：每个用例跑两次，输出落 outputs/、timing.json（含 total_tokens/duration_ms），用干净上下文避免污染；
3. 写断言：基于首轮输出，补可程序验证的断言到 grading.json（如“输出合法 JSON”“含字段 X”），别写模糊或脆弱的项；
4. 评分留证：scripts/grade.py 跑脚本化断言，记 PASS/FAIL + 输出原文证据；语义项用 LLM 评，整体对比可做盲测；
5. 聚合结果：scripts/aggregate.py 生成 benchmark.json，含两配置的通过率、token/耗时均值与标准差及 delta；
6. 分析模式：两配置都过的断言删掉；都挂的排查断言/用例；仅 with_skill 过的是技能价值点；抖动大则收紧指令；
7. 人工复核：写可执行反馈到 feedback.json（如“缺轴标签”），别写主观评价；
8. 迭代技能：从失败断言和反馈泛化问题（如精简冗余指令、补推理逻辑），开 iteration-N+1/ 重跑，直到满意/无反馈/delta 无提升。

适用边界与注意点

• 不适用场景：仅检查 SKILL.md 格式（用 package_skill.py 校验即可），或与技能输出质量无关的通用测试；
• 产物分离：evals/、iteration-N/ 等评估文件与技能本体目录分开，避免污染技能结构；
• 样本与统计：早期用例少时看原始通过数和 delta，别纠结统计显著性；结果抖动就收紧指令或查执行日志的瓶颈。