プラグインの評価（evals）

claude plugin eval は、プラグインをテストケースの組（スイート）に対して動かして、結果を採点するシェルコマンドです。各ケースは、現実的なプロンプトと1つ以上のグレーダーでできています。グレーダーは、Claude が出したものへの合否の確認で、返答への正規表現、特定のツールが呼ばれたか、別のモデルが返答を判定する採点基準などです。作り方はプラグインを作って配る、コマンドの引数の一覧はプラグインのリファレンスにあります。

このページで分かること#

• eval でできること（プラグインが狙いの結果を出させる確かさの測定、変更やモデル更新での劣化の検出、プラグインなしとの差）
• 最初のスイートを作って動かし、結果を読む手順
• ケース・グレーダー・モック・フィクスチャの書き方と、全フィールドの表
• コマンドのオプション、CI での使い方、終了コード
• 結果（HTML レポートと JSON）の読み方、実行が触れられる範囲、トラブル対処

スイートは claude plugin eval init に書かせることもできます。プラグインについて尋ね、ケースとグレーダーを提案し、試し、ファイルを書きます。開いているセッションから Claude に頼んで同じことをさせることもできます。1つのスキルをその場で磨く用途には、スキルの文書にある skill-creator プラグインが、evals/evals.json という別の形式で似た比較をします。2つのツールは、互いのケースのファイルを読みません（スキル）。ファイルの構文やスキーマのエラーを確かめたいだけなら、claude plugin validate を使います。

必要なもの#

• Claude Code v2.1.269 以降（claude --version で確認、claude update で更新）
• git が入っているなら Git 2.31 以降（git --version で確認）。古い git では、claude plugin eval はケースを動かす前に止まります。git が無ければ普通に動きます
• plugin.json か .claude-plugin/plugin.json のマニフェストを持つプラグインのディレクトリ、またはスキルのディレクトリのプラグイン
• 普段のセッションと同じ認証とモデルのプロバイダ。eval の実行・判定のグレーダー・claude plugin eval init は、自分の資格情報でモデルを呼ぶので、プランの使用量の上限か API の請求に数えられます。コマンドが出すコストは、それらの呼び出しの定価ベースの見積もりです（コストを抑える）。Amazon Bedrock・Google Cloud の Agent Platform・Microsoft Foundry で Claude Code を動かしているなら、普段のセッションと同じプロバイダーの変数を書き出したシェルからスイートを実行します。各実行は、そのシェルからそれを引き継ぐためです（prompt.md の env フィールドの説明のとおり）。

実行の仕組み#

スイートは、プラグイン内の evals/ というディレクトリにあります。各ケースは、プロンプトと1つ以上のグレーダーを持つ、自分のサブディレクトリです。プロンプトは、プラグインを使う人が打ちそうなもの（スキルの1つが扱うべき依頼など）です。

• 実行：ケースの1回の実行ごとに、Claude Code が、プラグインだけを読み込んだ、新しい隔離された非対話のセッションを始め、プロンプトを送り、Claude が終わるか、ケースのターンか時間の上限に達するまで作業させる。各グレーダーが、最終的な返答・トランスクリプト・Claude が作ったファイルを確かめて、合否を出す
• 採点：非決定的なエージェントの1回の実行では分かることが少ないので、各ケースは既定で3回動く。1回の実行の点数は、合格したグレーダーの割合（重みを付けていれば重み付き）で、ケースの点数は実行の平均。ケースが合格するのは、点数が --threshold（既定は 1.0）を満たすとき
• モデル呼び出しの量：スイートは、おおよそ、ケース数 × 実行回数のエージェント実行をプラグインありで、同じ数をプラグインなしの基準で行い、llm か baseline のグレーダー1つにつき、1回の実行ごとに短い判定の呼び出しを3回行う
• プラグインなしの基準：高い点数だけでは、プラグインが役立ったことは分かりません（プラグインなしでも Claude が同じようにできたかもしれないため）。そこで、ケースの実行を、プラグインを読み込まずに繰り返し、WITH と W/OUT の2つの点数を出す。その差の Δ が、プラグインの寄与。プラグインありでもなしでも 1.0 のケースは、プラグインが合格させたのではない。この2組の実行を、with アームと without アームと呼ぶ

最初のスイートを作る#

