skill-forge-eval

スキル評価パイプライン

マルチエージェントパイプラインを使用して、Claude Code スキルのトリガー、正確性、品質を検証するための構造化評価を実行します。

プロセス

ステップ 1：評価セットを定義する

以下から評価の定義を受け付けます。

• 評価セット JSON へのパス：evals/evals.json またはユーザーが指定したファイル
• インラインプロンプト：ユーザーが評価クエリを直接指定
• 自動生成：スキルの説明から生成（ステップ 1b を参照）

評価セットの JSON スキーマ：

{
  "skill_name": "my-skill",
  "skill_path": "./my-skill",
  "evals": [
    {
      "eval_id": 0,
      "eval_name": "descriptive-name",
      "prompt": "The user's task prompt",
      "input_files": [],
      "assertions": [
        {
          "name": "output-has-score",
          "check": "Output contains a numeric score between 0-100",
          "weight": 1.0
        }
      ],
      "should_trigger": true
    }
  ]
}

ステップ 1b：評価セットを自動生成する

評価セットが存在しない場合は、次の手順で生成します。

1. スキルの SKILL.md の説明と指示を読みます
2. python scripts/generate_eval_set.py <skill-path> を実行して、スターターセットを生成します
3. 生成したセットをユーザーに提示し、確認と編集を依頼します
4. 続行する前に、ユーザーが承認するか、内容を修正します

ステップ 2：ワークスペースを設定する

評価の成果物とスキルのファイルが混同されないよう、評価ワークスペースはスキルディレクトリの外部に作成します。同階層のディレクトリ、または専用の場所を使用します。

eval-workspace/
  iteration-1/
    eval-0/
      eval_metadata.json        # Assertions and config for this eval
      with_skill/
        outputs/                # Skill execution outputs
        timing.json             # Token count + duration
        grading.json            # Assertion results + evidence
      baseline/
        outputs/
        timing.json
        grading.json
    eval-1/
      eval_metadata.json
      with_skill/
        outputs/
        timing.json
        grading.json
      baseline/
        outputs/
        timing.json
        grading.json
    benchmark.json              # Aggregated metrics
    benchmark.md                # Human-readable report

各評価ディレクトリに、評価セットのエントリから eval_metadata.json を作成します。

{
  "eval_id": 0,
  "eval_name": "descriptive-name",
  "prompt": "The user's task prompt",
  "assertions": [...],
  "should_trigger": true
}

ステップ 3：評価実行を行う

セット内の各評価について、次の2つの実行を並行して開始します。

スキルありの実行（agents/skill-forge-executor.md に委任）：

Execute this task:
- Skill path: <path-to-skill>
- Task: <eval prompt>
- Input files: <eval files if any, or "none">
- Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Outputs to save: <what the assertions check>

ベースライン実行（agents/skill-forge-executor.md に委任）：

• 新規スキルの場合：スキルを読み込まずに実行します
• 改良したスキルの場合：以前のバージョンを使用して実行します（先にスナップショットを作成します）

各実行ディレクトリの timing.json に時間データを保存します。

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

ステップ 4：結果を採点する

完了した各実行について、agents/skill-forge-grader.md に採点を委任します。

1. eval_metadata.json に定義されたアサーションに基づいて採点します
2. 各実行の grading.json に結果を保存します。

{
  "eval_id": 0,
  "run_type": "with_skill",
  "assertions": [
    {
      "name": "output-has-score",
      "passed": true,
      "evidence": "Found score: 87/100 on line 14"
    }
  ],
  "pass_rate": 1.0
}

ステップ 5：集計と分析を行う

1. python scripts/aggregate_benchmark.py <workspace>/iteration-<N> --skill-name <name> を実行します

2. 次の内容を含む benchmark.json と benchmark.md が生成されます。

   • 評価ごとの合格率（with_skill と baseline の比較）
   • 平均時間とトークン使用量
   • 改善率（with_skill / baseline）

3. agents/skill-forge-analyzer.md に次の分析を委任します。

   • 集計値では見えにくいパターンを明らかにする
   • 一貫して失敗するアサーションの種類を特定する
   • 前回のイテレーションからのリグレッションを検出する

ステップ 6：結果を提示する

要約レポートを生成します。

# Eval Report: [skill-name] — Iteration [N]

## Overall
| Metric | With Skill | Baseline | Delta |
|--------|-----------|----------|-------|
| Pass Rate | X% | Y% | +Z% |
| Avg Time | Xs | Ys | -Zs |
| Avg Tokens | X | Y | -Z |

## Per-Eval Results
| Eval | With Skill | Baseline | Status |
|------|-----------|----------|--------|
| eval-0 | PASS | FAIL | Improved |
| eval-1 | PASS | PASS | Maintained |

## Patterns & Insights
[From analyzer agent]

## Recommendations
[Specific improvements based on failures]

ステップ 7：フィードバックを収集する

ユーザーのフィードバックを feedback.json に保存します。

{
  "reviews": [
    {
      "run_id": "eval-0-with_skill",
      "feedback": "the chart is missing axis labels",
      "timestamp": "2026-03-06T12:00:00Z"
    }
  ],
  "status": "complete"
}

次のイテレーションのために、フィードバックを /skill-forge evolve に渡します。

高度な機能：ブラインド比較

スキルのバージョン間で厳密な A/B テストを行うには、次の手順に従います。

1. agents/skill-forge-comparator.md に委任します
2. 次の2つのディレクトリを渡します：eval-<ID>/with_skill/outputs/ と eval-<ID>/baseline/outputs/
3. 比較担当者がランダムなラベル（Version A / Version B）を割り当てるため、どちらが新しいバージョンか分かりません
4. eval_metadata.json のアサーション基準に基づいて、各出力を評価します
5. どちらが「新しい」バージョンか「古い」バージョンかを知らない状態で、好みのスコアを返します

エラー処理

• 実行のタイムアウト：実行が5分を超えた場合は終了し、timing.json に "timed_out": true として記録します
• 実行の失敗：実行がクラッシュした場合は、エラーを実行ディレクトリの error.txt に保存し、残りの評価を続行します
• 採点の失敗：合否を判定できない場合は、判定できない理由を示す根拠とともに、アサーションを "passed": null として記録します
• ファイルの欠落：実行後に timing.json または grading.json が見つからない場合は、レポートで評価を未完了として示します
• 一部のみ完了：1つの評価が失敗しても処理を止めず、常に利用可能な結果をすべて集計して報告します

品質ゲート

評価実行を完了としてマークする前に、次の項目を確認します。

• すべての評価を実行済み（with_skill + baseline）
• すべての実行の時間データを取得済み
• すべてのアサーションを根拠とともに採点済み
• 合格率、時間、トークンを含むベンチマークを集計済み
• アナライザーで見つかったパターンを文書化済み
• 結果をユーザーに提示済み