skill-evaluator

スキル評価ツール

スキルが正確で、見つけやすく、有用かをテストします。単にユニットテストに合格するかどうかだけではありません。このハーネスはエージェントに依存しません。Agent Skills はすべてのコーディングエージェントで利用できるため、ユーザーが使用しているコーディングエージェントの CLI を実行します。

どのレイヤーをいつ使うか

コストと精度が段階的に高くなる 3 つのレイヤーがあります（詳しい説明は references/methodology.md を参照してください）。

レイヤー	確認すること	スクリプト	CLI が必要？
1. 決定論的	スクリプトはドキュメントに記載された数値を出力しますか？	run_script_checks.py	いいえ
2. トリガー	説明文は適切なプロンプトで起動しますか？	run_trigger_eval.py	はい
3. 品質	SKILL.md に従うことで、スキルなしの場合より良くなりますか？	run_quality_eval.py → 評価 → aggregate_benchmark.py	はい

レイヤー 1 は常に実行してください（無料です）。コーディングエージェントの CLI を実行できる場合は、レイヤー 2～3 も追加してください。

ステップ 0 — エージェントの CLI を選ぶ

ユーザーが使用しているコーディングエージェントを尋ね、アダプター ID に対応付けます。サポート対象： claude-code、openai-codex、antigravity（2026-06-18 に Gemini CLI に代わって登場した agy CLI）、cursor-cli、github-copilot-cli、amp、opencode、 grok-cli。全対応表と認証情報は references/adapters.md を参照するか、次を実行してください。

python scripts/agent_adapters.py list

バイナリがインストールされていることと、認証用環境変数が設定されていることを確認してください（対応表に記載されています）。 実際に実行する前に、必ずドライランを行い、実行される正確なコマンドを確認してください。

python scripts/agent_adapters.py build <agent> --prompt "test" --workdir /tmp/wd

ステップ 1 — 決定論的なスクリプトチェック（常に実行）

python scripts/run_script_checks.py --skill <path-to-skill> --json

スキルの evals/evals.json にある script_checks を実行し、各スクリプトを実行して、その --json 出力を機械的に検証可能なアサーションに照らして評価します。失敗が 1 つでもあるとゼロ以外の終了コードを返すため、CI でも安全に使えます。スキルに script_checks がほとんどない、またはまったくない場合は、答えを計算できるすべての評価項目に追加してください（スキーマは references/schemas.md を参照）。これは、ドキュメントとコードのずれを防ぐための、最も安価で長く使えるガードです。

ステップ 2 — トリガー／発見性の評価

説明文は適切なプロンプトで起動し、似ているが対象外のプロンプトでは起動しないでしょうか？

# Dry-run first (prints the per-CLI commands, runs nothing):
python scripts/run_trigger_eval.py --skill <path> --agent <agent> --dry-run

# Real run with a labelled query set (~20: half should-trigger, half near-miss):
python scripts/run_trigger_eval.py --skill <path> --agent <agent> \
  --queries queries.json --runs-per-query 3 --json

references/methodology.md に沿ってクエリセットを設計してください（肯定例と、判断が難しい否定例）。--queries を指定しない場合、スキルの評価用プロンプトが起動すべきケースとして使用されます。実際に判別できるかをテストするには、否定例を追加してください。

ステップ 3 — 出力品質の評価（スキルあり／なしの差分）

最も重要な指標は、SKILL.md に従ったエージェントがスキルなしの場合より良い結果を出せるかどうかです。

# 1. Dry-run the plan (no tokens spent):
python scripts/run_quality_eval.py --skill <path> --agent <agent> \
  --workspace <skill>-workspace --dry-run

# 2. Real run: with-skill AND no-skill baseline, isolated clean dirs each:
python scripts/run_quality_eval.py --skill <path> --agent <agent> \
  --workspace <skill>-workspace --iteration 1 --json

スキルありの実行では、一時的なプロジェクトの skills ディレクトリにスキルをインストールし、スキルなしのクリーンなベースラインも実行します。各実行について outputs/、response.txt、timing.json を保存します。

次に、各実行を評価し、assertions に照らして grading.json を作成します（references/grader.md を参照してください。数値を再計算し、具体的な証拠を必須とし、部分点は認めず、弱いアサーションには指摘を加えます）。機械的に検証できるアサーションには、目視確認ではなくレイヤー 1 を再利用してください。

次に、差分を含むベンチマークに集計します。

