herbertschrotter-blip/claude-skills-bpm

스킬 크리에이터

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

높은 수준에서 스킬 생성 과정은 다음과 같습니다:

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

이 스킬을 사용할 때 여러분의 임무는 사용자가 이 과정 중 어디에 있는지 파악하고, 그 단계를 진행하도록 도와주는 것입니다. 예를 들어, 사용자가 "나는 X를 위한 스킬을 만들고 싶어"라고 하면, 그 의미를 좁히고 초안을 작성하며 테스트 케이스를 만들고, 평가 방법을 결정한 후 모든 프롬프트를 실행하고 반복하도록 도울 수 있습니다.

반면, 사용자가 이미 스킬 초안을 가지고 있다면, 평가/반복 부분으로 바로 넘어갈 수 있습니다.

물론 항상 유연해야 하며, 사용자가 "평가를 많이 돌릴 필요 없어, 그냥 감으로 해보자"고 하면 그렇게 할 수도 있습니다.

스킬이 완성된 후에는 (순서는 유연하지만) 스킬 설명 개선기를 실행하여 스킬 트리거링을 최적화할 수도 있습니다. 이를 위한 별도 스크립트가 따로 있습니다.

좋나요? 좋습니다.

사용자와의 커뮤니케이션

스킬 크리에이터는 코딩 전문 용어에 대한 친숙도가 다양한 사람들이 사용할 가능성이 있습니다. 아직 들어보지 못했다면 (최근에야 시작된 트렌드이지만), Claude의 힘이 배관공들로 하여금 터미널을 열게 하고, 부모님과 조부모님께 "npm 설치 방법"을 검색하게 만드는 현상이 있습니다. 반면에 대다수의 사용자는 상당히 컴퓨터에 능숙할 것입니다.

따라서 문맥 신호에 주의하여 커뮤니케이션 방식을 조정하세요! 기본적인 경우, 몇 가지 예시를 들자면:

• "평가"와 "벤치마크"는 경계선에 있지만 괜찮습니다.
• "JSON"과 "어서션" 같은 용어는 사용자가 해당 용어를 설명 없이 사용해도 이해할 것이라는 명확한 신호가 있을 때만 사용하세요.

의심스러우면 용어를 간략히 설명해도 괜찮으며, 사용자가 이해할지 확신이 서지 않으면 짧은 정의를 덧붙이세요.

---

스킬 만들기

의도 파악

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

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

인터뷰 및 리서치

에지 케이스, 입/출력 형식, 예제 파일, 성공 기준, 의존성에 대해 사전에 질문하세요. 이 부분이 확실해질 때까지 테스트 프롬프트 작성을 기다리세요.

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

SKILL.md 작성

사용자 인터뷰를 바탕으로 다음 구성 요소를 채우세요:

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

스킬 작성 가이드

스킬의 구조

skill-name/
├── SKILL.md (필수)
│   ├── YAML 머리말 (이름, 설명 필수)
│   └── 마크다운 지침
└── 번들 리소스 (선택 사항)
    ├── scripts/    - 결정적/반복적 작업을 위한 실행 코드
    ├── references/ - 필요할 때 컨텍스트에 로드되는 문서
    └── assets/     - 출력에 사용되는 파일 (템플릿, 아이콘, 폰트)

프로그레시브 디스클로저 (점진적 정보 공개)

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

