eval-harness 快速入门

别再凭感觉说”新 Skill 更好用”,让数据帮你做决定。

这是什么?解决什么问题?

随着 Agent Skills 越来越多,大家普遍面临一个难题:装了这个 Skill 后,AI 的输出到底变好了还是变差了?不同的 Skill 组合,哪个效果最好?SKILL.md 写法的不同对结果有多大影响?

eval-harness 是一个社区维护的评估框架 Skill。它能帮你:

• 把一组测试任务(比如 50 道编程题)交给 AI 跑两遍——一遍装 Skill,一遍不装。
• 对比两轮输出的差异,计算成功率、代码质量、token 消耗等指标。
• 输出带统计显著性的报告,告诉你”提升是真实的,还是运气”。

这个 Skill 来自 affaan-m/everything-claude-code 仓库,是 Anthropic 黑客马拉松获奖项目。它特别适合 Skills 开发者做 A/B 测试,以及团队选型时做客观评估。

准备工作

• Node.js 18+ 或 Python 3.10+
• 一个支持 Agent Skill 的客户端(Claude Code、OpenCode 等)
• 一组测试任务(JSONL 格式,每行一个 prompt)
• 至少 30 分钟时间(评估需要多次跑 AI,会比较慢)
• API 访问令牌(评估会消耗 token)

3 步快速上手

第 1 步:克隆仓库

git clone https://github.com/affaan-m/everything-claude-code.git
cd everything-claude-code
ls skills/eval-harness/

你应该能看到 SKILL.md、harness.py(或 .js)、example_tasks/ 等文件。

第 2 步:准备测试任务集

在 tasks/ 目录创建一个 JSONL 文件,每行一个 JSON 对象:

{"id": "q1", "prompt": "写一个 Python 函数判断回文", "expected": "def is_palindrome(s): ..."}
{"id": "q2", "prompt": "修复这个 bug: ...", "expected": "fixed code..."}
{"id": "q3", "prompt": "解释 async/await", "rubric": "是否提到 event loop..."}

每条任务可以带 expected(期望输出)或 rubric(评分准则)。

第 3 步:跑评估

python harness.py \
  --tasks tasks/q1-q3.jsonl \
  --skill eval-harness \
  --baseline no-skill \
  --output report.html

跑完后打开 report.html,你会看到:

• 每个任务的两轮输出对比
• 成功率(通过的题目数 / 总题目数)
• 平均 token 消耗
• 统计显著性(p-value)
• 改进/退步的具体例子

常见踩坑

1. 测试集太小(< 10 题):统计结果不可信,跑出来的差异可能是运气。建议至少 30 题。
2. 测试任务太相似:如果 50 题都是”写排序”,优化点会过拟合,无法反映真实场景。要包含不同类型任务。
3. baseline 设置不当:baseline 应该是”完全不装任何 Skill”或”装的是上一版本”,而不是”装了不同 Skill”。
4. 评估指标单一:只看”通过率”是不够的,还应该看代码质量、可读性、token 效率。harness 支持多维度评分,但你需要主动配置。
5. 忽略 LLM 评分的主观性:用 LLM 当 judge 时,它自己也有偏好(倾向于自己风格的答案)。建议设置 rubric 而不是简单 yes/no。
6. 温度参数不固定:不同 temperature 会导致结果不稳定。评估时必须固定 temperature=0,否则数据不可复现。

初级用法

• 回归测试:每次 Skill 更新前,跑一遍测试集,确认新版本没退步。
• Skill A/B 测试:比较两个候选 Skill 哪个更适合你们团队的工作流。
• 模型对比:同一个 Skill,对比 GPT-4o、Claude Sonnet、Gemini 哪个跑分高。

高级玩法

• 配对样本 t 检验:harness 内置统计检验,告诉你提升是不是显著(p<0.05 才有意义)。
• 多轮对话评估:不仅评估单次回答,还评估多轮交互(任务分解、错误恢复、用户反馈响应)。
• 集成到 CI:GitHub Action 里每次 Skill 变更自动跑评估,把报告作为 PR 评论。

小技巧

