📌 참고: 이 문서는 공식 Claude Code 문서의 원문 + 레퍼런스입니다.

• 원문 링크를 직접 사용하셔도 됩니다
• 이 파일을 .claude/skills/ 하위에 복사하여 스킬로 등록할 수도 있습니다
  하지만, 모든 분기에서 실행하기 위해 reference md 도 필요로 하니 claude code 의 스킬 다운로드 기능을 사용하는 것을 추천합니다.

(2026.03.15 기준)

스킬 생성기

스킬을 새로 만들고 반복적으로 개선하기 위한 스킬입니다.

높은 수준에서, 스킬을 만드는 과정은 다음과 같습니다:

• 스킬이 무엇을 하고 대략 어떻게 해야 하는지 결정합니다
• 스킬 초안을 작성합니다
• 몇 가지 테스트 프롬프트를 만들고 스킬에 접근할 수 있는 claude를 실행합니다
• 사용자가 정성적, 정량적 모두로 결과를 평가하도록 돕습니다
  • 실행이 백그라운드에서 진행되는 동안, 정량적 평가가 없으면 초안을 작성합니다(이미 있다면 그대로 사용하거나 변경이 필요하다고 느끼면 수정할 수 있습니다). 그런 다음 사용자에게 설명합니다(이미 있었다면, 기존 것을 설명합니다)
  • eval-viewer/generate_review.py 스크립트를 사용하여 사용자에게 결과를 보여주고, 정량적 지표도 확인할 수 있게 합니다
• 사용자의 결과 평가 피드백을 기반으로 스킬을 다시 작성합니다(그리고 정량적 벤치마크에서 명백한 결함이 발견된 경우에도)
• 만족할 때까지 반복합니다
• 테스트 세트를 확장하고 더 큰 규모로 다시 시도합니다

이 스킬을 사용할 때의 역할은 사용자가 이 과정의 어디에 있는지 파악하고 이 단계들을 진행하도록 돕는 것입니다. 예를 들어, 사용자가 "X를 위한 스킬을 만들고 싶어요"라고 말할 수 있습니다. 그들이 의미하는 바를 좁히고, 초안을 작성하고, 테스트 케이스를 작성하고, 평가 방법을 결정하고, 모든 프롬프트를 실행하고, 반복하는 것을 도울 수 있습니다.

반면에, 이미 스킬 초안이 있을 수도 있습니다. 이 경우 바로 평가/반복 부분으로 갈 수 있습니다.

물론, 항상 유연해야 하며 사용자가 "많은 평가를 실행할 필요 없어요, 그냥 함께 작업합시다"라고 하면, 대신 그렇게 할 수 있습니다.

그런 다음 스킬이 완성된 후(하지만 다시, 순서는 유연합니다), 스킬 설명 개선기를 실행할 수도 있습니다. 이를 위한 별도의 스크립트가 있어 스킬의 트리거링을 최적화합니다.

좋습니다.

사용자와의 소통

스킬 생성기는 코딩 용어에 대한 익숙함이 매우 다양한 사람들이 사용할 수 있습니다. 들어보셨는지 모르겠지만(어떻게 아시겠어요, 아주 최근에 시작된 것인데), 지금 Claude의 힘에 영감을 받아 배관공들이 터미널을 열고, 부모님과 조부모님이 "npm 설치 방법"을 검색하는 트렌드가 있습니다. 반면에, 대다수의 사용자는 아마 상당히 컴퓨터에 능숙할 것입니다.

따라서 소통 방식을 결정하기 위해 맥락 단서에 주의를 기울이세요! 기본적인 경우, 대략적인 기준을 알려드리면:

• "evaluation"과 "benchmark"는 경계선상이지만 괜찮습니다
• "JSON"과 "assertion"은 사용자가 이것들이 무엇인지 알고 있다는 확실한 단서를 보기 전에는 설명 없이 사용하지 않는 것이 좋습니다

의심스러우면 용어를 간략히 설명해도 괜찮으며, 사용자가 이해할지 확신이 없으면 짧은 정의로 용어를 명확히 해도 됩니다.

---

스킬 생성

의도 파악

사용자의 의도를 이해하는 것부터 시작합니다. 현재 대화에 사용자가 캡처하고 싶은 워크플로가 이미 포함되어 있을 수 있습니다(예: "이것을 스킬로 만들어 주세요"라고 말하는 경우). 그렇다면, 대화 이력에서 먼저 답을 추출합니다 — 사용된 도구, 단계의 순서, 사용자가 한 수정, 관찰된 입출력 형식. 사용자가 빈 부분을 채워야 할 수 있으며, 다음 단계로 진행하기 전에 확인을 받아야 합니다.

1. 이 스킬이 Claude에게 무엇을 할 수 있게 해야 하나요?
2. 이 스킬이 언제 트리거되어야 하나요? (어떤 사용자 문구/맥락)
3. 예상되는 출력 형식은 무엇인가요?
4. 스킬이 작동하는지 확인하기 위해 테스트 케이스를 설정해야 하나요? 객관적으로 검증 가능한 출력(파일 변환, 데이터 추출, 코드 생성, 고정된 워크플로 단계)이 있는 스킬은 테스트 케이스의 이점을 얻습니다. 주관적인 출력(글쓰기 스타일, 예술)이 있는 스킬은 보통 필요하지 않습니다. 스킬 유형에 따라 적절한 기본값을 제안하되, 사용자가 결정하도록 합니다.

