스킬 크리에이터
이 스킬은 효과적인 스킬을 만들기 위한 지침을 제공합니다.
스킬에 대해
스킬은 모듈식의 자체 포함 패키지로, 특화된 지식, 워크플로우, 도구를 제공하여 Claude의 기능을 확장합니다. 스킬을 특정 도메인이나 작업에 대한 '온보딩 가이드'로 생각하세요. 스킬은 일반 목적의 에이전트를 어떤 모델도 완전히 소유할 수 없는 절차적 지식을 갖춘 특화 에이전트로 변환합니다.
스킬이 제공하는 것
- 특화된 워크플로우 - 특정 도메인에 대한 다단계 절차
- 도구 통합 - 특정 파일 형식이나 API 작업을 위한 지침
- 도메인 전문성 - 회사별 지식, 스키마, 비즈니스 로직
- 번들 리소스 - 복잡하고 반복적인 작업을 위한 스크립트, 참조, 자산
스킬의 구조
모든 스킬은 필수 SKILL.md 파일과 선택적 번들 리소스로 구성됩니다:
skill-name/
├── SKILL.md (필수)
│ ├── YAML 프론트매터 메타데이터 (필수)
│ │ ├── name: (필수)
│ │ └── description: (필수)
│ └── 마크다운 지침 (필수)
└── 번들 리소스 (선택)
├── scripts/ - 실행 가능한 코드 (Python/Bash 등)
├── references/ - 필요에 따라 컨텍스트에 로드되는 문서
└── assets/ - 출력에 사용되는 파일 (템플릿, 아이콘, 폰트 등)
SKILL.md (필수)
메타데이터 품질: YAML 프론트매터의 name과 description은 Claude가 스킬을 사용할 시점을 결정합니다. 스킬이 무엇을 하는지, 언제 사용해야 하는지 구체적으로 명시하세요. 3인칭을 사용하세요 (예: "이 스킬은 ...할 때 사용해야 합니다" 대신 "이 스킬을 ...할 때 사용하세요").
번들 리소스 (선택)
스크립트 (scripts/)
결정론적 신뢰성이 필요하거나 반복적으로 재작성되는 작업을 위한 실행 가능한 코드(Python/Bash 등).
- 포함 시점: 동일한 코드가 반복적으로 재작성되거나 결정론적 신뢰성이 필요할 때
- 예시: PDF 회전 작업을 위한
scripts/rotate_pdf.py - 이점: 토큰 효율적, 결정론적, 컨텍스트에 로드하지 않고 실행 가능
- 참고: 패치나 환경별 조정을 위해 Claude가 스크립트를 읽어야 할 수도 있음
참조 (references/)
Claude의 프로세스와 사고에 정보를 제공하기 위해 필요에 따라 컨텍스트에 로드되는 문서 및 참조 자료.
- 포함 시점: Claude가 작업 중 참조해야 하는 문서용
- 예시: 재무 스키마용
references/finance.md, 회사 NDA 템플릿용references/mnda.md, 회사 정책용references/policies.md, API 사양용references/api_docs.md - 사용 사례: 데이터베이스 스키마, API 문서, 도메인 지식, 회사 정책, 상세 워크플로우 가이드
- 이점: SKILL.md를 간결하게 유지, Claude가 필요하다고 판단할 때만 로드
- 모범 사례: 파일이 큰 경우(>10,000단어), SKILL.md에 grep 검색 패턴 포함
- 중복 방지: 정보는 SKILL.md 또는 참조 파일 중 한 곳에만 있어야 하며, 둘 다에 있으면 안 됩니다. 상세 정보는 SKILL.md에 두지 말고 참조 파일을 선호하세요. 이렇게 하면 SKILL.md를 간결하게 유지하면서 컨텍스트 윈도우를 차지하지 않고 정보를 검색 가능하게 만듭니다. SKILL.md에는 필수적인 절차적 지침과 워크플로우 안내만 유지하고, 상세 참조 자료, 스키마, 예시는 참조 파일로 이동하세요.
자산 (assets/)
컨텍스트에 로드되지 않고 Claude가 생성하는 출력물 내에서 사용되는 파일.
- 포함 시점: 스킬이 최종 출력에 사용될 파일이 필요할 때
- 예시: 브랜드 자산용
assets/logo.png, PowerPoint 템플릿용assets/slides.pptx, HTML/React 보일러플레이트용assets/frontend-template/, 타이포그래피용assets/font.ttf - 사용 사례: 템플릿, 이미지, 아이콘, 보일러플레이트 코드, 폰트, 복사되거나 수정되는 샘플 문서
- 이점: 출력 리소스를 문서와 분리, Claude가 파일을 컨텍스트에 로드하지 않고 사용 가능
점진적 공개 설계 원칙
스킬은 컨텍스트를 효율적으로 관리하기 위해 3단계 로딩 시스템을 사용합니다:
- 메타데이터 (name + description) - 항상 컨텍스트에 있음 (~100단어)
- SKILL.md 본문 - 스킬이 트리거될 때 (<5,000단어)
- 번들 리소스 - Claude가 필요에 따라 (무제한*)
*스크립트는 컨텍스트 윈도우에 읽어들이지 않고 실행될 수 있으므로 무제한입니다.
스킬 생성 프로세스
스킬을 생성하려면 "스킬 생성 프로세스"를 순서대로 따르되, 적용되지 않는 명확한 이유가 있는 경우에만 단계를 건너뛰세요.
1단계: 구체적인 예시를 통한 스킬 이해
이 단계는 스킬의 사용 패턴이 이미 명확하게 이해된 경우에만 건너뛰세요. 기존 스킬로 작업할 때도 여전히 가치가 있습니다.
효과적인 스킬을 만들려면 스킬이 어떻게 사용될지에 대한 구체적인 예시를 명확히 이해해야 합니다. 이러한 이해는 사용자의 직접적인 예시나 사용자 피드백으로 검증된 생성된 예시에서 얻을 수 있습니다.
예를 들어, 이미지 편집기 스킬을 구축할 때 관련 질문은 다음과 같습니다:
- "이미지 편집기 스킬이 지원해야 할 기능은 무엇인가요? 편집, 회전, 그 외 다른 것은요?"
- "이 스킬이 어떻게 사용될지 몇 가지 예시를 들어주시겠어요?"
- "사용자가 '이 이미지에서 적목 현상을 제거해줘' 또는 '이 이미지를 회전해줘'와 같은 요청을 할 수 있다고 상상합니다. 이 스킬이 사용될 다른 방식을 생각하시나요?"
- "사용자가 어떤 말을 하면 이 스킬이 트리거되어야 할까요?"
사용자를 압도하지 않으려면 단일 메시지에서 너무 많은 질문을 피하세요. 가장 중요한 질문부터 시작하고 필요에 따라 후속 질문을 하면 효과가 더 좋습니다.
스킬이 지원해야 할 기능에 대한 명확한 감이 생기면 이 단계를 마무리합니다.
2단계: 재사용 가능한 스킬 콘텐츠 계획
구체적인 예시를 효과적인 스킬로 전환하려면 각 예시를 다음 방법으로 분석하세요:
- 처음부터 예시를 어떻게 실행할지 고려
- 이러한 워크플로우를 반복적으로 실행할 때 도움이 될 스크립트, 참조, 자산 식별
예시: "이 PDF를 회전하는 것을 도와줘"와 같은 질문을 처리하는 pdf-editor 스킬을 구축할 때 분석 결과:
- PDF 회전은 매번 동일한 코드를 다시 작성해야 함
- 스킬에 저장할
scripts/rotate_pdf.py스크립트가 도움이 될 것임
예시: "할 일 앱을 만들어줘" 또는 "내 걸음 수를 추적하는 대시보드를 만들어줘"와 같은 질문을 처리하는 frontend-webapp-builder 스킬을 설계할 때 분석 결과:
- 프론트엔드 웹앱을 작성하려면 매번 동일한 HTML/React 보일러플레이트가 필요함
- 기본 HTML/React 프로젝트 파일이 포함된
assets/hello-world/템플릿을 스킬에 저장하는 것이 도움이 될 것임
예시: "오늘 로그인한 사용자는 몇 명인가요?"와 같은 질문을 처리하는 big-query 스킬을 구축할 때 분석 결과:
- BigQuery 쿼리는 매번 테이블 스키마와 관계를 다시 발견해야 함
- 테이블 스키마를 문서화한
references/schema.md파일을 스킬에 저장하는 것이 도움이 될 것임
스킬의 콘텐츠를 확립하려면 각 구체적인 예시를 분석하여 포함할 재사용 가능한 리소스(스크립트, 참조, 자산) 목록을 만드세요.
3단계: 스킬 초기화
이 시점에서 실제로 스킬을 생성합니다.
이 단계는 개발 중인 스킬이 이미 존재하고 반복 또는 패키징이 필요한 경우에만 건너뛰세요. 이 경우 다음 단계로 계속 진행하세요.
처음부터 새 스킬을 만들 때는 항상 init_skill.py 스크립트를 실행하세요. 이 스크립트는 스킬에 필요한 모든 것을 자동으로 포함하는 새 템플릿 스킬 디렉터리를 편리하게 생성하여 스킬 생성 프로세스를 훨씬 더 효율적이고 안정적으로 만듭니다.
사용법:
scripts/init_skill.py <skill-name> --path <output-directory>
스크립트가 수행하는 작업:
- 지정된 경로에 스킬 디렉터리 생성
- 적절한 프론트매터와 TODO 플레이스홀더가 있는 SKILL.md 템플릿 생성
scripts/,references/,assets/예시 리소스 디렉터리 생성- 각 디렉터리에 사용자 지정 또는 삭제 가능한 예시 파일 추가
초기화 후 필요에 따라 생성된 SKILL.md와 예시 파일을 사용자 지정하거나 삭제하세요.
4단계: 스킬 편집
(새로 생성되었거나 기존) 스킬을 편집할 때는 다른 Claude 인스턴스가 사용할 스킬을 만들고 있다는 점을 기억하세요. Claude에게 유익하고 자명하지 않은 정보를 포함하는 데 집중하세요. 어떤 절차적 지식, 도메인별 세부 정보, 또는 재사용 가능한 자산이 다른 Claude 인스턴스가 이러한 작업을 더 효과적으로 실행하는 데 도움이 될지 고려하세요.
재사용 가능한 스킬 콘텐츠로 시작
구현을 시작하려면 위에서 식별된 재사용 가능한 리소스(scripts/, references/, assets/ 파일)부터 시작하세요. 이 단계에는 사용자 입력이 필요할 수 있습니다. 예를 들어, brand-guidelines 스킬을 구현할 때 사용자가 assets/에 저장할 브랜드 자산이나 템플릿, 또는 references/에 저장할 문서를 제공해야 할 수 있습니다.
또한 스킬에 필요하지 않은 예시 파일과 디렉터리는 삭제하세요. 초기화 스크립트는 구조를 보여주기 위해 scripts/, references/, assets/에 예시 파일을 생성하지만, 대부분의 스킬은 이들 모두를 필요로 하지 않습니다.
SKILL.md 업데이트
작성 스타일: 전체 스킬을 명령형/부정형 형식(동사 우선 지침)으로 작성하고 2인칭은 사용하지 마세요. 객관적이고 지시적인 언어를 사용하세요 (예: "X를 수행하려면 Y를 하십시오" 대신 "X를 하려면 Y를 해야 합니다" 또는 "X를 해야 한다면"). 이는 AI 소비를 위한 일관성과 명확성을 유지합니다.
SKILL.md를 완성하려면 다음 질문에 답하세요:
- 스킬의 목적은 무엇인가요? (몇 문장으로)
- 스킬은 언제 사용되어야 하나요?
- 실제로 Claude는 스킬을 어떻게 사용해야 하나요? 위에서 개발된 모든 재사용 가능한 스킬 콘텐츠를 참조하여 Claude가 이를 사용하는 방법을 알 수 있도록 해야 합니다.
5단계: 스킬 패키징
스킬이 준비되면 사용자와 공유할 배포 가능한 zip 파일로 패키징해야 합니다. 패키징 프로세스는 먼저 스킬을 자동으로 검증하여 모든 요구 사항을 충족하는지 확인합니다:
scripts/package_skill.py <path/to/skill-folder>
선택적 출력 디렉터리 지정:
scripts/package_skill.py <path/to/skill-folder> ./dist
패키징 스크립트는 다음을 수행합니다:
-
스킬을 자동으로 검증하여 다음을 확인:
- YAML 프론트매터 형식 및 필수 필드
- 스킬 명명 규칙 및 디렉터리 구조
- 설명의 완전성과 품질
- 파일 구성 및 리소스 참조
-
검증이 통과하면 스킬을 패키징하여 스킬 이름으로 명명된 zip 파일(예:
my-skill.zip)을 생성합니다. 이 파일은 모든 파일을 포함하고 배포를 위한 적절한 디렉터리 구조를 유지합니다.
검증이 실패하면 스크립트는 오류를 보고하고 패키지를 생성하지 않고 종료합니다. 유효성 검사 오류를 수정하고 패키징 명령을 다시 실행하세요.
6단계: 반복
스킬을 테스트한 후 사용자가 개선을 요청할 수 있습니다. 이는 종종 스킬을 사용한 직후, 스킬이 어떻게 수행되었는지에 대한 새로운 컨텍스트와 함께 발생합니다.
반복 워크플로우:
- 실제 작업에 스킬 사용
- 어려움 또는 비효율성 발견
- SKILL.md 또는 번들 리소스를 업데이트해야 하는 방법 식별
- 변경 사항 구현 및 다시 테스트