# 스킬 (Skills)

> 슬래시 커맨드로 호출하는 재사용 가능한 온디맨드 기능을 만드는 방법.

스킬은 재사용 가능한 프롬프트와 워크플로우를 정의하는 마크다운 파일입니다. Claude Code에서 `/skill-name`을 입력하면 Claude가 해당 스킬의 지시사항을 로드하고 설명된 작업을 실행합니다. 세션 간에 반복하는 모든 워크플로우에 유용합니다 — 배포 실행, 변경 내역 작성, PR 검토, 팀 특유의 코딩 컨벤션 적용 등.

## 스킬 작동 방식

스킬은 `SKILL.md` 파일이 있는 `.claude/skills/` 안의 디렉토리입니다. `/skill-name`을 입력하면 Claude Code가 해당 스킬의 `SKILL.md`를 그 액션의 프롬프트로 로드합니다. 스킬은 지시사항, 컨텍스트, 제약, 호출 시 실행되는 인라인 셸 커맨드까지 포함할 수 있습니다.

스킬은 지연 로드됩니다 — 호출될 때만 읽히므로 스킬이 많이 정의되어 있어도 시작 시간이나 컨텍스트 크기에 영향을 주지 않습니다.

## 스킬 만들기

**1. 스킬 디렉토리 만들기:**
```bash
mkdir -p .claude/skills/my-skill
```

스킬은 다음 위치에 있을 수 있습니다:
- `.claude/skills/` (프로젝트 레벨, 현재 작업 디렉토리 기준)
- `~/.claude/skills/` (사용자 레벨, 모든 프로젝트에서 사용 가능)

**2. SKILL.md 작성:**
```markdown
---
description: 이 프로젝트의 전체 릴리즈 프로세스 실행
argument-hint: 버전 번호 (예: 1.2.3)
---

$ARGUMENTS 버전으로 프로젝트를 릴리즈합니다.

단계:
1. `package.json`의 버전을 $ARGUMENTS로 업데이트
2. CHANGELOG.md에 이 버전의 새 섹션 추가
3. `npm test` 실행 및 모든 테스트 통과 확인
4. "chore: release v$ARGUMENTS" 메시지로 커밋
5. `v$ARGUMENTS` git 태그 생성
```

**3. 스킬 호출:**
```
/my-skill 1.2.3
```

Claude가 스킬을 로드하고 지시사항을 실행합니다 — `1.2.3`이 `$ARGUMENTS`에 대입됩니다.

## 스킬 프론트매터

`SKILL.md` 상단의 프론트매터로 스킬 동작을 설정합니다. 모든 필드는 선택사항입니다.

| 필드 | 설명 |
|------|------|
| `description` | `/skills`에 표시되고 Claude가 언제 사용할지 결정하는 짧은 설명 |
| `argument-hint` | 슬래시 커맨드 자동완성에 표시되는 힌트 |
| `allowed-tools` | 이 스킬이 사용할 수 있는 도구 목록(기본값: 모두) |
| `when_to_use` | Claude가 언제 이 스킬을 적극적으로 사용해야 하는지 설명 |
| `model` | 이 스킬에 사용할 모델 (예: `claude-sonnet-4-6`) |
| `user-invocable` | `false`로 설정해 슬래시 커맨드 목록에서 숨김 (Claude는 여전히 사용 가능) |
| `context` | `fork`로 격리된 서브에이전트 컨텍스트에서 스킬 실행 |
| `paths` | 일치하는 파일이 터치될 때만 스킬 활성화하는 Glob 패턴 |
| `version` | 스킬 버전 문자열 |
| `hooks` | 이 스킬 실행에 범위가 제한된 훅 |

## 인수 대입

`SKILL.md` 어디서나 `$ARGUMENTS`를 사용해 슬래시 커맨드 뒤에 전달된 텍스트를 삽입합니다:

```markdown
$ARGUMENTS라는 이름의 새 React 컴포넌트를 프로젝트 컨벤션에 따라 생성합니다.
```

```
/new-component UserProfile
```

명명된 인수의 경우, 프론트매터에 인수를 나열하고 `$name` 구문으로 참조합니다:

