Skill 작성 모범 사례

좋은 Skills는 간결하고, 잘 구조화되어 있으며, 실제 사용을 통해 테스트됩니다. 이 가이드는 Claude가 효과적으로 발견하고 사용할 수 있는 Skills를 작성하는 데 도움이 되는 실용적인 작성 결정 사항을 제공합니다.

Skills의 작동 방식에 대한 개념적 배경은 Skills 개요를 참조하세요.

핵심 원칙

간결함이 핵심입니다

"Context window"(컨텍스트 윈도우)는 공공재입니다. 컨텍스트 윈도우는 Skill과 Claude가 알아야 하는 다른 모든 것이 함께 공유하며, 여기에는 다음이 포함됩니다:

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

Skill의 모든 토큰이 즉각적인 비용을 발생시키는 것은 아닙니다. 시작 시에는 모든 Skills의 메타데이터(name 및 description)만 사전 로드됩니다. Claude는 Skill이 관련성을 갖게 될 때만 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 토큰):

## 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와 라이브러리 작동 방식에 대한 정보를 가지고 있다고 가정합니다.

적절한 자유도 설정

작업의 취약성과 가변성에 맞게 구체성의 수준을 조정하세요.

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

다음과 같은 경우에 사용하세요:

• 여러 접근 방식이 유효한 경우
• 결정이 컨텍스트에 따라 달라지는 경우
• 휴리스틱이 접근 방식을 안내하는 경우

예시:

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

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

다음과 같은 경우에 사용하세요:

• 선호되는 패턴이 존재하는 경우
• 어느 정도의 변형이 허용되는 경우
• 구성이 동작에 영향을 미치는 경우

예시:

## Generate report

Use this template and customize as needed:

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

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

다음과 같은 경우에 사용하세요:

• 작업이 취약하고 오류가 발생하기 쉬운 경우
• 일관성이 매우 중요한 경우
• 특정 순서를 따라야 하는 경우

예시:

## Database migration

Run exactly this script:

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

Do not modify the command or add additional flags.

비유: Claude를 경로를 탐색하는 로봇이라고 생각해 보세요:

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

사용할 계획인 모든 모델로 테스트하세요

Skills는 모델에 추가되는 형태로 작동하므로 효과는 기반 모델에 따라 달라집니다. Skill을 함께 사용할 계획인 모든 모델로 테스트하세요.

모델별 테스트 고려 사항:

• Claude Haiku (빠르고 경제적): Skill이 충분한 안내를 제공하는가?
• Claude Sonnet (균형 잡힘): Skill이 명확하고 효율적인가?
• Claude Opus (강력한 추론): Skill이 과도한 설명을 피하고 있는가?

Opus에서 완벽하게 작동하는 것이 Haiku에서는 더 많은 세부 정보가 필요할 수 있습니다. 여러 모델에서 Skill을 사용할 계획이라면 모든 모델에서 잘 작동하는 지침을 목표로 하세요.

Skill 구조

명명 규칙

Skills를 더 쉽게 참조하고 논의할 수 있도록 일관된 명명 패턴을 사용하세요. Skill 이름에는 동명사 형태(동사 + -ing)를 사용하는 것을 고려하세요. 이는 Skill이 제공하는 활동이나 기능을 명확하게 설명합니다.

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
• skill 컬렉션 내의 일관되지 않은 패턴

일관된 명명은 다음을 더 쉽게 만듭니다:

• 문서와 대화에서 Skills 참조
• Skill이 무엇을 하는지 한눈에 이해
• 여러 Skills를 정리하고 검색
• 전문적이고 일관성 있는 skill 라이브러리 유지

효과적인 description 작성

description 필드는 Skill 발견을 가능하게 하며, Skill이 무엇을 하는지와 언제 사용해야 하는지를 모두 포함해야 합니다.

구체적으로 작성하고 핵심 용어를 포함하세요. Skill이 무엇을 하는지와 언제 사용해야 하는지에 대한 구체적인 트리거/컨텍스트를 모두 포함하세요.

