에이전트 스킬 베스트프랙티스 (Agent Skills Best Practices)¶

Claude가 스킬을 잘 찾아내고 사용하도록, 효과적인 스킬을 작성하는 방법을 다뤄요. 좋은 스킬은 간결하고, 구조가 잘 잡혀 있고, 실제 사용으로 검증된 스킬이에요. 이 가이드는 Claude가 스킬을 잘 발견하고 효과적으로 사용하도록 만드는 실용적인 작성 결정들을 안내합니다.

스킬이 어떻게 동작하는지에 대한 개념적 배경이 필요하다면 Skills 개요를 먼저 보는 게 좋아요.

핵심 원칙 (Core principles)¶

간결함이 핵심 (Concise is key)¶

컨텍스트 윈도우는 모두가 함께 쓰는 공공재예요. 여러분의 스킬은 Claude가 알아야 하는 다른 모든 것과 컨텍스트 윈도우를 나눠 씁니다. 여기에는 다음이 포함돼요.

시스템 프롬프트
대화 기록
다른 스킬들의 메타데이터
실제 요청

스킬의 모든 토큰이 즉시 비용이 드는 건 아니에요. 시작 시점에는 모든 스킬의 메타데이터(이름과 설명)만 미리 로드됩니다. Claude는 스킬이 관련이 있을 때만 SKILL.md를 읽고, 필요할 때만 추가 파일을 읽어요. 그런데도 SKILL.md를 간결하게 유지하는 건 여전히 중요합니다 — Claude가 이걸 로드하면 모든 토큰이 대화 기록 및 다른 컨텍스트와 경쟁하게 되거든요.

기본 가정: Claude는 이미 아주 똑똑하다

Claude가 이미 갖고 있지 않은 컨텍스트만 추가하세요. 모든 정보 조각에 질문을 던져 보는 거예요.

"이 설명이 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 토큰):

