Skill이란?
Skill은 SKILL.md 파일에 적은 지침으로 Claude의 작업 방식을 확장하는 기능입니다. 본문에 절차, 규칙, 점검 항목을 적어두면 Claude가 관련 작업에서 그 절차대로 작업하고, 사용자는 /skill-name으로 직접 실행할 수도 있습니다. CLAUDE.md와 달리 본문은 실제로 사용될 때만 불러오므로, 긴 참고 자료를 넣어도 평소에는 컨텍스트를 거의 차지하지 않습니다.
기존 커스텀 커맨드는 Skill로 통합됐습니다. .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md는 둘 다 /deploy를 만들고 같은 방식으로 동작하며, 기존 커맨드 파일도 계속 작동합니다. Skill은 frontmatter로 훅, 허용 도구, 서브에이전트 실행 등을 지정할 수 있어 단순한 문서 이상의 동작도 정의할 수 있습니다. 여러 Skill과 에이전트, 훅, MCP 서버를 묶어 배포하려면 Plugin을 사용합니다.
파일 구조
~/.claude/skills/<skill-name>/
├── SKILL.md # 필수 — frontmatter + 본문
└── (보조 파일) # 선택 — 참고 자료, 템플릿 등
SKILL.md 기본 형식
---
name: <skill-name>
description: <Claude가 이 Skill을 호출할 조건을 구체적으로 명시>
---
# Skill 제목
## 언제 사용하나
이 Skill이 호출되어야 하는 상황 명시.
## 절차
1. 첫 단계
2. 두 번째 단계
3. ...
## 점검 항목
- [ ] 항목 1
- [ ] 항목 2
name은 생략하면 디렉터리 이름이 기본값이 됩니다.
자주 쓰는 추가 frontmatter
| 필드 | 용도 |
|---|---|
disable-model-invocation: true | Claude가 자동으로 불러오지 않고, 사용자가 /name으로 실행할 때만 동작 |
user-invocable: false | / 메뉴에서 숨기고 Claude만 사용 (배경 지식용) |
paths | glob 패턴과 일치하는 파일을 다룰 때만 자동으로 불러옴 |
allowed-tools | Skill이 실행되는 턴에서 권한 확인 없이 쓸 도구 지정 |
description의 중요성
description은 Claude가 Skill을 호출할지 결정하는 핵심 신호입니다. 스킬 목록에서는 description과 when_to_use를 합친 텍스트가 1,536자에서 잘리므로 핵심 용도를 앞에 둡니다. 좋은 description의 특징:
- 트리거 조건 명시 — “X 작업 시”, “Y 파일을 다룰 때”
- 기능명과 키워드 포함 — 사용자가 실제로 쓸 표현
- 부정 조건도 명시 (선택) — “단, Z인 경우는 제외”
좋은 예
description: |
Use when creating or modifying SQL migration files in db/migrations/.
Enforces naming convention (timestamp_description.sql), reversibility,
and schema review checklist. Skip for read-only queries.
나쁜 예
description: Database stuff # 너무 일반적, 호출 조건 불명확
본문 작성 원칙
1. 절차는 번호 매겨 명시
Claude는 번호 매겨진 절차를 더 정확히 따릅니다.
2. 금지 사항은 굵게
**절대 하지 말 것**:
- 마이그레이션 파일을 직접 삭제
- ALTER TABLE 없이 컬럼 변경
3. 검증 단계 포함
## 검증
- 마이그레이션 적용 후 `npm test`
- 롤백 테스트: `npm run db:rollback && npm run db:migrate`
4. 외부 링크는 절대 경로
본문에 다른 Skill이나 문서를 참조할 때 명확히 표시합니다.
실전 예: 콘텐츠 검토 Skill
---
name: review-content
description: |
Use when reviewing or modifying content files in src/content/.
Checks frontmatter schema, ko/en pair consistency, link validity,
and applies the project quality rules.
---
# Content Review
## 실행 시점
- 콘텐츠 파일을 생성, 수정한 후
- 배포 전 최종 검토
## 절차
1. frontmatter 스키마 위반 확인
2. ko/en 페어 정합성 (slug, dates 동일)
3. 외부 링크 유효성
4. 본문 톤 일관성
## 검증
\```bash
npm run build
\```
Skill을 두는 위치
| 위치 | 적용 범위 |
|---|---|
~/.claude/skills/<name>/SKILL.md | 내 모든 프로젝트 (이 컴퓨터) |
.claude/skills/<name>/SKILL.md | 이 저장소의 세션. 커밋하면 팀 전체가 사용 |
플러그인 내 skills/<name>/SKILL.md | 플러그인이 활성화된 곳. /plugin-name:skill-name으로 실행 |
관리 설정(managed settings) 디렉터리의 .claude/skills/ | 조직이 배포한 컴퓨터의 모든 사용자 |
팀과 공유하려면 프로젝트의 .claude/skills/를 커밋하고, 여러 저장소나 공개 배포가 필요하면 플러그인으로 묶어 마켓플레이스에 등록합니다.
Claude Code는 Skill 디렉터리를 감시하므로 SKILL.md를 추가하거나 고치면 재시작 없이 현재 세션에 반영됩니다. 세션 시작 후에 새로 만든 최상위 skills 디렉터리는 /reload-skills로 불러옵니다.
흔한 실수
- ❌ description이 너무 짧음 — Claude가 트리거 못함
- ❌ 본문이 산문(에세이) 스타일 — 절차로 분리 필요
- ❌ 너무 광범위한 Skill — 한 Skill = 한 절차 원칙
- ❌ 다른 Skill과 트리거 조건 충돌 — 명확히 구분
다음 단계
- Superpowers 내장 Skills를 코드로 직접 읽어 구조 학습
- Obsidian Skills — 잘 설계된 Skill 모음 사례
- CLAUDE.md 잘 쓰는 법 — Skill과 CLAUDE.md의 역할 분리
- Extend Claude with skills — frontmatter 전체 목록과 고급 패턴