Claude Code Skills — 설정 & 다중 파일 구성

⚙️ Claude Code Skills — 설정 & 다중 파일 구성

allowed-tools · 효과적인 description · Progressive Disclosure · 스크립트 활용

📌 이 글의 핵심 요약

• name과 description은 필수, allowed-tools와 model은 선택 필드입니다.
• 좋은 description은 "무엇을 하는가"와 "언제 사용하는가" 두 가지에 답해야 합니다.
• Progressive Disclosure로 SKILL.md를 500줄 이하로 유지하고 참조 파일을 분리합니다.
• 스크립트는 내용 없이 출력(output)만 컨텍스트에 올라가므로 토큰을 절약할 수 있습니다.

1. Skill 메타데이터 필드

SKILL.md의 frontmatter에 작성할 수 있는 필드는 총 4가지입니다. 2개는 반드시 있어야 하고, 나머지 2개는 상황에 따라 추가합니다.

name필수

스킬의 고유 식별자

소문자·숫자·하이픈만 사용 가능. 최대 64자. 디렉토리 이름과 일치시키세요.

description필수

Claude가 스킬을 사용할 타이밍 기준 (가장 중요!)

최대 1,024자. Claude는 이 필드로 매칭 여부를 결정합니다. 내용이 충분히 구체적일수록 정확하게 트리거됩니다.

allowed-tools선택

스킬 활성화 중 사용 가능한 도구 제한

보안이 민감한 워크플로우나 읽기 전용 작업에 유용합니다. 생략하면 기본 권한 모델이 적용됩니다.

model선택

스킬에 사용할 Claude 모델 지정

예: sonnet, opus. 특정 작업에 최적화된 모델을 지정할 수 있습니다.

SKILL.md — 모든 필드 사용 예시

---
name:          codebase-onboarding
description:   Helps new developers understand how the system works.
               Use when someone asks about architecture, how to add
               a new feature, or where specific logic lives.
allowed-tools: Read, Grep, Glob, Bash   # 읽기 전용으로 제한
model:         sonnet
---

# 이 아래에 실제 지시 내용 작성

---

2. 효과적인 description 작성법

description을 잘 쓰는 것이 스킬 성공의 핵심입니다. Claude는 description의 언어를 기반으로 매칭 여부를 판단하기 때문입니다.

좋은 description은 반드시 두 가지 질문에 답해야 합니다.

❶ 무엇을 하는가? 스킬의 기능을 한 줄로 설명

+

❷ 언제 사용하는가? "Use when..." 패턴으로 구체적 상황 명시

✅ 좋은 description

Writes commit messages in conventional commit format.
Use when writing a commit, staging changes, or summarizing what changed.

❌ 나쁜 description

commit helper

→ 너무 짧고 모호해서 언제 트리거할지 Claude가 판단 불가

스킬이 기대한 상황에서 트리거되지 않는다면, 실제로 내가 Claude에게 입력하는 표현과 비슷한 키워드를 description에 더 추가해 보세요.

---

3. allowed-tools로 도구 접근 제한하기

스킬이 활성화된 동안 Claude가 사용할 수 있는 도구를 제한할 수 있습니다. 파일을 읽을 수는 있지만 수정은 하면 안 되는 상황, 혹은 보안이 민감한 워크플로우에서 특히 유용합니다.

읽기 전용 스킬 예시

---
name:          codebase-onboarding
description:   Helps new developers understand how the system works.
allowed-tools: Read, Grep, Glob, Bash
---

설정 방식	동작	용도
allowed-tools: Read, Grep, Glob, Bash	지정된 도구만 허용 (편집·쓰기 불가)	코드베이스 탐색, 읽기 전용 분석
allowed-tools 필드 생략	Claude 기본 권한 모델 그대로 적용	일반적인 개발 작업

allowed-tools를 사용하면 스킬이 활성화된 동안 해당 도구들은 별도 승인 없이 바로 사용됩니다. 제한된 도구 외의 작업은 Claude가 수행할 수 없습니다.

---

4. Progressive Disclosure — 다중 파일로 구성하기

스킬이 활성화되면 SKILL.md 전체 내용이 컨텍스트 윈도우에 올라옵니다. 모든 내용을 하나의 파일에 몰아 넣으면 두 가지 문제가 생깁니다.

❌ 하나의 거대한 SKILL.md

2,000줄짜리 파일 → 항상 전체 로드
→ 컨텍스트 윈도우 낭비
→ 관리 및 유지보수 어려움