```markdown
## 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 for PDF processing, but
pdfplumber is recommended because it's easy to use and handles most cases well.
First, you'll need to install it using pip. Then you can use the code below...

간결한 버전은 Claude가 PDF와 라이브러리가 어떻게 동작하는지 이미 안다고 가정해요.

적절한 자유도를 설정하세요 (Set appropriate degrees of freedom)¶

지시의 구체성 수준을 작업의 취약성(fragility)과 변동성(variability)에 맞추세요.

높은 자유도 (텍스트 기반 지시):

다음을 만족할 때 사용하세요.

여러 접근 방식이 모두 유효할 때
결정이 컨텍스트에 의존할 때
휴리스틱이 접근 방식을 안내할 때

예시:

## Code review process

1. Analyze the code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability and maintainability
4. Verify adherence to project conventions

중간 자유도 (매개변수가 있는 슈도코드 또는 스크립트):

다음을 만족할 때 사용하세요.

선호하는 패턴이 존재할 때
어느 정도의 변형이 허용될 때
설정이 동작에 영향을 줄 때

예시:

def generate_report(data, format="markdown", include_charts=True):
    # Process data
    # Generate output in specified format
    # Optionally include visualizations

낮은 자유도 (매개변수가 거의 없거나 없는 특정 스크립트):

다음을 만족할 때 사용하세요.

작업이 취약하고 오류가 나기 쉬울 때
일관성이 결정적일 때
특정 순서를 따라야 할 때

예시:

python scripts/migrate.py --verify --backup

명령을 수정하거나 추가 플래그를 붙이지 마세요.

비유: Claude를 길을 탐색하는 로봇으로 생각해 보세요.

양쪽에 절벽이 있는 좁은 다리: 안전하게 갈 방법은 하나뿐이에요. 구체적인 가드레일과 정확한 지시를 제공하세요 (낮은 자유도). 예: 정확한 순서로 실행해야 하는 데이터베이스 마이그레이션.
위험이 없는 넓은 들판: 성공으로 가는 길이 많아요. 일반적인 방향을 제시하고 Claude가 최선의 경로를 찾도록 신뢰하세요 (높은 자유도). 예: 컨텍스트가 최선의 접근을 결정하는 코드 리뷰.

사용하려는 모든 모델로 테스트하세요 (Test with all models you plan to use)¶

스킬은 모델에 대한 추가 요소(addition)처럼 동작하므로, 효과는 기본 모델에 따라 달라져요. 스킬을 사용하려는 모든 모델로 테스트하세요.

모델별 테스트 고려 사항:

Claude Haiku (빠르고 경제적): 스킬이 충분한 지침을 제공하는가?
Claude Sonnet (균형): 스킬이 명확하고 효율적인가?
Claude Opus (강력한 추론): 스킬이 과잉 설명을 피하는가?

Opus에 완벽하게 동작하는 것이 Haiku에는 더 많은 세부사항이 필요할 수 있어요. 스킬을 여러 모델에서 사용하려면 모두에서 잘 동작하는 지침을 목표로 하세요.

스킬 구조 (Skill structure)¶

YAML 프론트매터¶

SKILL.md 프론트매터는 두 개의 필드를 요구합니다:

name:

최대 64자
소문자, 숫자, 하이픈만 포함해야 함
XML 태그를 포함할 수 없음
예약어를 포함할 수 없음: "anthropic", "claude"

description:

비어 있으면 안 됨
최대 1,024자
XML 태그를 포함할 수 없음
스킬이 무엇을 하는지, 언제 사용해야 하는지를 설명해야 함

완전한 스킬 구조에 대한 자세한 내용은 Skills 개요를 참조하세요.

이름 규칙 (Naming conventions)¶

스킬을 참조하고 논의하기 쉽도록 일관된 명명 패턴을 사용하세요. 스킬 이름에는 동명사 형태(verb + -ing) 를 고려하세요. 스킬이 제공하는 활동이나 기능을 명확히 설명해 주거든요.

name 필드는 소문자, 숫자, 하이픈만 사용해야 한다는 점을 기억하세요.

좋은 명명 예시 (동명사 형태):

processing-pdfs
analyzing-spreadsheets
managing-databases
testing-code
writing-documentation

허용 가능한 대안:

명사구: pdf-processing, spreadsheet-analysis
행동 지향: process-pdfs, analyze-spreadsheets

피해야 할 것:

모호한 이름: helper, utils, tools
지나치게 일반적인 것: documents, data, files
예약어: anthropic-helper, claude-tools
스킬 컬렉션 내의 불일치한 패턴

일관된 명명은 다음을 쉽게 만들어요.

문서와 대화에서 스킬을 참조
스킬이 무엇을 하는지 한눈에 이해
여러 스킬을 정리하고 검색
전문적이고 응집력 있는 스킬 라이브러리 유지

효과적인 설명 작성 (Writing effective descriptions)¶

description 필드는 스킬 발견(discovery)을 가능하게 하며, 스킬이 무엇을 하는지와 언제 사용해야 하는지 둘 다 포함해야 해요.

항상 3인칭으로 작성하세요. 설명은 시스템 프롬프트에 주입되며, 일관되지 않은 시점(인칭)은 발견 문제를 일으킬 수 있어요.

좋음: "Processes Excel files and generates reports"
피함: "I can help you process Excel files"
피함: "You can use this to process Excel files"

구체적으로 쓰고 핵심 용어를 포함하세요. 스킬이 무엇을 하는지와, 언제 사용할 구체적인 트리거/컨텍스트를 모두 포함하세요.

각 스킬에는 정확히 하나의 description 필드가 있어요. 이 설명은 스킬 선택에 결정적입니다 — Claude는 잠재적으로 100개 이상의 스킬 중에서 이 설명을 사용해 올바른 스킬을 골라요. 설명은 Claude가 이 스킬을 언제 선택할지 알 수 있을 만큼 충분한 세부사항을 제공해야 하며, 나머지 SKILL.md는 구현 세부사항을 제공합니다.

효과적인 예시:

PDF Processing 스킬:

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.

Excel Analysis 스킬:

description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.

Git Commit Helper 스킬:

description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.

이런 모호한 설명은 피하세요:

description: Helps with documents

description: Processes data

description: Does stuff with files

점진적 공개 패턴 (Progressive disclosure patterns)¶

SKILL.md는 온보딩 가이드의 목차처럼, Claude가 필요할 때 세부 자료를 가리키는 개요 역할을 해요. 점진적 공개가 어떻게 동작하는지에 대한 설명은 개요의 "How Skills work"를 참조하세요.

실용적 지침:

최적 성능을 위해 SKILL.md 본문을 500줄 미만으로 유지
이 한도에 가까워지면 내용을 별도의 파일로 분할
지시, 코드, 리소스를 효과적으로 조직하기 위해 아래 패턴 사용

시각적 개요: 단순에서 복잡으로

기본 스킬은 메타데이터와 지시를 담은 SKILL.md 하나에서 시작해요. 스킬이 커지면 Claude가 필요할 때만 로드하는 추가 콘텐츠를 묶을 수 있어요.

완전한 스킬 디렉터리 구조는 이렇게 생겼어요.

pdf/
SKILL.md: Main instructions (loaded when triggered)
FORMS.md: Form-filling guide (loaded as needed)
reference.md: API reference (loaded as needed)
examples.md: Usage examples (loaded as needed)
scripts/
analyze_form.py: Utility script (executed, not loaded)
fill_form.py: Form filling script
validate.py: Validation script

패턴 1: 참조가 있는 상위 레벨 가이드

---
name: pdf-processing
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

# PDF Processing

## Quick start

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

Advanced features¶

Form filling: See FORMS.md for complete guide API reference: See REFERENCE.md for all methods Examples: See EXAMPLES.md for common patterns

Claude는 FORMS.md, REFERENCE.md, EXAMPLES.md를 필요할 때만 로드해요.

**패턴 2: 도메인별 구성**

여러 도메인이 있는 스킬은 관련 없는 컨텍스트를 로드하지 않도록 도메인별로 내용을 구성하세요. 사용자가 판매 지표에 대해 물어볼 때, Claude는 금융이나 마케팅 데이터가 아니라 판매 관련 스키마만 읽으면 돼요. 이렇게 하면 토큰 사용량을 낮추고 컨텍스트를 집중시킬 수 있어요.

bigquery-skill/ SKILL.md (overview and navigation) reference/ finance.md (revenue, billing metrics) sales.md (opportunities, pipeline) product.md (API usage, features) marketing.md (campaigns, attribution)

```markdown
# BigQuery Data Analysis

## Available datasets

