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단계: 벤치마크 보고서 생성

# 벤치마크 보고서: [skill-name]

## 반복 [N] vs [N-1]

### 요약
| 지표 | 현재 | 이전 | 델타 | 임계값 | 상태 |
|------|------|------|------|--------|------|
| 패스율 | 87% | 78% | +9% | >= 80% | 통과 |
| 평균 토큰 | 45K | 52K | -13% | <= 100K | 통과 |
| 평균 시간 | 34초 | 41초 | -17% | <= 120초 | 통과 |
| 개선비 | 1.45배 | 1.30배 | +0.15배 | >= 1.0배 | 통과 |

### 회귀 (조치 필요)
| 평가 | 이전 | 현재 | 비고 |
|------|------|------|------|
| eval-5 | 통과 | 실패 | 출력에 필수 섹션 누락 |

### 개선
| 평가 | 이전 | 현재 | 비고 |
|------|------|------|------|
| eval-3 | 실패 | 통과 | 오류 처리 이제 작동 |

### 평가별 세부 정보
[전체 분석 표]

### 분산 분석
| 평가 | 패스율 | 표준 편차 | 시행 횟수 | 신뢰성 |
|------|--------|-----------|-----------|--------|
| eval-0 | 100% | 0.00 | 3 | 높음 |
| eval-1 | 67% | 0.47 | 3 | 낮음 (조사 필요) |

### 권장 사항
[회귀, 신뢰성 낮은 평가, 임계값 실패에 기반]

6단계: 임계값 게이팅

임계값 중 하나라도 실패하는 경우:

1. 특정 임계값 세부 정보와 함께 실패로 플래그 지정
2. 실패를 유발한 평가 목록 작성
3. 문제 해결을 위해 /skill-forge evolve 실행 권장
4. 임계값 통과 전까지 게시 승인하지 않음

오류 처리

• 불안정한 시행: 시행이 타임아웃되거나 충돌하는 경우, 분산 계산에서 제외하고 평가별 결과에 "trials_completed" 대 "trials_requested"를 명시
• 시행 부족: 평가에 대해 완료된 시행이 2회 미만인 경우, 보고서에 분산을 "unreliable"로 플래그 지정
• 기준선 누락: 기준선 실행이 완전히 실패한 경우, 스킬 적용 결과만 보고하고 improvement_ratio를 건너뜁니다
• 임계값 경계 케이스: 패스율이 임계값과 정확히 일치하는 경우, 통과로 처리

다른 하위 스킬과의 통합

• skill-forge-eval: 평가 세트 및 채점 인프라 제공
• skill-forge-evolve: 벤치마크 실패를 개선 대상으로 수신
• skill-forge-publish: 게시 전 벤치마크 통과(점수 >= 임계값) 필요
• skill-forge-review: 리뷰 보고서에 벤치마크 요약 포함 가능