스킬 시스템

스킬이란?

스킬(Skill)은 재사용 가능한 온디맨드 워크플로우입니다. 슬래시 명령어(/skill-name)로 호출하며, 반복적인 작업을 표준화된 방식으로 자동화합니다. 훅이 이벤트 발생 시 자동으로 실행되는 것과 달리, 스킬은 사용자가 명시적으로 호출해야 실행됩니다.

파일 구조

스킬은 .claude/skills/<name>/SKILL.md 경로에 마크다운 파일로 정의됩니다.

.claude/
  skills/
    deploy/
      SKILL.md          # /deploy 명령어
    database/
      migrate/
        SKILL.md        # /database:migrate 명령어
    review/
      SKILL.md          # /review 명령어

네임스페이스 스킬은 디렉토리 계층으로 표현합니다. .claude/skills/database/migrate/SKILL.md는 /database:migrate 명령어로 호출됩니다.

Frontmatter 설정

---
description: "프로덕션 배포를 수행합니다"
argument-hint: "<환경명> [버전]"
allowed-tools:
  - Bash
  - Read
when_to_use: "프로덕션 또는 스테이징 환경에 배포할 때 사용합니다"
model: claude-sonnet-4-5
user-invocable: true
context: |
  현재 브랜치: `!git branch --show-current`
  최근 커밋: `!git log --oneline -5`
paths:
  - "deploy/**"
  - "*.dockerfile"
---

필드	설명
description	스킬 설명, /skills 목록에 표시
argument-hint	인수 힌트, 자동완성에 사용
allowed-tools	스킬이 사용할 수 있는 도구 목록
when_to_use	자동 활성화 조건 설명
model	스킬 실행에 사용할 모델
user-invocable	false면 자동 활성화 전용
context	호출 시 프롬프트에 주입할 컨텍스트
paths	관련 파일 패턴, 해당 파일 편집 시 자동 로드

인수 치환

스킬 본문에서 호출 시 전달된 인수를 사용할 수 있습니다.

# 배포 스킬

$ARGUMENTS 환경에 배포를 시작합니다.

다음 단계를 수행해 주세요:
1. `$ARG_ENV` 환경의 설정 파일 확인
2. `$ARG_VERSION` 버전으로 Docker 이미지 빌드
3. 배포 전 헬스체크 실행

문법	설명
$ARGUMENTS	전체 인수 문자열
$ARG_NAME	명명된 인수 (첫 번째 인수는 $ARG_1)

인라인 셸 명령어

백틱 앞에 !를 붙이면 스킬 호출 시 셸 명령어가 실행되고 출력이 프롬프트에 삽입됩니다.

---
context: |
  현재 Git 브랜치: `!git branch --show-current`
  변경된 파일: `!git diff --name-only`
  환경 변수: `!env | grep APP_`
---

위 컨텍스트를 참고하여 코드 리뷰를 수행해 주세요.

이 방식으로 스킬 실행 시점의 동적 정보를 자동으로 포함시킬 수 있습니다.

경로 기반 활성화

paths 필드를 설정하면 관련 파일 편집 시 스킬이 자동으로 활성화됩니다.

paths:
  - "src/migrations/**"
  - "*.sql"

위 설정이 있으면 SQL 파일이나 마이그레이션 파일을 편집할 때 Claude가 자동으로 해당 스킬을 참고합니다.

훅 vs 스킬 비교

항목	훅 (Hook)	스킬 (Skill)
트리거	이벤트 자동 실행	슬래시 명령어로 온디맨드
목적	자동화, 검사, 차단	반복 워크플로우 표준화
저장 위치	settings.json	.claude/skills/*/SKILL.md
입력	환경 변수	슬래시 명령어 인수
사용자 인식	백그라운드 실행	명시적 호출

/skills 명령어를 실행하면 현재 프로젝트에서 사용 가능한 모든 스킬 목록을 확인할 수 있습니다.