인터뷰 및 리서치

엣지 케이스, 입출력 형식, 예제 파일, 성공 기준, 의존성에 대해 능동적으로 질문합니다. 이 부분이 정리될 때까지 테스트 프롬프트 작성을 기다립니다.

사용 가능한 MCP를 확인합니다 - 리서치에 유용하다면(문서 검색, 유사한 스킬 찾기, 모범 사례 조회), 서브에이전트가 사용 가능하면 병렬로, 그렇지 않으면 인라인으로 리서치합니다. 사용자의 부담을 줄이기 위해 맥락을 준비해 옵니다.

SKILL.md 작성

사용자 인터뷰를 기반으로, 다음 구성 요소를 채웁니다:

• name: 스킬 식별자
• description: 언제 트리거되는지, 무엇을 하는지. 이것이 주요 트리거링 메커니즘입니다 - 스킬이 하는 일과 사용해야 하는 구체적인 맥락을 모두 포함합니다. 모든 "사용 시기" 정보는 본문이 아닌 여기에 들어갑니다. 참고: 현재 Claude는 스킬을 "과소 트리거"하는 경향이 있습니다 -- 유용할 때 사용하지 않는 것입니다. 이를 방지하기 위해 스킬 설명을 약간 "적극적으로" 만들어 주세요. 예를 들어, "간단하고 빠른 대시보드를 구축하여 내부 Anthropic 데이터를 표시하는 방법."이라고 쓰는 대신, "간단하고 빠른 대시보드를 구축하여 내부 Anthropic 데이터를 표시하는 방법. 사용자가 대시보드, 데이터 시각화, 내부 메트릭을 언급하거나, 명시적으로 '대시보드'를 요청하지 않더라도 어떤 종류의 회사 데이터를 표시하고 싶어할 때 반드시 이 스킬을 사용하세요."라고 쓸 수 있습니다.
• compatibility: 필요한 도구, 의존성 (선택 사항, 거의 필요하지 않음)
• 나머지 스킬 내용 :)

스킬 작성 가이드

스킬의 구조

skill-name/
├── SKILL.md (필수)
│   ├── YAML frontmatter (name, description 필수)
│   └── Markdown 지침
└── Bundled Resources (선택)
    ├── scripts/    - 결정적/반복적 작업을 위한 실행 가능 코드
    ├── references/ - 필요에 따라 컨텍스트에 로드되는 문서
    └── assets/     - 출력에 사용되는 파일 (템플릿, 아이콘, 폰트)

점진적 공개

스킬은 3단계 로딩 시스템을 사용합니다:

1. 메타데이터 (name + description) - 항상 컨텍스트에 포함 (~100 단어)
2. SKILL.md 본문 - 스킬이 트리거될 때마다 컨텍스트에 포함 (500줄 이하가 이상적)
3. 번들 리소스 - 필요에 따라 (무제한, 스크립트는 로딩 없이 실행 가능)

이 단어 수는 대략적이며 필요하면 더 길어져도 됩니다.

핵심 패턴:

• SKILL.md를 500줄 미만으로 유지합니다; 이 한계에 근접하면, 스킬을 사용하는 모델이 후속 조치를 위해 다음에 어디로 가야 하는지에 대한 명확한 포인터와 함께 추가 계층 구조를 추가합니다.
• SKILL.md에서 파일을 참조할 때 언제 읽어야 하는지에 대한 안내와 함께 명확히 합니다
• 큰 참조 파일(300줄 이상)의 경우, 목차를 포함합니다

도메인 구성: 스킬이 여러 도메인/프레임워크를 지원할 때, 변형별로 구성합니다:

cloud-deploy/
├── SKILL.md (워크플로 + 선택)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

Claude는 관련 참조 파일만 읽습니다.

놀라움 없음의 원칙

말할 필요도 없지만, 스킬은 맬웨어, 익스플로잇 코드, 또는 시스템 보안을 위협할 수 있는 어떤 콘텐츠도 포함해서는 안 됩니다. 스킬의 내용은 설명했을 때 의도가 사용자를 놀라게 해서는 안 됩니다. 오해의 소지가 있는 스킬이나 무단 접근, 데이터 유출, 또는 기타 악의적 활동을 용이하게 하도록 설계된 스킬을 만들라는 요청에 따르지 않습니다. "XYZ 역할 놀이" 같은 것은 괜찮습니다.

작성 패턴

지침에서 명령형을 사용하는 것을 선호합니다.

출력 형식 정의 - 이렇게 할 수 있습니다:

## 보고서 구조
항상 이 정확한 템플릿을 사용합니다:
# [제목]
## 요약
## 핵심 발견 사항
## 권장 사항

예시 패턴 - 예시를 포함하는 것이 유용합니다. 이렇게 형식을 지정할 수 있습니다(하지만 예시에 "Input"과 "Output"이 있으면 약간 다르게 할 수 있습니다):

