Anthropic Skill Creator의 구조와 동작 원리 - 스킬 개발부터 평가까지

개요

Anthropic의 Skill Creator는 Claude Code 스킬을 체계적으로 개발하고, 테스트하고, 개선할 수 있도록 설계된 도구다. 스킬을 처음 만들 때부터 테스트 케이스 작성, 자동 평가, 반복 개선, 그리고 트리거 정확도 최적화까지 전체 개발 사이클을 하나의 워크플로우로 관리할 수 있다.

단순히 SKILL.md 파일을 작성하는 것을 넘어서, 네 가지 운영 모드(Create, Eval, Improve, Benchmark)와 전용 에이전트 시스템(Grader, Comparator, Analyzer)을 통해 데이터 기반의 스킬 개선이 가능하다.

Skill Creator의 운영 모드와 에이전트 연결 구조를 나타낸 네트워크 다이어그램 (AI 생성 이미지)

---

파일 구조

Skill Creator의 프로젝트 구조는 다음과 같다.

skill-creator/
├── SKILL.md              # 메인 스킬 정의 파일
├── agents/               # 전용 에이전트 정의
│   ├── grader.md         # 채점 에이전트
│   ├── comparator.md     # 블라인드 비교 에이전트
│   └── analyzer.md       # 분석 에이전트
├── scripts/              # 자동화 스크립트
│   ├── aggregate_benchmark.py   # 벤치마크 결과 집계
│   ├── run_eval.py              # 평가 실행
│   ├── run_loop.py              # description 최적화 루프
│   ├── improve_description.py   # 설명 개선
│   ├── generate_report.py       # 리포트 생성
│   ├── package_skill.py         # 스킬 패키징
│   ├── quick_validate.py        # 빠른 검증
│   └── utils.py                 # 유틸리티 함수
├── references/           # 참조 문서
│   └── schemas.md        # JSON 스키마 정의
├── eval-viewer/          # 평가 결과 뷰어
│   ├── generate_review.py  # 리뷰 페이지 생성
│   └── viewer.html         # 결과 표시 HTML
├── assets/               # 정적 리소스
│   └── eval_review.html    # 트리거 평가 리뷰 템플릿
└── LICENSE.txt

---

SKILL.md의 구조

SKILL.md는 모든 스킬의 핵심 파일이다. YAML 프론트매터와 마크다운 본문으로 구성된다.

---
name: skill-creator
description: >
  Create new skills, modify and improve existing skills,
  and measure skill performance. Use when users want to
  create a skill from scratch, edit, or optimize an
  existing skill, run evals to test a skill, benchmark
  skill performance with variance analysis, or optimize
  a skill's description for better triggering accuracy.
compatibility:
  - "Requires: subagents (for spawning parallel test runs and grading)"
  - "Optional: MCPs for research during skill development"
---

name 필드는 /skill-creator라는 슬래시 커맨드로 호출할 때 사용되고, description은 Claude가 이 스킬을 언제 로드할지 판단하는 기준이 된다.

본문에는 네 가지 모드별 상세 지시사항이 포함되어 있다. 스킬 작성 가이드, 테스트 실행 방법, 개선 전략, 벤치마킹 절차 등이 모두 하나의 파일 안에 담겨 있다.

Progressive Disclosure 시스템

Skill Creator는 3단계 로딩 시스템을 사용한다.

• Level 1 - 메타데이터: name과 description만 로드 (약 100단어). 항상 컨텍스트에 포함
• Level 2 - SKILL.md 본문: 스킬이 트리거될 때 로드 (500줄 이하 권장)
• Level 3 - 번들 리소스: 필요한 시점에 로드 (scripts, references, assets 등)

이 구조 덕분에 컨텍스트 윈도우를 효율적으로 사용하면서도 필요한 정보에 접근할 수 있다.

Skill Creator의 운영 모드와 에이전트 연결 구조를 나타낸 네트워크 다이어그램 (AI 생성 이미지)

---

네 가지 운영 모드

1. Create 모드 - 스킬 작성

새로운 스킬을 처음부터 만드는 모드다. 인터랙티브 Q&A를 통해 사용자의 의도를 파악한다.

 

캡처하는 정보:

• 스킬이 Claude에게 어떤 기능을 부여하는지
• 언제 트리거되어야 하는지
• 출력 형식은 무엇인지
• 테스트 케이스를 설정할지 여부

