evaluate-skill

スキルを評価する

Caliper を操作します。スキルの評価を実行し、結果を読み取り、各失敗の修正箇所を特定します。

前提条件

caliper CLI が PATH 上にある必要があります。このスキルは Caliper リポジトリがないエージェントにもコピーできるため、見つからない場合はインストールしてください。

pipx install caliper-eval

フラグについては caliper <command> --help が正となります。REFERENCE.md では、完全な仕様形式、エンジン、結果の意味について説明しています。

4 つの問い

スキル評価では、4 つの別々の問いに答えます。それぞれ測定方法と修正箇所が異なるため、分けて考えてください。数値をまとめると、どちらがうまくいかなかったのかが分からなくなります。

問い	測定方法	失敗の修正箇所
発動するか：エージェントは、必要なときにだけスキルを使うか？	タスクの activates: とトリガープローブ	スキルの description フロントマター
機能するか：発動したあと、目的を達成できるか？	expect: / assert:。成功率として採点	スキルの本文
価値があるか：スキルを使わない場合より優れているか？	コントロール（--ablate <skill-name>：宣言された近傍からこのスキルを除いたもの）と caliper compare。本当に何もないエージェントを使うには、宣言されたすべてのスキルとすべての mcp: サーバーをアブレーションし、実行を分離します	タスク：コントロールでも成功する場合、タスクが簡単すぎます
維持できるか：編集後も、また時間が経っても良好な状態を保てるか？	各フル実行を前回の実行と比較する caliper compare、スキルのドリフト	変化の原因となった編集

仕様の形式

skills:
  - ./SKILL.md              # relative to the spec; installed, never preloaded
tasks:
  - name: What success looks like
    prompt: <what a real user would type; never names the skill>
    expect: <natural-language pass/fail criterion>
    assert: |               # optional deterministic Python check
      assert ...
    activates: [my-skill]   # frontmatter name: of the skill that should fire
  - name: Unrelated work stays unrelated
    prompt: <work no declared skill should answer>
    activates: []           # a trigger probe: no judge, cheap

仕様を書くときは、expect: または assert: を持つすべてのタスクで activates: も検証します。拒否する場合も対象です。そのタスクで委任するスキルと、宣言されたスキルを含めます。また、すべてのプロンプトは、スキルの名前を出さず、実際のユーザーからの依頼のように書きます。

仕様には backend / model や judge: ブロックを含めません。エンジンは実行時に、スキルとジャッジそれぞれについて独立して選択します。caliper run <spec> --model codex は codex で実行と採点を行い、--judge-model は別のジャッジを選択します。バックエンドは claude-code（デフォルト）、codex、pi、hermes です。各試行は新しい空の作業ディレクトリで実行されるため、setup: で相対パスを使ってフィクスチャを作成します。

実行

1. caliper validate <spec> を実行します。ネットワークには一切アクセスしません。
2. caliper run <spec> --k 1 を実行して、仕様とハーネスのエラーを洗い出します。スコアを確認する前に、これらを修正してください。
3. caliper run <spec> --k 3 --ablate <skill-name> を 1 回実行します（mcp: サーバーと名前が重複する場合は skill:<skill-name> と記述します）。これがコントロールです。宣言された近傍からこのスキルを除いたものです。スキルはインストールされないため、SKILL.md を編集しても数値は変わりません。結果のパスを保持してください（caliper list <spec-name> ではアブレーション済みの実行が示されます）。それと再度差分を比較します。タスクまたは宣言されたスキルが変わったときだけ、コントロールを再実行してください。
4. caliper run <spec> --k 3 を実行し、続けて caliper compare <control.json> <spec-name> を実行して、このスキルが存在する価値を確認します。編集のたびに、前回のフル実行のパスとも比較し、編集によって性能が保たれたか確認してください。性能が下がったスキルでも、コントロールを上回ることはあります。仕様名だけを指定すると、その仕様の最新の実行が参照されます。

実行が Not logged in で停止した場合は、エラーに表示されたログインコマンドを実行してよいかユーザーに確認します。承諾を得たら実行します（ユーザーが完了できるよう、ブラウザーが開きます）。承諾なしに実行してはいけません。hermes model は対話式の選択ツールなので、ユーザー自身のターミナルで実行するよう依頼してください。

