Claude Code Skills: 컨텍스트 기반 자동 전문 지식

Skills는 Claude Code의 핵심 기능 중 하나로, 특정 작업에 필요한 전문 지식을 자동으로 로드하는 모듈형 시스템입니다. 슬래시 명령어와 달리 수동 호출 없이 컨텍스트에 맞게 자동으로 활성화됩니다.

Skills란?

• 정의: 자동으로 활성화되는 도메인 전문 지식 패키지
• 활성화 방식: Claude가 작업 컨텍스트와 스킬 설명을 비교하여 관련 스킬을 투명하게 로드
• 장점: 명시적 호출 없이 필요한 전문 지식 자동 제공

Skills 디렉토리 구조

# 스킬 저장 위치 (우선순위 순)
~/.claude/skills/           # 전역 스킬 (모든 프로젝트)
.claude/skills/             # 프로젝트별 스킬
plugins/*/skills/           # 플러그인 내 스킬

# 스킬 폴더 구조 예시
~/.claude/skills/
├── security-audit/
│   ├── SKILL.md            # 필수: 스킬 정의 파일
│   └── helpers/            # 선택: 헬퍼 스크립트
│       └── scan.sh
├── code-review/
│   └── SKILL.md
└── documentation/
    └── SKILL.md

SKILL.md 파일 구조

SKILL.md는 스킬의 유일한 필수 파일입니다. YAML 메타데이터와 마크다운 지침으로 구성됩니다.

---
name: security-auditor
description: 코드 보안 취약점을 분석하고 개선안을 제시합니다
allowed-tools:
  - Read
  - Grep
  - Bash
model: sonnet
---

# 보안 감사 스킬

## 역할
당신은 보안 전문 코드 감사관입니다.

## 점검 항목
1. **XSS (Cross-Site Scripting)**
   - 사용자 입력이 HTML에 직접 출력되는지 확인
   - innerHTML 사용 여부 검사
   
2. **SQL Injection**
   - 문자열 연결 쿼리 검사
   - PreparedStatement 사용 확인
   
3. **CSRF (Cross-Site Request Forgery)**
   - CSRF 토큰 구현 확인
   - SameSite 쿠키 설정 검사

4. **인증/인가**
   - 하드코딩된 비밀번호 검사
   - 적절한 권한 체크 확인

## 보고 형식
발견된 취약점은 다음 형식으로 보고:
- 위험도: Critical/High/Medium/Low
- 위치: 파일명:라인번호
- 설명: 취약점 상세 설명
- 해결책: 권장 수정 방법

메타데이터 필드 상세

필드	필수	설명
name	필수	스킬의 고유 식별자
description	필수	Claude가 스킬 관련성을 판단하는 기준. 명확하게 작성
allowed-tools	선택	스킬이 사용할 수 있는 도구 목록
model	선택	사용할 모델 (haiku, sonnet, opus)
hooks	선택	스킬 라이프사이클 훅 정의

Skills vs 다른 기능 비교

기능	활성화 방식	용도
CLAUDE.md	항상 로드	정적 프로젝트 지식
Skills	컨텍스트 기반 자동	도메인별 전문 지식
슬래시 명령어	수동 호출 (/command)	명시적 워크플로우
Subagents	Claude 결정	병렬/격리된 작업

실용적인 스킬 예시

1. 코드 리뷰 스킬

---
name: code-reviewer
description: Pull Request 및 코드 변경사항을 리뷰합니다
allowed-tools:
  - Read
  - Grep
  - Bash
---

# 코드 리뷰어

## 리뷰 기준
1. 코드 품질
   - 가독성
   - 유지보수성
   - 중복 코드

2. 성능
   - 불필요한 연산
   - N+1 쿼리 문제
   - 메모리 사용

3. 테스트
   - 테스트 커버리지
   - 엣지 케이스

## 출력 형식
- ✅ 좋은 점
- ⚠️ 개선 필요
- ❌ 반드시 수정

2. 문서화 스킬

---
name: documentation-writer
description: API 문서와 README를 작성합니다
allowed-tools:
  - Read
  - Write
---

# 문서 작성자

## 문서화 규칙
- JSDoc 스타일 주석 사용
- 모든 public 함수에 예시 코드 포함
- 파라미터 타입과 반환값 명시

## README 구조
1. 프로젝트 소개
2. 설치 방법
3. 사용 예시
4. API 레퍼런스
5. 기여 가이드

스킬 훅 정의

스킬은 자체 라이프사이클 훅을 정의할 수 있습니다:

---
name: auto-formatter
description: 코드 저장 시 자동 포맷팅
hooks:
  PostToolUse:
    - matcher: "Edit|Write"
      command: "npx prettier --write $FILE"
      once: true
---

# 자동 포맷터 스킬
코드 편집 후 자동으로 Prettier를 실행합니다.

v2.1.0의 스킬 핫리로드

Claude Code 2.1.0부터 스킬이 자동으로 핫리로드됩니다:

• ~/.claude/skills 또는 .claude/skills에서 스킬 생성/수정 시 즉시 활성화
• 세션 재시작 불필요
• 실시간 스킬 개발 및 테스트 가능

스킬 개발 베스트 프랙티스

1. 명확한 description 작성: Claude가 스킬을 선택하는 기준
2. 최소 권한 원칙: 필요한 도구만 allowed-tools에 포함
3. 단일 책임: 하나의 스킬은 하나의 전문 영역만 담당
4. 경량 모델 사용: 간단한 작업은 haiku, 복잡한 분석은 sonnet
5. 구체적인 지침: 마크다운 본문에 명확한 가이드라인 제공

참고 자료:

• Claude Code Skills 공식 문서