Claude Agent Skills: SKILL.md 완전 분석 가이드

1. Skill이란 무엇인가

Skill은 Claude의 능력을 확장하는 폴더 단위의 패키지입니다. 폴더 안에는 SKILL.md라는 진입 파일이 반드시 있어야 하며, 이 파일은 두 부분으로 구성됩니다.

1. YAML frontmatter — --- 마커 사이에 들어가는 메타데이터. Claude가 "언제 이 스킬을 써야 하는가"를 판단하는 근거가 됩니다.

2. Markdown 본문 — 스킬이 실제로 트리거되었을 때 Claude가 따라야 할 지시문.

스킬은 Claude.ai, Claude Code, Claude Agent SDK, Claude API 등 모든 Claude 환경에서 동일한 형식으로 동작하는 오픈 표준(agentskills.io)입니다. Claude Code는 여기에 invocation control, subagent execution, dynamic context injection 같은 확장 기능을 더했습니다.

스킬을 만들어야 할 신호: 같은 지시·체크리스트·다단계 절차를 반복해서 채팅에 붙여 넣고 있을 때, 또는 CLAUDE.md의 한 섹션이 "사실"이 아니라 "절차"로 자라났을 때. CLAUDE.md와 달리 스킬의 본문은 사용될 때만 로드되므로, 긴 참조 문서를 두어도 평소에는 토큰 비용이 거의 0입니다.

2. 3단계 점진적 공개(Progressive Disclosure) 아키텍처

스킬의 가장 핵심적인 설계 원리는 3단계 점진적 공개입니다. 토큰을 절약하면서 무제한에 가까운 전문성을 유지하는 비결이 여기 있습니다.

즉 Claude는 시작할 때 모든 스킬의 메타데이터만 알고 있다가, 사용자의 요청을 보고 "이건 PDF 스킬이 필요하겠다"라고 판단하면 그 스킬의 본문을 읽고, 본문이 가리키는 FORMS.md 같은 파일이 필요하면 그때 추가로 읽습니다.

3. 스킬 디렉터리 구조

스킬은 SKILL.md 한 파일로 시작해 점차 부속 파일을 추가하며 확장합니다.

my-skill/
├── SKILL.md           # 필수. 진입점이자 메타데이터.
├── reference.md       # 상세 API 문서 (필요할 때만 로드)
├── examples.md        # 사용 예시 (필요할 때만 로드)
├── FORMS.md           # 도메인별 가이드 (필요할 때만 로드)
└── scripts/
    ├── helper.py      # Claude가 실행할 유틸 스크립트
    └── validate.sh    # 검증 스크립트

본문에서 보조 파일을 다음과 같이 명시적으로 가리키면, Claude는 "이 파일이 무엇이고 언제 열어야 하는지"를 알게 됩니다.

## Additional resources

- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

4. 스킬 저장 위치 (Claude Code 기준)

스킬을 어디에 두느냐가 누가 그 스킬을 쓸 수 있는지를 결정합니다.

우선순위: 같은 이름의 스킬이 여러 레벨에 있으면 Enterprise > Personal > Project 순으로 덮어씁니다. Plugin 스킬은 plugin-name:skill-name 네임스페이스를 쓰므로 충돌하지 않습니다. 스킬과 같은 이름의 .claude/commands/ 파일이 있다면 스킬이 우선합니다.

실시간 변경 감지: Claude Code는 스킬 디렉터리를 watch하므로, 세션 중에 스킬을 추가·수정·삭제해도 재시작 없이 반영됩니다. 단, 세션 시작 시점에 존재하지 않던 최상위 skills 디렉터리를 새로 만든 경우에는 재시작이 필요합니다.

5. YAML Frontmatter 완전 레퍼런스

Frontmatter는 ---로 둘러싼 YAML 블록이며, SKILL.md 파일의 맨 처음에 위치해야 합니다. 모든 필드는 선택사항이지만, description은 사실상 필수에 가깝습니다.

---
name: my-skill
description: What this skill does and when to use it.
disable-model-invocation: true
allowed-tools: Read Grep
---

Your skill instructions here...

5.1 핵심 두 필드: name과 description

5.2 Claude Code 전용 추가 필드

Claude Code는 오픈 표준에 다음 필드들을 더해서 호출 제어, 서브에이전트 실행, 동적 컨텍스트 주입 같은 고급 기능을 제공합니다.

5.3 호출 권한 매트릭스

두 필드의 조합으로 누가 스킬을 부를 수 있는지가 정해집니다.

6. 동적 컨텍스트 주입 (Dynamic Context Injection)

Claude Code의 강력한 기능 중 하나로, 스킬 본문이 Claude에게 전달되기 전에 셸 명령을 실행하고 그 출력으로 자리표시자를 치환합니다.

6.1 인라인 형식