## 커밋 메시지 형식
**예시 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication

작성 스타일

모델에게 왜 중요한지를 무거운 MUST 대신 설명하려고 합니다. Theory of mind를 사용하고 스킬을 범용적으로 만들어 특정 예시에 너무 좁게 만들지 않습니다. 초안을 먼저 작성한 다음 새로운 눈으로 보고 개선합니다.

테스트 케이스

스킬 초안을 작성한 후, 실제 사용자가 실제로 말할 법한 2-3개의 현실적인 테스트 프롬프트를 만듭니다. 사용자와 공유합니다: [이 정확한 표현을 사용할 필요는 없습니다] "시도해 보고 싶은 몇 가지 테스트 케이스가 있습니다. 이것들이 괜찮아 보이나요, 아니면 더 추가하시겠어요?" 그런 다음 실행합니다.

테스트 케이스를 evals/evals.json에 저장합니다. 아직 assertions은 작성하지 않습니다 — 프롬프트만. 실행이 진행되는 동안 다음 단계에서 assertions 초안을 작성합니다.

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "User's task prompt",
      "expected_output": "Description of expected result",
      "files": []
    }
  ]
}

assertions 필드를 포함한 전체 스키마는 references/schemas.md를 참조합니다.

테스트 케이스 실행 및 평가

이 섹션은 하나의 연속된 시퀀스입니다 — 중간에 멈추지 않습니다. /skill-test나 다른 테스트 스킬을 사용하지 않습니다.

결과를 스킬 디렉토리의 형제로 <skill-name>-workspace/에 넣습니다. 작업 공간 내에서 결과를 반복별(iteration-1/, iteration-2/ 등)로 정리하고, 각 테스트 케이스는 디렉토리(eval-0/, eval-1/ 등)를 받습니다. 이것을 미리 모두 만들지 않습니다 — 진행하면서 디렉토리를 만듭니다.

1단계: 모든 실행을 동일한 턴에 생성 (with-skill 및 baseline)

각 테스트 케이스에 대해 동일한 턴에 두 개의 서브에이전트를 생성합니다 — 하나는 스킬 있이, 하나는 없이. 이것이 중요합니다: with-skill 실행을 먼저 생성하고 나중에 baseline을 위해 돌아오지 않습니다. 모든 것을 한꺼번에 시작하여 거의 동시에 완료되도록 합니다.

스킬 포함 실행:

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 user cares about — e.g., "the .docx file", "the final CSV">

Baseline 실행 (동일 프롬프트, 하지만 baseline은 맥락에 따라 다름):

• 새 스킬 생성 시: 스킬 없음. 같은 프롬프트, 스킬 경로 없음, without_skill/outputs/에 저장.
• 기존 스킬 개선 시: 이전 버전. 편집 전에 스킬을 스냅샷 (cp -r <skill-path> <workspace>/skill-snapshot/)한 다음 baseline 서브에이전트를 스냅샷에 연결. old_skill/outputs/에 저장.

각 테스트 케이스에 대해 eval_metadata.json을 작성합니다(assertions은 지금은 비워둘 수 있습니다). 각 평가에 단순히 "eval-0"이 아닌, 무엇을 테스트하는지 설명하는 이름을 부여합니다. 이 이름을 디렉토리에도 사용합니다. 이번 반복이 새로운 또는 수정된 평가 프롬프트를 사용하는 경우, 각 새 평가 디렉토리에 이 파일들을 만듭니다 — 이전 반복에서 이어진다고 가정하지 않습니다.

{
  "eval_id": 0,
  "eval_name": "descriptive-name-here",
  "prompt": "The user's task prompt",
  "assertions": []
}

2단계: 실행 진행 중에 assertions 초안 작성

실행이 끝나기를 그냥 기다리지 않습니다 — 이 시간을 생산적으로 사용할 수 있습니다. 각 테스트 케이스에 대한 정량적 assertions 초안을 작성하고 사용자에게 설명합니다. evals/evals.json에 이미 assertions이 있으면, 검토하고 무엇을 확인하는지 설명합니다.

좋은 assertions은 객관적으로 검증 가능하고 설명적인 이름을 가집니다 — 벤치마크 뷰어에서 명확하게 읽혀 결과를 훑어보는 사람이 각각이 무엇을 확인하는지 즉시 이해할 수 있어야 합니다. 주관적인 스킬(글쓰기 스타일, 디자인 품질)은 정성적으로 평가하는 것이 더 낫습니다 — 인간의 판단이 필요한 것에 assertions을 강제하지 않습니다.

초안이 작성되면 eval_metadata.json 파일과 evals/evals.json을 assertions으로 업데이트합니다. 또한 사용자에게 뷰어에서 무엇을 볼 수 있는지 설명합니다 — 정성적 출력물과 정량적 벤치마크 모두.

3단계: 실행 완료 시 타이밍 데이터 캡처

각 서브에이전트 작업이 완료되면, total_tokens와 duration_ms를 포함하는 알림을 받습니다. 이 데이터를 즉시 실행 디렉토리의 timing.json에 저장합니다:

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}

