skill-eval-builder

スキル評価ビルダー

概要

スキル向けの小規模で実用的な評価をセットアップします。スキルと同じ場所に evals/ フォルダーを作成し、実際のケースをいくつか、実行可能なスクリプト、スコアカードを用意します。スクリプトだけでは判断できない点、つまり、スキルが必要なときに発動し（不要なときは静かにしている）、出力が有効であり、所要時間の上限内に収まるかを測定します。

基本原則： 評価はフレームワークではなく、フォルダーです。小さく保ちましょう。

入力

• 対象スキル — パスまたは名前（SKILL.md があるディレクトリ）。
• 実際のケースをいくつか — 発動すべきプロンプトと発動すべきでないプロンプト、および実際の入力。必要に応じて、ユーザーが見つけるのを手伝います。
• 重要な評価軸 — デフォルトは発動と検証です。適していれば所要時間などを追加します。

手順

1. 対象スキルを読む — SKILL.md、参照資料、スクリプトを確認し、その動作と生成物を把握します。
2. references/eval-dimensions.md から、スキルに適した評価軸を選びます。ワークフロースキルなら発動＋所要時間、機能スキルなら検証を重視します。
3. 実際のケースを3～5件集める — 発動すべきプロンプトと発動すべきでないプロンプト、および実際の入力を用意します。発動すべきでないケースを必ず1件以上含めてください。
4. ケースごとに「良好」の基準を定義する — fired_when に副作用の確認、validate に検証コマンド、budget_s に実際のベースラインに基づく値を設定します（references/eval-anatomy.md を参照）。
5. 成果物をスキルの隣に作成します：

   python3 "${CLAUDE_SKILL_DIR}/scripts/scaffold-evals.py" <target-skill-dir>
   

   次に、手順3～4のケースを evals/cases.md に記入します。
6. 確認してから、ベースラインを実行します：

   python3 <target-skill-dir>/evals/run.py --dry-run   # cases parse?
   python3 <target-skill-dir>/evals/run.py             # real run (calls claude -p)
   

7. 報告します — スコアカードと保存先を示します。

分類ゲートのテスト

スキルの冒頭に分類器（機能とバグを振り分ける、または続行するかどうかを判断するもの）がある場合は、そのゲートをテストします。

1. python3 "${CLAUDE_SKILL_DIR}/scripts/scaffold-evals.py" <target> --classify
2. ラベル、ゲート独自の指示、実際のラベル付き例（例：直近10件のトラッカーチケットと、正解データとしての既存ラベル）を evals/classify-cases.md に記入します。references/eval-anatomy.md を参照してください。
3. python3 <target>/evals/classify.py → 正解率と混同行列のスコアカードを出力します。

出力形式

スコアカード（評価軸 × ケース）と保存した成果物のパス：

┌───────────────────────────────┬──────────┬────────┬────────────────────┐
│ Case                          │ Fires?   │ Valid? │ Duration vs budget │
├───────────────────────────────┼──────────┼────────┼────────────────────┤
│ "add tests for X"             │ ✅       │ ✅     │ 40s / 60s ✅       │
│ "refactor Y" (shouldn't fire) │ ✅ quiet │ –      │ –                  │
└───────────────────────────────┴──────────┴────────┴────────────────────┘

<target-skill>/evals/ に保存されます（cases.md、run.py、results.md）。

ガイドライン

• 発動の確認には、文章の検索よりも、スキルが生成するファイルなどの観測可能な副作用を優先します。
• 実行結果はバイト単位で同一にはなりません。スキルの評価ではモデルを実行するため、そのばらつき自体が測定対象です。決定性を偽装せず、決定的なスクリプトがすでに保証している内容は評価しないでください（代わりにスクリプトを単体テストします）。
• 実際のケースを3～5件用意し、発動すべきでないケースを少なくとも1件含めます。references/eval-anatomy.md を参照してください。

ファイル

• scripts/scaffold-evals.py — evals/{cases.md, run.py, results.md}、または --classify を指定して classify-* 一式を作成します。
• scripts/run-evals.py — claude -p を使ってケースを実行し、各ケースの所要時間を計測して、発動と検証を確認し、スコアカードを表示・保存します。--dry-run はトークンを消費せずに解析します。
• scripts/classify-evals.py — ラベル付き例を claude -p で分類し、正解率と混同行列を報告します。--dry-run はトークンを消費せずに解析します。
• references/eval-dimensions.md — 評価軸の一覧と、それぞれが適用される場面。
• references/eval-anatomy.md — ケースの形式、副作用のパターン、アンチパターン。

スクリプトをここで実行できない場合（python3 と claude CLI が必要な場合、またはOSが異なる場合）でも、作業を中断しないでください。評価に必要なのは cases.md と小さなランナーだけです。利用可能なツールでケースを実行し、スコアカードを集計してください。