✅ Progressive Disclosure

SKILL.md는 핵심만 유지
상세 내용은 별도 파일로 분리
→ 필요할 때만 로드

권장 디렉토리 구조

.claude/skills/codebase-onboarding/
├── SKILL.md ← 핵심 지시 (500줄 이하 권장)
├── references/
│ ├── architecture-guide.md ← 시스템 설계 질문 시에만 로드
│ └── api-conventions.md ← API 관련 질문 시에만 로드
├── scripts/
│ └── validate-env.sh ← 내용 로드 없이 실행만
└── assets/
    └── onboarding-template.md ← 필요 시 참조

SKILL.md에서 참조 파일 연결하기

SKILL.md 본문에서 Claude에게 언제 어떤 파일을 읽을지 명확히 지시합니다.

SKILL.md — 참조 파일 연결 예시

---
name:        codebase-onboarding
description: Helps new developers understand how the system works.
---

## 기본 규칙
1. 항상 코드를 직접 수정하지 말고 설명만 제공할 것
2. 예시 코드는 실제 파일 경로를 함께 제시할 것

## 참조 파일 로드 기준
# 시스템 설계 / 아키텍처 질문이 들어오면:
→ references/architecture-guide.md 를 읽고 답변

# API 엔드포인트 / 규칙 관련 질문이 들어오면:
→ references/api-conventions.md 를 읽고 답변

# 그 외 일반 질문은 이 파일의 내용만으로 답변

SKILL.md는 목차처럼, 참조 파일들은 챕터처럼 생각하세요. 목차만 보고도 원하는 챕터를 찾아갈 수 있게 구성하는 것이 핵심입니다.

SKILL.md가 500줄을 넘기 시작하면, 내용 일부를 references 폴더로 분리하는 신호입니다.

---

5. 스크립트로 컨텍스트 절약하기

스킬 디렉토리의 scripts/ 폴더에 있는 스크립트는 내용을 컨텍스트에 올리지 않고 실행할 수 있습니다. 스크립트 코드 자체가 아닌, 실행 결과(output)만 토큰을 소비합니다.

📄

스크립트 파일 (scripts/validate-env.sh) 수백 줄의 검증 로직 — 컨텍스트에 올라가지 않음

로드 ✗

▶️

스크립트 실행 SKILL.md에서 "read하지 말고 실행하라"고 지시

실행 ✓

📤

실행 결과(output)만 컨텍스트에 추가 예: "✅ Node 20.x detected / ❌ .env file missing"

토큰 절약 ✓

SKILL.md에서 스크립트 지시 방법

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

---
name:        dev-setup
description: Sets up the development environment.
             Use when onboarding, setting up a new machine,
             or debugging environment issues.
---

중요: 아래 스크립트를 Read하지 말고, Bash로 직접 실행할 것.

환경 검증 시:
$ bash scripts/validate-env.sh

실행 결과를 바탕으로 누락된 항목을 사용자에게 안내하세요.

스크립트 활용이 특히 효과적인 경우는 다음과 같습니다.

활용 사례	이유
환경 검증 (Node, Python 버전 등)	매번 생성하는 것보다 검증된 코드가 더 신뢰성 있음
데이터 변환 작업	일관된 결과가 중요할 때
복잡한 설정 파일 파싱	스크립트 로직 자체가 길 때 토큰 절약 효과 큼

---

6. 전체 구성 한눈에 보기

완성된 다중 파일 스킬 예시

---
name:          codebase-onboarding
description:   Helps new developers understand the codebase.
               Use when someone asks about architecture, where
               to add a component, or how the system works.
allowed-tools: Read, Grep, Glob, Bash
model:         sonnet
---

## 기본 원칙
- 코드를 수정하지 말고 설명과 경로만 제공
- 실제 파일을 Read로 확인한 후 답변

## 스크립트 실행
Read하지 말고 Bash로 실행:
$ bash scripts/validate-env.sh

## 참조 파일 로드 기준
- 아키텍처·설계 질문 →  references/architecture-guide.md
- API 관련 질문      →  references/api-conventions.md

핵심 원칙 ✨

SKILL.md는 목차처럼 간결하게,
상세 내용은 references 폴더로 분리하고,
반복 작업은 scripts 폴더에 넣어 자동화하세요.

500줄 이하의 SKILL.md → 빠른 로드, 낮은 토큰 소비, 쉬운 유지보수 🚀