각 Skill에는 정확히 하나의 description 필드가 있습니다. description은 skill 선택에 매우 중요합니다. Claude는 이를 사용하여 잠재적으로 100개 이상의 사용 가능한 Skills 중에서 올바른 Skill을 선택합니다. description은 Claude가 언제 이 Skill을 선택해야 하는지 알 수 있을 만큼 충분한 세부 정보를 제공해야 하며, SKILL.md의 나머지 부분은 구현 세부 정보를 제공합니다.

효과적인 예시:

PDF 처리 skill:

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 분석 skill:

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

Git 커밋 도우미 skill:

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

다음과 같은 모호한 description은 피하세요:

description: Helps with documents

description: Processes data

description: Does stuff with files

점진적 공개 패턴

SKILL.md는 온보딩 가이드의 목차처럼 필요에 따라 Claude를 상세 자료로 안내하는 개요 역할을 합니다. "Progressive disclosure"(점진적 공개)가 어떻게 작동하는지에 대한 설명은 개요의 Skills 작동 방식을 참조하세요.

실용적인 안내:

• 최적의 성능을 위해 SKILL.md 본문을 500줄 미만으로 유지하세요
• 이 한도에 가까워지면 콘텐츠를 별도의 파일로 분할하세요
• 다음 패턴을 사용하여 지침, 코드, 리소스를 효과적으로 구성하세요

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

기본 Skill은 메타데이터와 지침을 포함하는 SKILL.md 파일 하나로 시작합니다:

Skill이 커지면 Claude가 필요할 때만 로드하는 추가 콘텐츠를 번들로 묶을 수 있습니다:

전체 Skill 디렉터리 구조는 다음과 같을 수 있습니다:

• pdf/
  • SKILL.md: 주요 지침 (트리거될 때 로드됨)
  • FORMS.md: 양식 작성 가이드 (필요에 따라 로드됨)
  • reference.md: API 참조 (필요에 따라 로드됨)
  • examples.md: 사용 예시 (필요에 따라 로드됨)
  • scripts/
    • analyze_form.py: 유틸리티 스크립트 (로드되지 않고 실행됨)
    • fill_form.py: 양식 작성 스크립트
    • validate.py: 검증 스크립트

패턴 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](FORMS.md) for complete guide
**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

Claude는 필요할 때만 FORMS.md, REFERENCE.md 또는 EXAMPLES.md를 로드합니다.

패턴 2: 도메인별 구성

여러 도메인이 있는 Skills의 경우, 관련 없는 컨텍스트를 로드하지 않도록 도메인별로 콘텐츠를 구성하세요. 사용자가 영업 지표에 대해 질문하면 Claude는 재무나 마케팅 데이터가 아닌 영업 관련 스키마만 읽으면 됩니다. 이렇게 하면 토큰 사용량이 낮게 유지되고 컨텍스트가 집중됩니다.

• bigquery-skill/
  • SKILL.md (개요 및 탐색)
  • reference/
    • finance.md (매출, 청구 지표)
    • sales.md (기회, 파이프라인)
    • product.md (API 사용량, 기능)
    • marketing.md (캠페인, 어트리뷰션)

# 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: 조건부 세부 정보

기본 콘텐츠를 보여주고 고급 콘텐츠로 연결하세요:

# 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를 읽습니다.

깊게 중첩된 참조를 피하세요

Claude는 다른 참조 파일에서 참조된 파일을 부분적으로만 읽을 수 있습니다. 중첩된 참조를 만나면 Claude는 전체 파일을 읽는 대신 head -100과 같은 명령을 사용하여 콘텐츠를 미리 볼 수 있으며, 이로 인해 불완전한 정보를 얻게 됩니다.

참조를 SKILL.md에서 한 단계 깊이로 유지하세요. 모든 참조 파일은 SKILL.md에서 직접 연결되어야 Claude가 필요할 때 전체 파일을 읽을 수 있습니다.

나쁜 예: 너무 깊음:

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

긴 참조 파일은 목차로 구조화하세요

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는 필요에 따라 전체 파일을 읽거나 특정 섹션으로 이동할 수 있습니다.

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

워크플로와 피드백 루프