**Finance**: Revenue, ARR, billing → See [reference/finance.md](reference/finance.md)
**Sales**: Opportunities, pipeline, accounts → See [reference/sales.md](reference/sales.md)
**Product**: API usage, features, adoption → See [reference/product.md](reference/product.md)
**Marketing**: Campaigns, attribution, email → See [reference/marketing.md](reference/marketing.md)

## Quick search

Find specific metrics using grep:

```bash
grep -i "revenue" reference/finance.md
grep -i "pipeline" reference/sales.md
grep -i "api usage" reference/product.md

**패턴 3: 조건부 세부사항**

기본 콘텐츠를 보여주고 고급 콘텐츠로 링크를 걸어요.

```markdown
# DOCX Processing

## Creating documents

Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents

For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

Claude는 사용자가 그 기능을 필요로 할 때만 REDLINING.md 또는 OOXML.md를 읽어요.

깊게 중첩된 참조 피하기 (Avoid deeply nested references)¶

Claude는 다른 참조 파일에서 참조된 파일을 읽을 때 부분적으로 읽을 수 있어요. 중첩 참조를 만나면 Claude는 전체 파일을 읽는 대신 head -100 같은 명령으로 내용을 미리 보여 불완전한 정보를 얻을 수 있어요.

SKILL.md에서 참조를 한 단계 깊이로 유지하세요. 모든 참조 파일은 SKILL.md에서 직접 링크되어야 필요할 때 완전한 파일을 읽을 수 있어요.

나쁜 예: 너무 깊음:

# SKILL.md
See [advanced.md](advanced.md)...

# advanced.md
See [details.md](details.md)...

# details.md
Here's the actual information...

좋은 예: 한 단계 깊이:

# SKILL.md

**Basic usage**: [instructions in SKILL.md]
**Advanced features**: See [advanced.md](advanced.md)
**API reference**: See [reference.md](reference.md)
**Examples**: See [examples.md](examples.md)

긴 참조 파일에는 목차 넣기 (Structure longer reference files with table of contents)¶

100줄이 넘는 참조 파일에는 상단에 목차를 포함하세요. 부분 읽기로 미리 보는 경우에도 Claude가 사용 가능한 정보의 전체 범위를 볼 수 있도록 해줘요.

예시:

# API Reference

## Contents
- Authentication and setup
- Core methods (create, read, update, delete)
- Advanced features (batch operations, webhooks)
- Error handling patterns
- Code examples

## Authentication and setup
...

## Core methods
...

그러면 Claude는 전체 파일을 읽거나 필요에 따라 특정 섹션으로 이동할 수 있어요.

이 파일시스템 기반 아키텍처가 점진적 공개를 어떻게 가능하게 하는지에 대한 자세한 내용은 이 가이드 뒷부분의 Runtime environment 섹션을 참조하세요.

워크플로와 피드백 루프 (Workflows and feedback loops)¶

복잡한 작업에는 워크플로 사용 (Use workflows for complex tasks)¶

복잡한 작업은 명확하고 순차적인 단계로 나누세요. 특히 복잡한 워크플로에는 Claude가 응답에 복사해서 진행 상황을 체크할 수 있는 체크리스트를 제공하세요.

예시 1: 리서치 종합 워크플로 (코드 없는 스킬용):

## Research synthesis workflow

Copy this checklist and track your progress:

Research Progress: - [ ] Step 1: Read all source documents - [ ] Step 2: Identify key themes - [ ] Step 3: Cross-reference claims - [ ] Step 4: Create structured summary - [ ] Step 5: Verify citations

**Step 1: Read all source documents**

Review each document in the `sources/` directory. Note the main arguments and supporting evidence.

**Step 2: Identify key themes**

Look for patterns across sources. What themes appear repeatedly? Where do sources agree or disagree?

**Step 3: Cross-reference claims**

For each major claim, verify it appears in the source material. Note which source supports each point.

**Step 4: Create structured summary**

Organize findings by theme. Include:
- Main claim
- Supporting evidence from sources
- Conflicting viewpoints (if any)

**Step 5: Verify citations**

Check that every claim references the correct source document. If citations are incomplete, return to Step 3.

이 예시는 코드가 필요 없는 분석 작업에 워크플로가 어떻게 적용되는지 보여줘요. 체크리스트 패턴은 복잡하고 다단계인 모든 프로세스에 잘 맞아요.

예시 2: PDF 양식 작성 워크플로 (코드 있는 스킬용):

## 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)

**Step 1: Analyze the form**

Run: `python scripts/analyze_form.py input.pdf`

This extracts form fields and their locations, saving to `fields.json`.

**Step 2: Create field mapping**

Edit `fields.json` to add values for each field.

**Step 3: Validate mapping**

Run: `python scripts/validate_fields.py fields.json`

Fix any validation errors before continuing.

**Step 4: Fill the form**

Run: `python scripts/fill_form.py input.pdf fields.json output.pdf`

**Step 5: Verify output**

Run: `python scripts/verify_output.py output.pdf`

If verification fails, return to Step 2.

명확한 단계는 Claude가 중요한 검증을 건너뛰는 것을 막아줘요. 체크리스트는 Claude와 사용자 모두가 다단계 워크플로에서 진행 상황을 추적하도록 도와줍니다.

