스킬 생성기

효과적인 스킬 생성을 위한 가이드.

스킬이란

스킬은 Claude의 기능을 확장하는 모듈화된 자체 완결형 패키지. 특정 도메인이나 작업을 위한 전문 지식, 워크플로우, 도구를 제공하여 범용 에이전트를 전문 에이전트로 변환한다.

스킬이 제공하는 것

•전문 워크플로우 - 특정 도메인의 다단계 절차
•도구 통합 - 특정 파일 형식이나 API 작업 지침
•도메인 전문성 - 회사별 지식, 스키마, 비즈니스 로직
•번들 리소스 - 복잡하고 반복적인 작업을 위한 스크립트, 참조 문서, 에셋

핵심 원칙

간결함이 핵심

컨텍스트 윈도우는 공공재. 스킬은 시스템 프롬프트, 대화 기록, 다른 스킬의 메타데이터, 사용자 요청과 컨텍스트 윈도우를 공유한다.

기본 전제: Claude는 이미 매우 똑똑하다. Claude가 모르는 정보만 추가할 것. 각 정보를 "Claude가 정말 이 설명이 필요한가?", "이 단락이 토큰 비용을 정당화하는가?"로 검증할 것.

장황한 설명보다 간결한 예시를 선호.

적절한 자유도 설정

작업의 취약성과 변동성에 따라 구체성 수준을 조정:

높은 자유도 (텍스트 기반 지침): 여러 접근법이 유효하고, 결정이 맥락에 따라 달라지거나, 휴리스틱이 접근법을 안내할 때.

중간 자유도 (의사코드 또는 파라미터가 있는 스크립트): 선호 패턴이 있고, 일부 변형이 허용되거나, 설정이 동작에 영향을 미칠 때.

낮은 자유도 (특정 스크립트, 적은 파라미터): 작업이 취약하고 오류 발생 가능성이 높거나, 일관성이 중요하거나, 특정 순서를 따라야 할 때.

Claude가 길을 탐색한다고 생각할 것: 절벽 옆 좁은 다리는 구체적 가드레일(낮은 자유도), 탁 트인 들판은 다양한 경로 허용(높은 자유도).

스킬의 구조

모든 스킬은 필수 SKILL.md 파일과 선택적 번들 리소스로 구성:

code

skill-name/
├── SKILL.md (필수)
│   ├── YAML 프론트매터 메타데이터 (필수)
│   │   ├── name: (필수)
│   │   └── description: (필수)
│   └── 마크다운 지침 (필수)
└── 번들 리소스 (선택)
    ├── scripts/          - 실행 가능한 코드 (Python/Bash 등)
    ├── references/       - 필요 시 컨텍스트에 로드되는 문서
    └── assets/           - 출력에 사용되는 파일 (템플릿, 아이콘, 폰트 등)

SKILL.md (필수)

모든 SKILL.md는 다음으로 구성:

•프론트매터 (YAML): name과 description 필드 포함. Claude가 스킬 사용 시점을 결정하기 위해 읽는 유일한 필드이므로, 스킬의 정체와 사용 시점을 명확하고 포괄적으로 기술하는 것이 매우 중요.
•본문 (마크다운): 스킬 사용 지침과 가이드. 스킬이 트리거된 후에만 로드됨.

번들 리소스 (선택)

스크립트 (`scripts/`)

결정론적 신뢰성이 필요하거나 반복적으로 재작성되는 작업을 위한 실행 가능 코드.

•포함 시점: 동일한 코드가 반복 재작성되거나 결정론적 신뢰성이 필요할 때
•예시: PDF 회전 작업을 위한 scripts/rotate_pdf.py
•장점: 토큰 효율적, 결정론적, 컨텍스트에 로드하지 않고 실행 가능
•참고: 패치나 환경별 조정을 위해 Claude가 읽어야 할 수 있음

참조 문서 (`references/`)

Claude의 프로세스와 사고에 정보를 제공하기 위해 필요 시 컨텍스트에 로드되는 문서.

•포함 시점: Claude가 작업 중 참조해야 하는 문서가 있을 때
•예시: 재무 스키마용 references/finance.md, 회사 NDA 템플릿용 references/mnda.md
•용도: 데이터베이스 스키마, API 문서, 도메인 지식, 회사 정책, 상세 워크플로우 가이드
•장점: SKILL.md를 가볍게 유지, Claude가 필요하다고 판단할 때만 로드
•모범 사례: 파일이 큰 경우(>10k 단어) SKILL.md에 grep 검색 패턴 포함
•중복 방지: 정보는 SKILL.md 또는 참조 파일 중 하나에만 존재해야 함. 핵심이 아닌 상세 정보는 참조 파일 선호—SKILL.md를 가볍게 유지하면서 컨텍스트 윈도우를 차지하지 않고 정보를 발견 가능하게 만듦.

