スキルベンチマーク

スキルベンチマーキングとパフォーマンストラッキング

複数回の試行、分散分析、傾向追跡を用いて、統計的な厳密さでイテレーション間のスキルパフォーマンスを測定・比較します。

プロセス

ステップ 1: ベンチマーク設定の定義

設定を以下のように受け入れます:

• 既存の評価セット: evals/evals.json へのパス (/skill-forge eval から)
• ベンチマーク設定: 試行回数としきい値を含むカスタム設定

ベンチマーク設定スキーマ:

{
  "skill_name": "my-skill",
  "skill_path": "./my-skill",
  "eval_set_path": "./evals/evals.json",
  "trials_per_eval": 3,
  "baseline_type": "no_skill",
  "previous_benchmark": null,
  "thresholds": {
    "min_pass_rate": 0.8,
    "max_avg_tokens": 100000,
    "max_avg_duration_seconds": 120,
    "min_improvement_ratio": 1.0
  }
}

ステップ 2: ベンチマーク実行の実施

各評価について、信頼できるメトリクスを得るために trials_per_eval 回（デフォルト: 3）実行します:

1. スキルあり実行（各評価につき3回）
2. ベースライン実行（各評価につき3回）
3. 実行ごとに success/fail、トークン数、所要時間を取得
4. 各実行の timing.json と grading.json を保存

可能な場合は、並列実行に agents/skill-forge-executor.md を使用します。

ステップ 3: 結果の集計

python scripts/aggregate_benchmark.py <workspace>/iteration-<N> --skill-name <name> を実行:

出力 benchmark.json スキーマ:

{
  "skill_name": "my-skill",
  "iteration": 1,
  "timestamp": "2026-03-06T12:00:00Z",
  "summary": {
    "total_evals": 10,
    "with_skill": {
      "pass_rate": 0.87,
      "pass_rate_std": 0.05,
      "avg_tokens": 45000,
      "avg_duration_seconds": 34.2
    },
    "baseline": {
      "pass_rate": 0.60,
      "pass_rate_std": 0.08,
      "avg_tokens": 62000,
      "avg_duration_seconds": 52.1
    },
    "improvement_ratio": 1.45,
    "token_savings_ratio": 0.73,
    "time_savings_ratio": 0.66
  },
  "per_eval": [
    {
      "eval_id": 0,
      "eval_name": "basic-trigger",
      "with_skill": {"pass_rate": 1.0, "avg_tokens": 30000, "avg_duration_seconds": 20.1},
      "baseline": {"pass_rate": 0.67, "avg_tokens": 50000, "avg_duration_seconds": 45.0},
      "trials": 3
    }
  ],
  "thresholds_met": {
    "min_pass_rate": true,
    "max_avg_tokens": true,
    "max_avg_duration_seconds": true,
    "min_improvement_ratio": true
  }
}

ステップ 4: 以前のイテレーションとの比較

previous_benchmark が指定されているか、以前の iteration-<N-1> が存在する場合:

1. 以前の benchmark.json を読み込む
2. メトリクスごとの差分を計算:
   • パス率の変化
   • トークン使用量の変化
   • 実行時間の変化
   • 新たな回帰（以前は合格したが今は不合格の評価）
   • 新たな改善（以前は不合格だったが今は合格の評価）

ステップ 5: ベンチマークレポートの生成

# ベンチマークレポート: [skill-name]

## イテレーション [N] vs [N-1]

### 概要
| メトリクス | 現在 | 前回 | 差分 | しきい値 | ステータス |
|--------|---------|----------|-------|-----------|--------|
| パス率 | 87% | 78% | +9% | >= 80% | PASS |
| 平均トークン数 | 45K | 52K | -13% | <= 100K | PASS |
| 平均時間 | 34s | 41s | -17% | <= 120s | PASS |
| 改善倍率 | 1.45x | 1.30x | +0.15x | >= 1.0x | PASS |

### 回帰（アクション必須）
| 評価 | 前回 | 現在 | 備考 |
|------|----------|---------|-------|
| eval-5 | PASS | FAIL | 出力に必須セクションが欠落 |

### 改善
| 評価 | 前回 | 現在 | 備考 |
|------|----------|---------|-------|
| eval-3 | FAIL | PASS | エラーハンドリングが機能するようになった |

### 評価ごとの詳細
[完全な内訳表]

### 分散分析
| 評価 | パス率 | 標準偏差 | 試行回数 | 信頼性 |
|------|-----------|---------|--------|-------------|
| eval-0 | 100% | 0.00 | 3 | 高 |
| eval-1 | 67% | 0.47 | 3 | 低（調査が必要） |

### 推奨事項
[回帰、信頼性の低い評価、しきい値違反に基づく]

ステップ 6: しきい値ゲート

しきい値を満たさないものがある場合:

1. 具体的なしきい値の詳細とともに FAIL としてフラグを立てる
2. どの評価が失敗の原因かをリストする
3. 問題に対処するために /skill-forge evolve の実行を推奨する
4. しきい値を満たすまで公開を承認しない

エラーハンドリング

• 不安定な試行: 試行がタイムアウトまたはクラッシュした場合、分散計算から除外し、評価ごとの結果に "trials_completed" 対 "trials_requested" を記載する
• 試行不足: 評価に対して完了した試行が2回未満の場合、レポートで分散を "unreliable" としてフラグを立てる
• ベースライン欠落: ベースライン実行が完全に失敗した場合、スキルありの結果のみを報告し、improvement_ratio をスキップする
• しきい値の境界: pass_rate がしきい値と正確に等しい場合、PASS として扱う

他のサブスキルとの統合

• skill-forge-eval: 評価セットと評価インフラを提供する
• skill-forge-evolve: ベンチマークの失敗を改善目標として受け取る
• skill-forge-publish: 公開前にベンチマークの合格（スコア >= しきい値）を要求する
• skill-forge-review: レビューレポートにベンチマークサマリーを含めることができる