196 lines
6.7 KiB
Markdown
196 lines
6.7 KiB
Markdown
# 스킬 (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 수신, 종료 코드와 출력 반환 |
|