自分のプラグインに1つのケースを書いて、動かし、結果を読みます。プラグインのルート（plugin.json か .claude-plugin/plugin.json があるディレクトリ）で端末を開き、試したいスキルが1つと、それを引き起こすはずの、ユーザーが打ちそうな依頼を用意します。

1. ケースを作る：プラグインのルートで次を実行する。Claude Code がこのディレクトリをまだ信頼していなければ、先に Trust this plugin directory? と聞かれるので y と答える。そのあと対話の Claude Code のセッションが開く。Claude はプラグインを読み、良い結果とは何かを尋ね、プラグインが働くべきプロンプトと働くべきでないプロンプトを提案し、それぞれのグレーダーを設計し、試しに1回動かして確かめ、プロンプトごとに1つのケースのディレクトリを evals/ の下に（プロンプトにちなんだ名前で）書く。Claude がスイートの準備ができたと言ったら、/exit か Ctrl+D でセッションを終えてシェルに戻る。プラグインのルートで開いているセッションがすでにあれば、そこで Claude に claude plugin eval init を動かすよう頼んでもよく、同じ質問がその会話で行われる

   bashコピー

   claude plugin eval init
   

2. スイートを動かす：プラグインのルートで、evals/ のすべてのケースを動かす。ステップ1でこのディレクトリを信頼済みなので、すぐに始まる（ケースを手で書いたなら、最初に Trust this plugin directory? [y/N] と聞かれる）。各ケースはプラグインありで3回、なしで3回なので、1ケースで6回の実行。1回終わるごとに、その実行の点数と各グレーダーの判定の進捗の行が出る

   bashコピー

   claude plugin eval .
   

3. 要約を読む：終わると、要約の表と、レポートの出力先が出る。WITH はプラグインありのケースの点数、W/OUT はなしの点数で、Δ が正ならプラグインが点数を上げた。COST はモデル呼び出しの定価ベースの見積もり、NOTES は、with アームで最も重みの大きい失敗したグレーダーの説明か、実行のエラー

   textコピー

   CASE        WITH  W/OUT Δ      RUNS COST    NOTES
   first-case  1.00  0.33  +0.67  6    $0.41
   
   1 case(s) · mean Δ +0.67 · 74s · $0.41
   Report: /Users/you/my-plugin/evals/results/2026-09-10T17-02-11-482Z/report.html
   Published: https://claude.ai/... · keep local next time with --no-publish
   

4. レポートを開いて直す：Published: の URL（無ければ Report: のパス）を開くと、各実行の各グレーダーの判定と説明が見え、llm のグレーダーでは、判定の票と判定した抜粋も見える。Published: の行が出るのは、アカウントがレポートを公開できるときだけ。最初によくある発見は、Δ がゼロ近くで、ケースの tool_used: Skill のグレーダーが失敗していること。Claude が自然な言い回しでスキルを選んでいない、という意味なので、スキルの description を直して、claude plugin eval . をもう一度動かして比べる

1つのケースを安く繰り返すには、1つのアームを1回だけ動かします。1回は結果がぶれるので、変更を信じる前に、既定の3回で確かめます。1つのアームでは、表に WITH・W/OUT・Δ の代わりに SCORE と PASS% の列が出ます。<case-name> は evals/ の下のディレクトリ名に置き換えます。

claude plugin eval . --case <case-name> --runs 1 --ablation none

ケースを書く#

claude plugin eval init が書くケースは、開いて変えて足せる、ただのファイルです。ケースは、プラグインの eval ディレクトリの下の、prompt.md・case.yaml・その両方を含むディレクトリです。各ケースに少なくとも1つのグレーダーを、graders/<name>.md のファイルか case.yaml の graders: の項目として与えます（無いと、ケースは読み込みに失敗します）。ケースをまとめるには、ケースでないディレクトリの下に入れ子にします。ケースのディレクトリの中にあるもの（graders/ やフィクスチャのファイル）は、そのケースのものです。新しいスイートでは、claude plugin eval init が書く次の配置を使います。

my-plugin/
├── .claude-plugin/plugin.json
├── skills/...
└── evals/
    ├── first-case/
    │   ├── prompt.md          # frontmatter: case fields; body: the prompt
    │   ├── graders/
    │   │   ├── criteria.md    # frontmatter: type + options; body: rubric or pattern
    │   │   └── skill-fired.md
    │   └── case.yaml          # optional: only for context.* fields
    ├── ignores-unrelated-request/
    │   └── ...
    └── results/               # written by each run; add to .gitignore