에셋 (`assets/`)

컨텍스트에 로드되지 않고, Claude가 생성하는 출력에 사용되는 파일.

•포함 시점: 스킬이 최종 출력에 사용할 파일이 필요할 때
•예시: 브랜드 에셋용 assets/logo.png, 파워포인트 템플릿용 assets/slides.pptx
•용도: 템플릿, 이미지, 아이콘, 보일러플레이트 코드, 폰트, 복사하거나 수정하는 샘플 문서
•장점: 출력 리소스를 문서와 분리, Claude가 컨텍스트에 로드하지 않고 파일 사용 가능

스킬에 포함하지 말아야 할 것

스킬은 기능을 직접 지원하는 필수 파일만 포함해야 한다. 다음과 같은 부수적 문서나 보조 파일을 생성하지 말 것:

•README.md
•INSTALLATION_GUIDE.md
•QUICK_REFERENCE.md
•CHANGELOG.md
•기타

스킬은 AI 에이전트가 해당 작업을 수행하는 데 필요한 정보만 포함해야 한다. 생성 과정, 설정 및 테스트 절차, 사용자 대면 문서 등의 부수적 맥락은 포함하지 말 것.

점진적 공개 설계 원칙

스킬은 3단계 로딩 시스템으로 컨텍스트를 효율적으로 관리:

•메타데이터 (이름 + 설명) - 항상 컨텍스트에 존재 (~100 단어)
•SKILL.md 본문 - 스킬 트리거 시 (<5k 단어)
•번들 리소스 - Claude의 필요에 따라 (스크립트는 컨텍스트 윈도우에 읽지 않고 실행 가능하므로 제한 없음)

점진적 공개 패턴

SKILL.md 본문은 핵심 내용만 포함하고 500줄 이하로 유지하여 컨텍스트 비대화 방지. 이 한계에 근접하면 별도 파일로 분리. 분리 시 SKILL.md에서 참조하고 읽어야 할 시점을 명확히 기술하는 것이 매우 중요.

핵심 원칙: 스킬이 여러 변형, 프레임워크, 옵션을 지원할 때는 SKILL.md에 핵심 워크플로우와 선택 가이드만 유지. 변형별 세부사항(패턴, 예시, 설정)은 별도 참조 파일로 이동.

패턴 1: 참조 문서를 활용한 상위 수준 가이드

markdown

# PDF 처리

## 빠른 시작

pdfplumber로 텍스트 추출:
[코드 예시]

## 고급 기능

- **폼 채우기**: [FORMS.md](FORMS.md)에서 전체 가이드 확인
- **API 참조**: [REFERENCE.md](REFERENCE.md)에서 전체 메서드 확인
- **예시**: [EXAMPLES.md](EXAMPLES.md)에서 일반적인 패턴 확인

Claude는 필요할 때만 FORMS.md, REFERENCE.md, EXAMPLES.md를 로드.

패턴 2: 도메인별 조직화

여러 도메인을 가진 스킬의 경우, 불필요한 컨텍스트 로딩을 피하기 위해 도메인별로 조직화:

code

bigquery-skill/
├── SKILL.md (개요 및 탐색)
└── reference/
    ├── finance.md (매출, 결제 지표)
    ├── sales.md (영업 기회, 파이프라인)
    ├── product.md (API 사용량, 기능)
    └── marketing.md (캠페인, 어트리뷰션)

사용자가 영업 지표를 물으면 Claude는 sales.md만 읽음.

마찬가지로, 여러 프레임워크나 변형을 지원하는 스킬은 변형별로 조직화:

code

cloud-deploy/
├── SKILL.md (워크플로우 + 제공자 선택)
└── references/
    ├── aws.md (AWS 배포 패턴)
    ├── gcp.md (GCP 배포 패턴)
    └── azure.md (Azure 배포 패턴)

사용자가 AWS를 선택하면 Claude는 aws.md만 읽음.

패턴 3: 조건부 세부사항

기본 내용을 보여주고 고급 내용은 링크:

markdown

# DOCX 처리

## 문서 생성

새 문서는 docx-js 사용. [DOCX-JS.md](DOCX-JS.md) 참조.

## 문서 편집

간단한 편집은 XML을 직접 수정.

**변경 추적**: [REDLINING.md](REDLINING.md) 참조
**OOXML 세부사항**: [OOXML.md](OOXML.md) 참조

