Skill 작성 모범 사례

좋은 Skill은 간결하고 잘 구조화되어 있으며 실제 사용으로 테스트됩니다. 이 가이드는 Claude가 Skill을 발견하고 효과적으로 사용할 수 있도록 도와주는 실용적인 작성 결정을 제공합니다.

Skill이 어떻게 작동하는지에 대한 개념적 배경은 Skill 개요를 참조하세요.

핵심 원칙

간결함이 핵심입니다

컨텍스트 윈도우는 공공재입니다. 당신의 Skill은 Claude가 알아야 할 다른 모든 것과 컨텍스트 윈도우를 공유합니다:

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

Skill의 모든 토큰이 즉각적인 비용을 발생시키지는 않습니다. 시작 시 모든 Skill의 메타데이터(이름과 설명)만 미리 로드됩니다. Claude는 Skill이 관련성이 있을 때만 SKILL.md를 읽고, 필요에 따라서만 추가 파일을 읽습니다. 그러나 SKILL.md에서 간결함을 유지하는 것은 여전히 중요합니다. Claude가 로드하면 모든 토큰이 대화 기록 및 다른 컨텍스트와 경쟁합니다.

기본 가정: Claude는 이미 매우 똑똑합니다

Claude가 이미 알고 있지 않은 컨텍스트만 추가하세요. 각 정보를 검토하세요:

• "Claude가 정말 이 설명이 필요한가?"
• "Claude가 이것을 알고 있다고 가정할 수 있는가?"
• "이 단락이 토큰 비용을 정당화하는가?"

좋은 예: 간결함 (약 50개 토큰):

## PDF 텍스트 추출

텍스트 추출을 위해 pdfplumber를 사용하세요:

```python
import pdfplumber

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

나쁜 예: 너무 장황함 (약 150개 토큰):

## PDF 텍스트 추출

PDF(Portable Document Format) 파일은 텍스트, 이미지 및 기타 콘텐츠를 포함하는 일반적인 파일 형식입니다. PDF에서 텍스트를 추출하려면 라이브러리를 사용해야 합니다. PDF 처리에 사용할 수 있는 많은 라이브러리가 있지만, pdfplumber를 권장합니다. 사용하기 쉽고 대부분의 경우를 잘 처리하기 때문입니다. 먼저 pip를 사용하여 설치해야 합니다. 그런 다음 아래 코드를 사용할 수 있습니다...

간결한 버전은 Claude가 PDF가 무엇인지, 라이브러리가 어떻게 작동하는지 알고 있다고 가정합니다.

적절한 자유도 설정

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

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

다음의 경우 사용하세요:

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

예:

## 코드 리뷰 프로세스

1. 코드 구조와 조직을 분석합니다
2. 잠재적 버그나 엣지 케이스를 확인합니다
3. 가독성과 유지보수성 개선을 제안합니다
4. 프로젝트 규칙 준수를 확인합니다

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

다음의 경우 사용하세요:

• 선호하는 패턴이 존재하는 경우
• 일부 변형이 허용되는 경우
• 구성이 동작에 영향을 미치는 경우

예:

## 보고서 생성

이 템플릿을 사용하고 필요에 따라 사용자 정의하세요:

```python
def generate_report(data, format="markdown", include_charts=True):
    # 데이터 처리
    # 지정된 형식으로 출력 생성
    # 선택적으로 시각화 포함