이것이 이 데이터를 캡처할 수 있는 유일한 기회입니다 — 작업 알림을 통해 전달되며 다른 곳에 저장되지 않습니다. 일괄 처리를 시도하기보다 각 알림이 도착할 때 처리합니다.

4단계: 채점, 집계, 뷰어 실행

모든 실행이 완료되면:

1. 각 실행 채점 — 채점 서브에이전트를 생성하거나(또는 인라인으로 채점) agents/grader.md를 읽고 출력물에 대해 각 assertion을 평가합니다. 결과를 각 실행 디렉토리의 grading.json에 저장합니다. grading.json expectations 배열은 text, passed, evidence 필드를 사용해야 합니다(name/met/details나 다른 변형이 아님) — 뷰어가 이 정확한 필드 이름에 의존합니다. 프로그래밍적으로 확인할 수 있는 assertions의 경우, 눈으로 확인하기보다 스크립트를 작성하고 실행합니다 — 스크립트가 더 빠르고, 신뢰할 수 있으며, 반복에 걸쳐 재사용할 수 있습니다.

2. 벤치마크에 집계 — skill-creator 디렉토리에서 집계 스크립트를 실행합니다:

   python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
   

   이것은 각 구성에 대한 pass_rate, time, tokens와 함께 평균 ± 표준편차 및 델타가 포함된 benchmark.json과 benchmark.md를 생성합니다. benchmark.json을 수동으로 생성하는 경우, 뷰어가 기대하는 정확한 스키마는 references/schemas.md를 참조합니다.
   각 with_skill 버전을 해당 baseline 짝 앞에 배치합니다.

3. 분석 패스 수행 — 벤치마크 데이터를 읽고 집계 통계가 숨길 수 있는 패턴을 발견합니다. agents/analyzer.md("벤치마크 결과 분석" 섹션)에서 무엇을 찾아야 하는지 참조합니다 — 스킬에 관계없이 항상 통과하는 assertions(비구별적), 높은 분산 평가(아마도 불안정), 시간/토큰 트레이드오프 등.

4. 뷰어 실행 — 정성적 출력물과 정량적 데이터 모두와 함께:

   nohup python <skill-creator-path>/eval-viewer/generate_review.py \
     <workspace>/iteration-N \
     --skill-name "my-skill" \
     --benchmark <workspace>/iteration-N/benchmark.json \
     > /dev/null 2>&1 &
   VIEWER_PID=$!
   

   반복 2 이상의 경우, --previous-workspace <workspace>/iteration-<N-1>도 전달합니다.

   Cowork / headless 환경: webbrowser.open()을 사용할 수 없거나 디스플레이가 없는 환경에서는, 서버를 시작하는 대신 --static <output_path>를 사용하여 독립형 HTML 파일을 작성합니다. 사용자가 "Submit All Reviews"를 클릭하면 피드백이 feedback.json 파일로 다운로드됩니다. 다운로드 후, 다음 반복이 가져갈 수 있도록 feedback.json을 작업 공간 디렉토리에 복사합니다.

참고: 뷰어를 만들기 위해 generate_review.py를 사용합니다; 커스텀 HTML을 작성할 필요가 없습니다.

5. 사용자에게 알림 — 대략 이런 식으로: "브라우저에서 결과를 열었습니다. 두 개의 탭이 있습니다 — 'Outputs'에서 각 테스트 케이스를 클릭하고 피드백을 남길 수 있고, 'Benchmark'에서 정량적 비교를 볼 수 있습니다. 완료되면 여기로 돌아와서 알려주세요."

사용자가 뷰어에서 보는 것

"Outputs" 탭은 한 번에 하나의 테스트 케이스를 보여줍니다:

• Prompt: 주어진 작업
• Output: 스킬이 생성한 파일, 가능한 경우 인라인으로 렌더링
• Previous Output (반복 2+): 이전 반복의 출력을 보여주는 접힌 섹션
• Formal Grades (채점이 실행된 경우): assertion 통과/실패를 보여주는 접힌 섹션
• Feedback: 입력하면 자동 저장되는 텍스트 박스
• Previous Feedback (반복 2+): 이전의 코멘트, 텍스트 박스 아래에 표시

"Benchmark" 탭은 통계 요약을 보여줍니다: 각 구성에 대한 통과율, 타이밍, 토큰 사용량과 함께 평가별 세부 분석 및 분석가 관찰.

내비게이션은 이전/다음 버튼 또는 화살표 키로 합니다. 완료되면 "Submit All Reviews"를 클릭하여 모든 피드백을 feedback.json에 저장합니다.

5단계: 피드백 읽기

사용자가 완료했다고 알려주면, feedback.json을 읽습니다:

{
  "reviews": [
    {"run_id": "eval-0-with_skill", "feedback": "the chart is missing axis labels", "timestamp": "..."},
    {"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."},
    {"run_id": "eval-2-with_skill", "feedback": "perfect, love this", "timestamp": "..."}
  ],
  "status": "complete"
}

빈 피드백은 사용자가 괜찮다고 생각했다는 의미입니다. 사용자가 구체적인 불만을 제기한 테스트 케이스에 개선을 집중합니다.

완료되면 뷰어 서버를 종료합니다:

kill $VIEWER_PID 2>/dev/null

