스킬 시스템 (Skills)

읽는 시간: 15분 | 난이도: 중급자

SKILL.md 파일로 Claude Code에 새로운 능력을 추가하는 방법을 배웁니다. 슬래시 명령어와 자동 호출을 모두 지원합니다.

스킬이란?

스킬(Skills)은 Claude Code의 재사용 가능한 지시 집합입니다. SKILL.md 파일을 만들면 Claude가 그것을 도구로 추가합니다. 스킬은 관련 대화에서 Claude가 자동으로 불러오거나, /skill-name 형태로 직접 호출할 수 있습니다.

슬래시 명령어와의 관계

기존 .claude/commands/ 폴더의 파일과 스킬은 동일하게 동작합니다. .claude/commands/review.md와 .claude/skills/review/SKILL.md는 모두 /review 명령어를 만들어냅니다. 기존 .claude/commands/ 파일은 그대로 작동하지만, 스킬은 추가 기능(보조 파일 디렉터리, 호출 제어, 자동 로드)을 지원합니다.

스킬의 두 가지 역할

• 참조 지식: API 컨벤션, 코딩 패턴, 도메인 지식처럼 현재 작업에 Claude가 적용할 지식
• 작업 지시: 배포, 커밋, 코드 생성처럼 단계별 절차가 있는 구체적인 작업

첫 번째 스킬 만들기

SKILL.md 파일 형식

모든 스킬은 SKILL.md 파일이 필요합니다. 파일은 두 부분으로 구성됩니다.

1. YAML 프런트매터 (--- 사이): Claude가 언제 이 스킬을 사용할지 제어
2. 마크다운 본문: 스킬이 호출될 때 Claude가 따를 지시 내용

---
name: explain-code
description: 코드를 시각적 다이어그램과 유추로 설명합니다. 코드 동작 설명, 코드베이스 교육, "이게 어떻게 작동해?"라는 질문에 사용합니다.
---

코드를 설명할 때 항상 다음을 포함하세요:

1. **유추로 시작**: 일상의 사물에 비유
2. **다이어그램 그리기**: ASCII 아트로 흐름이나 구조 표현
3. **코드 단계별 설명**: 무슨 일이 일어나는지 순서대로 설명
4. **흔한 실수 짚기**: 자주 하는 오해나 실수 한 가지

설명은 대화하듯 작성하세요. 복잡한 개념은 여러 유추를 사용하세요.

스킬 생성 예시

# 개인 스킬 폴더 생성 (모든 프로젝트에서 사용 가능)
mkdir -p ~/.claude/skills/explain-code

# SKILL.md 작성
cat > ~/.claude/skills/explain-code/SKILL.md << 'EOF'
---
name: explain-code
description: 코드를 시각적 다이어그램과 유추로 설명합니다. 코드 동작 설명, 코드베이스 교육, "이게 어떻게 작동해?"라는 질문에 사용합니다.
---

코드를 설명할 때 항상 다음을 포함하세요:

1. **유추로 시작**: 일상의 사물에 비유
2. **다이어그램 그리기**: ASCII 아트로 흐름이나 구조 표현
3. **코드 단계별 설명**: 무슨 일이 일어나는지 순서대로 설명
4. **흔한 실수 짚기**: 자주 하는 오해나 실수 한 가지

설명은 대화하듯 작성하세요.
EOF

스킬 테스트

# Claude가 자동으로 사용하도록 유도 (description과 일치하는 질문)
"이 코드가 어떻게 작동하는지 설명해줘"

# 또는 직접 호출
/explain-code src/auth/login.ts

스킬 저장 위치

스킬을 어디에 저장하느냐에 따라 적용 범위가 달라집니다.

같은 이름의 스킬이 여러 위치에 있으면 우선순위가 높은 쪽이 이깁니다: 엔터프라이즈 > 개인 > 프로젝트. 플러그인 스킬은 plugin-name:skill-name 형식의 네임스페이스를 사용하므로 다른 레벨과 충돌하지 않습니다.