```

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

다음의 경우 사용하세요:

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

예:

## 데이터베이스 마이그레이션

정확히 이 스크립트를 실행하세요:

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

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

비유: Claude를 경로를 탐색하는 로봇으로 생각하세요:

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

사용할 모든 모델로 테스트하세요

Skill은 모델에 추가되므로 효과는 기본 모델에 따라 달라집니다. 사용할 모든 모델로 Skill을 테스트하세요.

모델별 테스트 고려사항:

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

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

Skill 구조

명명 규칙

일관된 명명 패턴을 사용하여 Skill을 더 쉽게 참조하고 논의할 수 있도록 하세요. 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 컬렉션 내에서 일관성 없는 패턴

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

• 문서 및 대화에서 Skill 참조
• 한눈에 Skill이 무엇을 하는지 이해
• 여러 Skill을 구성하고 검색
• 전문적이고 응집력 있는 Skill 라이브러리 유지

효과적인 설명 작성

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

구체적이고 핵심 용어를 포함하세요. Skill이 무엇을 하는지와 사용할 시기의 구체적인 트리거/컨텍스트를 모두 포함하세요.

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

효과적인 예:

PDF 처리 Skill:

description: PDF 파일에서 텍스트 및 표 추출, 양식 작성, 문서 병합. PDF 파일로 작업하거나 사용자가 PDF, 양식 또는 문서 추출을 언급할 때 사용합니다.

Excel 분석 Skill:

description: Excel 스프레드시트 분석, 피벗 테이블 생성, 차트 생성. Excel 파일, 스프레드시트, 표 형식 데이터 또는 .xlsx 파일을 분석할 때 사용합니다.

Git 커밋 도우미 Skill:

description: git diff를 분석하여 설명적인 커밋 메시지 생성. 사용자가 커밋 메시지 작성 또는 스테이징된 변경 사항 검토에 대한 도움을 요청할 때 사용합니다.

다음과 같은 모호한 설명을 피하세요:

description: 문서 작업을 도와줍니다

description: 데이터를 처리합니다

description: 파일로 작업을 수행합니다

점진적 공개 패턴

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

실용적인 지침:

• 최적의 성능을 위해 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: PDF 파일에서 텍스트 및 표 추출, 양식 작성, 문서 병합. PDF 파일로 작업하거나 사용자가 PDF, 양식 또는 문서 추출을 언급할 때 사용합니다.
---

# PDF 처리

## 빠른 시작

pdfplumber로 텍스트 추출:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## 고급 기능

**양식 작성**: 전체 가이드는 [FORMS.md](FORMS.md) 참조
**API 참조**: 모든 메서드는 [REFERENCE.md](REFERENCE.md) 참조
**예**: 일반적인 패턴은 [EXAMPLES.md](EXAMPLES.md) 참조

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

패턴 2: 도메인별 구성

여러 도메인이 있는 Skill의 경우 콘텐츠를 도메인별로 구성하여 관련 없는 컨텍스트 로드를 피하세요. 사용자가 판매 지표를 요청하면 Claude는 판매 관련 스키마만 읽으면 되고 재무 또는 마케팅 데이터는 읽을 필요가 없습니다. 이렇게 하면 토큰 사용량이 낮고 컨텍스트가 집중됩니다.

bigquery-skill/
├── SKILL.md (개요 및 탐색)
└── reference/
    ├── finance.md (수익, 청구 지표)
    ├── sales.md (기회, 파이프라인)
    ├── product.md (API 사용, 기능)
    └── marketing.md (캠페인, 속성)

# BigQuery 데이터 분석

## 사용 가능한 데이터세트

**재무**: 수익, ARR, 청구 → [reference/finance.md](reference/finance.md) 참조
**판매**: 기회, 파이프라인, 계정 → [reference/sales.md](reference/sales.md) 참조
**제품**: API 사용, 기능, 채택 → [reference/product.md](reference/product.md) 참조
**마케팅**: 캠페인, 속성, 이메일 → [reference/marketing.md](reference/marketing.md) 참조

## 빠른 검색

grep을 사용하여 특정 지표 찾기:

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

패턴 3: 조건부 세부 정보

기본 콘텐츠를 표시하고 고급 콘텐츠로 연결:

# DOCX 처리

## 문서 생성

새 문서에 docx-js를 사용하세요. [DOCX-JS.md](DOCX-JS.md) 참조.

## 문서 편집

간단한 편집의 경우 XML을 직접 수정하세요.

**추적된 변경의 경우**: [REDLINING.md](REDLINING.md) 참조
**OOXML 세부 정보의 경우**: [OOXML.md](OOXML.md) 참조

Claude는 사용자가 해당 기능을 필요로 할 때만 REDLINING.md 또는 OOXML.md를 읽습니다.

깊게 중첩된 참조 피하기

Claude는 다른 참조된 파일에서 참조된 파일을 부분적으로 읽을 수 있습니다. 중첩된 참조를 만날 때 Claude는 head -100과 같은 명령을 사용하여 전체 파일을 읽는 대신 콘텐츠를 미리 보기하여 불완전한 정보를 초래할 수 있습니다.

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

나쁜 예: 너무 깊음:

# SKILL.md
[advanced.md](advanced.md) 참조...

# advanced.md
[details.md](details.md) 참조...

# details.md
실제 정보는 여기...

좋은 예: 한 수준 깊이:

# SKILL.md

**기본 사용**: [SKILL.md의 지침]
**고급 기능**: [advanced.md](advanced.md) 참조
**API 참조**: [reference.md](reference.md) 참조
**예**: [examples.md](examples.md) 참조

긴 참조 파일을 목차로 구조화하기

100줄 이상의 참조 파일의 경우 맨 위에 목차를 포함하세요. 이렇게 하면 부분 읽기로 미리 보기할 때도 Claude가 사용 가능한 정보의 전체 범위를 볼 수 있습니다.

예:

# API 참조

## 목차
- 인증 및 설정
- 핵심 메서드 (생성, 읽기, 업데이트, 삭제)
- 고급 기능 (배치 작업, 웹훅)
- 오류 처리 패턴
- 코드 예

## 인증 및 설정
...

## 핵심 메서드
...

Claude는 필요에 따라 전체 파일을 읽거나 특정 섹션으로 이동할 수 있습니다.

이 파일 시스템 기반 아키텍처가 점진적 공개를 가능하게 하는 방법에 대한 세부 정보는 아래 고급 섹션의 런타임 환경 섹션을 참조하세요.

워크플로우 및 피드백 루프

복잡한 작업에 워크플로우 사용

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

예 1: 연구 종합 워크플로우 (코드 없는 Skill의 경우):

## 연구 종합 워크플로우

이 체크리스트를 복사하고 진행 상황을 추적하세요:

```
연구 진행:
- [ ] 단계 1: 모든 소스 문서 읽기
- [ ] 단계 2: 주요 테마 식별
- [ ] 단계 3: 주장 교차 참조
- [ ] 단계 4: 구조화된 요약 생성
- [ ] 단계 5: 인용 확인
```

**단계 1: 모든 소스 문서 읽기**

`sources/` 디렉토리의 각 문서를 검토하세요. 주요 주장과 뒷받침하는 증거를 기록하세요.

**단계 2: 주요 테마 식별**

소스 전체에서 패턴을 찾으세요. 어떤 테마가 반복적으로 나타나나요? 소스가 동의하거나 불일치하는 곳은 어디인가요?

**단계 3: 주장 교차 참조**

각 주요 주장에 대해 소스 자료에 나타나는지 확인하세요. 각 포인트를 지원하는 소스를 기록하세요.

**단계 4: 구조화된 요약 생성**

테마별로 결과를 구성하세요. 다음을 포함하세요:
- 주요 주장
- 소스의 뒷받침하는 증거
- 상충하는 관점 (있는 경우)

**단계 5: 인용 확인**

모든 주장이 올바른 소스 문서를 참조하는지 확인하세요. 인용이 불완전하면 단계 3으로 돌아가세요.

이 예는 코드가 필요하지 않은 분석 작업에 워크플로우가 어떻게 적용되는지 보여줍니다. 체크리스트 패턴은 모든 복잡한 다단계 프로세스에 작동합니다.

예 2: PDF 양식 작성 워크플로우 (코드가 있는 Skill의 경우):

## PDF 양식 작성 워크플로우

이 체크리스트를 복사하고 완료하면서 체크하세요:

```
작업 진행:
- [ ] 단계 1: 양식 분석 (analyze_form.py 실행)
- [ ] 단계 2: 필드 매핑 생성 (fields.json 편집)
- [ ] 단계 3: 매핑 검증 (validate_fields.py 실행)
- [ ] 단계 4: 양식 작성 (fill_form.py 실행)
- [ ] 단계 5: 출력 확인 (verify_output.py 실행)
```

**단계 1: 양식 분석**

실행: `python scripts/analyze_form.py input.pdf`

이는 양식 필드와 위치를 추출하여 `fields.json`에 저장합니다.

**단계 2: 필드 매핑 생성**

`fields.json`을 편집하여 각 필드에 값을 추가하세요.

**단계 3: 매핑 검증**

실행: `python scripts/validate_fields.py fields.json`

계속하기 전에 검증 오류를 수정하세요.

**단계 4: 양식 작성**

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

**단계 5: 출력 확인**

실행: `python scripts/verify_output.py output.pdf`

검증이 실패하면 단계 2로 돌아가세요.

명확한 단계는 Claude가 중요한 검증을 건너뛰는 것을 방지합니다. 체크리스트는 Claude와 당신 모두 다단계 워크플로우를 통한 진행 상황을 추적하는 데 도움이 됩니다.

피드백 루프 구현

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

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

예 1: 스타일 가이드 준수 (코드 없는 Skill의 경우):

## 콘텐츠 검토 프로세스

1. STYLE_GUIDE.md의 지침에 따라 콘텐츠를 작성하세요
2. 체크리스트에 대해 검토하세요:
   - 용어 일관성 확인
   - 예가 표준 형식을 따르는지 확인
   - 필요한 모든 섹션이 있는지 확인
3. 문제가 발견된 경우:
   - 각 문제를 특정 섹션 참조와 함께 기록하세요
   - 콘텐츠를 수정하세요
   - 체크리스트를 다시 검토하세요
4. 모든 요구사항이 충족될 때만 진행하세요
5. 문서를 완성하고 저장하세요

이는 스크립트 대신 참조 문서를 사용하는 검증 루프 패턴을 보여줍니다. "검증자"는 STYLE_GUIDE.md이고 Claude는 읽고 비교하여 확인을 수행합니다.

예 2: 문서 편집 프로세스 (코드가 있는 Skill의 경우):

## 문서 편집 프로세스

1. `word/document.xml`에 편집을 수행하세요
2. **즉시 검증**: `python ooxml/scripts/validate.py unpacked_dir/`
3. 검증이 실패하면:
   - 오류 메시지를 주의 깊게 검토하세요
   - XML의 문제를 수정하세요
   - 검증을 다시 실행하세요
4. **검증이 통과할 때만 진행하세요**
5. 다시 빌드: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. 출력 문서를 테스트하세요

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

콘텐츠 지침

시간에 민감한 정보 피하기

오래될 정보를 포함하지 마세요:

나쁜 예: 시간에 민감함 (잘못될 것):

2025년 8월 이전에 이를 수행하는 경우 이전 API를 사용하세요.
2025년 8월 이후에는 새 API를 사용하세요.

좋은 예 ("이전 패턴" 섹션 사용):

## 현재 방법

v2 API 엔드포인트를 사용하세요: `api.example.com/v2/messages`

## 이전 패턴

<details>
<summary>레거시 v1 API (2025-08 사용 중단됨)</summary>

v1 API는 다음을 사용했습니다: `api.example.com/v1/messages`

이 엔드포인트는 더 이상 지원되지 않습니다.
</details>

이전 패턴 섹션은 주요 콘텐츠를 복잡하게 하지 않으면서 역사적 컨텍스트를 제공합니다.

일관된 용어 사용

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

좋음 - 일관성:

• 항상 "API 엔드포인트"
• 항상 "필드"
• 항상 "추출"

나쁨 - 일관성 없음:

• "API 엔드포인트", "URL", "API 경로", "경로" 혼합
• "필드", "상자", "요소", "컨트롤" 혼합
• "추출", "가져오기", "얻기", "검색" 혼합

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

일반적인 패턴

템플릿 패턴

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

엄격한 요구사항의 경우 (API 응답 또는 데이터 형식 같은):

## 보고서 구조

항상 이 정확한 템플릿 구조를 사용하세요:

```markdown
# [분석 제목]