ケースを手で書く#

Claude に claude plugin eval init でケースを書かせるのが推奨の道です。自分で書くなら、空のテンプレートから始めます。次のコマンドは、first-case という名前のケースを、仮の prompt.md と仮のグレーダー1つで書き、何も動かしません。

claude plugin eval init --bare first-case

evals/first-case/
├── prompt.md            # the prompt sent to Claude, plus run limits
└── graders/
    └── criteria.md      # one grader: how to score the result

prompt.md には、各実行で Claude が受け取るメッセージを書き、フロントマターに、実行の上限とケースが使えるツールを設定します。仮の本文を、スキルが扱うべき依頼に置き換えます。スキルの名前を出さず、ユーザーが打つ言い方で書きます。次はコミットメッセージの下書きをするスキルの例です。

---
max_turns: 10
allowed_tools: [Read, Glob, Grep, Skill]
---

Write me a commit message for this change: I renamed getUser to fetchUser and updated the three call sites.

各実行は空の作業ディレクトリで始まるので、作業に要るものはプロンプトに入れるか、先に作業場所を整えます。graders/ の各ファイルは、実行のあとに適用する1つの確認です。evals/first-case/graders/criteria.md の仮の内容を、判定モデル向けの採点基準（具体的な PASS と FAIL の条件）に置き換えます。

---
type: llm
---

PASS if <what a correct response contains>.
FAIL if <what a wrong or missing response looks like>.

次に、答えを出したのが自分のスキルかを確かめる2つ目のグレーダーを足します。evals/first-case/graders/skill-fired.md を作り、your-skill-name を skills/ の下のスキルのディレクトリ名（Claude がスキルを呼ぶときの名前）に置き換えます。

---
type: tool_used
tool: Skill
input_match: '"skill"\s*:\s*"(?:[\w-]+:)?your-skill-name"'
---

これは、plugin-name:skill-name の名前空間つきの形も含めて、実行中に Claude がそのスキルを少なくとも1回呼んだときに通ります。2つのファイルを保存したら、プラグインのルートから claude plugin eval . で動かします。

prompt.md の実行の上限とツール#

ケースの max_turns・timeout_seconds・model・tags と、使ってよい allowed_tools は、prompt.md のフロントマターに設定します（全フィールドと既定値は下の表）。Claude は本文を書いたままに受け取ります。本文の @path の言及はファイルの添付に展開されないので、Claude がファイルを読む必要があるなら、allowed_tools でそのためのツールを許します。

グレーダーを選んで重みを付ける#

グレーダーのフロントマターは type を設定し、任意で、実行の点数への寄与を大きくする weight と、基準との採点を制御する arm を設定します。6つの種類のうち、regex・tool_used・tool_order・file_exists はトランスクリプトとファイルから計算され無料で、llm と baseline は判定モデルを呼ぶので実行のコストが増えます。カスタムコードのグレーダーはありません。llm と baseline のグレーダーの判定モデルは、既定では Claude Code がバックグラウンドタスクに使うモデルです。--judge-model sonnet か完全なモデル ID で、自分で判定モデルを選べます。

llm グレーダーはモデルに判定を求めるので、答えが実行ごとに変わることがあり、読む文章が長いほど変わりやすくなります。スイートの点数を信頼できる程度に安定させる心がけは、次のとおりです。

プラグインなしの基準で採点する#

プラグインを試すとき、ケースは普通2つのアームで動きます。with アームはプラグインを読み込んだ実行で、without アームはプラグインなしの同じ数の実行です。要約とレポートは、2つの点数と、with から without を引いた Δ を出します。次の場合、ケースは with アームだけを動かすので、W/OUT の点数も Δ も付きません。

• --ablation none を渡す：すべてのケースが1つのアームだけを動かし、比較が要らないとき（グレーダーを直しているときなど）にコストが半分になる
• ケースがトランスクリプトを再開し、対象がパスである：. のようなパスの対象（入れたプラグインの名前でなく）では、context.history_file のケースは、記録された会話がすでにプラグインを反映している前提で、既定で1つのアームで動く。実行は、これらのケースを名指しする single-arm (no Δ) の通知を標準エラーへ出す。再開したターンをプラグインありとなしで比べるには、--ablation with-without を渡す
• ケースのためのプラグインが見つからない：対象がパスのとき、Claude Code がプラグインを見つけられなかったケースも、既定で1つのアームで動く（直し方は下のトラブル対処）

