| name | create-skill |
| description | Claude Code Skill을 생성하거나 기존 스킬을 개선합니다. 스킬 생성, 스킬 수정, SKILL.md 작성, 새 스킬 만들기, 스킬 개선, 스킬 업데이트 요청 시 활성화.
|
Skill 생성
Claude Code Skill을 생성하는 가이드입니다.
Progressive Disclosure 핵심
컨텍스트 윈도우는 공공재입니다. Claude는 이미 충분히 똑똑합니다. Claude가 모르는 정보만 추가하세요.
스킬은 3단계로 정보를 로드합니다. 생성 시 각 단계의 역할을 명확히 분리하세요.
| 단계 | 내용 | 토큰 예산 | 위치 |
|---|
| 1단계 Discovery | name + description | ~100 | frontmatter |
| 2단계 Activation | 핵심 지침, 사용 방법 | <5000 (<500줄) | SKILL.md 본문 |
| 3단계 Execution | 상세 문서, 스크립트, 리소스 | 무제한 | references/, scripts/, assets/ |
원칙: 1단계만으로 "이 스킬이 필요한가?" 판단 가능해야 하고, 2단계만으로 작업 수행이 가능해야 합니다. 3단계는 필요 시에만 로드합니다.
디렉토리 구조
skill-name/
├── SKILL.md # Stage 2: 핵심 지침 (필수, <500줄)
├── references/ # Stage 3: 상세 문서 (*.md)
│ └── detail.md
├── scripts/ # Stage 3: 실행 가능한 코드
│ └── main.py
└── assets/ # Stage 3: 템플릿, 설정, 리소스
└── template.json
| 디렉토리 | 역할 | 예시 |
|---|
references/ | 상세 가이드, 예제, 스키마 문서 | options.md, examples.md |
scripts/ | 스킬이 실행하는 코드 (자체 완결적) | lint.sh, analyze.py |
assets/ | 정적 리소스, 템플릿 파일 | template.json, config.yaml |
필수 요소
| 필드 | 설명 | 제약 |
|---|
name | 스킬 식별자 | 1-64자, 소문자/숫자/하이픈만, 디렉토리명과 일치 |
description | 무엇 + 언제 | 1-1024자, 트리거 키워드 포함 |
description 작성 패턴
description: >
[무엇을 하는지 1-2문장]
[언제/어떤 키워드에 사용하는지]
예시:
description: >
PDF 파일에서 텍스트와 테이블을 추출합니다.
PDF 작업, 문서 추출, 폼 처리 요청 시 사용.
생성 단계
1단계: 디렉토리 생성
mkdir -p skills/{name}/references
mkdir -p skills/{name}/scripts
mkdir -p skills/{name}/assets
2단계: Frontmatter 작성
---
name: skill-name
description: >
무엇을 하는지 설명.
언제 사용하는지 트리거 키워드 포함.
---
상세 필드는 Frontmatter 스키마 참조.
3단계: 본문 작성
본문은 Stage 2입니다. <500줄, <5000 토큰을 유지하며 핵심만 포함합니다.
기본 구조:
# 스킬 제목
## 개요
핵심 기능 2-3문장
## 사용 방법
단계별 지침 (핵심만)
## 상세 정보
- [참조 문서](references/detail.md)
판단 기준: 본문에 넣을지, references/로 분리할지:
- 본문: 매번 참조해야 하는 핵심 규칙, 필수 워크플로우
- references: 예제 모음, 상세 옵션, 엣지 케이스, 배경 설명
상세 가이드는 본문 작성 가이드 참조.
4단계: 검증
□ name이 1-64자, 소문자/숫자/하이픈만 사용하는가?
□ name이 디렉토리명과 일치하는가?
□ description이 무엇+언제를 명확히 설명하는가?
□ SKILL.md 본문이 500줄 이하인가?
□ 본문이 핵심만 포함하고 상세는 references/로 분리되었는가?
□ 파일 참조가 상대 경로이며 1단계 깊이인가?
상세 검증/보안 가이드는 검증 및 보안 참조.
파일 참조 규칙
스킬 내부 파일을 참조할 때:
- 상대 경로 사용 (절대 경로 금지)
- 1단계 깊이만 참조 (
references/file.md O, references/sub/file.md X)
- Markdown 링크 형식:
[표시 텍스트](references/file.md)
# 좋은 예
- [상세 가이드](references/guide.md)
- [스크립트](scripts/analyze.py)
# 나쁜 예
- [가이드](/absolute/path/guide.md) # 절대 경로
- [가이드](references/sub/deep/guide.md) # 깊은 중첩
선택 필드
| 필드 | 용도 | 예시 |
|---|
argument-hint | 인자 힌트 | [파일경로] |
disable-model-invocation | 사용자만 호출 | true (부작용 있는 작업) |
user-invocable | Claude만 호출 | false (내부 지식) |
context | 서브에이전트 실행 | fork |
agent | 서브에이전트 유형 | Explore, Plan, general-purpose |
allowed-tools | 도구 제한 | Read, Grep |
사용 패턴
| 패턴 | 설정 | 용도 |
|---|
| 일반 스킬 | 기본값 | 사용자/Claude 모두 호출 |
| 사용자 전용 | disable-model-invocation: true | 배포, DB 작업 등 부작용 |
| Claude 전용 | user-invocable: false | 내부 컨벤션, 배경 지식 |
| 격리 실행 | context: fork | 무거운 분석 작업 |
상세 가이드
