icartsh Skill Creator
이 SKILL은 효과적인 SKILL을 생성하기 위한 지침을 제공합니다.
SKILL에 대하여
SKILL은 특화된 지식, 워크플로우 및 도구를 제공하여 Claude의 기능을 확장하는 모듈화된 독립 패키지입니다. 특정 분야나 작업을 위한 "온보딩 가이드"라고 생각하세요. SKILL은 Claude를 일반 에이전트에서 특정 모델이 온전히 소유하기 어려운 절차적 지식을 갖춘 전문 에이전트로 변화시킵니다.
SKILL이 제공하는 것
- 특화된 워크플로우 - 특정 분야를 위한 다단계 절차
- 도구 통합 - 특정 파일 형식 또는 API 작업 지침
- 도메인 전문 지식 - 회사별 지식, 스키마, 비즈니스 로직
- 번들 리소스 - 복잡하고 반복적인 작업을 위한 스크립트, 참조 문서 및 에셋
핵심 원칙 (Core Principles)
간결함이 핵심 (Concise is Key)
컨텍스트 윈도우(context window)는 공공재와 같습니다. SKILL은 시스템 프롬프트, 대화 히스토리, 다른 SKILL의 메타데이터, 그리고 실제 사용자 요청 등 Claude가 필요로 하는 모든 요소와 컨텍스트 공간을 공유합니다.
기본 전제: Claude는 이미 충분히 똑똑합니다. Claude가 아직 가지고 있지 않은 컨텍스트만 추가하세요. 정보 하나하나에 대해 자문해 보세요: "Claude에게 이 설명이 정말 필요한가?", "이 문단이 소모되는 토큰만큼의 가치가 있는가?"
장황한 설명보다는 간결한 예시를 선호하세요.
적절한 자유도 설정 (Set Appropriate Degrees of Freedom)
작업의 취약성과 변동성에 맞춰 구체화 수준을 조정하세요:
높은 자유도 (텍스트 기반 지침): 여러 접근 방식이 유효하거나, 결정이 컨텍스트에 달려 있거나, 휴리스틱(heuristics)이 접근 방식을 안내할 때 사용합니다.
중간 자유도 (의사코드 또는 파라미터가 있는 스크립트): 선호되는 패턴이 존재하거나, 약간의 변동이 허용되거나, 설정이 동작에 영향을 줄 때 사용합니다.
낮은 자유도 (특정 스크립트, 적은 파라미터): 작업이 취약하고 오류가 발생하기 쉽거나, 일관성이 중요하거나, 특정 순서를 반드시 지켜야 할 때 사용합니다.
Claude가 길을 탐색하는 것을 상상해 보세요: 절벽이 있는 좁은 다리에는 구체적인 보호 난간(낮은 자유도)이 필요하고, 탁 트인 들판에서는 다양한 경로(높은 자유도)가 허용됩니다.
SKILL의 구조 (Anatomy of a Skill)
모든 SKILL은 필수 파일인 SKILL.md와 선택적인 번들 리소스로 구성됩니다:
skill-name/
├── SKILL.md (필수)
│ ├── YAML frontmatter metadata (필수)
│ │ ├── name: (필수)
│ │ └── description: (필수)
│ └── Markdown 지침 (필수)
└── Bundled Resources (선택 사항)
├── scripts/ - 실행 가능한 코드 (Python/Bash 등)
├── references/ - 필요에 따라 컨텍스트에 로드할 문서
└── assets/ - 출력물에 사용될 파일 (템플릿, 아이콘, 폰트 등)
SKILL.md (필수)
모든 SKILL.md는 다음으로 구성됩니다:
- Frontmatter (YAML):
name과description필드를 포함합니다. Claude가 SKILL의 사용 여부를 결정하기 위해 읽는 유일한 필드이므로, SKILL이 무엇인지와 언제 사용해야 하는지에 대해 명확하고 포괄적으로 설명하는 것이 매우 중요합니다. - Body (Markdown): SKILL을 사용하기 위한 지침과 안내입니다. SKILL이 트리거된 '이후'에만 로드됩니다.
번들 리소스 (선택 사항)
스크립트 (scripts/)
결정론적인 신뢰성이 필요하거나 반복적으로 재작성되는 작업을 위한 실행 가능한 코드(Python/Bash 등)입니다.
- 포함 시기: 동일한 코드가 반복적으로 작성되거나 결정론적인(deterministic) 신뢰성이 필요한 경우
- 예시: PDF 회전 작업을 위한
scripts/rotate_pdf.py - 장점: 토큰 효율적이며 결정론적이고, 컨텍스트에 로드하지 않고도 실행될 수 있음
- 참고: 패칭(patching)이나 환경별 조정을 위해 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에는 필수적인 절차 지침과 워크플로우 안내만 유지하고, 상세 참조 자료, 스키마, 예시는 참조 파일로 옮기세요.
에셋 (assets/)
컨텍스트에 로드하도록 의도된 것이 아니라, Claude가 생성하는 출력물 내에서 사용하기 위한 파일입니다.
- 포함 시기: 최종 출력물에 사용될 파일이 SKILL에 필요한 경우
- 예시: 브랜드 에셋용
assets/logo.png, 파워포인트 템플릿용assets/slides.pptx, HTML/React 보일러플레이트용assets/frontend-template/, 타이포그래피용assets/font.ttf - 유스케이스: 템플릿, 이미지, 아이콘, 보일러플레이트 코드, 폰트, 복사하거나 수정하여 사용할 샘플 문서
- 장점: 출력용 리소스를 문서와 분리하며, Claude가 파일을 컨텍스트에 로드하지 않고도 사용할 수 있게 함
SKILL에 포함하지 말아야 할 것
SKILL은 그 기능을 직접적으로 지원하는 필수 파일들만 포함해야 합니다. 다음과 같은 불필요한 문서나 보조 파일들을 만들지 마세요:
- README.md
- INSTALLATION_GUIDE.md
- QUICK_REFERENCE.md
- CHANGELOG.md
- 기타 등등
SKILL에는 AI 에이전트가 주어진 작업을 수행하는 데 필요한 정보만 포함되어야 합니다. 제작 과정에 대한 부수적인 컨텍스트, 설정 및 테스트 절차, 사용자용 문서 등은 포함하지 마세요. 불필요한 문서 파일은 혼란만 가중시킵니다.
점진적 노출 디자인 원칙 (Progressive Disclosure Design Principle)
SKILL은 컨텍스트를 효율적으로 관리하기 위해 3단계 로딩 시스템을 사용합니다:
- 메타데이터 (name + description) - 항상 컨텍스트에 상주 (~100 단어)
- SKILL.md 본문 - SKILL이 트리거될 때 로드 (<5k 단어)
- 번들 리소스 - Claude가 필요할 때 로드 (스크립트는 컨텍스트 로드 없이 실행 가능하므로 용량 제한 없음)
점진적 노출 패턴
컨텍스트 비대화를 최소화하기 위해 SKILL.md 본문은 필수 사항 위주로 500행 미만으로 유지하세요. 이 제한에 도달하면 콘텐츠를 별도 파일로 나누세요. 콘텐츠를 다른 파일로 분리할 때는, SKILL을 읽는 모델이 해당 파일의 존재와 사용 시점을 알 수 있도록 SKILL.md에서 이를 참조하고 언제 읽어야 하는지 명확히 설명하는 것이 매우 중요합니다.
핵심 원칙: SKILL이 여러 변형(variations), 프레임워크 또는 옵션을 지원하는 경우, SKILL.md에는 핵심 워크플로우와 선택 가이드만 유지하세요. 특정 변형에 국한된 세부 사항(패턴, 예시, 설정)은 별도의 참조 파일로 옮기세요.
패턴 1: 참조 문서를 동반한 상위 수준 가이드
# PDF Processing
## 빠른 시작
pdfplumber로 텍스트 추출:
[코드 예시]
## 고급 기능
- **폼 채우기(Form filling)**: 전체 가이드는 [FORMS.md](FORMS.md) 참조
- **API 참조**: 모든 메서드는 [REFERENCE.md](REFERENCE.md) 참조
- **예시**: 일반적인 패턴은 [EXAMPLES.md](EXAMPLES.md) 참조
Claude는 필요할 때만 FORMS.md, REFERENCE.md 또는 EXAMPLES.md를 로드합니다.
패턴 2: 도메인별 조직화
여러 도메인을 가진 SKILL의 경우, 무관한 컨텍스트 로드를 피하기 위해 도메인별로 콘텐츠를 구성하세요:
bigquery-skill/
├── SKILL.md (개요 및 탐색)
└── reference/
├── finance.md (매출, 청구 지표)
├── sales.md (기회, 파이프라인)
├── product.md (API 사용량, 기능)
└── marketing.md (캠페인, 어트리뷰션)
사용자가 매출 지표에 대해 물으면, Claude는 sales.md만 읽습니다.
마찬가지로 여러 프레임워크나 변형을 지원하는 SKILL도 변형별로 정리하세요:
cloud-deploy/
├── SKILL.md (워크플로우 + 프로바이더 선택)
└── references/
├── aws.md (AWS 배포 패턴)
├── gcp.md (GCP 배포 패턴)
└── azure.md (Azure 배포 패턴)
사용자가 AWS를 선택하면, Claude는 aws.md만 읽습니다.
패턴 3: 조건부 세부 사항
기본 콘텐츠를 보여주고, 고급 콘텐츠로 링크를 제공하세요:
# DOCX Processing
## 문서 생성
새 문서에는 docx-js를 사용하세요. [DOCX-JS.md](DOCX-JS.md) 참조.
## 문서 편집
단순한 편집의 경우 XML을 직접 수정하세요.
**수정 내용 추적(tracked changes)의 경우**: [REDLINING.md](REDLINING.md) 참조
**OOXML 세부 사항의 경우**: [OOXML.md](OOXML.md) 참조
Claude는 사용자가 해당 기능을 필요로 할 때만 REDLINING.md 또는 OOXML.md를 읽습니다.
중요 가이드라인:
- 깊은 중첩 참조 지양 - 참조는 SKILL.md에서 한 단계 깊이까지만 유지하세요. 모든 참조 파일은 SKILL.md에서 직접 링크되어야 합니다.
- 긴 참조 파일 구조화 - 100행 이상의 파일은 상단에 목차를 포함하여 Claude가 미리보기 시 전체 범위를 파악할 수 있게 하세요.
SKILL 제작 프로세스 (Skill Creation Process)
SKILL 제작은 다음 단계로 이루어집니다:
- 구체적인 예시를 통한 SKILL 이해 (Understand)
- 재사용 가능한 SKILL 콘텐츠 계획 (Plan)
- SKILL 초기화 (init_skill.py 실행)
- SKILL 편집 (리소스 구현 및 SKILL.md 작성)
- SKILL 패키징 (package_skill.py 실행)
- 실제 사용을 바탕으로 반복 개선 (Iterate)
정당한 사유가 없는 한 이 단계를 순서대로 따르세요.
Step 1: 구체적인 예시를 통한 SKILL 이해
SKILL의 사용 패턴이 이미 명확히 이해된 경우에만 이 단계를 생략하세요. 기존 SKILL을 개선할 때도 이 단계는 가치가 있습니다.
효과적인 SKILL을 제작하려면 SKILL이 어떻게 사용될지에 대한 구체적인 예시를 명확히 이해해야 합니다. 이는 직접적인 사용자 예시나, 사용자 피드백을 통해 검증된 생성 예시를 통해 가능합니다.
예를 들어, image-editor SKILL을 빌드할 때 다음과 같은 질문들이 도움이 됩니다:
- "image-editor SKILL은 어떤 기능을 지원해야 합니까? 편집, 회전, 그 외에 다른 기능은요?"
- "이 SKILL이 어떻게 사용될지에 대한 몇 가지 예를 들어주실 수 있나요?"
- "사용자들이 '이 이미지에서 적목 현상을 제거해줘'나 '이 이미지를 회전시켜줘'와 같은 요청을 할 것 같은데, 또 다른 유스케이스가 있을까요?"
- "사용자가 어떤 말을 했을 때 이 SKILL이 트리거되어야 합니까?"
사용자에게 부담을 주지 않기 위해 한 메시지에 너무 많은 질문을 하지 마세요. 가장 중요한 질문부터 시작하고 효과를 높이기 위해 필요에 따라 후속 질문을 하세요.
SKILL이 지원해야 할 기능에 대한 명확한 감이 잡히면 이 단계를 마칩니다.
Step 2: 재사용 가능한 SKILL 콘텐츠 계획
구체적인 예시를 효과적인 SKILL로 바꾸기 위해, 각 예시를 다음과 같이 분석하세요:
- 해당 예시를 처음부터 어떻게 실행할지 고려
- 이 워크플로우를 반복적으로 실행할 때 도움이 될 스크립트, 참조 문서 및 에셋 식별
예시: "이 PDF를 회전시켜줘"와 같은 쿼리를 처리하기 위한 pdf-editor SKILL을 빌드할 때의 분석:
- PDF를 회전하려면 매번 동일한 코드를 다시 작성해야 함
scripts/rotate_pdf.py스크립트를 SKILL에 저장해두면 도움이 됨
예시: "할 일 앱을 만들어줘"나 "내 걸음 수를 추적할 대시보드를 만들어줘"와 같은 쿼리를 처리하기 위한 frontend-webapp-builder SKILL을 설계할 때의 분석:
- 프런트엔드 웹앱을 작성할 때마다 동일한 보일러플레이트 HTML/React가 필요함
- 보일러플레이트 HTML/React 프로젝트 파일이 포함된
assets/hello-world/템플릿을 SKILL에 저장해두면 도움이 됨
예시: "오늘 몇 명의 사용자가 로그인했지?"와 같은 쿼리를 처리하기 위한 big-query SKILL을 빌드할 때의 분석:
- BigQuery를 쿼리할 때마다 테이블 스키마와 관계를 매번 다시 확인해야 함
- 테이블 스키마를 문서화한
references/schema.md파일을 SKILL에 저장해두면 도움이 됨
SKILL의 콘텐츠를 확립하기 위해, 각 구체적인 예시를 분석하여 포함할 재사용 리소스(스크립트, 참조 문서, 에셋) 목록을 만드세요.
Step 3: SKILL 초기화
이제 실제로 SKILL을 생성할 차례입니다.
개발하려는 SKILL이 이미 존재하고 개선이나 패키징만 필요한 경우에는 이 단계를 생략하고 다음 단계로 진행하세요.
새로운 SKILL을 처음부터 생성할 때는 항상 init_skill.py 스크립트를 실행하세요. 이 스크립트는 SKILL에 필요한 모든 것을 자동으로 포함하는 새 템플릿 SKILL 디렉토리를 생성하여, 제작 과정을 훨씬 효율적이고 안정적으로 만들어줍니다.
사용법:
scripts/init_skill.py <skill-name> --path <output-directory>
이 스크립트는:
- 지정된 경로에 SKILL 디렉토리 생성
- 올바른 frontmatter와 TODO 위치 표시가 포함된 SKILL.md 템플릿 생성
- 예시 리소스 디렉토리 생성:
scripts/,references/,assets/ - 커스터마이징하거나 삭제할 수 있는 각 디렉토리별 예시 파일 추가
초기화 후에는 생성된 SKILL.md와 예시 파일들을 필요에 따라 커스터마이징하거나 삭제하세요.
Step 4: SKILL 편집
(새로 생성되었거나 기존의) SKILL을 편집할 때, 이 SKILL은 Claude의 다른 인스턴스가 사용하기 위해 만들어진다는 점을 명심하세요. Claude에게 유익하면서도 자명하지 않은 정보를 포함하세요. 다른 Claude 인스턴스가 이러한 작업을 더 효과적으로 수행하도록 돕기 위해 어떤 절차적 지식, 도메인 세부 사항 또는 재사용 가능한 에셋이 도움이 될지 고려하세요.
검증된 디자인 패턴 학습
SKILL의 필요에 따라 다음 가이드를 참조하세요:
- 다단계 프로세스: 순차적 워크플로우와 조건부 로직에 대해서는 references/workflows.md를 참조하세요.
- 특정 출력 형식 또는 품질 표준: 템플릿 및 예시 패턴에 대해서는 references/output-patterns.md를 참조하세요.
이 파일들에는 효과적인 SKILL 디자인을 위한 검증된 모범 사례가 포함되어 있습니다.
재사용 가능한 SKILL 콘텐츠부터 시작
구현을 시작하기 위해 위에서 식별한 재사용 가능한 리소스(scripts/, references/, assets/) 파일들부터 작성하세요. 이 단계에서 사용자의 입력이 필요할 수 있습니다. 예를 들어 brand-guidelines SKILL을 구현할 때, 사용자가 assets/에 저장할 브랜드 에셋이나 템플릿, 또는 references/에 저장할 문서를 제공해야 할 수 있습니다.
추가된 스크립트는 실제로 실행하여 버그가 없는지, 출력이 예상과 일치하는지 반드시 테스트해야 합니다. 유사한 스크립트가 많은 경우, 완료 시간을 조절하면서도 신뢰성을 확보할 수 있도록 대표적인 샘플만 테스트하면 됩니다.
SKILL에 필요하지 않은 예시 파일과 디렉토리는 삭제해야 합니다. 초기화 스크립트는 구조를 보여주기 위해 각 디렉토리에 예시 파일들을 생성하지만, 대부분의 SKILL에서 이들이 모두 필요하지는 않습니다.
SKILL.md 업데이트
작성 가이드라인: 항상 명령형/부정사(imperative/infinitive) 형식을 사용하세요.
Frontmatter
name과 description 필드가 포함된 YAML frontmatter를 작성하세요:
name: SKILL 이름description: SKILL의 주요 트리거 메커니즘이며, Claude가 언제 이 SKILL을 사용해야 할지 이해하도록 돕습니다.- SKILL이 무엇을 하는지와 이를 언제 사용해야 하는지에 대한 구체적인 트리거/컨텍스트를 모두 포함하세요.
- "언제 사용할지"에 대한 모든 정보는 본문이 아닌 이곳에 포함하세요. 본문은 트리거된 후에 로드되므로, 본문의 "When to Use This Skill" 섹션은 Claude에게 도움이 되지 않습니다.
docxSKILL의 예시 설명: "수정 내용 추적(tracked changes), 메모, 포맷 보존 및 텍스트 추출을 지원하는 포괄적인 문서 생성, 편집 및 분석입니다. Claude가 다음을 위해 전문적인 문서(.docx 파일) 작업이 필요할 때 사용하세요: (1) 새 문서 생성, (2) 내용 수정 또는 편집, (3) 수정 내용 추적 작업, (4) 메모 추가 또는 기타 문서 관련 작업"
YAML frontmatter에 다른 필드를 포함하지 마세요.
본문 (Body)
SKILL과 번들 리소스를 사용하기 위한 지침을 작성하세요.
Step 5: SKILL 패키징
SKILL 개발이 완료되면, 사용자에게 공유할 배포용 .skill 파일로 패키징해야 합니다. 패키징 프로세스는 먼저 모든 요구 사항을 충족하는지 SKILL을 자동으로 검증합니다:
scripts/package_skill.py <path/to/skill-folder>
선택적인 출력 디렉토리 지정:
scripts/package_skill.py <path/to/skill-folder> ./dist
패키징 스크립트는 다음을 수행합니다:
검증 (Validate): SKILL을 자동으로 검사하며 다음 사항들을 확인합니다:
- YAML frontmatter 형식 및 필수 필드
- SKILL 명명 규칙 및 디렉토리 구조
- 설명(description)의 완전성 및 품질
- 파일 조직 및 리소스 참조
패키징 (Package): 검증을 통과하면 배포를 위한 적절한 디렉토리 구조와 모든 파일을 포함하는, SKILL 이름으로 명명된 .skill 파일(예:
my-skill.skill)을 생성합니다. .skill 파일은 .skill 확장자를 가진 zip 파일입니다.
검증에 실패하면 스크립트는 에러를 보고하고 패키지를 생성하지 않은 채 종료됩니다. 검증 에러를 수정한 후 패키징 명령을 다시 실행하세요.
Step 6: 반복 개선 (Iterate)
SKILL을 테스트한 후 사용자가 개선을 요청할 수 있습니다. 이는 대개 SKILL이 어떻게 작동했는지에 대한 생생한 컨텍스트가 남아 있는 사용 직후에 발생합니다.
반복 워크플로우:
- 실제 작업에 SKILL을 사용
- 어려움이나 비효율적인 부분 발견
- SKILL.md나 번들 리소스를 어떻게 업데이트해야 할지 식별
- 변경 사항 구현 및 재테스트