피드백 루프 구현 (Implement feedback loops)¶

일반 패턴: 검증기 실행 → 오류 수정 → 반복

이 패턴은 출력 품질을 크게 향상시켜요.

예시 1: 스타일 가이드 준수 (코드 없는 스킬용):

## Content review process

1. Draft your content following the guidelines in STYLE_GUIDE.md
2. Review against the checklist:
   - Check terminology consistency
   - Verify examples follow the standard format
   - Confirm all required sections are present
3. If issues found:
   - Note each issue with specific section reference
   - Revise the content
   - Review the checklist again
4. Only proceed when all requirements are met
5. Finalize and save the document

이것은 스크립트 대신 참조 문서를 사용하는 검증 루프 패턴을 보여줘요. "검증기"는 STYLE_GUIDE.md이며, Claude가 읽고 비교하여 검사를 수행합니다.

예시 2: 문서 편집 프로세스 (코드 있는 스킬용):

## Document editing process

1. Make your edits to `word/document.xml`
2. **Validate immediately**: `python ooxml/scripts/validate.py unpacked_dir/`
3. If validation fails:
   - Review the error message carefully
   - Fix the issues in the XML
   - Run validation again
4. **Only proceed when validation passes**
5. Rebuild: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. Test the output document

검증 루프는 오류를 조기에 잡아줘요.

콘텐츠 지침 (Content guidelines)¶

시간에 민감한 정보 피하기 (Avoid time-sensitive information)¶

곧 낡아버릴 정보는 넣지 마세요.

나쁜 예: 시간에 민감함 (곧 틀려짐):

If you're doing this before August 2025, use the old API. After August 2025, use the new API.

좋은 예 ("old patterns" 섹션 사용):

## Current method

Use the v2 API endpoint: `api.example.com/v2/messages`

## Old patterns

<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>

The v1 API used: `api.example.com/v1/messages`

This endpoint is no longer supported.
</details>

old patterns 섹션은 메인 콘텐츠를 어지럽히지 않으면서 과거 맥락을 제공해요.

일관된 용어 사용 (Use consistent terminology)¶

하나의 용어를 선택해서 스킬 전체에서 그걸 사용하세요:

좋음 - 일관됨:

항상 "API endpoint"
항상 "field"
항상 "extract"

나쁨 - 불일치:

"API endpoint", "URL", "API route", "path" 혼용
"field", "box", "element", "control" 혼용
"extract", "pull", "get", "retrieve" 혼용

일관성은 Claude가 지시를 파싱하고 따르는 것을 도와줘요.

일반 패턴 (Common patterns)¶

템플릿 패턴 (Template pattern)¶

출력 형식에 대한 템플릿을 제공하세요. 엄격함의 정도를 필요에 맞추세요.

엄격한 요구사항용 (API 응답이나 데이터 형식 등):

## Report structure

ALWAYS use this exact template structure:

# [Analysis Title]

## Executive summary
[One-paragraph overview of key findings]

## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data
- Finding 3 with supporting data

## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation

유연한 지침용 (적응이 유용할 때):

## Report structure

Here is a sensible default format, but use your best judgment based on the analysis:

# [Analysis Title]

## Executive summary
[Overview]

## Key findings
[Adapt sections based on what you discover]

## Recommendations
[Tailor to the specific context]

특정 분석 유형에 맞게 섹션을 조정하세요.

예시 패턴 (Examples pattern)¶

출력 품질이 예시를 보는 것에 달려 있는 스킬이라면, 일반 프롬프팅에서처럼 입출력 쌍을 제공하세요.

## Commit message format

Generate commit messages following these examples:

**Example 1:**
Input: Added user authentication with JWT tokens
Output:

feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware

**Example 2:**
Input: Fixed bug where dates displayed incorrectly in reports
Output:

fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation

**Example 3:**
Input: Updated dependencies and refactored error handling
Output:

chore: update dependencies and refactor error handling

Upgrade lodash to 4.17.21

Standardize error response format across endpoints

Follow this style: type(scope): brief description, then detailed explanation.

예시는 원하는 스타일과 세부 수준을 설명만으로 전달하는 것보다 Claude에게 더 명확하게 전달해요.

조건부 워크플로 패턴 (Conditional workflow pattern)¶

결정 지점을 통해 Claude를 안내하세요.

## Document modification workflow

1. Determine the modification type:

   **Creating new content?** → Follow "Creation workflow" below
   **Editing existing content?** → Follow "Editing workflow" below

2. Creation workflow:
   - Use docx-js library
   - Build document from scratch
   - Export to .docx format

3. Editing workflow:
   - Unpack existing document
   - Modify XML directly
   - Validate after each change
   - Repack when complete

워크플로가 많거나 복잡한 단계로 커지면, 별도의 파일로 옮기고 실행할 작업에 따라 적절한 파일을 읽도록 Claude에게 지시하는 것을 고려하세요.

평가와 반복 (Evaluation and iteration)¶

먼저 평가를 구축하세요 (Build evaluations first)¶

방대한 문서를 작성하기 전에 평가(evaluations)를 만드세요. 이렇게 해야 스킬이 상상 속의 문제를 문서화하는 대신 실제 문제를 해결할 수 있어요.

평가 주도 개발 (Evaluation-driven development):