python scripts/aggregate_benchmark.py <skill>-workspace/iteration-1 \
  --skill-name <name> --agent <agent> --json

run_summary.delta.pass_rate がスキルの価値です。平均値に隠れてしまうパターン（references/methodology.md を参照）も明らかにしてください。たとえば、判別力のないアサーション、分散の大きい評価、時間やトークンとのトレードオフなどです。

次に、レビューを生成し、自己評価する前にユーザーに提示します （サーバー不要の単独 HTML ページです）。

python eval-viewer/generate_review.py <skill>-workspace/iteration-1/benchmark.json -o review.html

スキルあり／なしの差分、設定ごとの統計、評価済みアサーションごとの詳細（テキスト、合否、証拠）を展開表示します。

ステップ 4 — 反復する

シグナル（失敗したアサーション、弱いアサーションへのフィードバック、トランスクリプト、人によるレビュー）をもとにスキルを改善します。過剰適合ではなく一般化を目指し、簡潔さを保ち、なぜそうするのかを説明し、繰り返し行う作業はスクリプトにまとめてください。iteration-<N+1>/ に再実行して比較します。結果がユーザーの期待を満たす、フィードバックがなくなる、または改善が頭打ちになるまで続けます。「新しいバージョンは本当に良くなっているか？」を確認するには、references/methodology.md で説明されているブラインド比較を使用してください。

報告する出力

• レイヤー 1：合格したチェック／合格したアサーション、ドキュメントとコードの不一致の有無。
• レイヤー 2：トリガーの合格率（反応したポジティブ、反応しなかったネガティブ）。
• レイヤー 3：スキルありとスキルなしの合格率の差分、および所要時間／トークンコスト。

参照ファイル

• references/adapters.md — CLI ごとのヘッドレスコマンド、スキルディレクトリ、認証、注意事項。
• references/methodology.md — 厳密な手法（複雑な評価ではお読みください）。
• references/grader.md — 実行結果を grading.json に採点する方法。
• references/schemas.md — すべてのファイルの正確な JSON 形式。
• eval-viewer/generate_review.py — ベンチマークをスタンドアロンの HTML レビューにレンダリングします。

検証チェックリスト

実施したレイヤーに該当する各項目を満たすまで、判定を報告しないでください。

• レイヤー 1：run_script_checks.py --json を実行し、summary 行（checks_passed/checks、assertions_passed/assertions）を記録して、ok: true（プロセスの終了コード 0）を確認しました。終了コードが 0 以外の場合は、合格したスキルではなく、ドキュメントとコードの不一致を意味します。
• レイヤー 1：少なくとも 1 つの数値アサーションについて、期待値を手計算で導き直し、スクリプトが出力した値と一致することを確認しました（例：指定された rel_tol／abs_tol の範囲内で approx）。アサーションの passed フラグが true であることだけを確認したのではありません。
• レイヤー 1：cases_without_checks を記録しました。計算可能な評価に script_check がない場合は、実行結果を完全に検証済みとして扱わず、カバレッジの不足として記録しました。
• レイヤー 2：ポジティブと、判別が難しいネガティブの両方を含むラベル付きセットで run_trigger_eval.py を実行し、クラスごとの合格数（しきい値以上の率で反応したポジティブ、しきい値を下回ったネガティブ）を記録しました。ポジティブのみの実行で測れるのは再現率であり、識別性能ではありません。
• レイヤー 2：--runs-per-query を 3 以上に設定して使用し、各クエリの trigger_rate を記録しました。率が --threshold に近いクエリは、明確な合格／不合格として数えず、不安定としてフラグを付けました。
• レイヤー 3：with_skill と without_skill のベースラインの両方を実行し、平均 ± 標準偏差とともに run_summary.delta.pass_rate（主要な値）を報告しました。スキルありの絶対合格率だけを報告してはいけません。
• レイヤー 3：outputs/ 内の実際のファイルを使って各実行を採点し（数値を再計算し、references/grader.md に従って成果物を開き）、期待項目ごとに具体的な evidence を記録し、結論を出す前に出力または benchmark.md をユーザーに提示しました。

よくある落とし穴と誤った正当化

