create-skill

Skill Creation

This is a guide for creating a Claude Code Skill.

Progressive Disclosure Essentials

The context window is a public good. Claude is already smart enough. Add only information Claude does not know.

A skill loads information in 3 stages. When creating one, clearly separate the role of each stage.

Stage	Content	Token Budget	Location
Stage 1 Discovery	name + description	~100	frontmatter
Stage 2 Activation	Core instructions, usage method	<5000 (<500줄)	SKILL.md body
Stage 3 Execution	Detailed documentation, scripts, resources	Unlimited	references/, scripts/, assets/

Principles: Stage 1 alone must make it possible to judge "is this skill needed?", and Stage 2 alone must make it possible to perform the task. Stage 3 is loaded only when needed.

Directory Structure

skill-name/
├── SKILL.md          # Stage 2: 핵심 지침 (필수, <500줄)
├── references/       # Stage 3: 상세 문서 (*.md)
│   └── detail.md
├── scripts/          # Stage 3: 실행 가능한 코드
│   └── main.py
└── assets/           # Stage 3: 템플릿, 설정, 리소스
    └── template.json

Directory	Role	Example
`references/`	Detailed guides, examples, schema documentation	`options.md`, `examples.md`
`scripts/`	Code the skill executes (self-contained)	`lint.sh`, `analyze.py`
`assets/`	Static resources, template files	`template.json`, `config.yaml`

Required Elements

Field	Description	Constraint
`name`	Skill identifier	1-64 characters, lowercase letters/numbers/hyphens only, matches directory name
`description`	What + When	1-1024 characters, includes trigger keywords

description Writing Pattern

description: >
  [무엇을 하는지 1-2문장]
  [언제/어떤 키워드에 사용하는지]

Example:

description: >
  PDF 파일에서 텍스트와 테이블을 추출합니다.
  PDF 작업, 문서 추출, 폼 처리 요청 시 사용.

Creation Steps

Step 1: Create Directory

mkdir -p skills/{name}/references
# 필요 시 추가
mkdir -p skills/{name}/scripts
mkdir -p skills/{name}/assets

Step 2: Write Frontmatter

---
name: skill-name
description: >
  무엇을 하는지 설명.
  언제 사용하는지 트리거 키워드 포함.
---

For detailed fields, see Frontmatter Schema .

Step 3: Write Body

The body is Stage 2. Keep it <500 lines and <5000 tokens, and include only the essentials.

Basic Structure:

# 스킬 제목

## 개요
핵심 기능 2-3문장

## 사용 방법
단계별 지침 (핵심만)

## 상세 정보
- [참조 문서](references/detail.md)

Criteria: Whether to put it in the body or separate it into references/:

Body: core rules that must be referenced every time, required workflows
references: example collections, detailed options, edge cases, background explanations

For detailed guides, see Body Writing Guide .

Step 4: Validation

□ name이 1-64자, 소문자/숫자/하이픈만 사용하는가?
□ name이 디렉토리명과 일치하는가?
□ description이 무엇+언제를 명확히 설명하는가?
□ SKILL.md 본문이 500줄 이하인가?
□ 본문이 핵심만 포함하고 상세는 references/로 분리되었는가?
□ 파일 참조가 상대 경로이며 1단계 깊이인가?

For detailed validation/security guides, see Validation and Security .

File Reference Rules

When referencing files inside a skill:

relative paths (absolute paths prohibited)
1 level deeponly (references/file.md O, references/sub/file.md X)
Markdown link format: [표시 텍스트](references/file.md)

# 좋은 예
- [상세 가이드](references/guide.md)
- [스크립트](scripts/analyze.py)

# 나쁜 예
- [가이드](/absolute/path/guide.md)       # 절대 경로
- [가이드](references/sub/deep/guide.md)  # 깊은 중첩

Optional Fields

Field	Purpose	Example
`argument-hint`	Argument hint	`[파일경로]`
`disable-model-invocation`	User-invocable only	`true` (side-effectful operations)
`user-invocable`	Claude only	`false` (internal knowledge)
`context`	Run subagent	`fork`
`agent`	Subagent type	`Explore`, `Plan`, `general-purpose`
`allowed-tools`	Tool restrictions	`Read, Grep`

Usage patterns

Pattern	Settings	Purpose
General skill	Default	Both user/Claude invoke
User only	`disable-model-invocation: true`	Deployment, DB operations, etc. side effects
Claude only	`user-invocable: false`	Internal conventions, background knowledge
Isolated execution	`context: fork`	Heavy analysis tasks