이후 자동으로 SKILL.md를 생성하는데, 이때 핵심 원칙이 있다. Description을 "pushy"하게 작성하라는 것이다. 스킬이 트리거되지 않는 문제(undertriggering)가 과도하게 트리거되는 문제보다 훨씬 흔하기 때문이다.

예를 들어, 대시보드 스킬의 description이라면 단순히 "대시보드를 만드는 스킬"이 아니라, "사용자가 대시보드, 데이터 시각화, 내부 메트릭스, 또는 어떤 종류의 데이터 표시를 언급할 때 이 스킬을 사용하라"는 식으로 적극적인 표현을 권장한다.

2. Eval 모드 - 테스트 케이스 실행

작성한 스킬의 품질을 정량적으로 평가하는 모드다. 핵심은 with-skill 실행과 baseline 실행을 병렬로 수행하는 것이다.

 

실행 흐름:

1. 테스트 프롬프트를 정의하고, 스킬이 적용된 실행과 적용되지 않은 실행을 동시에 시작
2. 실행이 진행되는 동안 assertion(검증 기준)을 작성
3. 실행 완료 시 타이밍 데이터를 기록
4. Grader 에이전트가 각 실행 결과를 채점
5. 결과를 집계하고 Eval Viewer에서 확인

evals.json 구조:

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "이 CSV 파일에서 매출 상위 5개 항목을 추출해줘",
      "expected_output": "매출 기준 정렬된 상위 5개 항목 목록",
      "files": ["sample_data.csv"]
    }
  ]
}

3. Improve 모드 - 반복 개선

평가 결과를 바탕으로 스킬을 개선하는 모드다. 단순히 실패한 테스트를 통과시키는 것이 아니라, 일반화 가능한 개선을 추구한다.

개선 원칙:

• 일반화: 특정 테스트만 통과하는 수정이 아닌, 다양한 프롬프트에서 작동하는 패턴으로 개선
• 프롬프트 경량화: 효과가 없는 지시사항은 제거. 출력뿐 아니라 실행 트랜스크립트를 분석
• 이유 설명: ALWAYS/NEVER 같은 강압적 표현 대신, 왜 그렇게 해야 하는지 근거를 제시
• 반복 작업 번들링: 서브에이전트가 독립적으로 같은 헬퍼 스크립트를 만들었다면, scripts/ 폴더에 통합

반복 루프:

1. 스킬에 개선 사항 적용
2. 모든 테스트 케이스를 iteration-<N+1>/ 디렉토리에서 재실행
3. 이전 이터레이션과 비교하며 Eval Viewer 실행
4. 사용자 피드백 대기
5. 피드백 반영 → 다시 개선 → 반복

사용자가 만족하거나, 모든 피드백이 비어있거나, 더 이상 의미 있는 진전이 없을 때 루프를 종료한다.

4. Benchmark 모드 - 성능 측정

동일한 테스트를 여러 번 실행하여 분산(variance)을 분석하는 모드다. 단일 실행에서는 보이지 않는 패턴을 포착할 수 있다.

Progressive Disclosure 3단계 로딩 시스템 구조도 (AI 생성 이미지)

---

핵심 에이전트 시스템

Skill Creator의 핵심은 세 가지 전용 에이전트다. 각각 독립적인 서브에이전트로 실행되어 객관적인 평가를 보장한다.

Grader 에이전트 - 채점

Grader는 두 가지 역할을 수행한다. 결과 채점과 평가 기준 자체에 대한 비평이다.

 

채점 프로세스:

1. 실행 트랜스크립트를 처음부터 끝까지 읽는다
2. 출력 파일을 직접 검사한다 (트랜스크립트의 주장에만 의존하지 않음)
3. 각 assertion에 대해 증거를 찾고 PASS/FAIL을 판정한다

PASS 기준: 증거가 진짜 작업 완료를 반영할 때. 파일이 존재하는 것만으로는 부족하고, 내용이 정확해야 한다.

FAIL 기준: 증거가 없거나, 증거가 기대와 모순되거나, 우연히 기준을 충족한 경우.

