AIエージェントのスキル評価｜3つのJSONと回帰テストの回し方

「スキルは呼ばれた。それなのに、出てきたものが思っていたものと違う」。AIエージェントに仕事を渡しはじめると、この段階でつまずきます。

descriptionを直せば、スキルは狙ったときに読まれるようになります。ところが、読まれたあとに何が出てくるかは、そこでは決まりません。呼ばれることと、正しく出せることは別の話だからです。

この記事は、スキルの精度を評価セットで測る手順と、直すたびに同じテストを回す回し方を扱います。使うのはevals.json・grading.json・benchmark.jsonという3つのJSONファイルです。

進行役は3人です。若葉さんが言葉の意味から聞き、高梨課長が自分の手で回す側から聞き、鈴木さん（本誌監修）が答えます。

01AIエージェントのスキル評価は、発火のテストと何が違うんですか？

若葉さん

若葉さんの発言

スキルが動いたかどうかは、画面を見れば分かりますよね。それ以上、何を測るんでしょうか。

鈴木さん

鈴木さんの発言

呼び鈴が鳴ったかと、出てきた料理がおいしかったかは、別の話だと思っています。前者だけ見て安心すると、後者を誰も見ないままになります。

Claude Codeの公式ドキュメントは、スキルを確かめる観点を2つに分けています。Claudeがそのスキルを読みにいくかどうかと、読んだ後に出す結果が期待どおりかどうかです（出典: Claude Code公式ドキュメント）。前者は発火の精度、後者がスキルの精度で、本記事は後者だけを扱います。

（出典: Claude Code公式ドキュメント「Evaluate and iterate on a skill」）

この線引きが要るのは、直す場所が違うからです。読みにいかないなら直すのは説明文で、読んだのに外れるなら直すのは中身です。どちらの症状なのかを決めずに手を入れると、直っていないほうの原因がそのまま残ります。

何をスキルにして、どう分割するかの設計判断はAIエージェントのスキル設計｜呼ばれる単位に分ける4つの型で扱っています。本記事は、設計したスキルが実際に動くかを確かめる段階です。

評価セットは、一度作って引き出しにしまう資料ではありません。書く・走らせる・記録する・集計する。この並びを一周として、スキルに手を入れるたびに同じ道をもう一度通ります。

一周が重いほど、二周目は回されなくなります。だから最初の一周は、小さく作るほうが続きます。ここから先は、その一周を順番に見ていきます。

02AIエージェントのスキル評価を始めるのに、特別な権限は要るんですか？

評価セットを作るのに、特別な権限は要りません。決めるのは、テストケースを書く場所と、実行結果を記録する場所の2つだけです。

本記事は、公式のskill-creatorプラグインを使う前提で進めます。導入はマーケットプレイス経由の1コマンドです（出典: Claude Code公式ドキュメント）。

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

マーケットプレイスが見つからない場合は/plugin marketplace add anthropics/claude-plugins-officialを先に実行します。導入後は「evaluate my <スキル名> skill with skill-creator」のように話しかけます。テストケース作成から採点までの流れが、そこから始まります（出典: Claude Code公式ドキュメント）。

入れる作業そのものは短く終わります。詰まるとしたら、足したあとに読み込み直していない、という一点です。

03評価セットを置く場所は、AIエージェントの運用でなぜ先に決めるんですか？

そろえるものは3点です。対象のスキルが、SKILL.mdとして既に書かれていること。出力を人が読んで合否を判定できる、具体的な依頼文が3つ前後は思い浮かぶこと。そして、評価セットと実行結果を置くワークスペースのディレクトリ名です。

3点目だけは、内容ではなく置き場の話です。結果を毎回ちがう場所へ吐くと、前の版と並べられなくなります。比較を前提にした仕組みなので、置き場の名前は最初に固定します。

検証環境は、Claude Code公式ドキュメントとAgent Skills公式ドキュメントの2つです（URLはprimary_sourcesに記載）。あわせてskill-creatorプラグイン本体のreferences・agentsファイルも、2026-08-03時点で確認しています。

04テストケースには、AIエージェントへの依頼文を何件書けばいいんですか？

高梨課長

高梨課長の発言

最初にテストケースをまとめて書いておけば、あとが楽になりますよね。

鈴木さん

鈴木さんの発言

そこは逆にしています。結果を見る前に書いた条件は、見当違いのまま数だけ増えるので。少なく作って、走らせてから足すほうが早いと思っています。

