name: skill-creator description: 효과적인 스킬 생성 가이드. 사용자가 Claude의 기능을 전문 지식, 워크플로우, 도구 통합으로 확장하는 새 스킬을 만들거나 기존 스킬을 업데이트하려 할 때 사용한다. license: Complete terms in LICENSE.txt

스킬 크리에이터

효과적인 스킬 생성을 위한 가이드를 제공하는 스킬이다.

스킬이란

스킬은 전문 지식, 워크플로우, 도구를 제공하여 Claude의 기능을 확장하는 모듈화된 자기 완결형 패키지다. 특정 도메인이나 작업을 위한 "온보딩 가이드"라고 생각하면 된다. 스킬은 범용 에이전트인 Claude를 어떤 모델도 완전히 갖출 수 없는 절차적 지식을 갖춘 전문 에이전트로 변환한다.

스킬이 제공하는 것

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

핵심 원칙

간결함이 핵심

컨텍스트 윈도우는 공공재다. 스킬은 Claude가 필요로 하는 모든 것과 컨텍스트 윈도우를 공유한다: 시스템 프롬프트, 대화 기록, 다른 스킬의 메타데이터, 실제 사용자 요청.

기본 가정: Claude는 이미 매우 똑똑하다. Claude가 이미 알지 못하는 컨텍스트만 추가한다. 각 정보에 대해 "Claude가 정말 이 설명이 필요한가?"와 "이 문단이 토큰 비용을 정당화하는가?"를 질문한다.

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

적절한 자유도 설정

작업의 취약성과 가변성에 맞게 구체성 수준을 조정한다:

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

중간 자유도 (의사코드 또는 매개변수가 있는 스크립트): 선호하는 패턴이 존재하거나, 약간의 변형이 허용되거나, 구성이 동작에 영향을 미칠 때 사용한다.

낮은 자유도 (특정 스크립트, 적은 매개변수): 작업이 취약하고 오류가 발생하기 쉽거나, 일관성이 중요하거나, 특정 순서를 따라야 할 때 사용한다.

Claude가 경로를 탐색한다고 생각하면 된다: 절벽이 있는 좁은 다리에는 특정 가드레일(낮은 자유도)이 필요하고, 열린 들판에서는 많은 경로(높은 자유도)가 허용된다.

스킬의 구조

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

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

SKILL.md (필수)

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

프론트매터 (YAML): name과 description 필드를 포함한다. 이것은 Claude가 스킬 사용 시점을 결정하기 위해 읽는 유일한 필드이므로, 스킬이 무엇인지, 언제 사용해야 하는지를 명확하고 포괄적으로 설명하는 것이 매우 중요하다.
본문 (마크다운): 스킬 사용을 위한 지침과 안내. 스킬이 트리거된 후에만 로드된다 (트리거되는 경우).

번들 리소스 (선택)