2つのアームの実行では、一部のグレーダーは scored: false で報告されます。「スキルが呼ばれた」のような確認は、プラグインなしでは通りえないので、数えると without アームがゼロに寄り、Δ が膨らみます。2つのアームを比べられるよう、Claude Code はそのようなグレーダーを両方のアームの点数から外し、with アームでは合否の目印としてだけ報告します。対象は次のとおりです。

• tool が Skill の、すべての tool_used グレーダー
• ケースの各モック化したサーバーが、自分のプラグインが宣言するものであるとき、target: mock_calls のすべての regex グレーダーと、focus: mock_calls のすべての llm グレーダー
• arm: with-only を付けたグレーダー

この除外を変える設定は3つあります。

• すべてのグレーダーが外される：ケースのグレーダーがすべて外される集合に入るときは、採点するものが残らないので、通常どおり採点される
• arm: both：グレーダーに arm: both を付けると、どちらのアームでも採点される。min: 0 と max: 0 の「スキルを呼んではいけない」確認に使う
• --ablation none：--ablation none では何も外されないので、同じスイートでも、2つのモードで絶対の点数が違うことがある

別の eval ディレクトリを使う#

evals/ が他のツールにすでに使われているなら、別のディレクトリにスイートを置けます。そのディレクトリを、全実行と全協力者が使うようにするには、プラグインの plugin.json に "experimental": { "evals": "quality/evals" } と書きます。1回の実行だけなら、claude plugin eval と claude plugin eval init の両方に --eval-dir quality/evals を渡します。両方設定すると、フラグのディレクトリが使われます。qa や quality/evals のように、普通のディレクトリ名からなる相対パスを渡します。絶対パスや .. を含むパスは受け付けられず、フラグの値ならエラー、マニフェストの値が使えないときは Warning: の行が出て、evals/ が使われます。ケース・結果・init の出力は、すべてそのディレクトリへ移ります。

フィクスチャとモックを用意する#

ケースには、プロンプト以上のもの（作業場所のファイルや git リポジトリ、続きにする前の会話、プラグインがつなぐ MCP サーバーの答え）が要ることがあります。それぞれをケースの横に用意するので、実行を繰り返せます。

作業場所や会話を用意する#

各実行は空の作業場所で始まります。ケースがプロンプト以上を要するときは、prompt.md の隣の case.yaml に context ブロックを足します。

• フィクスチャのファイルか git リポジトリ：ケースのディレクトリに Bash のスクリプトを書き、context.scaffold_script に名前を書く。スクリプトは、自分として、エージェントのサンドボックスの外で、--scaffold を渡したときだけ動くので、このフラグは、自分か組織が書いたスイートにだけ渡す
• 続きにする前の会話：トランスクリプトを .jsonl ファイルで保存し、context.history_file に名前を書くと、ケースのプロンプトが次のユーザーのターンになる。対象がパスのとき、このようなケースは既定で基準のアームなしで動く
• 実行中に Claude が読めるフィクスチャのディレクトリ：context.add_dirs に並べる

case.yaml には、schema_version: "1.1" と name も必要です（全フィールドは下の表）。次の case.yaml は、スクリプトから作業場所を用意し、Claude が resources/ ディレクトリのフィクスチャを読めるようにします。

schema_version: "1.1"
name: changelog-from-diff
tags: [smoke]
context:
  scaffold_script: fixture.sh
  add_dirs: [resources]

用意のスクリプトは、空の作業場所で、小さな固定の環境で始まります。シェルの PATH、実行の一時ホームディレクトリを指す HOME、TMPDIR、TERM=dumb のようないくつかの定数です。シェルのほかのものも、ケースの EVAL_* 変数も届きません。スクリプトが 0 以外で終了するか120秒より長く動くと、その実行は scaffold failed のエラーで 0 点になります。スクリプトはファイルと git の状態のためだけに使います（スクリプトが書いたプロジェクトの設定は読み込まれません）。

MCP サーバーをモックする#

