メインコンテンツへスキップ
Dev Tools 15分で読める

claude plugin eval 完全ガイド｜自作スキルの「効果ゼロ」を数値で見抜く

#Claude Code#plugin eval#スキル#Anthropic#開発ツール#AIエージェント#開発効率

「スキルを書いたのに、Claudeが全然使ってくれない。なんで？」

Qiitaユーザーのnaoki_ishimura氏が2026年9月12日に書いたこの一文は、多くのClaude Codeユーザーに刺さった。記事のタイトルは「自作スキルは本当に効いているのか、数値で確かめる」。氏がclaude plugin evalで測定したΔスコアはほぼ0だった。スキルがなくても結果は同じ。つまり自作スキルは「飾り」だったという発見だ。

同日、別のQiitaユーザーmoha0918_氏も同様の体験を報告した。「プラグインなし状態でも同じスコアが出た。スキル名の命名が自然言語とかけ離れていたのが原因だった」。

これほど痛烈なフィードバックを、感覚ではなくデータで示せるのが、Claude Code v2.1.269（2026年9月11日リリース）で追加されたclaude plugin evalだ。

この記事はこんな人におすすめ
  • Claude Codeで自作スキル・プラグインを運用している開発者
  • スキルが本当に機能しているか不安なエンジニア
  • プラグインの品質をCI/CDに組み込みたいチームリード
  • Agent Pluginsエコシステムを活用したい方

claude plugin evalとは何か

claude plugin evalは、Claude Codeのスキル（プラグイン）が実際に機能しているかを再現可能な数値で検証するコマンドだ。

v2.1.269以前、開発者はスキルの効果を「なんとなく良さそう」という感覚で判断するしかなかった。リリースノートはスキルが「動く」かどうかを教えてくれても、「効いているか」は教えてくれない。この空白を埋めるのがplugin evalの設計思想だ。

仕組みはシンプルだ。各テストケースをプラグインあり（WITH）で3回、プラグインなし（WOUT）で3回実行する。合計6回の実行結果からそれぞれの平均スコアを算出し、その差分をΔ（デルタ）として出力する。

WITHスコア平均  - WOUTスコア平均 = Δ

このΔが「プラグインが実際に貢献している量」だ。スコア単体ではなくΔだけがプラグインの価値を証明する。

eval suiteの構造

テストスイートはプラグインフォルダ内のevals/ディレクトリに格納される。各ケースは独立したサブディレクトリを持つ。

my-skill/
├── SKILL.md
└── evals/
    ├── case-commit-msg/
    │   ├── prompt.md        ← ユーザー入力を模したプロンプト
    │   └── graders/
    │       ├── tool_used.yaml
    │       └── regex.yaml
    └── case-no-trigger/
        ├── prompt.md
        └── graders/
            └── regex.yaml

prompt.mdには実際のユーザーがタイプするような自然な表現を使う。「コミットメッセージを書いて」は良い例だ。「commit-messageスキルを使ってコミットメッセージを書いて」は悪い例だ。ユーザーはスキル名を知らない。

6種類のグレーダー — 無料4種と有料2種

グレーダーはテストケースの合否を判定するルールだ。コストの観点から2グループに分かれる。

無料の4種（トランスクリプト・ファイル検査）

regex: Claudeの返答に特定のパターンが含まれるかを正規表現で検査する。最も手軽で、フォーマット検証に向いている。

# graders/regex.yaml
type: regex
pattern: "^feat\\(.+\\):"   # Conventional Commits形式を検査
target: response

tool_used: 特定のツール（スキル）が呼び出されたかを確認する。「このプロンプトでスキルが発火するか」の検証に不可欠だ。

# graders/tool_used.yaml
type: tool_used
tool: commit-message-skill

tool_order: 複数ツールの呼び出し順序を検証する。依存関係のある処理フローの検証に使う。

file_exists: 特定のファイルが生成・変更されたかを確認する。コード生成スキルなどに有効だ。

有料の2種（ジャッジモデル呼び出し）

llm: Claudeがジャッジとして返答の質を評価する。自由記述形式の出力（コードレビュー、要約など）の品質検証に使う。追加APIコストが発生する。

# graders/llm.yaml
type: llm
criteria: "コミットメッセージは変更の意図を明確に説明しているか"

baseline: 参照回答と比較して品質を評価する。最もコストが高いが、正確な品質基準がある場合に有効だ。

