스킬 평가 파이프라인

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단계: 평가 세트 자동 생성

평가 세트가 없으면 다음을 수행하여 생성합니다:

스킬의 SKILL.md 설명 및 지침을 읽습니다.
python scripts/generate_eval_set.py <skill-path>를 실행하여 시작 세트를 생성합니다.
생성된 세트를 검토 및 편집할 수 있도록 사용자에게 제시합니다.
사용자가 승인하거나 수정한 후 진행합니다.

2단계: 작업 공간 설정

평가 작업 공간을 스킬 디렉토리 외부에 생성하여 평가 아티팩트와 스킬 파일이 혼동되지 않도록 합니다. 형제 디렉토리나 전용 위치를 사용하십시오:

eval-workspace/
  iteration-1/
    eval-0/
      eval_metadata.json        # 이 평가에 대한 어설션 및 구성
      with_skill/
        outputs/                # 스킬 실행 출력
        timing.json             # 토큰 수 + 기간
        grading.json            # 어설션 결과 + 증거
      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              # 집계된 메트릭
    benchmark.md                # 사람이 읽을 수 있는 보고서

각 eval 디렉토리에 대해 평가 세트 항목에서 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에 위임합니다:

eval_metadata.json에 정의된 어설션에 대해 채점
실행당 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단계: 집계 및 분석

python scripts/aggregate_benchmark.py <workspace>/iteration-<N> --skill-name <name> 실행
다음을 포함하는 benchmark.json 및 benchmark.md 생성:
- 평가별 통과율 (with_skill vs baseline)
- 평균 시간 및 토큰 사용량
- 개선 비율 (with_skill / baseline)
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 테스트를 위해:

agents/skill-forge-comparator.md에 위임
두 디렉토리 전달: eval-<ID>/with_skill/outputs/ 및 eval-<ID>/baseline/outputs/
비교기는 무작위 레이블(Version A / Version B)을 할당하여 새 버전을 알 수 없도록 함
eval_metadata.json의 어설션 기준에 따라 각 출력 평가
"new" 또는 "old"를 알지 못한 상태에서 선호도 점수 반환

오류 처리

실행자 시간 초과: 실행이 5분을 초과하면 종료하고 timing.json에서 "timed_out": true로 표시
실행자 실패: 실행이 중단되면 오류를 실행 디렉토리의 error.txt에 저장하고 나머지 평가를 계속 진행
채점 실패: 채점에서 통과/실패를 확인할 수 없으면 어설션을 "passed": null로 표시하고 이유를 설명하는 증거 포함
파일 누락: 실행 후 timing.json 또는 grading.json이 없으면 보고서에서 평가를 불완전으로 표시
부분 완료: 사용 가능한 모든 결과를 집계하고 보고 — 하나의 실패한 평가에 차단되지 않음

품질 게이트

평가 실행을 완료로 표시하기 전에:

모든 평가 실행 (with_skill + baseline)
모든 실행에 대한 타이밍 데이터 캡처
모든 어설션에 증거와 함께 채점 완료
통과율, 시간, 토큰으로 벤치마크 집계
분석기 패턴 문서화
결과가 사용자에게 제시됨

스킬-포지-평가