SKILL.md 완전 가이드

번들 Skills

Claude Code에 기본 제공되는 Skills. 프롬프트 기반이라 병렬 에이전트를 생성하고, 파일을 읽고, 코드베이스에 적응한다.

스킬 저장 위치와 우선순위

저장 위치에 따라 적용 범위가 결정된다. 같은 이름이면 상위가 우선.

호출 제어: 누가 스킬을 사용하는가

frontmatter로 사용자/Claude 각각의 호출 권한을 분리한다

실전 예제

배포 스킬 (사용자만 호출)

---
name: deploy
description: 프로덕션 환경에 배포
disable-model-invocation: true
---

$ARGUMENTS를 프로덕션에 배포한다:

1. 테스트 스위트 실행
2. 애플리케이션 빌드
3. 배포 타겟에 푸시
4. 배포 성공 여부 확인

읽기 전용 탐색 스킬

---
name: safe-reader
description: 파일을 읽기만 하고 수정하지 않음
allowed-tools: Read Grep Glob
---

파일을 탐색하고 분석하되 절대 수정하지 않는다.
발견한 내용을 정리해서 보고한다.

이슈 수정 스킬

---
name: fix-issue
description: GitHub 이슈를 수정
disable-model-invocation: true
argument-hint: [issue-number]
---

GitHub 이슈 $ARGUMENTS를 코딩 표준에 맞게 수정한다:

1. 이슈 설명 읽기
2. 요구사항 파악
3. 수정 구현
4. 테스트 작성
5. 커밋 생성

Python 스크립트 번들링

스킬 디렉토리에 Python, Shell 등 스크립트를 함께 번들하면 Claude가 단일 프롬프트로 가능한 것 이상의 작업을 수행할 수 있다. 스크립트가 무거운 작업을 처리하고, Claude는 조율을 담당한다.

디렉토리 구조

# 코드베이스 시각화 스킬 — Python 스크립트 번들 예제
~/.claude/skills/
└── codebase-visualizer/
    ├── SKILL.md                     # 스킬 지침
    └── scripts/
        └── visualize.py             # 번들된 Python 스크립트

SKILL.md — 스크립트 실행 지시

핵심은 ${CLAUDE_SKILL_DIR} 변수다. 이 변수는 SKILL.md가 위치한 디렉토리의 절대 경로로 치환되므로, 현재 작업 디렉토리와 무관하게 번들된 스크립트를 정확히 참조할 수 있다.

---
name: codebase-visualizer
description: 코드베이스의 인터랙티브 트리 시각화를 생성한다. 새 레포 탐색, 프로젝트 구조 파악, 대용량 파일 식별에 사용.
allowed-tools: Bash(python *)
---

# Codebase Visualizer

프로젝트의 파일 구조를 접을 수 있는 인터랙티브 HTML 트리 뷰로 생성한다.

## 사용법

프로젝트 루트에서 시각화 스크립트를 실행한다:

```bash
python ${CLAUDE_SKILL_DIR}/scripts/visualize.py .
```

현재 디렉토리에 `codebase-map.html`을 생성하고 브라우저에서 연다.

## 시각화 내용
- 접기/펼치기 디렉토리: 폴더 클릭으로 토글
- 파일 크기: 각 파일 옆에 표시
- 색상 코딩: 파일 타입별 다른 색상
- 디렉토리 합계: 폴더별 총 크기 표시

scripts/visualize.py — 번들 스크립트

Python 기본 라이브러리만 사용하므로 별도 패키지 설치가 필요없다. 디렉토리 트리를 스캔해서 자체 완결형 HTML 파일을 생성한다.

#!/usr/bin/env python3
"""코드베이스의 인터랙티브 트리 시각화를 생성한다."""

import json, sys, webbrowser
from pathlib import Path
from collections import Counter

IGNORE = {'.git', 'node_modules', '__pycache__', '.venv', 'dist', 'build'}

def scan(path: Path, stats: dict) -> dict:
    result = {"name": path.name, "children": [], "size": 0}
    try:
        for item in sorted(path.iterdir()):
            if item.name in IGNORE or item.name.startswith('.'):
                continue
            if item.is_file():
                size = item.stat().st_size
                ext = item.suffix.lower() or '(no ext)'
                result["children"].append(
                    {"name": item.name, "size": size, "ext": ext}
                )
                result["size"] += size
                stats["files"] += 1
                stats["extensions"][ext] += 1
            elif item.is_dir():
                stats["dirs"] += 1
                child = scan(item, stats)
                if child["children"]:
                    result["children"].append(child)
                    result["size"] += child["size"]
    except PermissionError:
        pass
    return result

def generate_html(data, stats, output):
    # ... HTML 생성 로직 (요약 사이드바 + 막대 차트 + 트리 뷰)
    # 전체 코드: code.claude.com/docs/ko/skills 공식 문서 참조
    ...

if __name__ == '__main__':
    target = Path(sys.argv[1] if len(sys.argv) > 1 else '.').resolve()
    stats = {"files": 0, "dirs": 0, "extensions": Counter()}
    data = scan(target, stats)
    out = Path('codebase-map.html')
    generate_html(data, stats, out)
    print(f'Generated {out.absolute()}')
    webbrowser.open(f'file://{out.absolute()}')

스크립트 번들링 패턴 정리

# 스크립트 참조 패턴 비교

# 잘못된 방법 — 상대 경로 (작업 디렉토리에 따라 깨짐)
python ./scripts/visualize.py .

# 올바른 방법 — ${CLAUDE_SKILL_DIR} 사용 (항상 정확)
python ${CLAUDE_SKILL_DIR}/scripts/visualize.py .

# Shell 스크립트도 동일
bash ${CLAUDE_SKILL_DIR}/scripts/setup.sh

# Node.js 스크립트
node ${CLAUDE_SKILL_DIR}/scripts/generate.js

전체 코드와 더 많은 예제는 공식 문서 (code.claude.com/docs/ko/skills)를 참고한다.