---

스킬 개선

이것이 루프의 핵심입니다. 테스트 케이스를 실행했고, 사용자가 결과를 검토했으며, 이제 피드백을 기반으로 스킬을 더 좋게 만들어야 합니다.

개선 방법에 대한 사고

1. 피드백에서 일반화합니다. 여기서 일어나고 있는 큰 그림은 백만 번(어쩌면 문자 그대로, 어쩌면 더 많이) 다양한 프롬프트에 걸쳐 사용할 수 있는 스킬을 만들려는 것입니다. 여기서 당신과 사용자는 더 빠르게 진행하기 위해 몇 가지 예시만으로 반복합니다. 사용자는 이 예시들을 속속들이 알고 있으며 새로운 출력물을 빠르게 평가합니다. 하지만 당신과 사용자가 공동 개발하는 스킬이 그 예시에만 작동한다면, 쓸모없습니다. 세세하게 과적합하는 변경이나 억압적으로 제한적인 MUST를 넣기보다, 고집스러운 문제가 있다면 다른 메타포를 사용하거나 다른 작업 패턴을 추천해볼 수 있습니다. 시도하는 것이 상대적으로 저렴하고 어쩌면 훌륭한 것을 발견할 수도 있습니다.

2. 프롬프트를 간결하게 유지합니다. 기여하지 않는 것들을 제거합니다. 최종 출력물만이 아닌 전사록도 반드시 읽습니다 — 스킬이 모델로 하여금 비생산적인 일에 많은 시간을 낭비하게 만드는 것처럼 보이면, 그렇게 하도록 만드는 스킬의 부분들을 제거하고 결과를 볼 수 있습니다.

3. 이유를 설명합니다. 모델에게 요청하는 모든 것의 이유를 설명하기 위해 노력합니다. 오늘날의 LLM은 똑똑합니다. 좋은 theory of mind를 가지고 있으며 좋은 프레임이 주어지면 기계적인 지시를 넘어 정말로 일을 해낼 수 있습니다. 사용자의 피드백이 간결하거나 답답해 보이더라도, 실제로 작업을 이해하고 사용자가 왜 그것을 쓴 건지, 그리고 실제로 무엇을 쓴 건지 이해한 다음 이 이해를 지시사항에 전달하려고 합니다. 만약 모든 대문자로 ALWAYS나 NEVER를 쓰거나 매우 엄격한 구조를 사용하고 있다면, 그것은 경고 신호입니다 — 가능하다면 이유를 재구성하고 설명하여 모델이 왜 요청하는 것이 중요한지 이해하도록 합니다. 그것이 더 인간적이고, 강력하며, 효과적인 접근입니다.

4. 테스트 케이스 간 반복되는 작업을 찾습니다. 테스트 실행의 전사록을 읽고 서브에이전트들이 모두 독립적으로 유사한 헬퍼 스크립트를 작성했거나 같은 다단계 접근을 취했는지 확인합니다. 3개의 테스트 케이스 모두에서 서브에이전트가 create_docx.py나 build_chart.py를 작성했다면, 그것은 스킬이 해당 스크립트를 번들해야 한다는 강력한 신호입니다. 한 번 작성하여 scripts/에 넣고, 스킬에 그것을 사용하라고 알립니다. 이렇게 하면 모든 향후 호출에서 바퀴를 다시 발명하는 것을 절약합니다.

이 작업은 꽤 중요하며(여기서 연간 수십억 달러의 경제적 가치를 창출하려고 합니다!) 생각하는 시간이 병목이 아닙니다; 시간을 들여 정말 숙고하세요. 수정 초안을 작성한 다음 새로운 시각으로 보고 개선하는 것을 제안합니다. 정말로 최선을 다해 사용자의 입장에서 그들이 원하고 필요로 하는 것을 이해합니다.

반복 루프

스킬을 개선한 후:

1. 개선 사항을 스킬에 적용합니다
2. 모든 테스트 케이스를 새로운 iteration-<N+1>/ 디렉토리에서 다시 실행합니다. baseline 실행도 포함합니다. 새 스킬을 만드는 경우, baseline은 항상 without_skill(스킬 없음)입니다 — 이것은 반복에 걸쳐 동일합니다. 기존 스킬을 개선하는 경우, baseline으로 무엇이 적절한지 판단합니다: 사용자가 가지고 온 원래 버전, 또는 이전 반복.
3. --previous-workspace를 이전 반복에 지정하여 리뷰어를 실행합니다
4. 사용자가 검토하고 완료했다고 알려줄 때까지 기다립니다
5. 새로운 피드백을 읽고, 다시 개선하고, 반복합니다

다음이 될 때까지 계속합니다:

• 사용자가 만족한다고 합니다
• 피드백이 모두 비어 있습니다 (모든 것이 좋아 보입니다)
• 의미 있는 진전을 이루지 못하고 있습니다

---

고급: 블라인드 비교