격차(Gaps) 파악: 스킬 없이 대표적인 작업으로 Claude를 실행하세요. 구체적인 실패나 누락된 컨텍스트를 기록하세요
평가 생성: 이러한 격차를 테스트하는 세 가지 시나리오를 구축하세요
기준선 수립: 스킬 없이 Claude의 성능을 측정하세요
최소한의 지시 작성: 격차를 해결하고 평가를 통과할 수 있을 만큼만 내용을 만드세요
반복: 평가를 실행하고 기준선과 비교한 뒤 다듬으세요

이 접근 방식은 실제로 실현되지 않을지도 모르는 요구사항을 예측하는 대신 실제 문제를 해결하도록 보장해요.

평가 구조:

{
  "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 file using an appropriate PDF processing library or command-line tool",
    "Extracts text content from all pages in the document without missing any pages",
    "Saves the extracted text to a file named output.txt in a clear, readable format"
  ]
}

이 예시는 간단한 테스트 루브릭(rubric)을 사용하는 데이터 기반 평가를 보여줘요. 현재 이 평가를 실행하는 내장된 방법은 없으며, 사용자가 자신만의 평가 시스템을 만들 수 있어요. 평가는 스킬 효과를 측정하는 기준이 되는 진실(ground truth)입니다.

Claude와 함께 스킬을 반복적으로 개발하세요 (Develop Skills iteratively with Claude)¶

가장 효과적인 스킬 개발 프로세스는 Claude 자체를 포함해요. 다른 인스턴스("Claude B")들이 사용할 스킬을 만들기 위해 한 인스턴스의 Claude("Claude A")와 함께 작업하세요. Claude A는 지시를 설계하고 다듬는 것을 도와주고, Claude B는 실제 작업에서 그것을 테스트해요. Claude 모델이 효과적인 에이전트 지시를 작성하는 방법과 에이전트가 필요한 정보를 모두 이해하고 있기 때문에 가능한 일이에요.

새 스킬 만들기:

스킬 없이 작업 완료: 일반 프롬프팅으로 Claude A와 문제를 해결하세요. 작업하는 동안 자연스럽게 컨텍스트를 제공하고, 선호도를 설명하고, 절차적 지식을 공유하게 돼요. 반복해서 제공하는 정보가 무엇인지 주목하세요.
재사용 가능한 패턴 파악: 작업을 마친 뒤, 비슷한 미래 작업에 유용할 컨텍스트를 파악하세요. 예: BigQuery 분석을 작업했다면 테이블 이름, 필드 정의, 필터링 규칙(예: "항상 테스트 계정 제외"), 일반적인 쿼리 패턴을 제공했을 거예요.
Claude A에게 스킬 생성 요청: "방금 사용한 이 BigQuery 분석 패턴을 담은 스킬을 만들어 줘. 테이블 스키마, 명명 규칙, 테스트 계정 필터링 규칙을 포함해 줘."
간결성 검토: Claude A가 불필요한 설명을 추가하지 않았는지 확인하세요. "win rate가 무엇을 의미하는지 설명은 빼줘 — Claude는 이미 그걸 알고 있어."라고 요청하세요.
정보 아키텍처 개선: Claude A에게 콘텐츠를 더 효과적으로 정리해 달라고 요청하세요. 예: "나중에 테이블을 더 추가할 수 있으니 테이블 스키마를 별도의 참조 파일에 넣도록 정리해 줘."
비슷한 작업으로 테스트: 스킬이 로드된 새 인스턴스(Claude B)로 관련 사용 사례에 스킬을 사용해 보세요. Claude B가 올바른 정보를 찾고, 규칙을 올바르게 적용하고, 작업을 성공적으로 처리하는지 관찰하세요.
관찰에 기반한 반복: Claude B가 어려워하거나 뭔가를 놓치면, 구체적으로 Claude A에게 돌아가세요. "스킬을 사용할 때 Q4에 대해 날짜로 필터링하는 걸 잊었어. 날짜 필터링 패턴에 대한 섹션을 추가해야 할까?"

기존 스킬 반복:

스킬을 개선할 때도 같은 계층적 패턴이 이어져요. 다음을 번갈아 가며 합니다:

Claude A와 협업 (스킬 다듬기를 돕는 전문가)
Claude B로 테스트 (실제 작업을 수행하는 에이전트)
Claude B의 행동을 관찰하고 통찰을 Claude A로 가져오기
실제 워크플로에서 스킬 사용: (스킬이 로드된) Claude B에게 테스트 시나리오가 아닌 실제 작업을 주세요
Claude B의 행동 관찰: 어디에서 어려워하고, 성공하고, 예상치 못한 선택을 하는지 주목하세요. 예시 관찰: "Claude B에게 지역별 판매 보고서를 요청했는데, 스킬이 이 규칙을 언급했음에도 테스트 계정을 필터링하는 걸 잊었어."
개선을 위해 Claude A로 돌아가기: 현재 SKILL.md를 공유하고 관찰한 것을 설명하세요. "지역 보고서를 요청했을 때 Claude B가 테스트 계정 필터링을 잊더라고. 스킬이 필터링을 언급하는데, 충분히 눈에 띄지 않는 건가?"라고 물어보세요.
Claude A의 제안 검토: Claude A는 규칙을 더 눈에 띄게 재구성하거나, "always filter" 대신 "MUST filter"처럼 더 강한 표현을 사용하거나, 워크플로 섹션을 재구성하도록 제안할 수 있어요.
변경 적용 및 테스트: Claude A의 개선으로 스킬을 업데이트하고, 비슷한 요청으로 Claude B와 다시 테스트하세요
사용에 기반한 반복: 새 시나리오를 만날 때마다 이 관찰-다듬기-테스트 주기를 계속하세요. 각 반복은 가정이 아닌 실제 에이전트 행동에 기반해 스킬을 개선합니다.