Claude는 사용자가 해당 기능을 필요로 할 때만 REDLINING.md나 OOXML.md를 읽음.

중요 지침:

•깊은 중첩 참조 금지 - 참조는 SKILL.md에서 한 단계 깊이로 유지. 모든 참조 파일은 SKILL.md에서 직접 링크.
•긴 참조 파일 구조화 - 100줄 이상의 파일은 상단에 목차를 포함하여 Claude가 미리보기 시 전체 범위를 파악 가능하게 할 것.

스킬 생성 프로세스

스킬 생성은 다음 단계로 진행:

•구체적 예시로 스킬 이해
•재사용 가능한 스킬 콘텐츠 계획 (스크립트, 참조, 에셋)
•스킬 초기화 (init_skill.py 실행)
•스킬 편집 (리소스 구현 및 SKILL.md 작성)
•스킬 패키징 (package_skill.py 실행)
•실제 사용 기반 반복 개선

순서대로 수행하되, 해당하지 않는 명확한 이유가 있을 때만 건너뛸 것.

1단계: 구체적 예시로 스킬 이해

스킬의 사용 패턴이 이미 명확히 이해된 경우에만 건너뛸 것. 기존 스킬 작업 시에도 유용.

효과적인 스킬 생성을 위해 스킬이 어떻게 사용될지 구체적 예시를 명확히 이해할 것. 이 이해는 사용자의 직접 예시 또는 사용자 피드백으로 검증된 생성 예시에서 올 수 있다.

예를 들어, image-editor 스킬 구축 시 관련 질문:

•"image-editor 스킬이 어떤 기능을 지원해야 하나요? 편집, 회전, 그 외?"
•"이 스킬이 어떻게 사용될지 예시를 주실 수 있나요?"
•"이 스킬을 트리거해야 하는 사용자 발화는 무엇인가요?"

사용자를 압도하지 않기 위해 한 메시지에 너무 많은 질문 금지. 가장 중요한 질문부터 시작하고 필요 시 후속 질문.

스킬이 지원해야 하는 기능이 명확해지면 이 단계 종료.

2단계: 재사용 가능한 스킬 콘텐츠 계획

구체적 예시를 효과적인 스킬로 전환하기 위해, 각 예시를 분석:

•해당 예시를 처음부터 어떻게 실행할지 고려
•이러한 워크플로우를 반복 실행할 때 어떤 스크립트, 참조, 에셋이 도움이 될지 식별

예시: "이 PDF를 회전해 줘" 같은 쿼리를 처리하는 pdf-editor 스킬 구축 시:

•PDF 회전은 매번 동일한 코드를 재작성해야 함
•scripts/rotate_pdf.py 스크립트를 스킬에 저장하면 유용

예시: "오늘 로그인한 사용자 수는?" 같은 쿼리를 처리하는 big-query 스킬 구축 시:

•BigQuery 쿼리는 매번 테이블 스키마와 관계를 재탐색해야 함
•테이블 스키마를 문서화한 references/schema.md 파일을 스킬에 저장하면 유용

각 구체적 예시를 분석하여 포함할 재사용 리소스 목록 작성: 스크립트, 참조, 에셋.

3단계: 스킬 초기화

이 시점에서 실제로 스킬을 생성.

개발 중인 스킬이 이미 존재하고 반복 개선이나 패키징이 필요한 경우에만 건너뛸 것. 이 경우 다음 단계로 진행.

새 스킬을 처음부터 생성할 때는 항상 init_skill.py 스크립트를 실행할 것. 이 스크립트는 스킬에 필요한 모든 것을 자동 포함하는 템플릿 스킬 디렉토리를 편리하게 생성.

사용법:

bash

scripts/init_skill.py <skill-name> --path <output-directory>

스크립트 동작:

•지정된 경로에 스킬 디렉토리 생성
•적절한 프론트매터와 TODO 플레이스홀더가 있는 SKILL.md 템플릿 생성
•예시 리소스 디렉토리 생성: scripts/, references/, assets/
•각 디렉토리에 커스터마이징 또는 삭제 가능한 예시 파일 추가

초기화 후, 생성된 SKILL.md와 예시 파일을 필요에 따라 커스터마이징하거나 제거.

4단계: 스킬 편집

(새로 생성되거나 기존의) 스킬을 편집할 때, 스킬은 다른 Claude 인스턴스가 사용하기 위해 만들어진다는 점을 기억할 것. Claude에게 유용하고 비자명적인 정보를 포함. 어떤 절차적 지식, 도메인별 세부사항, 재사용 에셋이 다른 Claude 인스턴스의 작업 수행에 도움이 될지 고려.