두 버전의 스킬 간에 더 엄격한 비교가 필요한 상황(예: 사용자가 "새 버전이 실제로 더 나은가요?"라고 묻는 경우)을 위해, 블라인드 비교 시스템이 있습니다. 세부 사항은 agents/comparator.md와 agents/analyzer.md를 읽으세요. 기본 아이디어는: 어느 것이 어느 것인지 알려주지 않고 독립적인 에이전트에게 두 출력물을 주고 품질을 판단하게 하는 것입니다. 그런 다음 왜 승자가 이겼는지 분석합니다.

이것은 선택 사항이며, 서브에이전트가 필요하고, 대부분의 사용자는 필요하지 않습니다. 인간 리뷰 루프가 보통 충분합니다.

---

설명 최적화

SKILL.md frontmatter의 description 필드는 Claude가 스킬을 호출할지 결정하는 주요 메커니즘입니다. 스킬을 만들거나 개선한 후, 더 나은 트리거링 정확도를 위해 설명을 최적화할 것을 제안합니다.

1단계: 트리거 평가 쿼리 생성

20개의 평가 쿼리를 만듭니다 — 트리거해야 하는 것과 트리거하지 말아야 하는 것의 혼합. JSON으로 저장합니다:

[
  {"query": "the user prompt", "should_trigger": true},
  {"query": "another prompt", "should_trigger": false}
]

쿼리는 현실적이어야 하며 Claude Code나 Claude.ai 사용자가 실제로 입력할 법한 것이어야 합니다. 추상적인 요청이 아닌, 구체적이고 세부적인 요청이어야 합니다. 예를 들어, 파일 경로, 사용자의 직업이나 상황에 대한 개인적 맥락, 열 이름과 값, 회사 이름, URL. 약간의 배경 이야기. 일부는 소문자이거나 약어, 오타, 또는 캐주얼한 말투를 포함할 수 있습니다. 다양한 길이를 혼합하고, 명확한 것보다는 엣지 케이스에 집중합니다(사용자가 검토할 기회를 갖게 됩니다).

나쁜 예: "Format this data", "Extract text from PDF", "Create a chart"

좋은 예: "ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think"

트리거해야 하는 쿼리(8-10개)의 경우, 커버리지에 대해 생각합니다. 같은 의도의 다른 표현을 원합니다 — 일부는 격식체, 일부는 캐주얼. 사용자가 스킬이나 파일 유형을 명시적으로 이름 짓지 않지만 분명히 필요한 경우를 포함합니다. 흔하지 않은 사용 사례와 이 스킬이 다른 것과 경쟁하지만 승리해야 하는 경우를 추가합니다.

트리거하지 말아야 하는 쿼리(8-10개)의 경우, 가장 가치 있는 것은 근접 실패입니다 — 스킬과 키워드나 개념을 공유하지만 실제로는 다른 것이 필요한 쿼리. 인접 도메인, 단순한 키워드 매칭은 트리거하지만 실제로는 그러지 말아야 하는 모호한 표현, 그리고 쿼리가 스킬이 하는 것과 관련이 있지만 다른 도구가 더 적절한 맥락을 생각합니다.

피해야 할 핵심: 트리거하지 말아야 하는 쿼리를 명백히 관련 없게 만들지 않습니다. PDF 스킬의 부정 테스트로 "Write a fibonacci function"은 너무 쉽습니다 — 아무것도 테스트하지 않습니다. 부정 케이스는 진정으로 까다로워야 합니다.

2단계: 사용자와 검토

HTML 템플릿을 사용하여 사용자에게 평가 세트를 제시합니다:

1. assets/eval_review.html에서 템플릿을 읽습니다
2. 자리표시자를 교체합니다:
   • __EVAL_DATA_PLACEHOLDER__ → 평가 항목의 JSON 배열 (따옴표 없이 — JS 변수 할당입니다)
   • __SKILL_NAME_PLACEHOLDER__ → 스킬 이름
   • __SKILL_DESCRIPTION_PLACEHOLDER__ → 스킬의 현재 설명
3. 임시 파일에 작성하고(예: /tmp/eval_review_<skill-name>.html) 엽니다: open /tmp/eval_review_<skill-name>.html
4. 사용자가 쿼리를 편집하고, should-trigger를 토글하고, 항목을 추가/제거한 다음 "Export Eval Set"을 클릭할 수 있습니다
5. 파일이 ~/Downloads/eval_set.json에 다운로드됩니다 — 여러 개가 있는 경우(예: eval_set (1).json) Downloads 폴더에서 가장 최근 버전을 확인합니다

이 단계는 중요합니다 — 나쁜 평가 쿼리는 나쁜 설명으로 이어집니다.

3단계: 최적화 루프 실행

사용자에게 알립니다: "이것은 시간이 좀 걸릴 것입니다 — 최적화 루프를 백그라운드에서 실행하고 주기적으로 확인하겠습니다."

평가 세트를 작업 공간에 저장한 다음 백그라운드에서 실행합니다:

python -m scripts.run_loop \
  --eval-set <path-to-trigger-eval.json> \
  --skill-path <path-to-skill> \
  --model <model-id-powering-this-session> \
  --max-iterations 5 \
  --verbose

현재 세션을 구동하는 모델 ID(시스템 프롬프트에서)를 사용하여 트리거링 테스트가 사용자가 실제로 경험하는 것과 일치하도록 합니다.