복잡한 작업에는 워크플로를 사용하세요

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

예시 1: 연구 종합 워크플로 (코드가 없는 Skills용):

## 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 양식 작성 워크플로 (코드가 있는 Skills용):

## 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와 여러분 모두가 다단계 워크플로의 진행 상황을 추적하는 데 도움이 됩니다.

피드백 루프 구현

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

이 패턴은 출력 품질을 크게 향상시킵니다.

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

## 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: 문서 편집 프로세스 (코드가 있는 Skills용):

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

검증 루프는 오류를 조기에 포착합니다.

콘텐츠 가이드라인

시간에 민감한 정보를 피하세요

오래되어 부정확해질 정보는 포함하지 마세요:

나쁜 예: 시간에 민감함 (틀리게 될 것임):

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 섹션은 주요 콘텐츠를 어지럽히지 않으면서 역사적 컨텍스트를 제공합니다.

일관된 용어를 사용하세요

하나의 용어를 선택하고 Skill 전체에서 사용하세요:

좋음 - 일관됨:

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

나쁨 - 일관되지 않음:

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

일관성은 Claude가 지침을 파싱하고 따르는 데 도움이 됩니다.

일반적인 패턴

템플릿 패턴

출력 형식에 대한 템플릿을 제공하세요. 엄격함의 수준을 필요에 맞게 조정하세요.

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

## Report structure

ALWAYS use this exact template structure:

```markdown
# [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:

```markdown
# [Analysis Title]

## Executive summary
[Overview]

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

