skill-forge-eval

技能评估流水线

使用多 Agent 流水线对 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：执行评估运行

针对评估集中的每项评估，启动两个并行运行：

加载技能的运行（委派给 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，其中包含：

   • 每项评估的通过率（加载技能与基线的对比）
   • 平均耗时和 Token 用量
   • 改进比率（加载技能 / 基线）

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. 传入两个目录：eval-<ID>/with_skill/outputs/ 和 eval-<ID>/baseline/outputs/
3. 对比器分配随机标签（版本 A / 版本 B），因此无法知道哪个是新版本
4. 根据 eval_metadata.json 中的断言标准对每个输出评分
5. 在不知道哪个是“新”版本、哪个是“旧”版本的情况下，返回偏好评分

错误处理

• 执行器超时：如果运行超过 5 分钟，则终止运行，并在 timing.json 中标记 "timed_out": true
• 执行器失败：如果运行崩溃，则将错误保存到运行目录中的 error.txt，然后继续处理剩余评估
• 评分失败：如果无法判定通过或失败，则将断言标记为 "passed": null，并提供说明原因的证据
• 缺少文件：如果运行结束后缺少 timing.json 或 grading.json，则在报告中将该评估标记为未完成
• 部分完成：始终汇总并报告所有可用结果——不要因某一项评估失败而中止

质量门槛

将评估运行标记为完成前：

• 已执行所有评估（加载技能 + 基线）
• 已捕获每次运行的计时数据
• 已对所有断言评分并提供证据
• 已汇总基准测试，包括通过率、耗时和 Token 用量
• 已记录分析器发现的模式
• 已向用户呈现结果