실행되는 동안, 주기적으로 출력을 tail하여 사용자에게 어떤 반복에 있는지와 점수가 어떤지 업데이트합니다.

이것은 전체 최적화 루프를 자동으로 처리합니다. 평가 세트를 60% 훈련과 40% 유보 테스트로 분할하고, 현재 설명을 평가하며(각 쿼리를 3회 실행하여 신뢰할 수 있는 트리거율을 얻음), 실패한 것을 기반으로 개선을 제안하도록 Claude를 호출합니다. 훈련과 테스트 모두에서 각 새로운 설명을 재평가하며, 최대 5번 반복합니다. 완료되면 브라우저에 반복별 결과를 보여주는 HTML 보고서를 열고 best_description이 포함된 JSON을 반환합니다 — 과적합을 피하기 위해 훈련 점수가 아닌 테스트 점수로 선택됩니다.

스킬 트리거링 작동 방식

트리거링 메커니즘을 이해하면 더 나은 평가 쿼리를 설계하는 데 도움이 됩니다. 스킬은 이름 + 설명과 함께 Claude의 available_skills 목록에 표시되며, Claude는 해당 설명을 기반으로 스킬을 참조할지 결정합니다. 중요한 점은 Claude가 자체적으로 쉽게 처리할 수 있는 작업에 대해서만 스킬을 참조하지 않는다는 것입니다 — "이 PDF를 읽어줘"와 같은 간단한 한 단계 쿼리는 설명이 완벽하게 일치해도 스킬을 트리거하지 않을 수 있습니다. Claude가 기본 도구로 직접 처리할 수 있기 때문입니다. 복잡한, 다단계, 또는 전문적인 쿼리는 설명이 일치할 때 안정적으로 스킬을 트리거합니다.

이것은 평가 쿼리가 Claude가 실제로 스킬을 참조하는 것이 도움이 될 만큼 충분히 실질적이어야 한다는 것을 의미합니다. "read file X"와 같은 간단한 쿼리는 좋은 테스트 케이스가 아닙니다 — 설명 품질에 관계없이 스킬을 트리거하지 않습니다.

4단계: 결과 적용

JSON 출력에서 best_description을 가져와 스킬의 SKILL.md frontmatter를 업데이트합니다. 사용자에게 전/후를 보여주고 점수를 보고합니다.

---

패키지 및 제시 (present_files 도구가 사용 가능한 경우에만)

present_files 도구에 대한 접근 권한이 있는지 확인합니다. 없으면 이 단계를 건너뜁니다. 있으면, 스킬을 패키징하고 .skill 파일을 사용자에게 제시합니다:

python -m scripts.package_skill <path/to/skill-folder>

패키징 후, 설치할 수 있도록 결과 .skill 파일 경로를 사용자에게 안내합니다.

---

Claude.ai 전용 지침

Claude.ai에서는 핵심 워크플로(초안 → 테스트 → 검토 → 개선 → 반복)가 동일하지만, Claude.ai에는 서브에이전트가 없기 때문에 일부 메커니즘이 변경됩니다. 다음을 적용합니다:

테스트 케이스 실행: 서브에이전트가 없으므로 병렬 실행이 불가합니다. 각 테스트 케이스에 대해, 스킬의 SKILL.md를 읽은 다음 그 지시를 따라 테스트 프롬프트를 직접 수행합니다. 하나씩 합니다. 이것은 독립적인 서브에이전트보다 덜 엄격합니다(스킬을 작성하고 실행도 하니 전체 맥락을 가지고 있습니다), 하지만 유용한 점검입니다 — 그리고 인간 리뷰 단계가 보완합니다. Baseline 실행은 건너뜁니다 — 요청대로 스킬을 사용하여 작업을 완료합니다.

결과 검토: 브라우저를 열 수 없는 경우(예: Claude.ai의 VM에 디스플레이가 없거나, 원격 서버에 있는 경우), 브라우저 리뷰어를 완전히 건너뜁니다. 대신, 대화에서 직접 결과를 제시합니다. 각 테스트 케이스에 대해 프롬프트와 출력물을 보여줍니다. 출력물이 사용자가 봐야 하는 파일(예: .docx나 .xlsx)이면, 파일 시스템에 저장하고 다운로드하고 검사할 수 있도록 위치를 알려줍니다. 인라인으로 피드백을 요청합니다: "이거 어떻게 보이세요? 변경할 것이 있나요?"

벤치마킹: 정량적 벤치마킹은 건너뜁니다 — 서브에이전트 없이는 의미 있는 baseline 비교에 의존하기 때문입니다. 사용자의 정성적 피드백에 집중합니다.

반복 루프: 이전과 동일합니다 — 스킬을 개선하고, 테스트 케이스를 다시 실행하고, 피드백을 요청합니다 — 중간에 브라우저 리뷰어만 없을 뿐입니다. 파일 시스템이 있으면 여전히 결과를 반복 디렉토리에 정리할 수 있습니다.

설명 최적화: 이 섹션은 claude CLI 도구(구체적으로 claude -p)가 필요하며, Claude Code에서만 사용할 수 있습니다. Claude.ai에서는 건너뜁니다.

블라인드 비교: 서브에이전트가 필요합니다. 건너뜁니다.