結果の読み方

成功率（successes / usable）が主な指標です。pass@k と pass^k は、--verbose で確認できる補助的な指標です。アクティベーションは別の母集団を対象とする独立した評価指標です。成功率と並べて報告し、成功率に平均して含めないでください。

失敗したタスクをすべて追跡し、修正すべき箇所を特定してください。

シグナル	修正すべき箇所
実行が 2 で終了する（バックエンドの設定ミス、モデルを利用できない、フックまたは MCP サーバーの失敗、またはすべての試行が使用不可）	環境またはタスクのフックです。タスクの失敗ではなく、設定の問題として報告してください
⊘ 使用不可の試行（infra_error、timeout、judge_error）	スキルではありません。レート制限、認証、または判定側の問題です。スコアから除外されるため、再実行してください
cheat の結果	タスクです。答えが漏れています。タスクまたは sandbox: を厳格化してください
アクティベーションの失敗：期待したスキルが発動しなかった	そのスキルの description
アクティベーションの失敗：予期しないスキルも発動した	追加で発動したスキルの description、または2つのスキルの重複
ユーザー自身のスキルが発動したためのアクティベーションの失敗（レポートヘッダーの skill:）	description だけの問題ではありません。そのスキルはユーザーの環境で実際に競合しています。説明を明確にするか、実行を分離するか、ユーザーと相談して決めてください
アクティベーションは成功したが、スコアが低い	スキルの本文
判定側の推論で expect: が曖昧だと示されている	タスクの採点方法です。基準を観察可能にするか、assert: を追加してください
フル実行 ≈ 対照実行で、フル実行ではスキルが発動した	タスクです。そのスキルは不要です。スキルが一度も発動しなかった場合は、修正すべきなのはその description です（上記参照）

k=3 では、1回の試行で33ポイント変動します。変更を改善または悪化と判断する前に、k≥5 で再実行してください。caliper compare は低下を検出しますが、合否判定はしません。書き換えたスキルや短縮したスキルは、k≥5 で以前のスコアとの差が約5％以内に収まり、対照実行を上回るなら、安全に公開できます。

どの環境を測定するか

実行では、デフォルトでユーザー自身のカスタマイズ（ユーザースキル、プラグイン、ルール、設定、コネクター。バックエンドの例外については REFERENCE.md を参照）が読み込まれます。これは「自分のエージェントで自分のスキルは機能するか？」に答えるものです。バックエンドやモデルを比較するとき、結果をこのマシンの外に出すとき（共有、公開、他の人の実行結果との比較）、またはエージェントそのものを測定するときは、分離してください（--no-user-customizations、または spec 内の user_customizations: false）。環境ごとに設定が異なるため、分離しないと差分の一部が環境の違いによるものになります。ユーザー自身のスキルを対象にした --ablate では、どちらの実行でも同じ環境が読み込まれるため、分離は不要です。

どのモードで実行したか、何が読み込まれたかを必ずユーザーに伝えてください。レポートヘッダーの user customizations: の行を確認してください（この行がなければ分離されています）。また、caliper compare がそれについて提案する修正があれば、伝えてください。

まだ評価がない場合

ユーザーが何をテストするか決めていない場合（.eval.yaml のないスキル、または問題点を見つけたい評価）には、grill-skill を提案してください。ユーザーへの聞き取りを行い、spec を作成します。タスクを自分で設計する場合は、REFERENCE.md の「評価の設計」に従ってください。

完了条件

• すべてのタスクに観察可能な基準があり、少なくとも1つに決定的な assert: があること。
• 実行タスクでは activates: をアサートし、spec に少なくとも1つのトリガープローブがあること。
• フル実行が実行タスクで対照実行を上回り、以前のフル実行に対しても維持されること。トリガープローブには実行スコアがありません。フル実行のアクティベーションから確認してください。
• spec が caliper validate に合格すること。
• ユーザーに、.eval.yaml を SKILL.md の隣にコミットするよう伝えてあること。.caliper/results/ に保存した実行結果は、経時的な差分確認に役立ち、gitignore に追加しても問題ありません。