02-구조

02. 구조 — SKILL.md 파일 형식

디렉토리 레이아웃

.claude/skills/
└── explain-code/
    ├── SKILL.md          # 필수
    ├── examples/          # 모델이 필요 시 읽음
    │   └── ascii-diagrams.md
    └── reference.md       # 모델이 필요 시 읽음

SKILL.md만이 필수다. 같은 폴더의 다른 파일은 모델이 본문 지시에 따라 필요할 때만 읽는다 — 이게 토큰 절약의 핵심. 큰 레퍼런스를 SKILL.md에 박지 말고 옆에 두고 가리키게 한다.

frontmatter

---
name: explain-code
description: |
  Explains code with visual diagrams and analogies.
  Use when explaining how code works, teaching about a codebase,
  or when the user asks "how does this work?"
allowed-tools: ["Read", "Grep", "Glob"]
invocation: auto   # auto | manual
---

핵심 필드:

• name — 슬래시 명령 이름이 된다 (/explain-code).
• description — 자동 invoke의 트리거 텍스트. “어떨 때” 가 정확할수록 자동 호출이 정확해진다. “Use when …” 패턴이 가장 안정적.
• allowed-tools — 이 스킬이 활성화된 동안 추가로 허용되는 도구. 글로벌 settings보다 좁아야 한다.
• invocation — auto이면 description이 매칭될 때 자동 호출, manual이면 사용자가 /이름으로만 호출.

공식 문서의 한 줄:

“The name field becomes the /slash-command, and the description helps Claude decide when to load it automatically.”
의역: “name이 슬래시 명령이 되고, description은 Claude가 자동 로드 여부를 결정하는 단서다.”

본문 패턴

본문은 모델에게 주는 단계 지침이다. 다음 5섹션이 표준이다:

## 언제 쓰는가
<자동 invoke description의 더 풀어쓴 버전>

## 단계
1. ...
2. ...

## 출력 형식
<모델이 따라야 할 정확한 형식>

## 사용할 도구
<권장 도구와 호출 순서>

## 보조 파일
- `examples/ascii-diagrams.md` — 다이어그램 예시. 사용자가 다이어그램을 요청하면 읽어라.
- `reference.md` — 깊은 레퍼런스. 모호한 경우 읽어라.

스킬 ↔ 명령 마이그레이션

.claude/commands/deploy.md → .claude/skills/deploy/SKILL.md 로 옮긴 뒤 frontmatter에 description을 적으면 끝. 슬래시 호출은 그대로 동작한다.