スキルが MCP ツールを呼ぶプラグインを、後ろの本物のサービスなしで評価できます。ツールごとに1つの Markdown ファイルを、スイート全体なら evals/mocks/<server>/<tool>.md、1つのケースだけならそのケース自身の mocks/ ディレクトリに置きます。<server> は、プラグインの MCP 設定でのサーバーの名前です（MCP サーバーをつなぐ）。

実行は、頼まない限り、プラグインの本物の MCP サーバーを起動しません。Claude Code は、各サーバー自身の名前で代わりのサーバーを登録します。モックのファイルを持つツールはそこから答え、--allow-tools の許可なしで許され、モックのファイルが無いツールは Claude に使えません。モックがまったく無いサーバーは、ケースの mocked: の進捗の行に plugin_<plugin>_<server>[not started: no mock] と出ます。ファイルの本文が、ツールが Claude に返すものです。次のモックは、tracker という名前のサーバーの create_issue ツールの代わりになり、Claude が送る入力を確かめ、題をそのまま返します。evals/mocks/tracker/create_issue.md として保存します。

---
expect:
  title: string
  priority: [low, medium, high]
---

Created issue #4821: {{input.title}}

モックのファイルの本文とフロントマターは、次を受け付けます。

• 置換：{{input.<field>}} で呼び出しの入力のフィールドを、{{file:fixtures/{input.<field>}.json}} でモックの隣のフィクスチャファイルの中身を差し込む
• expect:：入力を守る。呼び出しが違反すると、実行は 0 点で中断し、理由を記録するので、プラグインがサーバーに頼んだ内容を、ケースで検証できる
• error: true：本文を、ツールのエラーとして返す
• type: agent：本文の指示に従って、判定モデルがサーバーとして答える

呼び出し自体を採点するには、グレーダーを target: mock_calls に向けます。プラグインの本物の MCP サーバーに対して動かすには、次のフラグを渡します。どちらの場合も、そのプロセスは、実行のサンドボックスの外で、自分として動き、ツールには --allow-tools の許可が要ります。

• --allow-real-servers：モックしていない各サーバーの本物のプロセスを起動し、モック化したツールはファイルから答え続ける
• --mocks off：mocks/ を丸ごと無視し、プラグインが宣言するすべてのサーバーを起動する

type: agent のモックは、--judge-model への呼び出しで答えるので、出力は実行ごとに変わり、判定モデルを変えると変わります。実行がエラーや中断なしで終わると、Claude Code は、エージェントのモックが返した各答えを、結果のディレクトリの mock-recordings/ に保存します。そこの ADOPT.txt を開くと、各記録と、それを作ったモックの隣の、コピー先の .replay/<server>/ ディレクトリが分かります。記録をそこへコピーすると、あとの実行は同じ呼び出しに、モデル呼び出しなしでその記録から答えます。CI の実行を繰り返せるよう、mocks/.replay/ を mocks/ の残りと一緒にコミットします。

eval を動かす#

スイートがあれば、claude plugin eval が動かします。対象の引数でどのプラグインとケースを動かすかを選び、読み取り専用のセット以外のケースに要るツールは --allow-tools で許し、実行回数・モデル・コスト・出力は他のオプションで制御します。

何を評価するか#

たいていは、プラグインのルートで claude plugin eval . を動かし、立っているプラグインを読み込んで、スイートのすべてのケースを動かします。1つのケースのファイルや、開発中でなく入れたプラグインを評価するには、別の対象を渡します。

ケース名で絞るには --case <glob>、指定したタグのどれかを持つケースだけにするには --tag <tag> を足します。対象は、--tag・--allow-tools・--json の前に置きます。最初の2つはリストを、--json は任意のパスを取るので、後ろに続く対象を自分の値として読みます。

ツールを許す#

実行は、許可を求めて止まることがありません。許可を与えていない、Bash・Write・Edit・WebFetch・WebSearch のような許可が要る組み込みツールは、セッションから外され、Claude は呼べません。実行が許すのは、ケースが allowed_tools に並べた読み取り専用のツール（Read・Glob・Grep・NotebookRead・Skill・AskUserQuestion・Agent・TodoWrite、タスクのツールの TaskCreate・TaskGet・TaskList・TaskUpdate・TaskStop）と、--allow-tools で許したものだけです。この許可は、その実行のすべてのケースに適用されます。

claude plugin eval . --allow-tools Write Edit "Bash(npm test *)"