모노레포 자동 탐색

하위 디렉터리의 파일을 편집할 때 Claude Code는 중첩된 .claude/skills/ 디렉터리에서 스킬을 자동으로 찾습니다. 예를 들어 packages/frontend/ 안의 파일을 편집하면 packages/frontend/.claude/skills/의 스킬도 자동으로 로드됩니다.

monorepo/
├── .claude/skills/            # 전체 프로젝트 스킬
├── packages/
│   ├── frontend/
│   │   └── .claude/skills/   # frontend 전용 스킬 (자동 탐색)
│   └── backend/
│       └── .claude/skills/   # backend 전용 스킬 (자동 탐색)

추가 디렉터리의 스킬

--add-dir로 추가한 디렉터리 안의 .claude/skills/도 자동으로 로드됩니다. 세션 중에 편집해도 재시작 없이 적용됩니다.

프런트매터 필드 완전 참조

SKILL.md 파일 상단의 --- 사이에 YAML로 작성합니다. 모든 필드는 선택사항이지만 description은 강력히 권장됩니다.

---
name: my-skill
description: 이 스킬이 무엇을 하는지, 언제 사용하는지
argument-hint: "[issue-number]"
disable-model-invocation: true
user-invocable: false
allowed-tools: Read, Grep, Glob
model: claude-opus-4-5
context: fork
agent: Explore
hooks:
  stop:
    - type: command
      command: echo "스킬 완료"
---

스킬 지시 내용...

스킬 디렉터리 구조

각 스킬은 SKILL.md를 진입점으로 하는 디렉터리입니다.

my-skill/
├── SKILL.md           # 주요 지시 (필수)
├── reference.md       # 상세 참조 문서 (필요할 때 로드)
├── examples/
│   └── sample.md      # 예상 결과 형식 예시
└── scripts/
    └── validate.sh    # Claude가 실행할 수 있는 스크립트

SKILL.md에서 보조 파일을 참조하면 Claude가 각 파일의 내용과 로드 시점을 알 수 있습니다.

## 추가 리소스

- 전체 API 상세 내용은 [reference.md](reference.md) 참조
- 사용 예시는 [examples.md](examples.md) 참조

핵심 원칙: SKILL.md는 500줄 이내로 유지하고, 상세 참조 자료는 별도 파일로 분리하세요.

문자열 치환 ($ARGUMENTS)

스킬은 동적 값을 위한 문자열 치환을 지원합니다.

단일 인수 예시

---
name: fix-issue
description: GitHub 이슈 번호를 받아 수정합니다
disable-model-invocation: true
argument-hint: "[issue-number]"
---

GitHub 이슈 $ARGUMENTS를 우리 코딩 표준에 따라 수정하세요.

1. 이슈 설명 읽기
2. 요구사항 파악
3. 수정 구현
4. 테스트 작성
5. 커밋 생성

/fix-issue 123을 실행하면 Claude는 "GitHub 이슈 123을 우리 코딩 표준에 따라 수정하세요..."를 받습니다.

위치 인수 예시

---
name: migrate-component
description: 컴포넌트를 한 프레임워크에서 다른 프레임워크로 마이그레이션합니다
argument-hint: "[component] [from-framework] [to-framework]"
---

$0 컴포넌트를 $1에서 $2로 마이그레이션하세요.
기존 동작과 테스트를 모두 보존하세요.

/migrate-component SearchBar React Vue를 실행하면:

• $0 → SearchBar
• $1 → React
• $2 → Vue

세션 ID 예시

---
name: session-logger
description: 이 세션의 활동을 로그에 기록합니다
---

다음 내용을 logs/${CLAUDE_SESSION_ID}.log에 기록하세요:

$ARGUMENTS

호출 제어

기본적으로 사용자와 Claude 모두 어떤 스킬이든 호출할 수 있습니다. 두 가지 프런트매터 필드로 이를 제한할 수 있습니다.