패키징: package_skill.py 스크립트는 Python과 파일 시스템이 있는 곳이면 어디서든 작동합니다. Claude.ai에서 실행하면 사용자가 결과 .skill 파일을 다운로드할 수 있습니다.

기존 스킬 업데이트: 사용자가 새로 만드는 것이 아니라 기존 스킬을 업데이트하라고 요청할 수 있습니다. 이 경우:

• 원래 이름을 보존합니다. 스킬의 디렉토리 이름과 name frontmatter 필드를 확인합니다 -- 변경하지 않고 사용합니다. 예: 설치된 스킬이 research-helper이면, research-helper.skill을 출력합니다(research-helper-v2가 아닌).
• 편집하기 전에 쓰기 가능한 위치에 복사합니다. 설치된 스킬 경로가 읽기 전용일 수 있습니다. /tmp/skill-name/에 복사하고, 거기서 편집하고, 복사본에서 패키징합니다.
• 수동으로 패키징하는 경우, /tmp/에서 먼저 준비한 다음 출력 디렉토리에 복사합니다 -- 권한 때문에 직접 쓰기가 실패할 수 있습니다.

---

Cowork 전용 지침

Cowork에 있다면, 알아야 할 주요 사항:

• 서브에이전트가 있으므로, 메인 워크플로(테스트 케이스를 병렬로 생성, baseline 실행, 채점 등)가 모두 작동합니다. (하지만 타임아웃으로 심각한 문제가 발생하면, 병렬이 아닌 직렬로 테스트 프롬프트를 실행해도 됩니다.)
• 브라우저나 디스플레이가 없으므로, 평가 뷰어를 생성할 때 서버를 시작하는 대신 --static <output_path>를 사용하여 독립형 HTML 파일을 작성합니다. 그런 다음 사용자가 클릭하여 브라우저에서 HTML을 열 수 있는 링크를 제공합니다.
• 어떤 이유에서인지, Cowork 설정은 테스트를 실행한 후 Claude가 평가 뷰어를 생성하는 것을 꺼리게 만드는 것 같으므로, 다시 한번 강조합니다: Cowork에 있든 Claude Code에 있든, 테스트를 실행한 후에는 항상 인간이 직접 수정하기 전에 예시를 볼 수 있도록 generate_review.py를 사용하여 평가 뷰어를 생성해야 합니다(자체 boutique html 코드를 작성하는 것이 아님). 미리 사과하지만 대문자로 말하겠습니다: 입력을 직접 평가하기 전에 평가 뷰어를 생성하세요. 가능한 한 빨리 인간 앞에 놓아야 합니다!
• 피드백은 다르게 작동합니다: 실행 중인 서버가 없으므로, 뷰어의 "Submit All Reviews" 버튼이 feedback.json을 파일로 다운로드합니다. 거기서 읽을 수 있습니다(먼저 접근 권한을 요청해야 할 수 있습니다).
• 패키징은 작동합니다 — package_skill.py는 Python과 파일 시스템만 필요합니다.
• 설명 최적화(run_loop.py / run_eval.py)는 브라우저가 아닌 subprocess를 통해 claude -p를 사용하므로 Cowork에서도 잘 작동해야 하지만, 스킬을 완전히 마치고 사용자가 좋은 상태라고 동의할 때까지 저장해 두세요.
• 기존 스킬 업데이트: 사용자가 새로 만드는 것이 아닌 기존 스킬을 업데이트하라고 요청할 수 있습니다. 위의 Claude.ai 섹션의 업데이트 안내를 따릅니다.

---

참조 파일

agents/ 디렉토리에는 전문화된 서브에이전트를 위한 지침이 포함되어 있습니다. 해당 서브에이전트를 생성해야 할 때 읽습니다.

• agents/grader.md — 출력물에 대해 assertions을 평가하는 방법
• agents/comparator.md — 두 출력물 간 블라인드 A/B 비교 방법
• agents/analyzer.md — 한 버전이 다른 것을 이긴 이유를 분석하는 방법

references/ 디렉토리에는 추가 문서가 있습니다:

• references/schemas.md — evals.json, grading.json 등의 JSON 구조

---

강조를 위해 핵심 루프를 한 번 더 반복합니다:

• 스킬이 무엇에 관한 것인지 파악합니다
• 스킬을 초안 작성하거나 편집합니다
• 테스트 프롬프트에 대해 스킬에 접근할 수 있는 claude를 실행합니다
• 사용자와 함께 출력물을 평가합니다:
  • benchmark.json을 만들고 eval-viewer/generate_review.py를 실행하여 사용자가 검토할 수 있게 합니다
  • 정량적 평가를 실행합니다
• 당신과 사용자가 만족할 때까지 반복합니다
• 최종 스킬을 패키징하여 사용자에게 반환합니다.

작업을 잊지 않도록 TodoList가 있다면 단계를 추가하세요. Cowork에 있다면, "평가 JSON을 만들고 eval-viewer/generate_review.py를 실행하여 인간이 테스트 케이스를 검토할 수 있게 합니다"를 TodoList에 구체적으로 넣어 실행되도록 합니다.

행운을 빕니다!