skill-creatorのevalでスキルの効果を測る — benchmark.jsonの読み方まで

スキルを書いて一度試し、動いたように見えたところで手を止めてしまう。これが最も多い落とし穴です。skill-creatorプラグインのeval機能は、同じプロンプトを「スキルあり」と「スキルなし」で別々のセッションに走らせ、採点して数字で比べます。Claude Codeの会話の中で回せる、1つのスキル向けの評価ループです。

この記事では、導入からevals/evals.jsonの書き方、出力されるgrading.jsonとbenchmark.jsonの読み方、結果が割れたときの直し方までを順に扱います。

skill-creatorのevalとは何か

skill-creatorは、Anthropicが公式マーケットプレイスで配布しているプラグインです。Claude Code内で「スキルあり/なしの比較ループ」を自動化するプラグインです。

評価の考え方は、Claude Code docsの「Evaluate and iterate on a skill」に書かれています。スキルが発火する様子を見ただけでは、Claudeがスキルを見つけたことしか分かりません。意図どおりに動いたかは別に測ります。測る対象は2つです。

• 期待するプロンプトでClaudeがスキルを呼ぶか
• 呼んだときの出力が期待に沿うか

比較は、現実的なプロンプトを数個集め、それぞれを新しいセッションでスキルあり・なしの2通りに走らせる形です。新しいセッションにするのは、スキルを書いたときの文脈が残っていると、指示文の不足が隠れてしまうためです。

プラグインが備える機能は次のとおりです。

skill-creatorプラグインを導入する

インストールは公式マーケットプレイスから行います。

/plugin install skill-creator@claude-plugins-official

失敗したら、Claude Codeが返すメッセージで切り分けます。

• Marketplace "claude-plugins-official" not foundが出たときは、マーケットプレイスが未登録です。/plugin marketplace add anthropics/claude-plugins-officialで追加してから、もう一度インストールします
• マーケットプレイスにプラグインが見つからないというメッセージのときは、プラグイン名の綴りを確認します

インストール結果にRun /reload-plugins to activate.と出た場合、Claude Codeが続けてその再読み込みを実行します。再読み込み時に「次のメッセージで会話を読み直すことになる」という警告が出たら、/reload-plugins --forceで現在のセッションにスキルを反映できます。再読み込みの仕組みは/reload-pluginsの解説にあります。

最初の評価ループを回す

導入が済んだら、評価したいスキルの名前を挙げて頼みます。docsの例は次の文です。

evaluate my summarize-changes skill with skill-creator

ここから先は、プラグインがテストケースの作成を対話で案内します。流れは次の5段階です。

1. プロンプトと期待する出力を決め、evals/evals.jsonに書く
2. テストケースごとに、スキルありとスキルなしの実行を同じターンで起動する
3. 実行を待つあいだにアサーションを起草する
4. 採点し、benchmark.jsonに集計してレビュー画面を開く
5. 所感をもとにスキルを直し、iteration-2として全ケースをもう一度回す

3段目の「実行を待つあいだに書く」は、プラグインが持つSKILL.mdの手順にある動きです。アサーションは最初から完璧に書けないため、1回目の出力を見てから足す前提になっています。

evals.jsonの書き方

手で書くのはこのファイルだけです。形式はagentskills.ioの評価ガイドに沿っており、次の形になります。以下はガイドの例に沿った書き方の例で、summarize-changes向けに内容を置き換えています。

{
  "skill_name": "summarize-changes",
  "evals": [
    {
      "id": 1,
      "prompt": "直近のコミット5件を、レビュー担当者向けに変更点の要約にしてほしい",
      "expected_output": "変更の目的ごとにまとまった箇条書きの要約。ファイル名の羅列ではない。",
      "files": []
    },
    {
      "id": 2,
      "prompt": "この差分、リファクタと機能追加が混ざってるんだけど分けて説明できる?",
      "expected_output": "リファクタと機能追加を分けた説明。",
      "files": ["evals/files/mixed.diff"]
    }
  ]
}

プロンプトの書き方の要点は4つです。

• 最初は2〜3ケースから始める。結果を見る前に作り込まない
• 言い回しを変える。「hey can you clean up this csv」のような砕けた文と、パスや列名まで指定した精密な文を混ぜる
• 境界条件を最低1つ入れる。壊れた入力や、指示が曖昧になりやすい依頼など
• 現実の文脈を入れる。「データを処理して」のような曖昧な依頼では何も測れない

アサーションは、1回目の出力を見てから足します。検証できる形で書くのがコツです。