テストケースは、プロンプト（依頼文）と期待結果（成功の説明）の2つを基本とし、任意で入力ファイルを添えます。agentskills.ioが定める「テストケースの3つの要素」は、プロンプト・期待結果・入力ファイル（任意）です。判定条件（検証可能な言い切り）は、ここに含まれません（出典: agentskills.io公式）。

最初は2〜3件のテストケースで始めます。件数を絞るのは、結果を見る前に大量の依頼文を書いても、見当違いな判定条件を量産するだけだからです（出典: agentskills.io公式）。

たとえの左右がずれていないので、迷ったときは学校側に戻して考えられます。問題文を配る前に採点基準を細かく決めない、というのは、答案を見たことがない段階では基準が書けないという当たり前の話です。

evals.jsonに書くフィールドは次のとおりです。

（出典: skill-creatorのreferences/schemas.md、2026-08-03時点で確認）

必須の4つを見ると、どれも人が読んで意味の分かる文です。機械が読む形へ寄せるのは、あとの工程になります。

新入社員のオンボーディング資料を作るonboarding-checklistというスキルで、依頼文を1件書くと次のようになります。

{
  "skill_name": "onboarding-checklist",
  "evals": [
    {
      "id": 1,
      "prompt": "営業部で正社員が1人入るので、初日から1か月分の受け入れ準備をまとめて",
      "expected_output": "部署・雇用形態別のテンプレートに沿った、初日・1週間・1か月のタスク一覧",
      "files": []
    }
  ]
}

05判定条件は、AIエージェントのスキル評価テストのどこで書き足すんですか？

最初の実行結果を見てから、expectationsを書き足します。良い判定条件と弱い判定条件には、はっきりした差があります。

• 良い例：「出力に初日・1週間・1か月の3つの見出しがある」（数えられる）
• 弱い例：「出力が良い」（何を数えるか分からない）
• 弱い例：「見出しの文言が一言一句『初日タスク』と一致する」（言い回しが違うだけで落ちる）

（出典: agentskills.io公式）

弱い例は、ゆるすぎるものと厳しすぎるものの両方向に出ます。片方だけ気をつけても、もう片方で落ちます。

重なりの外へ出た条件は、通っても落ちても意味を持ちません。ゆるいほうへ外れれば何をしても通り、厳しいほうへ外れれば何をしても落ちる。どちらも、スキルの出来とは無関係に結果が決まります。

06AIエージェントにスキルを渡さない実行を、なぜ同じだけ回すんですか？

高梨課長

高梨課長の発言

スキルを使わない実行まで回すのは、二度手間に見えます。

鈴木さん

鈴木さんの発言

比べる相手がいないと、出てきたものが良いかどうかを言えないんです。同じ依頼を素のまま投げた結果が、その基準点になります。

評価セットができたら、同じ依頼文を2通りで実行します。スキルを使う場合と、使わない場合です。スキルを使わない実行が、比較のためのbaseline（基準点）になります（出典: agentskills.io公式）。

差がほとんど出ないときに分かることもあります。その仕事は、スキルを書かなくても届いていたということです。書いた側の徒労には見えますが、労力を向ける先を教えてくれる結果でもあります。

既存スキルを改善する場合は、baselineの選び方が変わります。

（出典: skill-creatorのSKILL.md、2026-08-03時点で確認）

07同じテストを回すとき、AIエージェントはセッションを分けるんですか？

実行は、テストケースごとにサブエージェントを2体（with_skill用とwithout_skill用）立ち上げます。それぞれのテストケースを、前の実行の文脈を引きずらない独立したセッションで走らせるためです（出典: agentskills.io公式）。サブエージェントの定義ファイルの書き方はClaude Codeサブエージェント定義｜渡る情報4点と権限の絞り方にまとめています。

席を分ける手間は、そのまま比較の土台になります。前の回の答えが目に入る状態で採点すると、差が出ても、それが手引きの効果なのか順番の効果なのかを言えません。

{
  "total_tokens": 84852,
  "duration_ms": 23332
}

08採点と集計は、AIエージェントのスキル評価でどう分かれるんですか？

採点は、判定条件ごとにPASS・FAILと根拠をgrading.jsonへ書きます。ここまでは、テストケース1件ごとの作業です。

複数のテストケース分をまとめるときは、公式スクリプトを使います。

python -m scripts.aggregate_benchmark <workspace>/iteration-1 --skill-name onboarding-checklist