ありがちな近道	それが間違っている理由／対処方法
「スクリプトが実行されて終了コードが 0 だったので、スキルは正しいです。」	終了コードが 0 というのは、プロセスがクラッシュしなかったことを示すだけです。run_script_checks.py が 0 以外を返すのは、アサーションまたは expect_exit が失敗した場合に限られます。assertions_passed/assertions の件数を確認し、少なくとも 1 つの数値を自分でも再計算してください。スクリプトが正常に実行されても、誤った値を出力することがあります。
「アサーションに合格したので、数値は正しいです。」	弱いアサーション（例：「cfl_checker.py に言及している」、またはフィールドに対する exists／truthy）は、実行結果が間違っていても合格します。値と結論を検証するアサーション（再計算した期待値を指定した approx／eq）を使い、簡単に成立してしまうアサーションを指摘する採点者の eval_feedback を確認して対処してください。
「すべてのトリガークエリが反応したので、検出は機能しています。」	肯定例だけのセットで測れるのは再現率であり、適合率ではありません。何にでも反応する過剰な説明でも合格してしまいます。--threshold を下回る、判定が難しいニアミスの否定例が必要です。これがなければ、識別テストに意味はありません。
「クエリごとに 1 回実行すれば、トリガー率を把握できます。」	検出はトランスクリプトに基づくヒューリスティックであり、トリガーの発生は確率的です。1 回の実行では率は 0 か 1 になります。--runs-per-query を 3 以上にし、しきい値付近の率は決定的な結果ではなく、不安定なものとして扱ってください。
「スキルを使った場合の合格率が高いので、このスキルには価値があります。」	価値を示すのは絶対的な合格率ではなく、スキルを使った場合と使わない場合の差分です。スキルなしでもエージェントがすでにタスクに合格している場合、差分は約 0 で、スキルはレイテンシやトークンを増やすだけかもしれません。必ず without_skill のベースラインを実行し、delta.pass_rate を報告してください。
「アサーションに合格したので、出力ファイルを開く必要はありません。」	自動採点で確認されるのは、アサーションに含めた内容だけです。また、トランスクリプトには実際には行っていない作業が記載されている場合があります。outputs/ のファイルを開いて数値を再計算し、user_notes.md を読み、スキルを問題ないと判断する前に benchmark.md を確認してください（またはユーザーに確認してもらってください）。

セキュリティ

入力検証

• --agent は、既知のアダプター ID／エイリアスの固定許可リスト （agent_adapters.py）に照らして解決されます。未知の値は拒否されます（終了コード 2）。
• --skill は SKILL.md を含むディレクトリである必要があります。そうでない場合、ランナーは終了コード 2 で終了します。
• script_checks の演算子とドット区切りのパスは固定セットと照合されます。ユーザー文字列が eval() に渡されたり、シェルに渡されたりすることはありません。

ファイルアクセス

• 決定論的レイヤーは、スキルに含まれるスクリプトを実際のインタープリターで実行し、そのスキルの evals/evals.json のみを読み取ります。
• 品質レイヤーとトリガーレイヤーは、ユーザー指定のワークスペース内に分離された作業ディレクトリを作成し、スキルをコピーして、そこに結果を書き込みます。

ツールの制限

• Bash：ハーネスの Python スクリプトと、選択したコーディングエージェントの CLI を実行します。
• Read/Grep/Glob：スキルと結果を調べます。Write：ワークスペースのひな型を作成します。

安全対策

• eval()／exec() は使用しません。サブプロセスの呼び出しには明示的な引数リストを使い（shell=True は使用しません）、コマンドは文字列を連結せず、アダプターの仕様から構築します。
• トリガーレイヤーと品質レイヤーでは、各 CLI の自動承認フラグ（例：--dangerously-skip-permissions）を渡します。これにより、安全対策を減らした状態でエージェントが実行されます。信頼できるスキルのみを評価し、できればサンドボックス／コンテナー内で実行してください。必ず最初に --dry-run を使って、実際のコマンドを確認してください。認証情報は環境変数から読み取り、コマンドの引数として渡すことはありません。

制限事項

• レイヤー 2～3 には、サポート対象の CLI がインストールされ、認証済みである必要があります。そうでない場合は、レイヤー 1 のみを使用してください。
• トリガー検出はツール横断のヒューリスティック（トランスクリプトがスキルを参照したかどうか）です。Claude Code で最も精度の高い検出を行うには、stream-json のツール使用イベントを解析してください。
• トークン数の計上はベストエフォートです。ヘッドレス出力で使用量を報告する CLI は一部に限られます。
• 新しい CLI（Antigravity、Grok）の信頼度は中程度です。ベンダーの --help と --dry-run でフラグを確認してください。