skill-forge-benchmark

技能基准测试与性能跟踪

通过多次试验、方差分析和趋势跟踪，以严谨的统计方法衡量并比较技能在不同迭代中的表现。

流程

步骤 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. 捕获每次运行的数据：通过/失败、令牌数、耗时
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：可在审查报告中加入基准测试摘要