ケースが許可していないツールを求めたとき、進捗の出力は not granted として一覧にします。モックした MCP サーバーのツールには許可が要りません。本物のプラグインの MCP サーバーのツールには、サーバーの起動（--allow-real-servers か --mocks off）と、--allow-tools "mcp__plugin_my-plugin_github__*" のような名前での許可の両方が要ります（プラグインの MCP ツールの名前は mcp__plugin_<plugin>_<server>__<tool>）。

Bash をどんな形でも許すと、すべてのコマンドが Claude Code の OS レベルのサンドボックスの下で動きます。書き込みは実行の作業場所に限られ、ホームディレクトリと Claude Code の設定は読めず、ネットワークは --allow-tools "WebFetch(domain:example.com)" で許したドメインに限られます。サンドボックスのバックエンドが無いマシンで Bash か PowerShell を許すと、Claude Code は、制限なしで動かさず、各実行を拒否し、ケースは実行エラーを示して、たいてい 0 点になります。ネイティブの Windows にはバックエンドが無いので、シェルを許すスイートは WSL2 で動かし、Linux では先に bubblewrap と socat を入れます（サンドボックス）。

コマンドのオプション#

実行回数・モデル・採点・コスト・ツールの許可・モック・出力のオプションは次のとおりです。完全な一覧は claude plugin eval --help にあり、--case・--tag・--eval-dir・--no-scaffold・--report・--verbose も含みます。

CI で動かす#

CI のジョブでは、結果を保存するため --json で動かし、終了コードでビルドを失敗させます。初回の信頼のプロンプトでジョブが待たないよう --trust-plugin を渡し、点数を時間をまたいで比べられるよう2つのモデルを固定し、レポートは手元だけに置き、上限としてコストの天井を設定します。

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

with から without を引いた差は報告されますが、終了コードを変えません。HTML のレポートの書き込みや公開の問題も変えません。ケースの点数が低い理由を見るには、--json なしで手元で動かして、実行ごとの進捗とグレーダーの行を出させます。CI のランナーには次も要ります。

• インストールと資格情報：Claude Code のインストールと、ANTHROPIC_API_KEY やクラウドプロバイダーの変数のような環境の資格情報
• 信頼：--trust-plugin なしで、チェックアウトのディレクトリを Claude Code がまだ信頼していないジョブには、初回の信頼のプロンプトが要り、尋ねられない実行は 1 で拒否される
• init：claude plugin eval init は質問のために端末が要る。CI では claude plugin eval init --bare <name> で空のテンプレートを得る

コストを予測できるようにするには、変更のたびの素早いスイートには判定を呼ばないグレーダーだけを置き、Δ が要らないところでは --ablation none を使い、partial: true のドキュメントと skippedPaidGraders を持つ実行は、グラフにする推移から外します。

結果を読む#

少なくとも1つのケースを動かすと、eval ディレクトリの中に results/<timestamp>/ ディレクトリが書かれ、aggregate-result.json と report.html が入ります。パスの対象ではプラグインの下、名前で指定したプラグインでは現在のディレクトリの下です。要約の表・JSON・レポートは、同じ結果のデータを描きます。

HTML レポート#

report.html は、外への要求をしない、1つの自己完結したファイルなので、CI のジョブに添付したり、ディスクから開いたりできます。上から読みます。

• 判定の行とタイル：スイート全体で、プラグインが役立ったかに答える。Suite score はケースごとの、プラグインありの点数の平均、Ablation Δ は基準の点数よりどれだけ上か下か、Cases はしきい値を満たしたケースの数、Perfect runs はすべてのグレーダーが通った、プラグインありの実行の割合
• 各ケースのカード：ケース自身の Δ とプラグインありの点数を、バーのしきい値に目盛りを付けて示す。Δ が負のケースは左端が赤になり、スクロールしても劣化が目立つ
• ケースの中：プラグインありの実行が先で、基準の実行が後。各実行が、グレーダーを合否のチップとともに並べる。失敗したグレーダーは、説明つきですでに展開されていて、llm のグレーダーは判定の票と見せた証拠も出すので、点数が低い理由が分かる。tool_used: Skill のように点数に数えられないグレーダーには、plugin-fired indicator のバッジが付く
• Prompt と Graders：実行の下にあり、ケースのプロンプトと各グレーダーの採点基準かパターンが出るので、スイートなしでレポートを読む人にも、何を頼み、何が良いとされたかが分かる