Grader의 독특한 점은 평가 기준 자체를 비평한다는 것이다. 예를 들어, "출력에 이름 'John Smith'가 포함되어 있어야 한다"는 assertion이 있다면, Grader는 "이름이 언급만 되어도 통과할 수 있으니, 실제로 주요 연락처로 표시되는지까지 검증해야 한다"는 피드백을 준다. 약한 assertion이 통과하는 것이 실패보다 더 위험하다는 철학이 반영된 설계다.

Comparator 에이전트 - 블라인드 비교

Comparator의 핵심 원칙은 블라인드 평가다. 두 개의 출력을 A와 B로만 받고, 어떤 시스템이 어떤 출력을 만들었는지 알지 못한 상태에서 품질을 판단한다.

 

평가 프로세스:

1. 두 출력을 모두 읽고 분석
2. 작업에 맞는 평가 루브릭(rubric)을 자동 생성
3. 콘텐츠 점수(정확성, 완전성, 정밀도)와 구조 점수(조직성, 포맷팅, 사용성)를 각각 1-5점으로 채점
4. 종합 점수를 1-10 스케일로 산출
5. 승자를 결정하고 근거를 설명

루브릭은 작업 유형에 따라 자동으로 조정된다. PDF 양식이면 "필드 정렬"과 "텍스트 가독성"이, 데이터 출력이면 "스키마 정확성"이 평가 기준이 된다.

Analyzer 에이전트 - 분석

Analyzer는 두 가지 모드로 작동한다.

Post-hoc 분석: Comparator가 승자를 결정한 후, 양쪽 스킬과 트랜스크립트를 분석하여 왜 이겼는지, 패배한 쪽은 어떻게 개선할 수 있는지 구체적인 제안을 만든다.

개선 제안은 우선순위(high/medium/low)와 카테고리(instructions, tools, examples, error_handling, structure, references)로 분류된다. "high"는 비교 결과를 바꿀 수 있는 수준, "medium"은 품질 향상이지만 승패는 바뀌지 않을 수준이다.

벤치마크 분석: 여러 번의 실행 결과에서 집계 지표만으로는 보이지 않는 패턴을 찾는다. 어떤 assertion이 항상 통과하는지, 어떤 eval이 불안정한지(flaky), 스킬이 실행 시간에 어떤 영향을 주는지 등을 분석한다.

네 가지 운영 모드의 순환 구조 (AI 생성 이미지)

---

전체 워크플로우

실제 사용 흐름을 단계별로 정리하면 다음과 같다.

Step 1: 스킬 작성

/skill-creator 명령으로 시작하면 인터랙티브 Q&A를 통해 의도를 파악한다. 이후 적절한 디렉토리 구조와 SKILL.md를 자동 생성한다.

Step 2: 테스트 케이스 실행

with-skill 실행과 baseline 실행을 병렬로 시작한다. 실행이 진행되는 동안 검증 기준(assertion)을 작성한다. 핵심은 정량적이고 객관적으로 검증 가능한 assertion을 만드는 것이다.

Step 3: 채점 및 평가

Grader 에이전트가 각 실행 결과를 채점하고, aggregate_benchmark.py 스크립트가 결과를 집계한다. 이후 Eval Viewer가 브라우저에서 결과를 시각화한다.

Eval Viewer는 두 개의 탭을 제공한다.

• Outputs 탭: 각 실행의 출력을 검토하고 피드백을 남길 수 있는 인터페이스
• Benchmark 탭: 정량적 비교 데이터를 보여주는 대시보드

Step 4: 개선

피드백을 기반으로 스킬을 수정하고, 새로운 iteration 디렉토리에서 재실행한다. --previous-workspace 옵션으로 이전 이터레이션과 비교할 수 있다.

Step 5: Description 최적화

스킬의 기능이 확정되면 트리거 정확도를 높이는 작업을 진행한다.

1. 20개의 트리거 평가 쿼리 생성 (트리거되어야 할 것 8-10개 + 트리거되면 안 되는 것 8-10개)
2. 사용자 검토용 HTML 페이지 생성
3. run_loop.py로 자동 최적화 루프 실행
4. 최적화된 description을 SKILL.md에 반영

트리거 평가 쿼리는 현실적이어야 한다. "데이터를 포맷팅해줘" 같은 추상적 요청이 아니라, "보스가 방금 보낸 xlsx 파일에 수익률 퍼센트 컬럼을 추가해야 하는데..." 같은 구체적이고 맥락이 포함된 요청으로 작성한다.