## 요약
[주요 결과의 한 단락 개요]

## 주요 결과
- 뒷받침하는 데이터가 있는 결과 1
- 뒷받침하는 데이터가 있는 결과 2
- 뒷받침하는 데이터가 있는 결과 3

## 권장사항
1. 구체적인 실행 가능한 권장사항
2. 구체적인 실행 가능한 권장사항
```

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

## 보고서 구조

다음은 합리적인 기본 형식이지만 분석에 따라 최선의 판단을 사용하세요:

```markdown
# [분석 제목]

## 요약
[개요]

## 주요 결과
[발견한 내용에 따라 섹션 조정]

## 권장사항
[특정 컨텍스트에 맞게 조정]
```

필요에 따라 섹션을 조정하세요.

예 패턴

출력 품질이 예를 보는 것에 달려 있는 Skill의 경우 일반 프롬프팅처럼 입력/출력 쌍을 제공하세요:

## 커밋 메시지 형식

다음 예를 따르는 커밋 메시지를 생성하세요:

**예 1:**
입력: JWT 토큰으로 사용자 인증 추가
출력:
```
feat(auth): JWT 기반 인증 구현

로그인 엔드포인트 및 토큰 검증 미들웨어 추가
```

**예 2:**
입력: 보고서에서 날짜가 잘못 표시되는 버그 수정
출력:
```
fix(reports): 시간대 변환에서 날짜 형식 수정