claude.ai のサブスクリプションでサインインしていて、アカウントでアーティファクトが使えるなら、Claude Code は、レポートを非公開のアーティファクトとして公開し、Published: <url> と出します（アーティファクト）。手元だけにするには --no-publish を渡します。API キーの認証のように Published: の行が出ないときは、手元のファイルがレポートです。Claude Code のセッションが始めた実行（Claude にスイートを動かすよう頼んだときなど）も、手元に残り、Report: の行が kept local と言います。公開するには、そのコマンドに --publish-report を足します。

JSON の結果#

aggregate-result.json と --json の出力は、CI のスクリプトが解析できる、schemaVersion: 1 の版つきドキュメントです。フィールド名は camelCase で、新しいフィールドは既存のものを名前変更せずに足されるので、スクリプトは知らないフィールドを無視するように書きます。合否判定のスクリプトが普通読むフィールドは次のとおりです（ドキュメントは、スイートの設定、すべてのグレーダーの定義、説明と証拠つきの実行ごとのグレーダーの結果も持ちます）。

実行が触れられる範囲#

claude plugin eval は、対象のプラグインのスキル・フック・エージェントを読み込み、その eval スイートを自分のマシンで自分として動かします。プラグインを指すことは claude --plugin-dir と同じ信頼の判断なので、信頼できるプラグインだけを評価します。ここで説明する隔離は、試験されるエージェントが届くものを制限するもので、プラグイン自身のコードへの境界ではありません。スイートが通っても、プラグインが安全かどうかは何も言えません。

プラグインのディレクトリを信頼する#

あるディレクトリに対して初めて claude plugin eval を動かすと、Claude Code は、そこから何かを読み込む前に Trust this plugin directory? と尋ねます（そこで対話の claude セッションの信頼のプロンプトをすでに承認していれば尋ねません）。git リポジトリの中では、yes と答えるとリポジトリ全体を信頼し、対話のセッションにも及びます。標準入力か標準出力が端末でないとき、または --json では、実行は尋ねられず 1 で拒否されます。自分のマシンで動かすプラグインにだけ、--trust-plugin で自分で信頼を宣言します。パスでなく名前で指定した対象（入れたプラグインかスキルのディレクトリのプラグイン）は、プロンプトを飛ばします。プラグインとスイートの一部は、その実行でフラグを渡したときだけ動きます。

• ケースの scaffold_script：--scaffold で
• 読み取り専用のセット以外のツール：--allow-tools で
• プラグインの本物の MCP サーバー：--allow-real-servers か --mocks off で

ケースの allowed_tools と、スキル自身の allowed-tools のフロントマターは、これらのどれも広げられません。自分が書いていないフックをプラグインが含むとき、または本物の MCP サーバーを起動するときは、コンテナや CI のランナーのような隔離環境で動かしたのでない限り、その点数は参考として扱います（フックとサーバーはエージェントのサンドボックスの外で動き、採点に使うファイルを変えうるため）。

実行の隔離#

各実行は、一時のホームディレクトリ・作業ディレクトリ・Claude Code の設定を得て、試験されるエージェントはそこで、自分のプラグインだけを読み込んだ claude -p の子プロセスとして動きます。ケースを書くときは、次の結果を踏まえます。

• 個人のものもプロジェクトのものも読み込まれない：ユーザー設定・フック・CLAUDE.md・MCP サーバー・他に入れたプラグイン・メモリ・スキルは無い。プロジェクトスコープの設定も、どこからも読まれない（作業場所の上でも中でも、用意のスクリプトが書いたものでも、.claude/・CLAUDE.md・.mcp.json は読み込まれず、add_dirs のディレクトリは読み取りのアクセスだけを与える）。シェルの環境の大半も渡らず、許可リストと EVAL_* 変数だけが実行に届く。ケースが頼るスキル・エージェント・フック・MCP サーバーは、試験するプラグインに入れて配る（用意のスクリプトが与えられるのはファイルと git の状態だけ）
• 管理ポリシーは実行を制限しうる：管理者がマシンに配った管理設定の制限は、実行の中でも適用されるので、管理されたマシンでの結果は、そのポリシーのぶん、管理されていないマシンと違うことがある
• Artifact ツールはオフ：アーティファクトを公開するスキルは、その手前までに作ったものでしか採点できない
• ケースの定義はエージェントから隠される：実行は eval ディレクトリを読めないので、Claude はケースのプロンプト・グレーダー・兄弟のケースを見られない
• シェルコマンド以外にはネットワークのサンドボックスが無い：許したシェルコマンドはサンドボックスのネットワークの規則の下で動く。WebFetch(domain:…) の許可はそのドメインに直接届き、プラグイン自身のフックや、起動した本物の MCP サーバーは、どのホストにも届く