• 先用 5 道题小规模验证流程跑通,再扩到 50 道完整测试。
• 评估结果不要只看平均值,要看方差——稳定的 Skill 比偶尔超神的 Skill 更值得依赖。
• 跑评估时用固定的 API key 和 region,避免后端策略变化导致数据不可比。
• 把报告归档到 eval-history/,长期看 Skill 演进的趋势。
• LLM judge 的 prompt 也要评估,形成”元评估”闭环。

常见问题 FAQ

Q1: 这个 Skill 跟 eval-harness 有什么关系?必须装吗?

A: Skill 是给 AI Agent 用的”技能包”,能告诉 Agent 怎么按特定规范工作。不是必须装——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。

Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?

A: eval-harness 来自 community,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。

Q3: 装了这个 Skill 后,会拖慢 Agent 响应吗?

A: 会的——Skill 通常会增加 prompt 长度,导致响应变慢、token 消耗增加。但质量提升明显。建议:1) 只装项目必需的 Skill;2) 用 Skill 启动/加载/卸载机制按需加载;3) 定期清理不用的 Skill。

Q4: 怎么验证 Skill 装对了?

A: 在 Agent 中输入”列出已加载的 Skill”或类似命令。如果 Skill 出现在列表里,说明装对了。然后用 Skill 跑一个相关任务,看输出是否符合 Skill 规范。

Q5: 这个 Skill 有许可证吗?能商用吗?

A: 取决于 eval-harness 的许可证。常见许可证包括 MIT(完全自由)、Apache-2.0(自由但有专利条款)、源可用(可看不能用)、GPL(强开源)。商用前请查仓库 LICENSE 文件。

进阶学习建议

如果想进一步用好 eval-harness,建议按以下路径学习:

第 1 周:熟练使用

• 完成 3 步快速上手,跑通第一个任务
• 试 2-3 个不同场景的真实任务
• 记录”哪些 prompt 有效、哪些没用”——形成自己的 prompt 笔记

第 2 周:理解机制

• 阅读 Skill 的官方文档(README、SKILL.md)
• 了解 Skill 的”触发关键词”和”输出格式”
• 学习”如何用更具体的描述触发 Skill”

第 3-4 周:组合使用

• 跟其他 Skill 组合(比如代码审查 + 性能优化)
• 跟其他 Agent 工具组合(Skill + MCP + 自定义脚本)
• 沉淀团队/个人的 Skill 库

长期:贡献社区

• 把自定义的 Skill 开源到 GitHub
• 提 PR 改进现有 Skill
• 写使用心得分享到 CSDN/掘金/知乎

推荐资源:

• 官方文档:https://github.com/affaan-m/everything-claude-code
• 官方仓库 README 里的 Examples
• 社区最佳实践:Anthropic 官方博客 https://www.anthropic.com/blog
• 国内社区:CSDN AI 板块、掘金 AI 板块

避免的坑:

• 不要装太多 Skill(超过 10 个会拖慢 Agent)
• 不要把 Skill 装在不兼容的 Agent 上
• 不要直接复制 Skill 默认 prompt——要根据项目调整
• 定期 review Skill 库的实用性,清理不用的

参考链接

• Skill 仓库:https://github.com/affaan-m/everything-claude-code
• Anthropic 评估指南:https://docs.anthropic.com/en/docs/build-with-claude/evaluation
• OpenAI Evals 框架:https://github.com/openai/evals
• 提示工程评估最佳实践:https://www.promptingguide.ai/
• LangSmith 评估工具:https://docs.smith.langchain.com/evaluation

我的个人推荐(测试编辑 Mnet)

最常用的 1 个核心用法:每天打开 Agent 第一时间加载这个 Skill,既不消耗太多 token 也能规范输出。

最容易踩的坑:别把 Skill 提示词当”开箱即用”的最终答案——它只是给你一个”标准框架”,具体项目还得你自己调整。

适合人群:做过 3+ 个实际项目的开发者,而不是”看一遍文档就完事”的小白。

3 个月使用心得:刚开始用时觉得”规范是约束”,用了 3 个月后才发现”规范是省时间”——避免每次重新决策同样的细节。

推荐配合的工具:Claude Code / Cursor / OpenCode 任选一个主流 Agent 即可,不要在工具选择上纠结太久。

长期价值:这类 Skill 的核心价值不是”立竿见影的输出”,而是”持续一致的质量”——长期用下来,你的项目质量会稳定在专业水平。

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。