```yaml
---
arguments: [name, directory]
---
```

## 인라인 셸 커맨드

스킬은 호출 시 실행되는 셸 커맨드를 임베드할 수 있습니다. 출력이 Claude가 보기 전에 프롬프트에 삽입됩니다:

```markdown
---
description: 최근 변경 사항 검토
---

컨텍스트를 위한 최근 커밋들:

!`git log --oneline -20`

위 변경 사항을 검토하고 무엇이 달성됐는지 요약해주세요.
```

`!` 프리픽스 후 백틱으로 감싼 커맨드가 실행되고 해당 블록이 출력으로 교체됩니다.

> ⚠️ 인라인 셸 커맨드는 셸과 동일한 권한으로 실행됩니다. 스킬이 로드될 때가 아니라 호출될 때 실행됩니다.

## 스킬 목록 보기

```
/skills
```

모든 범위(프로젝트, 사용자, Managed)의 사용 가능한 모든 스킬과 설명을 표시합니다.

## 네임스페이스 스킬

서브디렉토리의 스킬은 콜론으로 네임스페이스됩니다:

```
.claude/skills/
  deployment/
    SKILL.md      → /deployment
  database/
    migrate/
      SKILL.md    → /database:migrate
    seed/
      SKILL.md    → /database:seed
```

## 경로 기반 조건부 스킬

`paths` 프론트매터 필드를 추가해 일치하는 파일 작업 시에만 스킬을 활성화합니다:

```yaml
---
description: Django 모델 검토
paths: "**/*.py"
when_to_use: Django 모델 파일 편집 시 사용
---
```

Glob 패턴과 일치하는 파일을 읽거나, 쓰거나, 편집할 때 스킬이 자동으로 Claude의 컨텍스트에 로드됩니다.

## 사용자 레벨 스킬

`~/.claude/skills/`의 스킬은 각 저장소에 추가하지 않아도 모든 프로젝트에서 사용할 수 있습니다:

```bash
mkdir -p ~/.claude/skills/standup
cat > ~/.claude/skills/standup/SKILL.md << 'EOF'
---
description: 스탠드업 업데이트를 위해 오늘 작업한 내용 요약
---

이 저장소에서 오늘의 git 커밋을 확인하고 스탠드업 형식으로 요약해주세요: 한 일, 다음에 할 일, 막히는 것. 3-4문장으로 유지해주세요.
EOF
```

## 스킬 예시: 컴포넌트 생성기

```markdown
---
description: 테스트와 함께 새 React 컴포넌트 생성
argument-hint: ComponentName
allowed-tools: Write, Bash
---

$ARGUMENTS라는 이름의 새 React 컴포넌트를 만듭니다.

1. `src/components/$ARGUMENTS/$ARGUMENTS.tsx` 생성:
   - TypeScript를 사용하는 함수형 컴포넌트
   - `$ARGUMENTSProps`라는 Props 인터페이스
   - 컴포넌트를 설명하는 JSDoc 주석
   - default export

2. `src/components/$ARGUMENTS/$ARGUMENTS.test.tsx` 생성:
   - React Testing Library를 사용한 최소 하나의 렌더링 테스트
   - 스냅샷 테스트

3. 컴포넌트를 re-export하는 `src/components/$ARGUMENTS/index.ts` 생성

4. `npx tsc --noEmit`을 실행해 타입 오류 없음 확인
```

호출:
```
/new-component Button
```

## 훅 vs 스킬 비교

| 기능 | 스킬 | 훅 |
|------|------|-----|
| 호출 | 명시적: `/skill-name` 또는 Claude가 필요를 인식 | 자동: 도구 이벤트에 발생 |
| 용도 | 의도적으로 트리거하려는 반복 가능한 워크플로우 | 부작용, 포맷팅, lint, 차단 |
| 설정 | `.claude/skills/`의 `SKILL.md` | 설정 JSON의 `hooks` 필드 |
| 컨텍스트 | 파일, 셸 출력, 상세 지시사항 포함 가능 | 이벤트 JSON 수신, 종료 코드와 출력 반환 |