このコマンドは、with_skillとwithout_skillそれぞれのpass_rate・所要時間・トークン数を集計します。平均と標準偏差つきでbenchmark.jsonにまとめます（出典: skill-creatorのSKILL.md、2026-08-03時点で確認）。

積み上げの向きは、下から上へ一方通行です。上の段で数字が動いたら、理由は下の段にしかありません。集計だけを眺めて原因を考えても答えは出ないので、必ず根拠の段まで降りて読みます。

09いつも通る判定条件だと、生成AIの地力とスキルの効果が混ざりませんか？

スキルの有無に関わらず毎回通る判定条件は、比較の役に立ちません。この場合、スキルの実力ではなく、Claude自身の地力を測っているだけです。

逆に、毎回落ちる判定条件も要注意です。判定条件そのものが壊れているか、テストケースが難しすぎる可能性があります（出典: agentskills.io公式）。

厄介なのは、この2つが数字の上では健全に見えることです。毎回通る条件は合格率を押し上げ、毎回落ちる条件は下げます。どちらも安定しているので、ばらつきの数字にも異常は出ません。

だから見るのは、合格率そのものより、スキルを渡した側と渡さない側の差です。差が動かない条件は、何を測っているのかをもう一度書き直します。

10フィールド名を1つ変えると、AIエージェントの評価結果はなぜ空欄になるんですか？

高梨課長

高梨課長の発言

採点までは終わっているのに、画面に何も出ないことがありました。どこを見ればいいでしょうか。

鈴木さん

鈴木さんの発言

中身より先に、名札を疑っています。表示する側は決められた名前しか探しにいかないので、名前が違うだけで、あるはずのものが無いことになります。

grading.jsonとbenchmark.jsonは、キー名の厳密な一致をビューアが前提にしています。

（出典: skill-creatorのagents/grader.md・references/schemas.md、2026-08-03時点で確認）

正しい書き方は、次の3フィールドの組み合わせです。

{
  "text": "出力に初日・1週間・1か月の3つの見出しがある",
  "passed": true,
  "evidence": "outputs/checklist.mdの見出しを確認。3つとも存在した"
}

前後で変わったのは中身ではなく、ラベルだけです。それでも見え方は正反対になります。

フィールド名を自己流の命名（name・met・detailsなど）に置き換えても、採点そのものは動きます。結果だけが画面に出ないため、原因の切り分けに時間がかかります。動いているのに見えないという症状は、壊れて止まる症状より見つけにくい種類の不具合です。

11AIエージェントのスキル評価テストは、直すたびに何を見て合否を決めるんですか？

若葉さん

若葉さんの発言

1回やってみて良くなっていたら、それで採用でいいんでしょうか。

鈴木さん

鈴木さんの発言

そこは慎重にしています。1回の結果だけだと、たまたま良かったのか、本当に良くなったのかを分けられないので。

1回の実行結果で一喜一憂しないことが前提です。stddev（ばらつき）が大きいテストケースは、モデルの気まぐれか、スキルの指示があいまいかのどちらかを疑います（出典: agentskills.io公式）。

判定は、pass_rateの差（delta）とstddevの組み合わせで見ます。

区画の中に、判断を止める場所があるのが要点です。良い・悪いの二択にすると、ばらつきの大きい結果まで、どちらかへ押し込むことになります。保留という行き先を先に作っておくと、迷った結果をそのまま迷いとして置いておけます。

スキルを編集するたびに、この判定を繰り返します。次の3つが、改善すべき箇所を教えてくれます。

• 判定条件のFAIL：どの手順が抜けているかを直接示す
• 人が読んだ感想：判定条件だけでは拾えない、構成や体裁の粗さを示す
• 実行の過程そのもの：同じヘルパースクリプトを毎回書き直しているなら、それはスキルに同梱すべき部品だという合図

（出典: agentskills.io公式「Iterating on the skill」）

3つ目だけ、毛色が違います。出力ではなく、作業のしかたを見ています。毎回同じ手当てをしているなら、その手当てはスキルの外にあるべきではない、という読み方です。

改善のたびに新しいiterationディレクトリへ結果を残し、前のiterationと並べて比較します。差分が出なくなるか、人の感想が毎回空欄になった回が、その改善の止めどきです（出典: agentskills.io公式）。

12よくある質問

13まとめ｜今日やる3つのこと

確かめる目は2つに割れました。書く順番は、依頼文と期待結果が先で、判定条件はあとでした。そして採用の判断は、1回の結果ではなく、差とばらつきの組み合わせで決めました。