• 良い例: 「出力ファイルが有効なJSONである」「レポートに3件以上の提案が含まれる」
• 弱い例: 「出力が良い」(曖昧すぎて採点できない)、特定の一文と完全一致を求めるもの(言い回しが違うだけで落ちる)

文体や見た目のような「らしさ」は、アサーションに分解せず、後述の人間によるレビューに任せます。

実行後にできるファイル

プラグインのSKILL.mdでは、結果を<skill-name>-workspace/にスキルディレクトリの隣として置き、反復ごとにiteration-1/、iteration-2/を切ります。その中に、テストケースごとのディレクトリができます。agentskills.ioの評価ガイドが示す構成は次のとおりです。

summarize-changes/
├── SKILL.md
└── evals/
    └── evals.json
summarize-changes-workspace/
└── iteration-1/
    ├── eval-review-summary/
    │   ├── with_skill/
    │   │   ├── outputs/
    │   │   ├── timing.json
    │   │   └── grading.json
    │   └── without_skill/
    │       ├── outputs/
    │       ├── timing.json
    │       └── grading.json
    └── benchmark.json

timing.jsonにはトークン数と所要時間が入ります。サブエージェントのタスク完了通知に載るtotal_tokensとduration_msは他の場所に保存されないため、ガイドは完了直後に控えるよう勧めています。

grading.jsonとbenchmark.jsonを読む

grading.jsonはアサーションごとの根拠

採点は各アサーションを出力と照らし、PASSまたはFAILと根拠を書く作業です。プラグインのSKILL.mdは、フィールド名をtext・passed・evidenceに固定しています。レビュー画面がこの名前に依存するためです。ガイドの形は次のとおりです(値は例示)。

{
  "assertion_results": [
    {
      "text": "出力が変更の目的ごとにまとまっている",
      "passed": true,
      "evidence": "目的別に3つの見出しが立っている"
    },
    {
      "text": "ファイル名の羅列で終わっていない",
      "passed": false,
      "evidence": "後半が変更ファイル名の列挙のみ"
    }
  ],
  "summary": { "passed": 1, "failed": 1, "total": 2, "pass_rate": 0.5 }
}

採点の原則は2つあります。PASSには具体的な根拠を要求すること。「要約がある」というアサーションに、見出しだけあって中身が薄い出力を通してはいけません。もう1つは、アサーション自体を見直すこと。常に通る簡単すぎるもの、常に落ちる難しすぎるもの、出力だけでは確かめられないものは、次の反復で直します。

機械的に確かめられる項目は、LLMの判断に任せず検証スクリプトで書く方が確実です。プラグインのSKILL.mdも、プログラムで確認できる項目にはスクリプトを書いて実行するよう求めています。

benchmark.jsonはスキルの費用対効果

集計はbenchmark.jsonにまとまります。プラグインのSKILL.mdでは、python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>で生成する手順です。agentskills.ioのガイドが示す形は次のとおりです(値は公式ガイドの例示)。

{
  "run_summary": {
    "with_skill":    { "pass_rate": { "mean": 0.83, "stddev": 0.06 } },
    "without_skill": { "pass_rate": { "mean": 0.33, "stddev": 0.10 } },
    "delta": { "pass_rate": 0.50, "time_seconds": 13.0, "tokens": 1700 }
  }
}

(実際のファイルにはtime_secondsとtokensの平均・標準偏差も入ります。上はpass_rateだけに絞った抜粋です)

見るのはdeltaです。スキルが何を買い、何を払っているかが出ます。ガイドの例では、13秒の追加で合格率が50ポイント上がるなら見合う可能性が高く、トークンが倍になって2ポイントしか上がらないなら見合わない可能性がある、とされています。

stddevは、1つのケースを複数回走らせて初めて意味を持ちます。ケースが2〜3件で1回ずつの初期は、合格数そのものとdeltaを見れば足ります。

集計のあとは、平均値が隠す偏りを探します。

• スキルあり・なしの両方で常に通るアサーションは、スキルの価値を測っていません。外すか置き換えます
• 両方で常に落ちるアサーションは、アサーションが壊れているか、ケースが難しすぎます
• スキルありだけ通るアサーションが、スキルが効いている箇所です。どの指示やスクリプトが効いたかを掘ります
• 実行のたびに結果が揺れるなら、指示が曖昧です。例や具体的な指針を足します
• 1つだけ所要時間が3倍かかるケースは、実行の記録を読んで詰まりを探します

スキルなしのベースラインを作る

比較の土台は、新規スキルなら「スキルなし」です。既存スキルの改善では、編集前の版を土台にします。ガイドとプラグインの手順は、編集前にcp -r <skill-path> <workspace>/skill-snapshot/でスナップショットを取り、その版を土台の実行に指すよう求めています。出力はwithout_skill/ではなくold_skill/outputs/に保存します。

