6.7 KiB
스킬 (Skills)
슬래시 커맨드로 호출하는 재사용 가능한 온디맨드 기능을 만드는 방법.
스킬은 재사용 가능한 프롬프트와 워크플로우를 정의하는 마크다운 파일입니다. Claude Code에서 /skill-name을 입력하면 Claude가 해당 스킬의 지시사항을 로드하고 설명된 작업을 실행합니다. 세션 간에 반복하는 모든 워크플로우에 유용합니다 — 배포 실행, 변경 내역 작성, PR 검토, 팀 특유의 코딩 컨벤션 적용 등.
스킬 작동 방식
스킬은 SKILL.md 파일이 있는 .claude/skills/ 안의 디렉토리입니다. /skill-name을 입력하면 Claude Code가 해당 스킬의 SKILL.md를 그 액션의 프롬프트로 로드합니다. 스킬은 지시사항, 컨텍스트, 제약, 호출 시 실행되는 인라인 셸 커맨드까지 포함할 수 있습니다.
스킬은 지연 로드됩니다 — 호출될 때만 읽히므로 스킬이 많이 정의되어 있어도 시작 시간이나 컨텍스트 크기에 영향을 주지 않습니다.
스킬 만들기
1. 스킬 디렉토리 만들기:
mkdir -p .claude/skills/my-skill
스킬은 다음 위치에 있을 수 있습니다:
.claude/skills/(프로젝트 레벨, 현재 작업 디렉토리 기준)~/.claude/skills/(사용자 레벨, 모든 프로젝트에서 사용 가능)
2. SKILL.md 작성:
---
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를 사용해 슬래시 커맨드 뒤에 전달된 텍스트를 삽입합니다:
$ARGUMENTS라는 이름의 새 React 컴포넌트를 프로젝트 컨벤션에 따라 생성합니다.
/new-component UserProfile
명명된 인수의 경우, 프론트매터에 인수를 나열하고 $name 구문으로 참조합니다:
---
arguments: [name, directory]
---
인라인 셸 커맨드
스킬은 호출 시 실행되는 셸 커맨드를 임베드할 수 있습니다. 출력이 Claude가 보기 전에 프롬프트에 삽입됩니다:
---
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 프론트매터 필드를 추가해 일치하는 파일 작업 시에만 스킬을 활성화합니다:
---
description: Django 모델 검토
paths: "**/*.py"
when_to_use: Django 모델 파일 편집 시 사용
---
Glob 패턴과 일치하는 파일을 읽거나, 쓰거나, 편집할 때 스킬이 자동으로 Claude의 컨텍스트에 로드됩니다.
사용자 레벨 스킬
~/.claude/skills/의 스킬은 각 저장소에 추가하지 않아도 모든 프로젝트에서 사용할 수 있습니다:
mkdir -p ~/.claude/skills/standup
cat > ~/.claude/skills/standup/SKILL.md << 'EOF'
---
description: 스탠드업 업데이트를 위해 오늘 작업한 내용 요약
---
이 저장소에서 오늘의 git 커밋을 확인하고 스탠드업 형식으로 요약해주세요: 한 일, 다음에 할 일, 막히는 것. 3-4문장으로 유지해주세요.
EOF
스킬 예시: 컴포넌트 생성기
---
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 수신, 종료 코드와 출력 반환 |