skill-forge-benchmark

スキルのベンチマークとパフォーマンスの追跡

複数回の試行、分散分析、傾向の追跡を用いて、統計的な厳密さをもって反復ごとのスキルのパフォーマンスを測定・比較します。

プロセス

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

次の設定を受け付けます。

• 既存の評価セット：/skill-forge eval から生成された evals/evals.json のパス
• ベンチマーク設定：試行回数としきい値を指定したカスタム設定

ベンチマーク設定のスキーマ：

{
  "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. 実行ごとに、合否、トークン数、所要時間を記録します
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：ベンチマークレポートの生成

# Benchmark Report: [skill-name]

## Iteration [N] vs [N-1]

### Summary
| Metric | Current | Previous | Delta | Threshold | Status |
|--------|---------|----------|-------|-----------|--------|
| Pass Rate | 87% | 78% | +9% | >= 80% | PASS |
| Avg Tokens | 45K | 52K | -13% | <= 100K | PASS |
| Avg Time | 34s | 41s | -17% | <= 120s | PASS |
| Improvement | 1.45x | 1.30x | +0.15x | >= 1.0x | PASS |

### Regressions (Action Required)
| Eval | Previous | Current | Notes |
|------|----------|---------|-------|
| eval-5 | PASS | FAIL | Output missing required section |

### Improvements
| Eval | Previous | Current | Notes |
|------|----------|---------|-------|
| eval-3 | FAIL | PASS | Error handling now works |

### Per-Eval Detail
[Full breakdown table]

### Variance Analysis
| Eval | Pass Rate | Std Dev | Trials | Reliability |
|------|-----------|---------|--------|-------------|
| eval-0 | 100% | 0.00 | 3 | High |
| eval-1 | 67% | 0.47 | 3 | Low (investigate) |

### Recommendations
[Based on regressions, low-reliability evals, and threshold failures]

ステップ 6：しきい値によるゲート判定

いずれかのしきい値を満たさない場合は、次の処理を行います。

1. 具体的なしきい値の詳細を示して FAIL と判定します
2. 失敗の原因となった評価を列挙します
3. 問題に対処するため、/skill-forge evolve の実行を推奨します
4. しきい値を満たすまで、公開を承認しないでください

エラー処理

• 不安定な試行：試行がタイムアウトまたはクラッシュした場合は、分散の計算から除外し、評価ごとの結果に "trials_completed" と "trials_requested" を記録します
• 試行回数不足：評価で完了した試行が 2 回未満の場合、レポートで分散を "unreliable" として示します
• ベースラインの欠落：ベースラインの実行がすべて失敗した場合は、スキルありの結果のみを報告し、improvement_ratio の計算を省略します
• しきい値の境界ケース：合格率がしきい値と完全に一致する場合は、PASS として扱います

他のサブスキルとの連携

• skill-forge-eval：評価セットと採点インフラストラクチャを提供します
• skill-forge-evolve：ベンチマークの失敗を改善対象として受け取ります
• skill-forge-publish：公開前にベンチマークの合格（スコア >= しきい値）が必要です
• skill-forge-review：レビュー報告にベンチマークの概要を含めることができます