세 가지 핵심 에이전트가 맞물려 동작하는 구조 (AI 생성 이미지)

---

스크립트 상세

aggregate_benchmark.py

여러 eval 디렉토리의 grading.json 파일을 읽어 하나의 benchmark.json과 benchmark.md로 통합한다. pass rate, 실행 시간, 토큰 사용량 등을 집계한다.

python -m scripts.aggregate_benchmark workspace/iteration-1 --skill-name my-skill

run_loop.py

Description 최적화를 자동으로 반복 실행하는 스크립트다. 현재 description으로 트리거 평가를 실행하고, 실패한 케이스를 분석하여 description을 개선한다.

python -m scripts.run_loop \
  --eval-set trigger-eval.json \
  --skill-path ./my-skill \
  --model claude-opus-4-6 \
  --max-iterations 5 \
  --verbose

run_eval.py

개별 평가를 실행하는 스크립트. 서브에이전트를 생성하여 지정된 프롬프트로 스킬을 실행하고 결과를 저장한다.

quick_validate.py

스킬의 기본 구조가 올바른지 빠르게 검증한다. YAML 프론트매터, 필수 필드, 파일 참조 등을 확인한다.

package_skill.py

완성된 스킬을 배포 가능한 형태로 패키징한다.

---

Eval Viewer 상세

Eval Viewer는 평가 결과를 브라우저에서 인터랙티브하게 검토할 수 있는 도구다.

generate_review.py가 iteration 디렉토리의 데이터를 읽어 viewer.html 템플릿과 결합하여 리뷰 페이지를 생성한다.

nohup python eval-viewer/generate_review.py \
  workspace/iteration-1 \
  --skill-name "my-skill" \
  --benchmark workspace/iteration-1/benchmark.json \
  > /dev/null 2>&1 &

두 번째 이터레이션부터는 --previous-workspace 옵션으로 이전 결과와 나란히 비교할 수 있다. 원격 환경에서는 --static 옵션으로 독립 실행형 HTML 파일을 생성한다.

사용자는 Outputs 탭에서 각 실행 결과에 피드백을 남기고, 완료되면 "Export" 버튼을 누른다. 이 피드백은 feedback.json으로 저장되어 다음 개선 루프의 입력이 된다.

---

블라인드 비교 심화

블라인드 비교는 두 버전의 스킬을 엄밀하게 비교할 때 사용하는 기능이다.

 

작동 방식:

1. 두 스킬 버전으로 동일한 프롬프트를 실행
2. 출력을 A와 B로 라벨링 (어떤 버전인지 숨김)
3. Comparator 에이전트가 블라인드 상태에서 품질 판단
4. 승자 결정 후 Analyzer 에이전트가 원인 분석

이 방식의 장점은 확증 편향(confirmation bias)을 제거한다는 것이다. 새 버전이 더 좋을 것이라는 기대 없이 순수하게 출력 품질만으로 판단한다.

Comparator는 동점 판정을 거의 하지 않도록 설계되어 있다. 두 출력이 모두 실패하면 "덜 나쁜 쪽"을, 모두 뛰어나면 "미세하게 더 나은 쪽"을 선택한다.

---

마무리

Skill Creator는 스킬 개발을 "감으로 만들고 직접 써보며 수정하는" 방식에서 "데이터 기반으로 측정하고 체계적으로 개선하는" 방식으로 바꿔주는 도구다.

핵심 가치를 정리하면 다음과 같다.

• 구조화된 평가: 주관적 판단이 아닌 정량적 assertion으로 품질 측정
• 블라인드 비교: 편향 없는 A/B 테스트로 개선 효과 검증
• 반복 개선 루프: 피드백 → 수정 → 재평가의 체계적 순환
• 트리거 최적화: description을 자동으로 개선하여 스킬 발동 정확도 향상

스킬 하나를 잘 만드는 것과 스킬이 실제로 잘 작동하는지 확인하는 것은 다른 문제다. Skill Creator는 이 간극을 메워주는 도구로, Claude Code 스킬 생태계에서 품질 관리의 기준을 제시하고 있다.

---

참고 자료

• Anthropic Skills GitHub Repository
• Skill Creator SKILL.md
• Claude Code Skills 공식 문서
• Skill Authoring Best Practices

이 글은 Claude Code를 활용하여 작성되었습니다.