팀 피드백 수집:

스킬을 팀원들과 공유하고 그들의 사용을 관찰
질문: 스킬이 예상대로 활성화되나요? 지시가 명확한가요? 무엇이 빠져 있나요?
피드백을 통합해 자신의 사용 패턴에서 격차를 해결

이 접근 방식이 효과적인 이유: Claude A는 에이전트의 필요를 이해하고, 여러분은 도메인 전문성을 제공하며, Claude B는 실제 사용을 통해 격차를 드러내고, 반복적 개선은 가정이 아닌 관찰된 행동에 기반해 스킬을 개선해요.

Claude가 스킬을 어떻게 탐색하는지 관찰하세요 (Observe how Claude navigates Skills)¶

스킬을 반복할 때, Claude가 실제로 스킬을 어떻게 사용하는지 주의를 기울이세요. 다음을 관찰하세요.

예상치 못한 탐색 경로: Claude가 예상하지 못한 순서로 파일을 읽나요? 구조가 생각만큼 직관적이지 않을 수 있어요
놓친 연결: Claude가 중요한 파일에 대한 참조를 따르지 못하나요? 링크가 더 명시적이거나 눈에 띄어야 할 수도 있어요
특정 섹션에 대한 과의존: Claude가 같은 파일을 반복해서 읽으면, 그 내용이 메인 SKILL.md에 있어야 하는지 고려하세요
무시된 콘텐츠: Claude가 번들 파일에 전혀 접근하지 않으면, 불필요하거나 메인 지시에서 신호가 약한 것일 수 있어요

가정이 아닌 이러한 관찰에 기반해 반복하세요. 스킬 메타데이터의 'name'과 'description'은 특히 중요해요. Claude는 현재 작업에 응답해 스킬을 트리거할지 결정할 때 이것을 사용합니다. 스킬이 무엇을 하는지, 언제 사용해야 하는지 명확히 설명하는지 확인하세요.

피해야 할 안티패턴 (Anti-patterns to avoid)¶

Windows 스타일 경로 피하기 (Avoid Windows-style paths)¶

파일 경로에는 Windows에서도 항상 앞슬래시(forward slashes)를 사용하세요.

✓ 좋음: scripts/helper.py, reference/guide.md
✗ 피함: scripts\helper.py, reference\guide.md

유닉스 스타일 경로는 모든 플랫폼에서 동작하지만, Windows 스타일 경로는 유닉스 시스템에서 오류를 일으켜요.

너무 많은 옵션 제공 피하기 (Avoid offering too many options)¶

필요하지 않으면 여러 접근 방식을 제시하지 마세요.

나쁜 예: 너무 많은 선택지 (혼란스러움):

"You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or..."

좋은 예: 기본값 제공 (탈출구 포함):

"Use pdfplumber for text extraction:
import pdfplumber
For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."

고급: 실행 가능한 코드가 있는 스킬 (Advanced: Skills with executable code)¶

다음 섹션은 실행 가능한 스크립트를 포함한 스킬에 초점을 맞춰요. 스킬이 마크다운 지시만 사용한다면 Checklist for effective Skills로 건너뛰세요.