검증된 디자인 패턴 학습

스킬의 필요에 따라 다음 가이드를 참조:

•다단계 프로세스: 순차적 워크플로우와 조건부 로직은 references/workflows.md 참조
•특정 출력 형식 또는 품질 기준: 템플릿과 예시 패턴은 references/output-patterns.md 참조

이 파일들에는 효과적인 스킬 설계를 위한 검증된 모범 사례가 포함.

재사용 콘텐츠부터 시작

구현을 시작할 때, 위에서 식별한 재사용 리소스부터 시작: scripts/, references/, assets/ 파일. 이 단계에서 사용자 입력이 필요할 수 있음. 예를 들어 brand-guidelines 스킬 구현 시, 사용자가 assets/에 저장할 브랜드 에셋이나 references/에 저장할 문서를 제공해야 할 수 있음.

추가된 스크립트는 실제로 실행하여 버그가 없고 출력이 예상과 일치하는지 테스트해야 함. 유사한 스크립트가 많은 경우 대표 샘플만 테스트하여 모두 작동하는지에 대한 확신을 확보하면서 완료 시간과 균형을 맞출 것.

스킬에 필요하지 않은 예시 파일과 디렉토리는 삭제할 것.

SKILL.md 업데이트

작성 지침: 항상 명령형/부정사 형태 사용.

프론트매터

name과 description으로 YAML 프론트매터 작성:

•name: 스킬 이름
•
description: 스킬의 주요 트리거 메커니즘으로, Claude가 스킬 사용 시점을 이해하는 데 도움을 줌.
- •스킬이 하는 일과 사용 시점/트리거를 모두 포함.
- •모든 "사용 시점" 정보는 여기에 포함 - 본문이 아닌. 본문은 트리거 후에만 로드되므로, 본문의 "이 스킬 사용 시점" 섹션은 Claude에게 도움이 안 됨.

YAML 프론트매터에 다른 필드를 포함하지 말 것.

본문

스킬 및 번들 리소스 사용 지침 작성.

5단계: 스킬 패키징

스킬 개발이 완료되면 사용자와 공유할 배포 가능한 .skill 파일로 패키징해야 함. 패키징 프로세스는 자동으로 먼저 유효성 검사를 수행:

bash

scripts/package_skill.py <path/to/skill-folder>

출력 디렉토리 지정 (선택):

bash

scripts/package_skill.py <path/to/skill-folder> ./dist

패키징 스크립트 동작:

•
유효성 검사 자동 수행:
- •YAML 프론트매터 형식 및 필수 필드
- •스킬 네이밍 규칙 및 디렉토리 구조
- •설명 완전성 및 품질
- •파일 조직 및 리소스 참조
•
유효성 검사 통과 시 패키징, 스킬 이름을 딴 .skill 파일(예: my-skill.skill) 생성. 모든 파일을 포함하고 배포를 위한 적절한 디렉토리 구조 유지. .skill 파일은 .skill 확장자를 가진 zip 파일.

유효성 검사 실패 시 오류를 보고하고 패키지 생성 없이 종료. 유효성 오류를 수정하고 패키징 명령을 다시 실행.

6단계: 반복 개선

스킬 테스트 후 사용자가 개선을 요청할 수 있음. 종종 스킬 사용 직후, 스킬의 성능에 대한 생생한 맥락과 함께 요청됨.

반복 워크플로우:

•실제 작업에서 스킬 사용
•어려움이나 비효율 발견
•SKILL.md나 번들 리소스 업데이트 방법 식별
•변경 구현 및 재테스트

스킬 생성기

스킬이란

스킬이 제공하는 것

핵심 원칙

간결함이 핵심

적절한 자유도 설정

스킬의 구조

SKILL.md (필수)

번들 리소스 (선택)

스크립트 (scripts/)

참조 문서 (references/)

에셋 (assets/)

스킬에 포함하지 말아야 할 것

점진적 공개 설계 원칙

점진적 공개 패턴

스킬 생성 프로세스

1단계: 구체적 예시로 스킬 이해

2단계: 재사용 가능한 스킬 콘텐츠 계획

3단계: 스킬 초기화

4단계: 스킬 편집

검증된 디자인 패턴 학습

재사용 콘텐츠부터 시작

SKILL.md 업데이트

프론트매터

본문

5단계: 스킬 패키징

6단계: 반복 개선

스크립트 (`scripts/`)

참조 문서 (`references/`)

에셋 (`assets/`)