1. 메타데이터 (이름 + 설명) - 항상 컨텍스트에 있음 (~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 역할극" 같은 것은 괜찮습니다.

작성 패턴

지침에는 명령형을 사용하는 것이 좋습니다.

출력 형식 정의 - 다음과 같이 할 수 있습니다:

## 보고서 구조
항상 다음 정확한 템플릿을 사용하세요:
# [제목]
## 요약
## 주요 발견사항
## 권장사항

예제 패턴 - 예제를 포함하는 것이 유용합니다. 다음과 같이 형식을 지정할 수 있습니다 (하지만 예제에 "입력"과 "출력"이 있다면 약간 다르게 할 수도 있습니다):

## 커밋 메시지 형식
**예제 1:**
입력: JWT 토큰을 사용한 사용자 인증 추가
출력: feat(auth): implement JWT-based authentication

작성 스타일

모델에게 왜 중요한지 설명하려고 노력하세요. 무거운 "MUST" 대신 이론적 사고를 사용하고, 스킬을 특정 예제에 지나치게 좁히지 말고 일반적으로 만드세요. 초안을 작성한 후 새로운 시각으로 다시 보고 개선하세요.

테스트 케이스

스킬 초안을 작성한 후 2-3개의 현실적인 테스트 프롬프트(실제 사용자가 말할 법한 것)를 생각해 보세요. 사용자와 공유하세요: (정확히 이 언어를 사용할 필요는 없습니다) "여기 제가 시도해 보고 싶은 몇 가지 테스트 케이스가 있습니다. 이것들이 적절해 보이나요, 아니면 더 추가하시겠어요?" 그런 다음 실행하세요.

테스트 케이스를 evals/evals.json에 저장하세요. 아직 어서션을 작성하지 마세요 — 프롬프트만 작성하세요. 다음 단계에서 실행이 진행되는 동안 어서션 초안을 작성할 것입니다.

{
  "skill_name": "예시-스킬",
  "evals": [
    {
      "id": 1,
      "prompt": "사용자의 작업 프롬프트",
      "expected_output": "예상 결과 설명",
      "files": []
    }
  ]
}

전체 스키마(나중에 추가할 assertions 필드 포함)는 references/schemas.md를 참조하세요.

테스트 케이스 실행 및 평가

이 섹션은 연속적인 과정입니다 — 중간에 멈추지 마세요. /skill-test나 다른 테스트 스킬을 사용하지 마세요.

결과를 스킬 디렉토리와 같은 레벨에 <skill-name>-workspace/로 저장하세요. 워크스페이스 내에서는 반복별로 결과를 정리하고 (iteration-1/, iteration-2/ 등), 그 안에 각 테스트 케이스마다 디렉토리를 만드세요 (eval-0/, eval-1/ 등). 처음부터 모두 만들지 말고, 진행하면서 디렉토리를 만드세요.

1단계: 모든 실행을 동시에 시작 (스킬 있음 AND 기준점)

각 테스트 케이스에 대해 같은 턴에 두 개의 하위 에이전트를 시작하세요 — 하나는 스킬을 사용하고, 다른 하나는 사용하지 않습니다. 이 점이 중요합니다: 먼저 스킬 사용 실행을 시작하고 나중에 기준점을 돌아오지 마세요. 모든 것을 한 번에 시작하여 거의 동시에 완료되도록 하세요.

스킬 사용 실행:

이 작업을 실행하세요:
- 스킬 경로: <스킬-경로>
- 작업: <평가 프롬프트>
- 입력 파일: <평가 파일 (없으면 "없음")>
- 출력 저장 위치: <워크스페이스>/iteration-<N>/eval-<ID>/with_skill/outputs/
- 저장할 출력: <사용자가 원하는 것 — 예: ".docx 파일", "최종 CSV">

기준점 실행 (동일한 프롬프트, 기준점은 맥락에 따라 다름):

• 새 스킬 생성: 스킬 없이. 동일한 프롬프트, 스킬 경로 없음, without_skill/outputs/에 저장.
• 기존 스킬 개선: 이전 버전. 편집 전에 스킬을 스냅샷으로 저장하고 (cp -r <skill-path> <workspace>/skill-snapshot/), 기준점 하위 에이전트가 스냅샷을 가리키도록 합니다. old_skill/outputs/에 저장.

각 테스트 케이스에 대해 eval_metadata.json을 작성하세요 (어서션은 지금 비워 둘 수 있음). 각 평가에 테스트 중인 내용을 기반으로 설명적인 이름을 지정하세요 — 단순히 "eval-0"이 아니라. 이 이름을 디렉토리 이름으로도 사용하세요. 이 반복에서 새 평가 프롬프트를 사용하거나 수정한 경우, 각 새 평가 디렉토리에 대해 이 파일을 만드세요 — 이전 반복에서 가져온 것으로 가정하지 마세요.

{
  "eval_id": 0,
  "eval_name": "설명적인-이름-여기에",
  "prompt": "사용자의 작업 프롬프트",
  "assertions": []
}

2단계: 실행이 진행되는 동안 어서션 초안 작성

실행이 완료되기를 기다리지 마세요 — 이 시간을 생산적으로 사용할 수 있습니다. 각 테스트 케이스에 대한 정량적 어서션 초안을 작성하고 사용자에게 설명하세요. evals/evals.json에 어서션이 이미 존재하는 경우, 검토하고 무엇을 확인하는지 설명하세요.

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

초안이 작성되면 eval_metadata.json 파일과 evals/evals.json을 어서션으로 업데이트하세요. 또한 사용자에게 뷰어에서 무엇을 보게 될지 설명하세요 — 정성적 출력과 정량적 벤치마크 모두.

3단계: 실행이 완료됨에 따라 타이밍 데이터 캡처

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

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

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

4단계: 평가, 집계 및 뷰어 실행

모든 실행이 완료되면:

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

2. 벤치마크로 집계 — 스킬 크리에이터 디렉토리에서 집계 스크립트를 실행하세요:

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

   이 명령은 각 구성에 대해 pass_rate, 시간, 토큰을 포함한 benchmark.json과 benchmark.md를 생성하며, 평균 ± 표준편차와 델타를 제공합니다. benchmark.json을 수동으로 생성하는 경우, 뷰어가 기대하는 정확한 스키마는 references/schemas.md를 참조하세요. 각 with_skill 버전을 해당 기준점보다 먼저 배치하세요.

3. 분석 패스 수행 — 벤치마크 데이터를 읽고 집계 통계가 숨길 수 있는 패턴을 표면화하세요. agents/analyzer.md ("벤치마크 결과 분석" 섹션)에서 무엇을 찾아야 하는지 확인하세요 — 스킬과 관계없이 항상 통과하는 어서션(비판별적), 분산이 큰 평가(아마 불안정할 수 있음), 시간/토큰 트레이드오프 등.

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

   nohup python <skill-creator-path>/eval-viewer/generate_review.py
   

이 스킬은 스킬 생성 및 개선에 관한 내용입니다.