disable-model-invocation: true

사용자만 스킬을 호출할 수 있습니다. 부작용이 있거나 타이밍을 직접 제어해야 하는 작업에 사용합니다. (예: /commit, /deploy, /send-slack-message) Claude가 코드가 준비된 것처럼 보인다고 스스로 배포하는 것을 원하지 않을 때 씁니다.

---
name: deploy
description: 애플리케이션을 프로덕션에 배포합니다
disable-model-invocation: true
---

$ARGUMENTS를 프로덕션에 배포하세요:

1. 테스트 스위트 실행
2. 애플리케이션 빌드
3. 배포 대상에 푸시
4. 배포 성공 확인

user-invocable: false

Claude만 스킬을 호출할 수 있습니다. 사용자가 직접 실행하는 명령어가 아닌 배경 지식에 사용합니다. 예를 들어 legacy-system-context 스킬은 오래된 시스템 작동 방식을 설명하는데, Claude는 관련 상황에서 이를 알아야 하지만 /legacy-system-context는 사용자가 직접 실행할 의미 있는 명령이 아닙니다.

---
name: legacy-payment-context
description: 레거시 결제 시스템의 내부 구조와 특이점을 설명합니다. 결제 관련 코드 수정 시 사용합니다.
user-invocable: false
---

이 프로젝트의 레거시 결제 시스템에 대해:

- 2015년에 구축된 커스텀 PG 연동 레이어 사용
- `PaymentGateway` 클래스는 스레드 안전하지 않음 (싱글턴 사용 금지)
- 환불은 반드시 `RefundProcessor`를 통해야 하며 직접 DB 조작 금지
- 트랜잭션 ID는 `TXN-` 접두사로 시작하는 레거시 형식 사용

호출 제어 요약표

실전 예제

예제 1: 커밋 메시지 생성기

---
name: commit
description: 스테이징된 변경사항을 분석하여 Conventional Commits 형식의 커밋 메시지를 생성합니다
disable-model-invocation: true
allowed-tools: Bash(git *)
---

스테이징된 변경사항을 분석하여 커밋 메시지를 작성하세요.

1. `git diff --staged`로 변경사항 확인
2. 변경의 목적과 범위를 파악
3. Conventional Commits 형식으로 작성: `type(scope): subject`
   - type: feat, fix, docs, style, refactor, test, chore
   - subject: 현재 시제, 50자 이내
4. 본문이 필요하면 빈 줄 후 상세 설명 추가
5. `git commit -m "..."` 실행 전 확인 요청

$ARGUMENTS가 있으면 커밋 메시지에 반영하세요.

# 직접 호출
/commit

# 추가 컨텍스트와 함께
/commit fix for the login timeout issue

예제 2: 코드 리뷰 체크리스트

---
name: code-review
description: 코드 리뷰를 체계적으로 수행합니다. PR 검토나 코드 품질 점검 시 사용합니다.
argument-hint: "[file-or-directory]"
allowed-tools: Read, Grep, Glob
---

$ARGUMENTS의 코드를 다음 체크리스트로 검토하세요:

## 1. 정확성
- [ ] 로직 오류나 엣지 케이스 누락 없음
- [ ] 에러 처리 적절
- [ ] 입력 검증 완료

## 2. 보안
- [ ] SQL 인젝션, XSS 등 취약점 없음
- [ ] 민감한 데이터 로깅 없음
- [ ] 인증/인가 올바르게 구현

## 3. 성능
- [ ] 불필요한 반복 연산 없음
- [ ] N+1 쿼리 문제 없음

## 4. 가독성
- [ ] 함수/변수명이 의도를 명확히 표현
- [ ] 복잡한 로직에 주석 있음
- [ ] 함수가 단일 책임 원칙 준수

각 항목에 대해 구체적인 파일명과 줄 번호를 포함하여 보고서를 작성하세요.