스크립트 (`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가 필요하다고 판단할 때만 로드됨
모범 사례: 파일이 큰 경우 (>10k 단어), SKILL.md에 grep 검색 패턴을 포함한다
중복 방지: 정보는 SKILL.md나 레퍼런스 파일 중 한 곳에만 있어야 하며 둘 다에 있으면 안 된다. 정보가 스킬에 정말 핵심적인 것이 아니라면 레퍼런스 파일에 상세 정보를 두는 것을 선호한다—이렇게 하면 SKILL.md가 간결해지면서 컨텍스트 윈도우를 독점하지 않고 정보를 발견할 수 있게 된다. 필수적인 절차 지침과 워크플로우 안내만 SKILL.md에 유지하고, 상세 참조 자료, 스키마, 예제는 레퍼런스 파일로 옮긴다.

에셋 (`assets/`)

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

포함 시점: 스킬이 최종 출력에 사용할 파일이 필요할 때
예시: 브랜드 에셋용 assets/logo.png, 파워포인트 템플릿용 assets/slides.pptx, HTML/React 보일러플레이트용 assets/frontend-template/, 타이포그래피용 assets/font.ttf
사용 사례: 템플릿, 이미지, 아이콘, 보일러플레이트 코드, 폰트, 복사하거나 수정할 샘플 문서
장점: 출력 리소스를 문서와 분리하고, 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: 레퍼런스가 있는 고수준 가이드

# PDF 처리

## 빠른 시작

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

## 고급 기능

- **폼 채우기**: 전체 가이드는 [FORMS.md](FORMS.md) 참조
- **API 레퍼런스**: 모든 메서드는 [REFERENCE.md](REFERENCE.md) 참조
- **예제**: 일반적인 패턴은 [EXAMPLES.md](EXAMPLES.md) 참조

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

패턴 2: 도메인별 구성

여러 도메인이 있는 스킬의 경우, 관련 없는 컨텍스트 로드를 피하기 위해 도메인별로 콘텐츠를 구성한다:

bigquery-skill/
├── SKILL.md (개요 및 탐색)
└── reference/
    ├── finance.md (수익, 청구 지표)
    ├── sales.md (기회, 파이프라인)
    ├── product.md (API 사용량, 기능)
    └── marketing.md (캠페인, 귀속)

사용자가 영업 지표에 대해 물으면, Claude는 sales.md만 읽는다.

마찬가지로, 여러 프레임워크나 변형을 지원하는 스킬은 변형별로 구성한다:

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

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

패턴 3: 조건부 세부사항

기본 콘텐츠를 보여주고 고급 콘텐츠로 링크한다:

# 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 스크립트를 스킬에 저장하면 도움이 된다

예시: "할 일 앱 만들어줘"나 "걸음 수 추적 대시보드 만들어줘"와 같은 쿼리를 위한 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 인스턴스가 이러한 작업을 더 효과적으로 실행하는 데 도움이 될 절차적 지식, 도메인별 세부사항, 재사용 가능한 에셋이 무엇인지 고려한다.

검증된 디자인 패턴 학습하기

스킬의 필요에 따라 다음 도움이 되는 가이드를 참조한다:

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

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

재사용 가능한 스킬 콘텐츠로 시작하기

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

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

스킬에 필요 없는 예제 파일과 디렉토리는 삭제해야 한다. 초기화 스크립트는 구조를 보여주기 위해 scripts/, references/, assets/에 예제 파일을 생성하지만, 대부분의 스킬은 모두 필요하지 않다.

SKILL.md 업데이트

작성 가이드라인: 항상 명령형/지시형을 사용한다.

프론트매터

name과 description이 포함된 YAML 프론트매터를 작성한다:

name: 스킬 이름
description: 스킬의 주요 트리거 메커니즘이며, Claude가 언제 스킬을 사용해야 하는지 이해하는 데 도움을 준다.
- 스킬이 하는 일과 사용 시점의 특정 트리거/컨텍스트를 모두 포함한다.
- 모든 "언제 사용하는지" 정보는 여기에 포함한다 - 본문에는 넣지 않는다. 본문은 트리거 후에만 로드되므로, 본문의 "이 스킬을 사용할 때" 섹션은 Claude에게 도움이 되지 않는다.
- docx 스킬의 설명 예시: "변경 추적, 주석, 서식 보존, 텍스트 추출을 지원하는 포괄적인 문서 생성, 편집, 분석. Claude가 전문 문서(.docx 파일)를 다룰 때 사용: (1) 새 문서 생성, (2) 콘텐츠 수정 또는 편집, (3) 변경 추적 작업, (4) 주석 추가, 또는 기타 문서 작업"

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

본문

스킬과 번들 리소스 사용 지침을 작성한다.

5단계: 스킬 패키징

스킬 개발이 완료되면, 사용자와 공유할 배포 가능한 .skill 파일로 패키징해야 한다. 패키징 프로세스는 모든 요구사항을 충족하는지 확인하기 위해 먼저 자동으로 스킬을 검증한다:

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

선택적 출력 디렉토리 지정:

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

패키징 스크립트가 하는 일:

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

검증 실패 시, 스크립트는 오류를 보고하고 패키지를 생성하지 않고 종료한다. 검증 오류를 수정하고 패키징 명령을 다시 실행한다.

6단계: 반복

스킬을 테스트한 후, 사용자가 개선을 요청할 수 있다. 종종 스킬 사용 직후에 스킬이 어떻게 수행되었는지에 대한 생생한 컨텍스트와 함께 발생한다.

반복 워크플로우:

실제 작업에 스킬 사용
어려움이나 비효율성 인지
SKILL.md나 번들 리소스를 어떻게 업데이트해야 하는지 식별
변경 구현 및 재테스트

Name	skill-creator
Description	효과적인 스킬 생성 가이드. 사용자가 Claude의 기능을 전문 지식, 워크플로우, 도구 통합으로 확장하는 새 스킬을 만들거나 기존 스킬을 업데이트하려 할 때 사용한다.

skill-creator

SKILL.md