보고서 생성 전체에서 UTC 타임스탬프를 일관되게 사용
```

**예 3:**
입력: 의존성 업데이트 및 오류 처리 리팩토링
출력:
```
chore: 의존성 업데이트 및 오류 처리 리팩토링

- lodash를 4.17.21로 업그레이드
- 엔드포인트 전체에서 오류 응답 형식 표준화
```

이 스타일을 따르세요: type(scope): 간단한 설명, 그 다음 상세 설명.

예는 설명만으로는 원하는 스타일과 세부 정보 수준을 Claude가 더 명확하게 이해하는 데 도움이 됩니다.

조건부 워크플로우 패턴

Claude를 의사 결정 지점을 통해 안내하세요:

## 문서 수정 워크플로우

1. 수정 유형을 결정하세요:

   **새 콘텐츠를 생성하나요?** → 아래 "생성 워크플로우" 따르기
   **기존 콘텐츠를 편집하나요?** → 아래 "편집 워크플로우" 따르기

2. 생성 워크플로우:
   - docx-js 라이브러리 사용
   - 처음부터 문서 빌드
   - .docx 형식으로 내보내기

3. 편집 워크플로우:
   - 기존 문서 압축 해제
   - XML 직접 수정
   - 각 변경 후 검증
   - 완료 시 다시 압축

평가 및 반복

먼저 평가 구축

광범위한 문서를 작성하기 전에 평가를 만드세요. 이렇게 하면 Skill이 상상한 것이 아닌 실제 문제를 해결합니다.

평가 주도 개발:

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

이 접근 방식은 실제 문제를 해결하는 것을 보장하며 충족되지 않을 수 있는 요구사항을 예상하지 않습니다.

평가 구조:

{
  "skills": ["pdf-processing"],
  "query": "이 PDF 파일에서 모든 텍스트를 추출하고 output.txt에 저장하세요",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "적절한 PDF 처리 라이브러리 또는 명령줄 도구를 사용하여 PDF 파일을 성공적으로 읽습니다",
    "페이지를 놓치지 않고 문서의 모든 페이지에서 텍스트 콘텐츠를 추출합니다",
    "추출된 텍스트를 명확하고 읽기 쉬운 형식으로 output.txt라는 파일에 저장합니다"
  ]
}

Claude와 함께 반복적으로 Skill 개발

가장 효과적인 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을 만드세요. 테이블 스키마, 명명 규칙, 테스트 계정 필터링 규칙을 포함하세요."

   Claude 모델은 Skill 형식과 구조를 기본적으로 이해합니다. Skill을 만들기 위해 특수 시스템 프롬프트나 "Skill 작성" Skill이 필요하지 않습니다. Claude에게 Skill을 만들도록 요청하면 적절한 프론트매터와 본문 콘텐츠가 있는 제대로 구조화된 SKILL.md를 생성할 것입니다.

4. 간결함 검토: Claude A가 불필요한 설명을 추가하지 않았는지 확인하세요. 묻기: "Claude가 이미 알고 있으므로 win rate가 무엇인지에 대한 설명을 제거하세요."

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

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

7. 관찰에 따라 반복: Claude B가 어려움을 겪거나 뭔가 놓친 경우 구체적으로 Claude A로 돌아가세요: "Claude가 이 Skill을 사용했을 때 Q4에 대해 날짜로 필터링하는 것을 잊었습니다. 날짜 필터링 패턴에 대한 섹션을 추가해야 하나요?"

기존 Skill 반복:

같은 계층적 패턴이 Skill을 개선할 때 계속됩니다. 다음 사이를 번갈아 가며:

• 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는 규칙을 더 눈에 띄게 하기 위해 재구성하거나, "항상 필터링" 대신 "MUST 필터링"과 같은 더 강한 언어를 사용하거나, 워크플로우 섹션을 재구성할 것을 제안할 수 있습니다.

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

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

팀 피드백 수집:

1. 팀원과 Skill을 공유하고 사용을 관찰하세요
2. 묻기: Skill이 예상대로 활성화되나요? 지침이 명확한가요? 무엇이 누락되었나요?
3. 자신의 사용 패턴의 맹점을 해결하기 위해 피드백을 통합하세요

이 접근 방식이 작동하는 이유: Claude A는 에이전트 필요를 이해하고, 당신은 도메인 전문 지식을 제공하고, Claude B는 실제 사용을 통해 격차를 드러내고, 반복적 개선은 가정이 아닌 관찰된 동작에 따라 Skill을 개선합니다.

Claude가 Skill을 탐색하는 방식 관찰

Skill을 반복할 때 Claude가 실제로 Skill을 사용하는 방식에 주의하세요. 다음을 살펴보세요:

• 예상치 못한 탐색 경로: 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 시스템에서 오류를 일으킵니다.

너무 많은 옵션 제공 피하기

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

**나쁜 예: 너무 많은 선택** (혼란스러움):
"pypdf, pdfplumber, PyMuPDF, pdf2image 또는... 를 사용할 수 있습니다"

**좋은 예: 기본값 제공** (탈출구 포함):
"텍스트 추출을 위해 pdfplumber를 사용하세요:
```python
import pdfplumber
```

OCR이 필요한 스캔된 PDF의 경우 대신 pdf2image와 pytesseract를 사용하세요."

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

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

해결하고 미루지 마세요

Skill용 스크립트를 작성할 때 Claude에게 미루지 말고 오류 조건을 처리하세요.

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

def process_file(path):
    """파일을 처리하고 존재하지 않으면 생성합니다."""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        # 실패하는 대신 기본 콘텐츠로 파일 생성
        print(f"파일 {path}을(를) 찾을 수 없어 기본값 생성")
        with open(path, 'w') as f:
            f.write('')
        return ''
    except PermissionError:
        # 실패하는 대신 대안 제공
        print(f"{path}에 액세스할 수 없어 기본값 사용")
        return ''

나쁜 예: Claude에게 미루기:

def process_file(path):
    # 그냥 실패하고 Claude가 알아내도록 하기
    return open(path).read()

구성 매개변수도 정당화되고 문서화되어야 "부두 상수"(Ousterhout의 법칙)를 피합니다. 올바른 값을 모르면 Claude가 어떻게 결정할까요?

좋은 예: 자체 문서화:

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

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

나쁜 예: 매직 숫자:

TIMEOUT = 47  # 왜 47?
RETRIES = 5   # 왜 5?

유틸리티 스크립트 제공

Claude가 스크립트를 작성할 수 있더라도 미리 만든 스크립트는 장점이 있습니다:

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

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

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

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

• 스크립트 실행 (가장 일반적): "analyze_form.py를 실행하여 필드 추출"
• 참조로 읽기 (복잡한 로직의 경우): "필드 추출 알고리즘은 analyze_form.py 참조"

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

예:

## 유틸리티 스크립트

**analyze_form.py**: PDF에서 모든 양식 필드 추출

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

출력 형식:
```json
{
  "field_name": {"type": "text", "x": 100, "y": 200},
  "signature": {"type": "sig", "x": 150, "y": 500}
}
```

**validate_boxes.py**: 겹치는 경계 상자 확인

```bash
python scripts/validate_boxes.py fields.json
# 반환: "OK" 또는 충돌 나열
```

**fill_form.py**: PDF에 필드 값 적용

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

시각적 분석 사용

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

## 양식 레이아웃 분석

1. PDF를 이미지로 변환:
   ```bash
   python scripts/pdf_to_images.py form.pdf
   ```

2. 각 페이지 이미지를 분석하여 양식 필드 식별
3. Claude는 시각적으로 필드 위치 및 유형을 볼 수 있음

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

검증 가능한 중간 출력 생성

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

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

해결책: 위에 표시된 워크플로우 패턴을 사용하지만 실행하기 전에 변경 사항을 검증하는 중간 changes.json 파일을 추가하세요. 워크플로우는 다음과 같이 됩니다: 분석 → 계획 파일 생성 → 계획 검증 → 실행 → 확인.

이 패턴이 작동하는 이유:

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

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

구현 팁: 검증 스크립트를 상세하게 만들고 "필드 'signature_date'을(를) 찾을 수 없습니다. 사용 가능한 필드: customer_name, order_total, signature_date_signed"와 같은 구체적인 오류 메시지를 제공하여 Claude가 문제를 수정하는 데 도움을 줍니다.

패키지 의존성

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

• claude.ai: npm 및 PyPI에서 패키지를 설치하고 GitHub 저장소에서 가져올 수 있습니다
• Anthropic API: 네트워크 액세스가 없고 런타임 패키지 설치가 없습니다

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

런타임 환경

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

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

Claude가 Skill에 액세스하는 방식:

1. 메타데이터 미리 로드: 시작 시 모든 Skill의 YAML 프론트매터에서 이름과 설명이 시스템 프롬프트에 로드됩니다
2. 필요에 따라 파일 읽기: Claude는 필요할 때 파일 시스템에서 SKILL.md 및 다른 파일에 액세스하기 위해 bash 읽기 도구를 사용합니다
3. 효율적으로 스크립트 실행: 유틸리티 스크립트는 전체 콘텐츠를 컨텍스트에 로드하지 않고 bash를 통해 실행할 수 있습니다. 스크립트의 출력만 토큰을 소비합니다
4. 큰 파일에 대한 컨텍스트 페널티 없음: 참조 파일, 데이터 또는 문서는 실제로 읽을 때까지 컨텍스트 토큰을 소비하지 않습니다

• 파일 경로 중요: Claude는 파일 시스템처럼 Skill 디렉토리를 탐색합니다. 슬래시(reference/guide.md)를 사용하고 백슬래시는 사용하지 마세요
• 파일 이름을 설명적으로: 콘텐츠를 나타내는 이름을 사용하세요: form_validation_rules.md, doc2.md 아님
• 발견을 위해 구성: 도메인 또는 기능별로 디렉토리 구조화
  • 좋음: reference/finance.md, reference/sales.md
  • 나쁨: docs/file1.md, docs/file2.md
• 포괄적인 리소스 번들: 전체 API 문서, 광범위한 예, 큰 데이터세트 포함; 액세스할 때까지 컨텍스트 페널티 없음
• 결정론적 작업에 스크립트 선호: Claude가 검증 코드를 생성하도록 요청하는 대신 validate_form.py 작성
• 실행 의도 명확히:
  • "analyze_form.py를 실행하여 필드 추출" (실행)
  • "추출 알고리즘은 analyze_form.py 참조" (참조로 읽기)
• 파일 액세스 패턴 테스트: 실제 요청으로 테스트하여 Claude가 디렉토리 구조를 탐색할 수 있는지 확인

예:

bigquery-skill/
├── SKILL.md (개요, 참조 파일 지시)
└── reference/
    ├── finance.md (수익 지표)
    ├── sales.md (파이프라인 데이터)
    └── product.md (사용 분석)

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

기술 아키텍처에 대한 완전한 세부 정보는 Skill 개요의 Skill이 어떻게 작동하는지를 참조하세요.

MCP 도구 참조

Skill이 MCP(Model Context Protocol) 도구를 사용하는 경우 항상 정규화된 도구 이름을 사용하여 "도구를 찾을 수 없음" 오류를 피하세요.

형식: ServerName:tool_name

예:

BigQuery:bigquery_schema 도구를 사용하여 테이블 스키마를 검색합니다.
GitHub:create_issue 도구를 사용하여 문제를 생성합니다.

여기서:

• BigQuery 및 GitHub는 MCP 서버 이름입니다
• bigquery_schema 및 create_issue는 해당 서버 내의 도구 이름입니다

서버 접두사 없이 Claude는 특히 여러 MCP 서버를 사용할 수 있을 때 도구를 찾지 못할 수 있습니다.

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

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

**나쁜 예: 설치를 가정**:
"pdf 라이브러리를 사용하여 파일을 처리합니다."

**좋은 예: 의존성에 대해 명시적**:
"필수 패키지 설치: `pip install pypdf`

그런 다음 사용:
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```"

기술 노트

YAML 프론트매터 요구사항

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

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

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

토큰 예산

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

효과적인 Skill 체크리스트

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

핵심 품질

• 설명이 구체적이고 핵심 용어를 포함합니다
• 설명에 Skill이 무엇을 하는지와 언제 사용하는지가 포함됩니다
• SKILL.md 본문이 500줄 이하입니다
• 추가 세부 정보가 별도 파일에 있습니다 (필요한 경우)
• 시간에 민감한 정보가 없습니다 (또는 "이전 패턴" 섹션에 있습니다)
• 전체에서 일관된 용어를 사용합니다
• 예가 추상적이 아닌 구체적입니다
• 파일 참조가 한 수준 깊이입니다
• 점진적 공개가 적절하게 사용됩니다
• 워크플로우에 명확한 단계가 있습니다

코드 및 스크립트

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

테스트

• 최소 3개의 평가가 생성되었습니다
• Haiku, Sonnet, Opus로 테스트되었습니다
• 실제 사용 시나리오로 테스트되었습니다
• 팀 피드백이 통합되었습니다 (해당하는 경우)

다음 단계