/code-review src/auth/
/code-review src/components/Payment.tsx

예제 3: API 엔드포인트 스캐폴딩

---
name: new-endpoint
description: 새 REST API 엔드포인트를 프로젝트 컨벤션에 맞게 생성합니다
disable-model-invocation: true
argument-hint: "[HTTP-method] [path]"
---

$ARGUMENTS[0] 메서드, $ARGUMENTS[1] 경로로 새 API 엔드포인트를 생성하세요.

이 프로젝트의 컨벤션을 따르세요:
- 컨트롤러: `src/controllers/` (기존 파일 참조)
- 라우터 등록: `src/routes/index.ts`
- 요청 검증: Zod 스키마 사용
- 에러 응답: `{ error: string, code: string }` 형식
- 성공 응답: `{ data: T, meta?: object }` 형식

생성할 파일:
1. 컨트롤러 파일
2. Zod 스키마
3. 단위 테스트 (`*.test.ts`)

기존 엔드포인트 하나를 읽어서 패턴을 파악한 후 작성하세요.

/new-endpoint POST /api/users
/new-endpoint GET /api/products/:id

예제 4: 배포 체크리스트

---
name: pre-deploy
description: 배포 전 점검 사항을 확인합니다
disable-model-invocation: true
argument-hint: "[environment]"
allowed-tools: Bash(git *), Bash(npm *), Read
---

$ARGUMENTS(기본값: staging) 환경 배포 전 다음을 확인하세요:

1. **Git 상태 확인**
   - `git status`로 미커밋 변경사항 없는지 확인
   - 현재 브랜치가 올바른지 확인

2. **테스트 통과 확인**
   - `npm test`로 전체 테스트 실행
   - 실패한 테스트가 있으면 중단

3. **환경 설정 확인**
   - `.env.$ARGUMENTS` 파일 존재 확인
   - 필수 환경변수 누락 없는지 확인

4. **의존성 감사**
   - `npm audit`으로 보안 취약점 확인

5. **빌드 확인**
   - `npm run build` 실행하여 빌드 오류 없는지 확인

모든 확인이 통과하면 배포 진행 가능 여부를 최종 요약하세요.

예제 5: React 컴포넌트 생성기

---
name: new-component
description: React 컴포넌트를 프로젝트 표준에 맞게 생성합니다
disable-model-invocation: true
argument-hint: "[ComponentName]"
---

$0 React 컴포넌트를 생성하세요.

이 프로젝트 표준:
- TypeScript 사용 (`.tsx`)
- 함수형 컴포넌트 + 훅
- Props 타입은 `interface ${ComponentName}Props` 형식
- CSS Module 사용 (`$0.module.css`)
- 스토리북 파일 생성 (`$0.stories.tsx`)
- 테스트 파일 생성 (`$0.test.tsx`)

생성 경로: `src/components/$0/`

기존 컴포넌트(`src/components/Button/`)를 참조하여 동일한 패턴으로 작성하세요.

/new-component Modal
/new-component DataTable

고급 기능

동적 컨텍스트 주입 (!command)

!`command` 구문은 스킬 내용이 Claude에게 전달되기 전에 셸 명령어를 실행합니다. 명령어 출력이 자리표시자를 대체하므로 Claude는 실제 데이터를 받습니다.

---
name: pr-summary
description: 풀 리퀘스트의 변경사항을 요약합니다
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## 풀 리퀘스트 컨텍스트
- PR diff: !`gh pr diff`
- PR 댓글: !`gh pr view --comments`
- 변경된 파일: !`gh pr diff --name-only`

## 작업
이 풀 리퀘스트를 다음 형식으로 요약하세요:
- 변경 목적
- 주요 변경사항 (파일별)
- 잠재적 위험 요소
- 리뷰어가 집중해야 할 부분

실행 순서:

1. 각 !`command`가 즉시 실행됨 (Claude가 아무것도 보기 전에)
2. 출력이 스킬 내용의 자리표시자를 대체
3. Claude는 실제 PR 데이터가 포함된 완성된 프롬프트를 받음

이것은 전처리이지 Claude가 실행하는 것이 아닙니다. Claude는 최종 결과만 봅니다.

팁: 스킬 내용 어디에든 ultrathink라는 단어를 포함하면 확장 사고 모드가 활성화됩니다.

서브에이전트에서 실행 (context: fork)

프런트매터에 context: fork를 추가하면 스킬이 격리된 환경에서 실행됩니다. 스킬 내용이 서브에이전트를 구동하는 프롬프트가 되고, 대화 기록에 접근할 수 없습니다.

---
name: deep-research
description: 주제를 철저히 조사합니다
context: fork
agent: Explore
---

$ARGUMENTS를 철저히 조사하세요:

1. Glob과 Grep으로 관련 파일 찾기
2. 코드 읽고 분석
3. 구체적인 파일 참조와 함께 발견사항 요약

실행 과정:

1. 새로운 격리된 컨텍스트 생성
2. 서브에이전트가 스킬 내용을 프롬프트로 받음
3. agent 필드가 실행 환경(모델, 도구, 권한) 결정
4. 결과가 요약되어 메인 대화로 반환됨

agent 필드 옵션:

• Explore: 코드베이스 탐색에 최적화된 읽기 전용 도구
• Plan: 계획 수립 전용
• general-purpose: 기본 에이전트
• .claude/agents/의 커스텀 서브에이전트 이름

주의: context: fork는 명시적인 작업 지시가 있는 스킬에만 의미가 있습니다. "이 API 컨벤션을 사용하세요" 같은 가이드라인만 있는 스킬은 서브에이전트가 실행할 작업이 없어 의미 없는 결과를 반환합니다.

도구 접근 제한 (allowed-tools)

allowed-tools 필드로 스킬 활성화 시 Claude가 사용할 수 있는 도구를 제한합니다.

---
name: safe-reader
description: 파일을 읽기만 하고 수정하지 않습니다
allowed-tools: Read, Grep, Glob
---

요청한 파일을 읽고 분석하되 어떤 파일도 수정하지 마세요.

$ARGUMENTS

특정 도구의 특정 명령만 허용할 수도 있습니다.

---
name: git-status-check
description: Git 상태만 확인합니다
allowed-tools: Bash(git status), Bash(git log *), Bash(git diff *)
---

현재 Git 저장소 상태를 확인하고 요약하세요.

모델 지정 (model)

특정 스킬에 다른 모델을 사용할 수 있습니다.

---
name: architecture-review
description: 아키텍처 수준의 심층 분석을 수행합니다
model: claude-opus-4-5
context: fork
agent: Explore
---

$ARGUMENTS의 아키텍처를 심층 분석하세요:

1. 전체 구조와 모듈 간 의존성 파악
2. 설계 패턴 식별 및 평가
3. 확장성, 유지보수성 관점에서 검토
4. 개선 권장사항 제시

.claude/commands/와의 호환성

기존 .claude/commands/ 파일은 그대로 작동합니다. 스킬과 명령어가 같은 이름을 공유하면 스킬이 우선합니다.

마이그레이션 경로

# 기존 명령어 파일
.claude/commands/review.md

# 스킬로 이전 (선택사항)
mkdir -p .claude/skills/review
mv .claude/commands/review.md .claude/skills/review/SKILL.md

스킬로 이전하면 얻는 추가 기능:

• 보조 파일 디렉터리 지원 (reference.md, examples/, scripts/)
• disable-model-invocation으로 자동 호출 제어
• user-invocable: false로 배경 지식 전용 사용
• context: fork로 서브에이전트 실행

스킬 공유

스킬 배포 범위에 따른 방법:

• 프로젝트 스킬: .claude/skills/를 버전 관리에 커밋
• 플러그인: 플러그인에 skills/ 디렉터리 생성
• 관리형: managed settings로 조직 전체에 배포