実践: initからレポート解読まで

Step 1: テストスイートを自動生成する

プラグインフォルダ内で以下を実行する。

cd my-skill/
claude plugin eval init

Claudeが対話形式でスキルの目的を質問し、テストケースとグレーダーの候補を提案してくれる。提案を確認・調整してからevals/ディレクトリに書き出す。実行前にコスト見積もりが表示されるので、--max-cost-usd 2.00のような上限を設定しておくと安心だ。

Step 2: 評価を実行する

# スキルフォルダのルートで実行
claude plugin eval .

# コスト上限を設定する場合
claude plugin eval . --max-cost-usd 5.00

各ケースが6回（WITH×3、WOUT×3）実行される。完了後にHTMLレポートとJSONが生成される。

Step 3: レポートを読む

出力例は次のようになる。

Case: case-commit-msg
  WITH:  0.83 (avg of 3 runs)
  WOUT:  0.81 (avg of 3 runs)
  Δ:     +0.02   ← ほぼ効果なし

Case: case-no-trigger
  WITH:  0.30
  WOUT:  0.89
  Δ:     -0.59   ← プラグインが邪魔している

Δが0に近い場合の診断と対処

「Δ≈0かつtool_usedグレーダーが失敗」は最も多い失敗パターンだ。スキルが一度も呼び出されていないことを意味する。

原因1: スキルの説明文がユーザーの言葉と乖離している

SKILL.mdのdescription:に書いた表現が技術的すぎると、Claudeはそのスキルを選ばない。「commit-message-generatorを使ってコミットメッセージを作成する」ではなく「このdiffを見てコミットメッセージを書いてほしい」のような自然な言い方で発火するかをprompt.mdで試す。

原因2: trigger_phraseが自然な入力と一致していない

スキルのトリガー設定がある場合、実際のユーザー入力と一致するよう調整する。kai_kou氏はQiitaの記事で「プロンプトをユーザー視点で書き直したらΔが0.4改善した」と報告している。

原因3: 「WITHもWOUTも高スコア」パターン

ベースモデルが十分賢くて、スキルなしでも同じ品質の出力を出せている場合だ。この場合、スキルの存在意義を問い直す必要がある。一貫性の強制（特定のフォーマット指定など）に絞ってスキルを再設計すると効果が出やすい。

CI/CDゲートとして使う — 光と影

光: スキルのデグレを自動で検出できる

claude plugin evalはCI-friendlyな終了コードを返す。

  • 終了コード0: 全ケースパス
  • 終了コード1: Δ閾値を下回るケースあり
  • 終了コード2: --max-cost-usdの上限に到達

GitHub Actionsに組み込む場合は次のようになる。

- name: Verify plugin quality
  run: |
    claude plugin eval . --delta-threshold 0.1 --max-cost-usd 3.00

Claudeのモデルアップデートがあるたびに、以前は機能していたスキルが意図通り動かなくなることがある。suwa_nobu氏はQiitaで「47本のスキルを運用して学んだこと」として「モデル更新でΔが突然0に近づいたスキルが3本あった。evalがなければ気づかなかった」と報告している。

影: コストと実行時間のトレードオフ

1ケースあたり6回実行するため、テストスイートが大きくなるとコストが無視できなくなる。MarkTechPostの分析記事によると、10ケース×llmグレーダー使用時のコストは1回あたり約$0.5〜$1.5程度（モデルやプロンプト長による）。毎PRで実行するには割高な場合もある。

現実的な運用方針:

  • プルリクエスト時: 無料グレーダー（regex、tool_used）のみで高速チェック
  • 週次または手動: llmグレーダーを含む完全評価
  • モデルアップデート後: 必ず全スイートを実行
tool_usedグレーダーを必ず入れること

どのスキルにも最低1つのtool_usedグレーダーを含めることを推奨する。「スキルが呼ばれているか」は最も基本的な品質指標であり、これが通らないならスコアがどれだけ高くてもΔは意味をなさない。

Claude Codeのスキルとプラグインについてさらに詳しく知りたい方は、関連記事もあわせて読んでほしい。

詳しく見る

関連記事

本記事の情報はClaude Code v2.1.269（2026年9月11日リリース）時点のものだ。コマンドの仕様、グレーダーの種類、コスト体系は今後のアップデートで変更される可能性がある。最新情報は公式ドキュメントを参照すること。

Share