它到底是什么

claude plugin eval 属于 claude plugin 子命令组（别名 claude plugins）。官方 CLI 参考页的命令表只列出 claude plugin，子命令指向 plugin reference，该表没有单独列出 eval。

官方文档 Test plugins with evals 的定义是：它用一组测试 case 跑你的 plugin 并打分。

• 每个 case 是一条贴近真实使用的 prompt，加一个或多个 grader。
• grader 是对 Claude 产出的 pass/fail 检查，例如对回复做 regex 匹配、检查是否调用了某个 tool，或用第二个模型按 rubric 评判回复。
• 除了打分，它还会跑一次不加载该 plugin 的对照（baseline），用来衡量 plugin 本身的贡献。

claude plugin eval init 会向你询问 plugin 的情况，提议 case 和 grader，试跑后写出文件。官方文档说明，你也可以在已打开的会话里让 Claude 完成同样的事。

它的 case 格式与 skill-creator plugin 使用的 evals/evals.json 是两套东西。若只想检查 plugin 文件的语法和 schema，应使用 claude plugin validate，而不是 eval。

版本要求：MarkTechPost 与 dev.to 两篇文章都写明需要 Claude Code v2.1.269 或更高。我没能在官方页面的可读部分核实这一点，请以 claude --version 和 claude plugin eval --help 为准。

用法 / 语法

# 生成 eval 套件
claude plugin eval init
claude plugin eval init --bare commit-message   # 生成一个空白 case 模板

# 运行套件(plugin 路径可以是 .)
claude plugin eval .
claude plugin eval ./receipt-tools --runs 5 --case '58mm-*'

Flag 列表

官方 plugins-reference 列出了 --eval-dir、--filter <pattern> 和 --json（不带 path 参数）。其余 flag 只出现在下方来源列出的第三方文章中。其中 matthewswong 对部分 flag 有说明，其他文章大多只给出示例。

评分模型与 grader

dev.to 与 matthewswong 的说明：

• 默认每个 case 带 plugin 跑 3 次、不带 plugin 跑 3 次。
• 每个 case 报告 WITH、W/OUT 和 Δ（WITH 减去 W/OUT）。
• 对 Skill 的 tool_used grader 会同时从两个 arm 的计分总额里排除，避免用"没有 plugin 就不可能通过"的检查抬高 Δ。

6 种 grader（MarkTechPost、matthewswong 一致）：

目录布局（dev.to、matthewswong 一致）：

evals/
  <case-name>/
    prompt.md          # 文件正文就是 prompt
    graders/
      <name>.md        # frontmatter 声明 type,正文写判据

退出码 / 输出格式

我没能读到官方页面的退出码章节。下表来自 dev.to 和 matthewswong，两者在 0 和 1 上一致，对 2 的细节说法略有出入，请当作待核实信息。

MarkTechPost 补充了两点：没有终端时，未加 --trust-plugin 的不受信任 checkout 会被拒绝并以 exit 1 退出；报告方面的问题不会改变退出码。

输出：终端分数表、HTML 报告，以及 --json 指定的 JSON 文件。JSON 内部字段结构我没有找到可靠文档，这里不展开。

Shell 集成 / 自动化

MarkTechPost 和 dev.to 给出的 CI 调用：

claude plugin eval . \
  --trust-plugin \
  --json results.json \
  --threshold 0.8 \
  --model claude-sonnet-5 \
  --judge-model claude-haiku-4-5 \
  --no-publish \
  --max-cost-usd 20

由于阈值和花费上限都会反映在退出码里，它可以直接作为 CI job 的 gate。

运行约束 / 限制

常见坑

以下均为第三方文章的观点，不是官方文档条文：

1. prompt 里点名 skill 会让激活测试失效：prompt 应该模拟用户真实措辞（matthewswong）。
2. 缺少"不应触发"的 case：没有这类 case 会奖励过宽的匹配（matthewswong）。
3. 只看 WITH 分数不够：必须结合无 plugin 基线的 W/OUT 和 Δ 才能判断 plugin 是否有贡献（dev.to、matthewswong）。
4. 分数带噪声：评分由模型完成，单次运行只是样本；正的平均 Δ 也可能掩盖个别很差的 case（explainx）。
5. 限流错误会使结果失效：dev.to 建议限流恢复后重跑再采信分数。
6. 纯 llm 套件昂贵：建议用免费的机械断言（regex、tool_used 等）搭配少量 judge grader（matthewswong、dev.to）。

来源

• Test plugins with evals - Claude Code Docs
• Plugins reference - Claude Code Docs
• CLI reference - Claude Code Docs
• Anthropic Adds Plugin Evals to Claude Code - MarkTechPost
• Claude Code plugin eval: gate skills on delta before you merge - DEV Community
• Claude Code Plugin Eval: Catch a Skill That Never Activates - matthewswong.com
• claude plugin eval: Score Your Claude Code Plugin - explainx.ai