Claude의 스킬 접근 권한 제어

모든 스킬 비활성화

# /permissions에 deny 규칙 추가
Skill

특정 스킬만 허용 또는 차단

# 특정 스킬만 허용
Skill(commit)
Skill(review-pr *)

# 특정 스킬 차단
Skill(deploy *)

권한 구문: Skill(name)은 정확히 일치, Skill(name *)은 접두사 일치(어떤 인수도 허용).

주의: user-invocable 필드는 메뉴 표시 여부만 제어합니다. Claude의 프로그래밍 방식 호출을 막으려면 disable-model-invocation: true를 사용하세요.

시각적 출력 생성

스킬은 어떤 언어의 스크립트든 번들링하여 실행할 수 있습니다. 강력한 패턴 중 하나는 시각적 출력 생성입니다: 브라우저에서 열리는 인터랙티브 HTML 파일로 데이터를 탐색하거나 리포트를 만들 수 있습니다.

코드베이스 시각화 스킬 예시

mkdir -p ~/.claude/skills/codebase-visualizer/scripts

~/.claude/skills/codebase-visualizer/SKILL.md:

---
name: codebase-visualizer
description: 코드베이스의 인터랙티브 트리 시각화를 생성합니다. 새 저장소 탐색, 프로젝트 구조 파악, 큰 파일 찾기에 사용합니다.
allowed-tools: Bash(python *)
---

# 코드베이스 시각화기

프로젝트 루트에서 시각화 스크립트를 실행하세요:

\`\`\`bash
python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .
\`\`\`

이 명령은 현재 디렉터리에 `codebase-map.html`을 생성하고 기본 브라우저로 엽니다.

이 패턴은 의존성 그래프, 테스트 커버리지 리포트, API 문서, DB 스키마 시각화 등 다양한 시각적 출력에 활용할 수 있습니다.

트러블슈팅

스킬이 트리거되지 않음

Claude가 기대한 스킬을 사용하지 않을 때:

1. description에 사용자가 자연스럽게 말할 법한 키워드가 포함되어 있는지 확인
2. "어떤 스킬이 사용 가능해?"로 스킬이 목록에 나오는지 확인
3. description에 더 가깝게 요청을 재표현
4. 스킬이 user-invocable이면 /skill-name으로 직접 호출

스킬이 너무 자주 트리거됨

원하지 않을 때 Claude가 스킬을 사용한다면:

1. description을 더 구체적으로 수정
2. 수동 호출만 원한다면 disable-model-invocation: true 추가

Claude가 모든 스킬을 보지 못함

스킬 description이 컨텍스트에 로드됩니다. 스킬이 많으면 문자 예산을 초과할 수 있습니다. 예산은 컨텍스트 창의 2%로 동적으로 조정되며 기본값은 16,000자입니다.

# 컨텍스트 상태 확인 (제외된 스킬 경고 표시)
/context

# 한도 재정의
export SLASH_COMMAND_TOOL_CHAR_BUDGET=32000

스킬 목록 확인

# 사용 가능한 스킬 확인
/
# 또는
"어떤 스킬이 사용 가능해?"

요약

스킬 시스템은 SKILL.md 파일로 Claude Code의 기능을 무한히 확장할 수 있는 도구입니다.

핵심 개념

모범 사례

• description을 상세하게 작성하여 Claude가 언제 사용할지 알게 하기
• 부작용이 있는 작업은 disable-model-invocation: true 사용
• 배경 지식은 user-invocable: false 사용
• SKILL.md는 500줄 이내로 유지, 상세 내용은 보조 파일로 분리
• 프로젝트 팀과 공유할 스킬은 .claude/skills/를 버전 관리에 포함

다음 단계

• 훅 시스템 - 이벤트 기반 자동화
• MCP 통합 - 외부 서비스 연동
• Settings - 고급 설정