## Recommendations
[Tailor to the specific context]
```

Adjust sections as needed for the specific analysis type.

예시 패턴

출력 품질이 예시를 보는 것에 달려 있는 Skills의 경우, 일반 프롬프팅과 마찬가지로 입력/출력 쌍을 제공하세요:

## 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에게 더 명확하게 전달합니다.

조건부 워크플로 패턴

결정 지점을 통해 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

평가와 반복

평가를 먼저 구축하세요

광범위한 문서를 작성하기 전에 평가를 만드세요. 이렇게 하면 Skill이 상상된 문제를 문서화하는 것이 아니라 실제 문제를 해결하도록 보장합니다.

평가 주도 개발:

1. 격차 식별: Skill 없이 대표적인 작업에서 Claude를 실행하세요. 구체적인 실패나 누락된 컨텍스트를 문서화하세요
2. 평가 생성: 이러한 격차를 테스트하는 세 가지 시나리오를 구축하세요
3. 기준선 설정: Skill 없이 Claude의 성능을 측정하세요
4. 최소한의 지침 작성: 격차를 해결하고 평가를 통과할 만큼의 콘텐츠만 만드세요
5. 반복: 평가를 실행하고, 기준선과 비교하고, 개선하세요

이 접근 방식은 결코 실현되지 않을 수 있는 요구 사항을 예상하는 것이 아니라 실제 문제를 해결하도록 보장합니다.

평가 구조:

{
  "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"
  ]
}

Claude와 함께 반복적으로 Skills 개발하기

가장 효과적인 Skill 개발 프로세스에는 Claude 자체가 참여합니다. Claude의 한 인스턴스("Claude A")와 함께 작업하여 다른 인스턴스("Claude B")가 사용할 Skill을 만드세요. Claude A는 지침을 설계하고 개선하는 데 도움을 주고, Claude B는 실제 작업에서 이를 테스트합니다. 이것이 효과가 있는 이유는 Claude 모델이 효과적인 에이전트 지침을 작성하는 방법과 에이전트에게 필요한 정보가 무엇인지를 모두 이해하기 때문입니다.

새 Skill 만들기:

1. Skill 없이 작업 완료하기: 일반 프롬프팅을 사용하여 Claude A와 함께 문제를 해결하세요. 작업하면서 자연스럽게 컨텍스트를 제공하고, 선호 사항을 설명하고, 절차적 지식을 공유하게 됩니다. 반복적으로 제공하는 정보가 무엇인지 주목하세요.

2. 재사용 가능한 패턴 식별하기: 작업을 완료한 후, 유사한 향후 작업에 유용할 어떤 컨텍스트를 제공했는지 식별하세요.

   예시: BigQuery 분석을 수행했다면 테이블 이름, 필드 정의, 필터링 규칙(예: "항상 테스트 계정 제외"), 일반적인 쿼리 패턴을 제공했을 수 있습니다.

3. Claude A에게 Skill 생성 요청하기: "방금 사용한 이 BigQuery 분석 패턴을 담은 Skill을 만들어 줘. 테이블 스키마, 명명 규칙, 테스트 계정 필터링에 대한 규칙을 포함해 줘."

4. 간결성 검토하기: Claude A가 불필요한 설명을 추가하지 않았는지 확인하세요. 다음과 같이 요청하세요: "win rate가 무엇을 의미하는지에 대한 설명을 제거해 줘 - Claude는 이미 그것을 알고 있어."

5. 정보 아키텍처 개선하기: Claude A에게 콘텐츠를 더 효과적으로 구성하도록 요청하세요. 예: "테이블 스키마가 별도의 참조 파일에 있도록 구성해 줘. 나중에 더 많은 테이블을 추가할 수도 있어."

6. 유사한 작업에서 테스트하기: 관련 사용 사례에서 Claude B(Skill이 로드된 새 인스턴스)와 함께 Skill을 사용하세요. Claude B가 올바른 정보를 찾고, 규칙을 올바르게 적용하고, 작업을 성공적으로 처리하는지 관찰하세요.

7. 관찰에 기반하여 반복하기: Claude B가 어려움을 겪거나 무언가를 놓치면 구체적인 내용을 가지고 Claude A에게 돌아가세요: "Claude가 이 Skill을 사용했을 때 Q4에 대해 날짜로 필터링하는 것을 잊었어. 날짜 필터링 패턴에 대한 섹션을 추가해야 할까?"

기존 Skills 반복 개선하기:

Skills를 개선할 때도 동일한 계층적 패턴이 계속됩니다. 다음을 번갈아 수행합니다:

• Claude A와 작업하기 (Skill 개선을 돕는 전문가)
• Claude B로 테스트하기 (Skill을 사용하여 실제 작업을 수행하는 에이전트)
• Claude B의 행동 관찰하기 및 인사이트를 Claude A에게 가져가기

1. 실제 워크플로에서 Skill 사용하기: Claude B(Skill이 로드됨)에게 테스트 시나리오가 아닌 실제 작업을 주세요

2. Claude B의 행동 관찰하기: 어디서 어려움을 겪는지, 성공하는지, 예상치 못한 선택을 하는지 기록하세요

   관찰 예시: "Claude B에게 지역별 영업 보고서를 요청했을 때, 쿼리는 작성했지만 Skill에 이 규칙이 언급되어 있음에도 테스트 계정을 필터링하는 것을 잊었다."

3. 개선을 위해 Claude A에게 돌아가기: 현재 SKILL.md를 공유하고 관찰한 내용을 설명하세요. 다음과 같이 요청하세요: "지역별 보고서를 요청했을 때 Claude B가 테스트 계정 필터링을 잊은 것을 발견했어. Skill에 필터링이 언급되어 있지만 충분히 눈에 띄지 않는 것 같아?"

4. Claude A의 제안 검토하기: Claude A는 규칙을 더 눈에 띄게 재구성하거나, "always filter" 대신 "MUST filter"와 같은 더 강한 표현을 사용하거나, 워크플로 섹션을 재구조화할 것을 제안할 수 있습니다.

5. 변경 사항 적용 및 테스트하기: Claude A의 개선 사항으로 Skill을 업데이트한 다음, 유사한 요청으로 Claude B와 다시 테스트하세요

6. 사용에 기반하여 반복하기: 새로운 시나리오를 만날 때마다 이 관찰-개선-테스트 주기를 계속하세요. 각 반복은 가정이 아닌 실제 에이전트 행동에 기반하여 Skill을 개선합니다.

팀 피드백 수집하기:

1. 팀원들과 Skills를 공유하고 그들의 사용을 관찰하세요
2. 질문하세요: Skill이 예상대로 활성화되는가? 지침이 명확한가? 무엇이 빠져 있는가?
3. 자신의 사용 패턴에서의 격차를 해결하기 위해 피드백을 반영하세요

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

Claude가 Skills를 탐색하는 방식 관찰하기

Skills를 반복 개선하면서 Claude가 실제로 어떻게 사용하는지 주의 깊게 살펴보세요. 다음을 주시하세요:

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

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

피해야 할 안티패턴

Windows 스타일 경로를 피하세요

Windows에서도 파일 경로에 항상 슬래시를 사용하세요:

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

Unix 스타일 경로는 모든 플랫폼에서 작동하지만, Windows 스타일 경로는 Unix 시스템에서 오류를 일으킵니다.

너무 많은 옵션을 제공하지 마세요

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

**Bad example: Too many choices** (confusing):
"You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or..."

**Good example: Provide a default** (with escape hatch):
"Use pdfplumber for text extraction:
```python
import pdfplumber
```

For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."

고급: 실행 가능한 코드가 있는 Skills

다음 섹션은 실행 가능한 스크립트를 포함하는 Skills에 중점을 둡니다. Skill이 markdown 지침만 사용한다면 효과적인 Skills를 위한 체크리스트로 건너뛰세요.

미루지 말고 해결하세요

Skills용 스크립트를 작성할 때, 오류 조건을 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:
        # 실패하는 대신 기본 콘텐츠로 파일 생성
        print(f"File {path} not found, creating default")
        with open(path, "w") as f:
            f.write("")
        return ""
    except PermissionError:
        # 실패하는 대신 대안 제공
        print(f"Cannot access {path}, using default")
        return ""

나쁜 예: Claude에게 미루기:

def process_file(path):
    # 그냥 실패 처리하고 Claude가 알아서 해결하도록 둡니다
    return open(path).read()

구성 매개변수도 "부두 상수(voodoo constants)"(Ousterhout의 법칙)를 피하기 위해 정당화되고 문서화되어야 합니다. 여러분이 올바른 값을 모른다면 Claude는 어떻게 그것을 결정할까요?

좋은 예: 자체 문서화:

# HTTP 요청은 일반적으로 30초 이내에 완료됩니다
# 느린 연결을 고려하여 타임아웃을 더 길게 설정합니다
REQUEST_TIMEOUT = 30

# 세 번의 재시도로 안정성과 속도의 균형을 맞춥니다
# 대부분의 간헐적 실패는 두 번째 재시도에서 해결됩니다
MAX_RETRIES = 3

나쁜 예: 매직 넘버:

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

유틸리티 스크립트 제공

Claude가 스크립트를 작성할 수 있더라도, 미리 만들어진 스크립트는 이점을 제공합니다:

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

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

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

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

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

대부분의 유틸리티 스크립트의 경우, 더 신뢰할 수 있고 효율적이기 때문에 실행이 선호됩니다. 스크립트 실행이 어떻게 작동하는지에 대한 자세한 내용은 다음 런타임 환경 섹션을 참조하세요.

예시:

## Utility scripts

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

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

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

**validate_boxes.py**: Check for overlapping bounding boxes

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

**fill_form.py**: Apply field values to PDF

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

시각적 분석 사용

입력을 이미지로 렌더링할 수 있는 경우, Claude가 이를 분석하도록 하세요:

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

Claude의 비전 기능은 레이아웃과 구조를 분석하는 데 도움이 됩니다.

검증 가능한 중간 출력 만들기

Claude가 복잡하고 개방형인 작업을 수행할 때 실수를 할 수 있습니다. "계획-검증-실행" 패턴은 Claude가 먼저 구조화된 형식으로 계획을 만들고, 실행하기 전에 스크립트로 해당 계획을 검증하도록 하여 오류를 조기에 포착합니다.

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

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

이 패턴이 효과적인 이유:

• 오류를 조기에 포착: 검증은 변경 사항이 적용되기 전에 문제를 찾습니다
• 기계 검증 가능: 스크립트는 객관적인 검증을 제공합니다
• 되돌릴 수 있는 계획: Claude는 원본을 건드리지 않고 계획을 반복할 수 있습니다
• 명확한 디버깅: 오류 메시지가 구체적인 문제를 가리킵니다

사용 시기: 일괄 작업, 파괴적인 변경, 복잡한 검증 규칙, 중대한 작업.

구현 팁: Claude가 문제를 수정하는 데 도움이 되도록 "Field 'signature_date' not found. Available fields: customer_name, order_total, signature_date_signed"와 같은 구체적인 오류 메시지로 검증 스크립트를 상세하게 만드세요.

패키지 의존성

Skills는 플랫폼별 제한이 있는 코드 실행 환경에서 실행됩니다:

• claude.ai: npm 및 PyPI에서 패키지를 설치하고 GitHub 리포지토리에서 가져올 수 있습니다
• Claude API: 네트워크 접근이 없으며 런타임 패키지 설치가 불가능합니다

SKILL.md에 필요한 패키지를 나열하고 코드 실행 도구 문서에서 사용 가능한지 확인하세요.

런타임 환경

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

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

Claude가 Skills에 접근하는 방법:

1. 메타데이터 사전 로드: 시작 시 모든 Skills의 YAML frontmatter에서 name과 description이 시스템 프롬프트에 로드됩니다
2. 파일은 필요 시 읽기: Claude는 필요할 때 bash Read 도구를 사용하여 파일 시스템에서 SKILL.md 및 기타 파일에 접근합니다
3. 스크립트는 효율적으로 실행: 유틸리티 스크립트는 전체 내용을 컨텍스트에 로드하지 않고 bash를 통해 실행할 수 있습니다. 스크립트의 출력만 토큰을 소비합니다
4. 대용량 파일에 대한 컨텍스트 페널티 없음: 참조 파일, 데이터 또는 문서는 실제로 읽힐 때까지 컨텍스트 토큰을 소비하지 않습니다

• 파일 경로가 중요합니다: Claude는 skill 디렉터리를 파일 시스템처럼 탐색합니다. 백슬래시가 아닌 슬래시(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 (개요, 참조 파일을 가리킴)
  • reference/
    • finance.md (매출 지표)
    • sales.md (파이프라인 데이터)
    • product.md (사용량 분석)

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

기술 아키텍처에 대한 전체 세부 정보는 Skills 개요의 Skills 작동 방식을 참조하세요.

MCP 도구 참조

Skill이 MCP(Model Context Protocol) 도구를 사용하는 경우, "tool not found" 오류를 피하기 위해 항상 완전한 도구 이름을 사용하세요.

형식: 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가 도구를 찾지 못할 수 있습니다.

도구가 설치되어 있다고 가정하지 마세요

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

**Bad example: Assumes installation**:
"Use the pdf library to process the file."

**Good example: Explicit about dependencies**:
"Install required package: `pip install pypdf`

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

기술 노트

YAML frontmatter 요구 사항

SKILL.md frontmatter에는 특정 검증 규칙이 있는 name 및 description 필드가 필요합니다:

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

전체 구조 세부 정보는 Skills 개요를 참조하세요.

토큰 예산

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

효과적인 Skills를 위한 체크리스트

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

핵심 품질

• description이 구체적이고 핵심 용어를 포함함
• description이 Skill이 무엇을 하는지와 언제 사용해야 하는지를 모두 포함함
• SKILL.md 본문이 500줄 미만임
• 추가 세부 정보가 별도의 파일에 있음 (필요한 경우)
• 시간에 민감한 정보가 없음 (또는 "old patterns" 섹션에 있음)
• 전체적으로 일관된 용어 사용
• 예시가 추상적이지 않고 구체적임
• 파일 참조가 한 단계 깊이임
• 점진적 공개가 적절하게 사용됨
• 워크플로에 명확한 단계가 있음

코드와 스크립트

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

테스트

• 최소 세 개의 평가 생성
• Haiku, Sonnet, Opus로 테스트
• 실제 사용 시나리오로 테스트
• 팀 피드백 반영 (해당하는 경우)

다음 단계