연기하지 말고 해결하세요 (Solve, don't defer)¶

스킬용 스크립트를 작성할 때는 Claude에 맡기는 대신 오류 조건을 직접 처리하세요.

좋은 예: 오류를 명시적으로 처리:

def process_file(path):
    """Process a file, creating it if it doesn't exist."""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        # Create file with default content instead of failing
        print(f"File {path} not found, creating default")
        with open(path, "w") as f:
            f.write("")
        return ""
    except PermissionError:
        # Provide alternative instead of failing
        print(f"Cannot access {path}, using default")
        return ""

나쁜 예: Claude에 연기:

def process_file(path):
    # Just fail and let Claude figure it out
    return open(path).read()

설정 매개변수도 "voodoo constants"(Ousterhout의 법칙)를 피하기 위해 근거가 있고 문서화되어야 해요. 올바른 값을 모른다면 Claude가 어떻게 결정할 수 있을까요?

좋은 예: 자기 문서화(self-documenting):

# HTTP requests typically complete within 30 seconds
# Longer timeout accounts for slow connections
REQUEST_TIMEOUT = 30

# Three retries balances reliability vs speed
# Most intermittent failures resolve by the second retry
MAX_RETRIES = 3

나쁜 예: 매직 넘버:

TIMEOUT = 47  # Why 47?
RETRIES = 5  # Why 5?

유틸리티 스크립트 제공 (Provide utility scripts)¶

Claude가 스크립트를 직접 작성할 수 있더라도, 미리 만들어진 스크립트는 장점이 있어요.

유틸리티 스크립트의 이점:

생성된 코드보다 더 신뢰할 수 있음
토큰 절약 (코드를 컨텍스트에 포함할 필요 없음)
시간 절약 (코드 생성 불필요)
사용 간 일관성 보장

앞서 나온 다이어그램은 실행 가능한 스크립트가 지시 파일과 어떻게 함께 동작하는지 보여줘요. 지시 파일(forms.md)이 스크립트를 참조하고, Claude는 그 내용을 컨텍스트에 로드하지 않고도 실행할 수 있어요.

중요한 구분: 지시에서 Claude가 무엇을 해야 하는지 분명히 하세요:

스크립트 실행 (가장 일반적): "Run analyze_form.py to extract fields"
참조로 읽기 (복잡한 로직용): "See analyze_form.py for the field extraction algorithm"

대부분의 유틸리티 스크립트는 실행이 더 신뢰할 수 있고 효율적이므로 선호돼요. 스크립트 실행이 어떻게 동작하는지에 대한 자세한 내용은 다음 Runtime environment 섹션을 참조하세요.

예시:

## Utility scripts

**analyze_form.py**: Extract all form fields from PDF

```bash
python scripts/analyze_form.py input.pdf > fields.json

Output format:

{
  "field_name": {"type": "text", "x": 100, "y": 200},
  "signature": {"type": "sig", "x": 150, "y": 500}
}

validate_boxes.py: Check for overlapping bounding boxes

python scripts/validate_boxes.py fields.json
# Returns: "OK" or lists conflicts

fill_form.py: Apply field values to PDF

python scripts/fill_form.py input.pdf fields.json output.pdf

### 시각적 분석 사용 (Use visual analysis)

입력을 이미지로 렌더링할 수 있을 때는 Claude가 그것을 분석하게 하세요.

```markdown
## Form layout analysis

1. Convert PDF to images:
   ```bash
   python scripts/pdf_to_images.py form.pdf
   ```

2. Analyze each page image to identify form fields
3. Claude can see field locations and types visually

이 예시에서는 pdf_to_images.py 스크립트를 직접 작성해야 해요. Claude의 비전 기능은 레이아웃과 구조를 분석하는 데 도움이 됩니다.

검증 가능한 중간 출력 만들기 (Create verifiable intermediate outputs)¶

Claude가 복잡하고 개방적인 작업을 수행할 때 실수를 할 수 있어요. "계획-검증-실행" 패턴은 Claude가 먼저 구조화된 형식으로 계획을 만들고, 실행 전에 스크립트로 그 계획을 검증하게 하여 오류를 조기에 잡아줘요.

예시: 스프레드시트에 기반해 PDF의 50개 양식 필드를 업데이트하라고 Claude에게 요청하는 경우를 상상해 보세요. 검증 없이는 Claude가 존재하지 않는 필드를 참조하거나, 충돌하는 값을 만들거나, 필수 필드를 놓치거나, 업데이트를 잘못 적용할 수 있어요.

해결책: 앞서 보여준 워크플로 패턴(PDF 양식 채우기)을 사용하되, 변경을 적용하기 전에 검증되는 중간 changes.json 파일을 추가하세요. 워크플로는 다음과 같이 돼요: 분석 → 계획 파일 생성 → 계획 검증 → 실행 → 검증.

이 패턴이 효과적인 이유:

조기 오류 포착: 검증이 변경 적용 전에 문제를 찾아줘요
기계적 검증 가능: 스크립트가 객관적 검증을 제공해요
되돌릴 수 있는 계획: Claude는 원본을 건드리지 않고 계획을 반복할 수 있어요
명확한 디버깅: 오류 메시지가 특정 문제를 가리켜요

언제 사용: 배치 작업, 파괴적 변경, 복잡한 검증 규칙, 위험도가 높은 작업.

구현 팁: 'signature_date' 필드를 찾을 수 없다. 사용 가능한 필드: customer_name, order_total, signature_date_signed 같은 구체적인 오류 메시지로 검증 스크립트를 장황하게 만들어 Claude가 문제를 고치도록 도와주세요.

패키지 의존성 (Package dependencies)¶

스킬은 플랫폼별 제한사항이 있는 코드 실행 환경에서 실행돼요.

claude.ai: npm과 PyPI에서 패키지를 설치하고 GitHub 저장소에서 가져올 수 있음
Claude API: 네트워크 접근이 없고 런타임 패키지 설치가 없음

필요한 패키지를 SKILL.md에 나열하고 Code execution tool 문서에서 사용 가능한지 확인하세요.

런타임 환경 (Runtime environment)¶

스킬은 파일시스템 접근, bash 명령, 코드 실행 기능이 있는 코드 실행 환경에서 실행돼요. 이 아키텍처의 개념적 설명은 개요의 The Skills architecture를 참조하세요.

이것이 작성에 미치는 영향:

Claude가 스킬에 접근하는 방법:

메타데이터 미리 로드: 시작 시 모든 스킬의 YAML 프론트매터의 이름과 설명이 시스템 프롬프트에 로드됨
파일 온디맨드 읽기: Claude는 필요할 때 bash Read 도구로 SKILL.md 및 기타 파일을 파일시스템에서 접근
스크립트 효율적 실행: 유틸리티 스크립트는 전체 내용을 컨텍스트에 로드하지 않고 bash로 실행 가능. 스크립트의 출력만 토큰을 소비
대형 파일에 대한 컨텍스트 패널티 없음: 참조 파일, 데이터, 문서는 실제로 읽을 때까지 컨텍스트 토큰을 소비하지 않음
파일 경로가 중요: Claude는 스킬 디렉터리를 파일시스템처럼 탐색. 앞슬래시(reference/guide.md)를 사용하고 역슬래시는 사용하지 말 것
파일을 설명적으로 이름 짓기: 내용을 나타내는 이름 사용: doc2.md가 아닌 form_validation_rules.md
발견을 위해 구성: 디렉터리를 도메인이나 기능별로 구성. 좋음: reference/finance.md, reference/sales.md. 나쁨: docs/file1.md, docs/file2.md
종합적인 리소스 번들링: 완전한 API 문서, 광범위한 예시, 대형 데이터셋 포함; 접근할 때까지 컨텍스트 패널티 없음
결정적 작업에는 스크립트 선호: Claude에게 검증 코드를 생성하라고 요청하지 말고 validate_form.py를 작성
실행 의도를 명확히:
"Run analyze_form.py to extract fields" (실행)
"See analyze_form.py for the extraction algorithm" (참조로 읽기)
파일 접근 패턴 테스트: 실제 요청으로 테스트해 Claude가 디렉터리 구조를 탐색할 수 있는지 확인

예시:

bigquery-skill/
SKILL.md (overview, points to reference files)
reference/
finance.md (revenue metrics)
sales.md (pipeline data)
product.md (usage analytics)

사용자가 매출에 대해 물어보면 Claude는 SKILL.md를 읽고 reference/finance.md 참조를 보고 bash를 호출해 그 파일만 읽어요. sales.md와 product.md는 필요할 때까지 컨텍스트 토큰을 0개 소비하며 파일시스템에 남아 있어요. 이 파일시스템 기반 모델이 점진적 공개를 가능하게 합니다. Claude는 각 작업이 요구하는 것을 정확히 탐색하고 선택적으로 로드할 수 있어요.

기술 아키텍처에 대한 완전한 세부사항은 Skills 개요의 How Skills work를 참조하세요.

MCP 도구 참조 (MCP tool references)¶

스킬이 MCP(Model Context Protocol) 도구를 사용한다면 "tool not found" 오류를 피하기 위해 항상 정규화된(fully qualified) 도구 이름을 사용하세요.

형식: ServerName:tool_name

예시:

Use the BigQuery:bigquery_schema tool to retrieve table schemas. Use the GitHub:create_issue tool to create issues.

여기서:

BigQuery와 GitHub는 MCP 서버 이름
bigquery_schema와 create_issue는 그 서버 안의 도구 이름

서버 접두사 없이는, 특히 여러 MCP 서버가 있을 때 Claude가 도구를 찾지 못할 수 있어요.

도구가 설치되어 있다고 가정하지 마세요 (Avoid assuming tools are installed)¶

패키지가 사용 가능하다고 가정하지 마세요.

나쁜 예: 설치를 가정:

"Use the pdf library to process the file."

좋은 예: 의존성에 대해 명시적:

"Install required package: pip install pypdf

Then use it: python from pypdf import PdfReader reader = PdfReader("file.pdf")"

기술 노트 (Technical notes)¶

YAML 프론트매터 요구사항¶

SKILL.md 프론트매터는 특정 검증 규칙이 있는 name과 description 필드를 요구합니다:

name: 최대 64자, 소문자/숫자/하이픈만, XML 태그 없음, 예약어 없음
description: 최대 1,024자, 비어 있지 않음, XML 태그 없음

완전한 구조 세부사항은 Skills 개요를 참조하세요.

토큰 예산 (Token budgets)¶

최적 성능을 위해 SKILL.md 본문을 500줄 미만으로 유지하세요. 내용이 이 한도를 초과하면 앞서 설명한 점진적 공개 패턴을 사용해 별도의 파일로 분할하세요. 아키텍처 세부사항은 Skills 개요를 참조하세요.

효과적인 스킬을 위한 체크리스트 (Checklist for effective Skills)¶

스킬을 공유하기 전에 다음을 확인하세요:

핵심 품질 (Core quality)

코드와 스크립트 (Code and scripts)

스크립트가 Claude에 연기하지 않고 문제를 해결
오류 처리가 명시적이고 도움이 됨
"voodoo constants" 없음 (모든 값에 근거가 있음)
필수 패키지가 지시에 나열되고 사용 가능한지 확인됨
스크립트에 명확한 문서화
Windows 스타일 경로 없음 (모두 앞슬래시)
중요 작업에 대한 검증/확인 단계
품질이 중요한 작업에 피드백 루프 포함

테스팅 (Testing)

평가(evaluations)가 3개 이상 생성됨
Haiku, Sonnet, Opus로 테스트됨
실제 사용 시나리오로 테스트됨
팀 피드백 통합 (해당하는 경우)

다음 단계 (Next steps)¶

Get started with Agent Skills — 첫 스킬 만들기
Use Skills in Claude Code — Claude Code에서 스킬 생성 및 관리
Use Skills with the API — 프로그래밍 방식으로 스킬 업로드 및 사용

원문: Skill authoring best practices — Claude Platform Docs