eval スイートのリファレンス#

スイートに入りうるものはすべて、プラグインの eval ディレクトリ（別のものを設定しない限り evals/）の下にあります。prompt.md か case.yaml を持つディレクトリがケースとして数えられ、グレーダーが少なくとも1つ無いケースは、graders を名指しする invalid case.yaml のエラーで読み込みに失敗します。claude plugin eval が eval ディレクトリで読み書きするすべてのファイルは次のとおりです。

evals/
├── <case>/                        # one directory per case; nest under a non-case directory to group
│   ├── prompt.md                  # frontmatter: case and run fields; body: the prompt
│   ├── case.yaml                  # optional: context.* fields, or the whole case in one file
│   ├── graders/
│   │   └── <name>.md              # one grader per file; frontmatter: type and options; body: rubric
│   ├── mocks/                     # optional: mocks for this case only, same layout as below
│   └── <fixtures, scripts, transcripts referenced by case.yaml>
├── mocks/                         # optional: suite-wide MCP mocks
│   ├── <server>/
│   │   ├── <tool>.md              # one mocked tool; body: the tool result
│   │   ├── _server.md             # optional: one agent that answers several tools
│   │   ├── _tools.json            # optional: saved tools/list response for real descriptions and schemas
│   │   └── fixtures/              # files inserted with {{file:fixtures/...}}
│   └── .replay/<server>/          # adopted agent-mock recordings, answered without a model call
└── results/<timestamp>/           # written by each run; add results/ to .gitignore
    ├── aggregate-result.json
    ├── report.html
    └── mock-recordings/           # agent-mock answers from clean runs, with ADOPT.txt

prompt.md のフロントマター#

prompt.md のフロントマターは、次のフィールドを受け付けます。未知のキーはエラーです。

case.yaml のフィールド#

case.yaml は、prompt.md の代わり、または相棒で、ケースを YAML で記述し、他のファイルを指すフィールドを足します。schema_version: "1.1" と name が必要です。prompt.md のフィールドのうち、description・tags・plugins・runs・expected_outcome は最上位に、model・max_turns・timeout_seconds・allowed_tools・append_system_prompt・env は execution: の下に置きます。両方のファイルがあるときは、prompt.md のフロントマターが、対応する case.yaml のフィールドを上書きし、prompt.md の本文がプロンプトで、graders/*.md は case.yaml に並べたグレーダーのあとに足されます。次のフィールドは case.yaml にだけあります。

グレーダーのフロントマター#

graders/ の下のグレーダーのファイルは、どれも、種類ごとのオプションに加えて、次のキーをフロントマターに取ります。グレーダーの名前は、.md を除いたファイル名です。

regex のグレーダーは target を、llm のグレーダーは focus を取ります。どちらも同じ値を受け付けます。

グレーダーの種類と、通る条件は次のとおりです。

モックのファイル#

mocks/<server>/ の下の <tool>.md は、1つのツールに答えます。本文がツールの結果で、{{input.<field>}} と {{file:fixtures/<name>}} の置換を使えます。フロントマターは次のキーを受け付けます。

サーバーのディレクトリのツールのファイルの隣には、任意の2つのファイルを置けます。

• _server.md：複数のツールに答える、1つの type: agent のモック。ツールはフロントマターの tools: キーに並べる。同じツールの <tool>.md が優先する。expect: の守りは、ここでなく個々の <tool>.md に置く
• _tools.json：本物のサーバーから保存した tools/list の応答。モックしたツールが、許容的なプレースホルダーでなく、本物の説明と入力スキーマを持つ

ケース自身の mocks/ ディレクトリは同じ配置で、スイートのモックをファイルごとに上書きします。

トラブル対処#

作者がよく出会う問題を、見えるものごとに並べます。