[Agent Skills 완전정복 #6] 스킬 품질 평가하기 — eval로 검증하고 개선하기

Agent Skills 시리즈 여섯 번째 편. "한 번 돌려보니 되던데?"는 검증이 아닙니다.
이번엔 스킬이 정말 좋은 출력을 내는지 구조적으로 평가하고 개선하는 eval(평가) 루프를 정리합니다.

핵심 질문은 셋입니다 — 다양한 프롬프트에서 일관되게 동작하나? 엣지 케이스도 처리하나? 스킬이 없을 때보다 정말 나은가?

---

🧪 1. 테스트 케이스 설계

테스트 케이스는 세 부분 — 프롬프트 / 기대 출력 / (선택) 입력 파일. 스킬 폴더 안 evals/evals.json에 저장합니다.

{
  "skill_name": "csv-analyzer",
  "evals": [
    {
      "id": 1,
      "prompt": "data/sales_2025.csv 월별 매출에서 매출 상위 3개월 찾아 막대차트 만들어줘",
      "expected_output": "상위 3개월 막대차트(축 라벨·값 포함)",
      "files": ["evals/files/sales_2025.csv"]
    }
  ]
}

• 2~3개로 시작 — 첫 결과를 보기 전엔 과투자 금지
• 프롬프트를 다양하게 — 격식/캐주얼, 짧은 것/상세한 것
• 엣지 케이스를 최소 하나 — 잘못된 입력, 모호한 요청 등
• 현실적 맥락 — 파일 경로·컬럼명. "이 데이터 처리해줘"는 너무 막연

이 단계에선 합격/불합격 기준(assertion)을 아직 정하지 마세요. 첫 실행 결과를 본 뒤 추가합니다.

---

⚖️ 2. 실행 — '있을 때 vs 없을 때'

핵심 패턴은 각 케이스를 두 번 돌리는 것 — 스킬 있이(with_skill) 한 번, 스킬 없이(without_skill) 한 번. 비교 기준선이 생깁니다. (기존 스킬 개선 시엔 이전 버전을 기준선으로.)

• 결과는 iteration-N/ 디렉토리에 케이스별로 정리, 각 케이스는 with/without 하위 폴더
• 각 실행은 깨끗한 컨텍스트에서 시작해야 함 (Claude Code의 서브에이전트처럼 매번 새 세션)
• 타이밍 데이터(토큰·소요시간)도 기록 — 품질은 좋아져도 토큰이 3배라면 다른 트레이드오프니까

---

✅ 3. Assertion(검증문) 작성

출력이 만족해야 할 검증 가능한 문장들. 첫 실행 결과를 본 뒤 추가합니다.

좋은 assertion	약한 assertion
"출력 파일이 유효한 JSON이다" (코드로 검증 가능)	"출력이 좋다" (채점 불가)
"차트에 축 라벨이 있다" (구체·관찰 가능)	"정확히 'Total Revenue: $X' 문구를 쓴다" (너무 깨지기 쉬움)

글쓰기 톤·디자인처럼 객관화하기 어려운 건 assertion이 아니라 사람 리뷰로 잡습니다.

---

📝 4. 채점(Grading)

각 assertion을 실제 출력에 대조해 PASS/FAIL + 구체적 증거를 기록합니다. 증거는 의견이 아니라 출력을 인용·참조해야 해요.

{
  "text": "양쪽 축에 라벨이 있다",
  "passed": false,
  "evidence": "Y축은 'Revenue ($)'로 라벨됨, X축은 라벨 없음"
}

• 기계적 체크(유효 JSON·행 수·파일 존재)는 LLM보다 스크립트가 안정적
• PASS엔 구체적 증거를 요구하라. "Summary" 제목만 있고 알맹이가 없으면 FAIL
• 채점하며 assertion 자체도 점검 — 항상 통과/항상 실패/검증 불가한 것은 다음 회차에 수정

두 버전 비교엔 블라인드 비교도 유용 — 어느 버전인지 숨기고 LLM 심판에게 조직·가독·완성도를 평가시키면 편향 없이 종합 품질을 잡습니다.

---

📈 5. 집계 & 패턴 분석

회차별 통계를 benchmark.json으로 모읍니다. 핵심은 delta — 스킬이 무엇을 들이고(시간·토큰↑) 무엇을 사는가(통과율↑).

예: 스킬 통과율 0.83 vs 무스킬 0.33 → delta +0.50. 13초·1700토큰 더 쓰고 통과율 50%p 올랐다면 충분히 가치 있음. 토큰 2배에 2%p 개선이면 글쎄.

• 양쪽에서 항상 통과하는 assertion은 제거 — 스킬 가치를 부풀릴 뿐
• 양쪽에서 항상 실패면 assertion이 깨졌거나 테스트가 너무 어려움
• 스킬에선 통과, 무스킬에선 실패 → 여기가 스킬이 가치를 더하는 지점. 왜 그런지 이해
• 회차 간 결과가 들쭉날쭉(stddev↑)하면 지침이 모호 → 예시·구체성 보강

---

👤 6. 사람 리뷰 & 반복

assertion은 내가 적은 것만 봅니다. 사람은 예상 못 한 문제, "기술적으론 맞지만 핵심을 놓친" 출력을 잡아요. 케이스별로 구체적 피드백을 남기세요("축 라벨 누락" O / "별로임" X).

개선의 핵심: 실패한 assertion + 사람 피드백 + 실행 trace 세 신호와 현재 SKILL.md를 LLM에 함께 주고 수정안을 받는 것. 이때 — 일반화하라 / 스킬을 군더더기 없이 / "왜"를 설명하라 / 반복 작업은 스크립트로 번들.

루프: 개선안 받기 → 적용 → 새 iteration에서 재실행 → 채점·집계 → 사람 리뷰 → 반복. 결과에 만족하거나, 피드백이 계속 비거나, 개선이 멈추면 종료.

---

✍️ 마무리

"되던데?"를 "있을 때 vs 없을 때를 수치로 비교"로 바꾸는 게 eval의 전부입니다. skill-creator 스킬이 이 과정 대부분을 자동화해 줍니다.

👉 다음 편 → [#7] 스킬에 스크립트 넣기

---

📎 출처: 이 글은 Agent Skills 공식 문서 — Evaluating skill output quality (© Anthropic, CC BY 4.0)를 한국어로 번역·재구성한 것입니다.

---