---
description: Summarizes uncommitted changes and flags anything risky.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points...

여기서 git diff HEAD는 스킬이 Claude에게 전달되기 전에 실행되고, 그 출력이 그 자리에 박힙니다. Claude는 명령 자체를 보지 않고 실제 diff만 봅니다.

6.2 멀티라인 형식

## Environment
```!
node --version
npm --version
git status --short
```

6.3 비활성화

설정에서 "disableSkillShellExecution": true로 두면 모든 사용자·프로젝트·플러그인 스킬의 셸 주입이 차단되고, 각 명령은 [shell command execution disabled by policy]로 치환됩니다. 번들·관리형 스킬은 영향받지 않습니다.

7. 문자열 치환 변수

인덱스 인자는 쉘 스타일 따옴표 규칙을 따르므로, 여러 단어를 한 인자로 넘기려면 /my-skill "hello world" second처럼 따옴표로 감싸야 합니다.

8. 서브에이전트 실행: context: fork

스킬에 context: fork를 추가하면 그 스킬은 대화 이력과 격리된 서브에이전트 컨텍스트에서 실행됩니다. 스킬 본문이 곧 서브에이전트의 프롬프트가 됩니다.

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

주의: context: fork는 "지시"가 있는 스킬에서만 의미 있습니다. "이 API 컨벤션을 써라" 같은 가이드라인만 있고 작업 지시가 없으면, 서브에이전트는 가이드라인만 받고 할 일이 없어 빈손으로 돌아옵니다.

9. 스킬 컨텐츠 생명주기

스킬이 호출되면 렌더링된 SKILL.md 본문이 단일 메시지로 대화에 삽입되고 세션이 끝날 때까지 거기 머뭅니다. Claude Code는 이후 턴에서 스킬 파일을 다시 읽지 않습니다. 따라서 작업 내내 적용돼야 할 가이드는 일회성 단계가 아니라 상시 지시로 써야 합니다.

Auto-compaction(컨텍스트가 가득 찼을 때 대화를 요약하는 과정)에서:

• 각 스킬의 가장 최근 호출본이 요약 뒤에 다시 붙음.

• 호출당 처음 5,000 토큰까지 보존.

• 재첨부 전체 예산은 25,000 토큰. 한 세션에서 너무 많은 스킬을 호출했다면 오래된 것부터 통째로 떨어져 나감.

compaction 이후 스킬이 영향을 못 주는 것 같다면, 그 스킬을 다시 호출해 본문을 복구하세요.

10. 스킬 작성 베스트 프랙티스

10.1 핵심 원칙 — 간결함이 곧 품질

"컨텍스트 윈도우는 공공재"입니다. 한 번 로드된 SKILL.md는 세션 내내 토큰을 소비합니다. 작성할 때마다 자문하세요.

• "Claude가 이 설명을 정말로 모르는가?"

• "Claude는 이미 안다고 가정해도 되지 않나?"

• "이 문단은 토큰 비용을 정당화하는가?"

좋은 예 (≈50 토큰)

## Extract PDF text

Use pdfplumber for text extraction:

```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

나쁜 예 (≈150 토큰)

## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available...

10.2 자유도(Degrees of Freedom) 조절

작업의 깨지기 쉬움과 일관성 요구에 맞춰 지시의 구체성을 조절합니다.

비유하자면 Claude는 길을 가는 로봇입니다. 양옆이 절벽인 좁은 다리에서는 정확한 가드레일을, 탁 트인 들판에서는 방향만 알려주고 자유를 주세요.

10.3 description 작성 원칙

• 3인칭으로 쓴다. description은 시스템 프롬프트에 주입되므로 1인칭("I can help...")은 발견 정확도를 떨어뜨립니다.

• 무엇을 하는지 + 언제 쓰는지를 모두 포함.

• 구체적 키워드를 박는다. 사용자가 자연스럽게 말할 법한 단어를 포함시킵니다.

• 핵심 use case를 앞에 둔다. 1,536자(Claude Code 표시 캡)에서 잘려나가도 살아남도록.

좋은 예

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

나쁜 예

description: Helps with documents
description: Does stuff with files

10.4 네이밍 컨벤션

일관된 이름 짓기는 발견과 유지보수에 모두 좋습니다. 권장 패턴은 동명사형(gerund)입니다.

• 권장: processing-pdfs, analyzing-spreadsheets, managing-databases

• 대안: pdf-processing, analyze-spreadsheets

• 피할 것: helper, utils, tools, documents, data

• 금지: anthropic-*, claude-* (예약어)

10.5 진보적 공개 패턴 3가지

패턴 1 — 상위 가이드 + 참조 파일

# PDF Processing

## Quick start
Extract text with pdfplumber: ...

## Advanced features
**Form filling**: See [FORMS.md](FORMS.md)
**API reference**: See [REFERENCE.md](REFERENCE.md)
**Examples**: See [EXAMPLES.md](EXAMPLES.md)

패턴 2 — 도메인별 분리 (예: BigQuery 스킬에서 finance/sales/product/marketing 폴더로 분리)

패턴 3 — 조건부 상세 (기본 내용은 인라인, 특수 기능만 외부 파일로)

10.6 참조는 1단계까지만

중첩된 참조(SKILL.md → advanced.md → details.md)는 Claude가 head -100 같은 부분 읽기를 쓸 때 정보를 놓치게 만듭니다. 모든 참조 파일은 SKILL.md에서 직접 가리키세요.

10.7 100줄 넘는 참조 파일에는 목차를

긴 참조 파일은 맨 위에 목차를 두어, Claude가 부분 읽기로 미리보기할 때도 전체 스코프를 파악할 수 있게 합니다.

10.8 워크플로와 피드백 루프

복잡한 작업은 체크리스트와 단계로 분해합니다. Claude가 응답 안에 복사해 진행 상황을 체크할 수 있도록 만드세요.

## PDF form filling workflow

Copy this checklist and check off items as you complete them:

```
Task Progress:
- [ ] Step 1: Analyze the form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill the form (run fill_form.py)
- [ ] Step 5: Verify output (run verify_output.py)
```

피드백 루프 패턴: 검증기 실행 → 오류 수정 → 반복. 이 패턴은 출력 품질을 크게 끌어올립니다.

10.9 콘텐츠 가이드라인

• 시간 의존 정보 금지. "2025년 8월 이전에는…" 같은 표현은 곧 틀린 정보가 됩니다. 폐기된 패턴은 <details>로 접어 "Old patterns" 섹션에.

• 용어 일관성. "field"로 시작했으면 "box", "element", "control"로 흔들지 말 것.

10.10 공통 패턴 3가지

1. Template 패턴 — 출력 포맷의 템플릿 제공. 엄격할 때는 "ALWAYS use this exact template", 유연할 때는 "Here is a sensible default".

2. Examples 패턴 — input/output 쌍을 보여줘 스타일을 학습시킴.

3. Conditional workflow 패턴 — "X면 A 워크플로, Y면 B 워크플로"로 결정 분기 안내.

10.11 평가 우선(Evaluation-First) 개발

문서를 잔뜩 쓰기 전에 평가부터 만드세요.

1. 스킬 없이 Claude를 대표 과제에 돌려 실패 지점 발견.

2. 이 갭을 검증하는 시나리오 3개 작성.

3. 스킬 없을 때 베이스라인 측정.

4. 갭을 메우는 최소한의 지시문 작성.

5. 반복 평가하며 개선.

평가 JSON 예시:

{
  "skills": ["pdf-processing"],
  "query": "Extract all text from this PDF file and save it to output.txt",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "Successfully reads the PDF using an appropriate library",
    "Extracts text from all pages",
    "Saves to output.txt in a readable format"
  ]
}

10.12 Claude로 Claude의 스킬 만들기

가장 효과적인 스킬 개발은 "Claude A로 스킬을 만들고 Claude B로 시험한다"입니다.

1. 스킬 없이 Claude A와 작업해 보며 반복적으로 제공하는 컨텍스트 식별.

2. Claude A에게 "방금 한 작업을 스킬로 만들어줘" 요청.

3. 불필요한 설명 제거 ("Claude가 이미 아는 내용은 빼줘").

4. Claude B(스킬 로드된 별도 인스턴스)에서 실사용.

5. B의 실패·예상치 못한 선택을 가지고 A로 돌아와 개선.

11. 안티패턴

• Windows 백슬래시 경로 금지. scripts/helper.py로 항상 슬래시.

• 선택지를 너무 많이 주지 말 것. "pypdf, pdfplumber, PyMuPDF 중 골라라"가 아니라, "기본은 pdfplumber, OCR이 필요하면 pdf2image + pytesseract"처럼 디폴트와 탈출구만.

• "voodoo constants" 금지. 스크립트의 TIMEOUT = 47 같은 미설명 숫자. 주석으로 정당화하세요.

• punt 금지. 스크립트가 에러를 그냥 던지고 Claude에게 떠넘기지 말 것. 직접 핸들링하세요.

• 설치 가정 금지. "그냥 pdf 라이브러리를 쓰세요"가 아니라 pip install pypdf 같은 명시적 설치 지시.

• MCP 도구는 풀네임으로. BigQuery:bigquery_schema처럼 ServerName:tool_name.

12. 도구 권한과 보안

allowed-tools는 스킬이 활성화된 동안 해당 도구들의 사용 권한을 미리 허락합니다. 도구를 제한하는 게 아니라 권한 프롬프트를 건너뛰게 하는 것입니다.

---
name: commit
description: Stage and commit the current changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

프로젝트 .claude/skills/의 스킬은 워크스페이스 신뢰(trust) 다이얼로그를 수락한 후에 allowed-tools가 효력을 가집니다. 저장소를 신뢰하기 전에 스킬 내용을 검토하세요 — 스킬은 스스로에게 광범위한 도구 접근을 줄 수 있습니다.

차단하려면 /permissions에서 deny 룰을 추가합니다.

# 모든 스킬 차단
Skill

# 특정 스킬만 허용
Skill(commit)
Skill(review-pr *)

# 특정 스킬만 차단
Skill(deploy *)

13. skillOverrides로 가시성 제어

스킬 frontmatter를 수정하기 어려울 때(공유 저장소, MCP 서버 제공 스킬 등) .claude/settings.local.json에서 가시성을 조절합니다. /skills 메뉴에서 스킬을 선택하고 Space로 상태를 순환시킨 뒤 Enter로 저장하면 자동으로 기록됩니다.

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

플러그인 스킬은 skillOverrides가 적용되지 않으며 /plugin으로 관리합니다.

14. 실전 예시 모음

14.1 가장 단순한 스킬

---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

14.2 인자를 받는 스킬

---
name: migrate-component
description: Migrate a component from one framework to another
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

호출: /migrate-component SearchBar React Vue

14.3 동적 컨텍스트 + 서브에이전트

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

14.4 번들 스크립트 실행

---
name: codebase-visualizer
description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
allowed-tools: Bash(python3 *)
---

# Codebase Visualizer

## Usage

Run the visualization script from your project root:

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

This creates `codebase-map.html` in the current directory.

14.5 사용자 전용 배포 스킬

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
allowed-tools: Bash(./deploy.sh *)
---

Deploy $ARGUMENTS to production:

1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

14.6 실제 Anthropic이 배포한 docx 스킬의 frontmatter

---
name: docx
description: "Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. ... Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation."
license: Proprietary. LICENSE.txt has complete terms
---

주목할 점: ① "Triggers include:"로 키워드를 명시, ② "Do NOT use for..."로 잘못된 트리거를 차단, ③ 표준 외 필드(license)는 무시되지만 메타데이터로 남겨둠.

15. 트러블슈팅

16. 효과적 스킬 체크리스트

핵심 품질

• description이 구체적이고 핵심 키워드 포함

• description에 "무엇을 하는지 + 언제 쓰는지" 모두 명시

• SKILL.md 본문 500줄 이하

• 추가 상세는 별도 파일로 분리

• 시간 의존 정보 없음 (또는 "Old patterns" 섹션에)

• 전체에서 일관된 용어

• 예시가 추상이 아닌 구체

• 참조는 1단계까지만

• 점진적 공개를 적절히 활용

• 워크플로가 명확한 단계로 구성

코드와 스크립트

• 스크립트가 문제를 해결하지 Claude에게 떠넘기지 않음

• 에러 핸들링이 명시적이고 유용

• voodoo 상수 없음 — 모든 값이 정당화됨

• 필요한 패키지를 명시하고 가용성 확인

• 스크립트에 명확한 문서화

• Windows 백슬래시 경로 없음

• 중요한 작업에 검증·검수 단계

• 품질이 중요한 작업에 피드백 루프

테스팅

• 최소 3개의 평가 작성

• Haiku, Sonnet, Opus에서 모두 테스트

• 실사용 시나리오로 검증

• (가능하다면) 팀 피드백 반영

17. 한눈에 보는 요약

1. 스킬 = 폴더 + SKILL.md. Frontmatter(메타데이터) + Markdown(지시문).

2. 3단계 점진적 공개로 토큰을 아끼면서 깊이를 유지. (메타데이터 → 본문 → 보조 파일)

3. description이 전부다. 100개 중 이 스킬을 고를 단 하나의 근거. 3인칭, 키워드, 트리거를 모두 박아라.

4. 본문 500줄 이하, 참조 1단계, 일관된 용어, 시간 의존 정보 금지.

5. frontmatter 옵션으로 호출 제어와 컨텍스트 격리를 정밀하게.

6. 평가부터 만들고 Claude로 Claude의 스킬을 만들어라.

7. side effect 있는 작업은 disable-model-invocation: true로 안전하게.

8. 저장소 신뢰 전에는 스킬 본문을 반드시 검토한다.

참고 자료 (공식)

• Extend Claude with skills — Claude Code Docs

• Skill authoring best practices — Claude API Docs

• Agent Skills overview

• Skills Quickstart

• anthropics/skills (공개 스킬 레퍼런스 저장소)

• Equipping agents for the real world with Agent Skills (Engineering blog)

• Agent Skills 오픈 표준 사이트