Skill 생성

Claude Code Skill을 생성하는 가이드입니다.

Progressive Disclosure 핵심

컨텍스트 윈도우는 공공재입니다. Claude는 이미 충분히 똑똑합니다. Claude가 모르는 정보만 추가하세요.

스킬은 3단계로 정보를 로드합니다. 생성 시 각 단계의 역할을 명확히 분리하세요.

원칙: 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

필수 요소

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)  # 깊은 중첩

선택 필드

사용 패턴

상세 가이드

• Frontmatter 스키마
• 템플릿 모음
• 본문 작성 가이드
• 검증 및 보안