スキルなしを手で再現したいときの手段は、スキルの種類で分かれます。個人スキルやプロジェクトスキルなら、skillOverridesに"off"を書けば、Claudeにも/メニューにも出なくなります。

{
  "skillOverrides": {
    "summarize-changes": "off"
  }
}

一方で、プラグインが配るスキルにはskillOverridesが効きません。docsは、プラグインのスキルは/pluginで管理すると明記しています。skill-creatorの自動ループは、この手作業の切り替えを肩代わりするものです。skillOverridesの全体像はskillOverridesとmodelOverridesの解説にあります。

所感を反映して次の反復へ

数字と採点だけでは、アサーションに書かなかった問題は拾えません。そのため、レビュー画面で人間が各出力を見て所感を書きます。プラグインのSKILL.mdでは、ブラウザーを開けない環境向けに--static <output_path>で単体のHTMLを書き出せます。所感は「Submit All Reviews」でfeedback.jsonとしてダウンロードされ、ワークスペースにコピーすると次の反復が読みます。

所感は行動に移せる粒度で書きます。「グラフに軸ラベルがない」は使えますが、「見た目が悪い」は使えません。空欄は問題なしの意味です。

直すときの指針もガイドにあります。

• 個別のテストケースに合わせず、根本の問題を広く直す
• スキルを短く保つ。規則を足しても合格率が頭打ちなら、指示を減らして結果が保たれるかを試す
• 「常にXせよ」ではなく、理由を添えて書く
• どのケースでもサブエージェントが同じ補助スクリプトを書いていたら、そのスクリプトをscripts/に同梱する

終わりは、満足したとき、所感がずっと空欄になったとき、反復しても改善が見えなくなったときのいずれかです。

descriptionの発火率も同じ仕組みで測る

出力の質は、スキルが呼ばれてはじめて意味を持ちます。skill-creatorは、発火すべきプロンプトと発火すべきでないプロンプトを作り、descriptionを調整する機能も持ちます。SKILL.mdの手順では、run_loopが評価セットを訓練用60%・検証用40%に分け、各クエリを3回走らせて発火率を出します。その結果から修正案を作り、最大5回反復します。最良のdescriptionは、過学習を避けるため検証側の得点で選ばれます。

前提として、Claudeが単純な1手のタスクではスキルを引かない点があります。「このファイルを読んで」のような依頼は、descriptionが完全に合っていても発火しないことがあります。発火の評価用プロンプトは、スキルの助けが要る程度に手間のある依頼にします。

この機能は、スキル本体を仕上げてから回す順序で案内されています。本文の評価より先に、descriptionだけを磨く使い方は勧められていません。

claude plugin evalとの使い分け

似た名前のclaude plugin evalは別の仕組みです。docsは、2つの形式は互換性がないと明記しています。

プラグインとして配るスキルなら、開発中はskill-creatorで反復し、公開前後の継続検証はclaude plugin evalに分けるのが素直な流れです。後者の書き方とCI組み込みはclaude plugin evalの使い方で扱っています。スキル自体の書き方はClaude Code Skills完全ガイドが入口です。

評価を回すときのつまずき

• 1回目のpass rateが100%になる: ケースがやさしすぎるか、アサーションが緩いかです。スキルなし側も高得点なら、その課題はスキルの出番ではありません。Anthropicの発表も、モデルが進むとスキルなしでも通る「能力補強型」のスキルは不要になりうると述べ、evalsがそれを教えるとしています
• 同じケースが通ったり落ちたりする: 1回の実行で判断せず、同じケースを複数回走らせてstddevを見ます
• スキルを書いた会話でそのまま試す: 作成時の文脈が指示の不足を隠します。評価は必ず新しいセッションで走らせます
• アサーションを増やしすぎる: 質の高低を全部アサーションにしようとすると、脆くなります。文体のような感覚的な質は人のレビューに回します

言い切れること・まだ分からないこと

skill-creatorのevalが最も効くのは、モデルの更新や自分の編集のあとに「前より良くなったか、悪くなったか」を数字で確かめる場面です。感覚で「効いている気がする」と言い続けるより、ケース2〜3件でもdeltaが出る方が、直す場所を決めやすくなります。

分からないのは、ケース数を増やしたときの安定性です。示されている集計値は例示にとどまり、何ケースあればstddevが安定するかの基準は示されていません。ケースは少なく始めて、失敗が偏る場所に足していくのがガイドの筋です。