Agent Skills 모범 사례: 효과적인 Claude Skills 작성 완벽 가이드
효과적인 Claude Skills 작성을 위한 Agent Skills 모범 사례를 알아보세요. 간결성과 점진적 공개(progressive disclosure)의 핵심 원칙부터 실행 가능한 코드를 활용한 고급 패턴까지 다룹니다.
이 글은 Anthropic의 공식 문서 Skill Authoring Best Practices를 기반으로 작성되었습니다.
Agent Skills 모범 사례를 따르는 것은 안정적으로 작동하는 Claude Skills를 작성하는 데 필수적입니다. 이 가이드는 가장 중요한 Agent Skills 모범 사례를 다룹니다 — Claude가 효과적으로 발견하고 사용할 수 있는 Claude Skills를 작성하기 위한 실용적인 작성 결정 사항들입니다.
핵심 Agent Skills 모범 사례
간결함이 핵심
Agent Skills 모범 사례 중 가장 중요한 것은 간결함입니다. Skill은 Claude가 알아야 할 다른 모든 것과 컨텍스트 윈도우를 공유합니다 — 시스템 프롬프트, 대화 이력, 다른 Skills의 메타데이터, 그리고 실제 요청을 포함합니다.
Skill의 모든 토큰에 즉각적인 비용이 드는 것은 아닙니다. 시작 시에는 모든 Skills의 메타데이터(이름과 설명)만 사전 로드됩니다. 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를 추천합니다.
사용하기 쉽고 대부분의 경우를 잘 처리하기 때문입니다...
간결한 버전은 Claude가 PDF가 무엇이고 라이브러리가 어떻게 작동하는지 알고 있다고 가정합니다.
적절한 자유도 설정
작업의 민감도와 가변성에 맞게 구체성 수준을 조절하세요.
높은 자유도 (텍스트 기반 지침) — 여러 접근 방식이 유효할 때 사용:
## 코드 리뷰 프로세스
1. 코드 구조와 조직을 분석한다
2. 잠재적 버그나 엣지 케이스를 확인한다
3. 가독성과 유지보수성 향상을 제안한다
4. 프로젝트 규칙 준수 여부를 확인한다
중간 자유도 (의사 코드 또는 파라미터가 있는 스크립트) — 선호하는 패턴이 있을 때 사용:
## 보고서 생성
이 템플릿을 사용하고 필요에 따라 커스터마이즈하세요:
```python
def generate_report(data, format="markdown", include_charts=True):
# 데이터 처리
# 지정된 형식으로 출력 생성
# 선택적으로 시각화 포함
```
낮은 자유도 (특정 스크립트, 파라미터 거의 없음) — 작업이 민감할 때 사용:
## 데이터베이스 마이그레이션
정확히 이 스크립트를 실행하세요:
```bash
python scripts/migrate.py --verify --backup
```
명령어를 수정하거나 추가 플래그를 넣지 마세요.
Claude를 경로를 탐색하는 로봇으로 생각하세요:
- 절벽이 있는 좁은 다리: 안전한 길은 하나뿐입니다. 정확한 지침을 제공하세요 (낮은 자유도).
- 넓은 들판: 많은 경로가 성공으로 이어집니다. 일반적인 방향을 제시하세요 (높은 자유도).
사용 예정인 모든 모델로 테스트
Skills는 모델의 추가 기능으로 작동하므로, 효과는 기반 모델에 따라 달라집니다:
- Claude Haiku (빠르고 경제적): Skill이 충분한 안내를 제공하는가?
- Claude Sonnet (균형): Skill이 명확하고 효율적인가?
- Claude Opus (강력한 추론): Skill이 과도한 설명을 피하는가?
Opus에서 완벽하게 작동하는 것이 Haiku에서는 더 자세한 설명이 필요할 수 있습니다.
Skill 구조를 위한 Agent Skills 모범 사례
명명 규칙
Skill 이름에 동명사 형태 (동사 + -ing)를 사용하세요. name 필드는 소문자, 숫자, 하이픈만 사용해야 합니다.
좋은 예:
processing-pdfsanalyzing-spreadsheetsmanaging-databasestesting-codewriting-documentation
피해야 할 것:
- 모호한 이름:
helper,utils,tools - 과도하게 일반적:
documents,data,files - 예약어:
anthropic-helper,claude-tools
효과적인 설명 작성
description 필드는 Skill 탐색을 가능하게 하며, Skill이 무엇을 하는지와 언제 사용해야 하는지를 포함해야 합니다.
항상 3인칭으로 작성하세요. 설명은 시스템 프롬프트에 삽입됩니다:
- 좋음: "Processes Excel files and generates reports"
- 피하기: "I can help you process Excel files"
효과적인 예:
# PDF 처리
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 분석
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
# Git 커밋 도우미
description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
점진적 공개 패턴
SKILL.md는 Claude를 필요에 따라 상세 자료로 안내하는 개요 역할을 합니다.
- SKILL.md 본문은 최적 성능을 위해 500줄 이내로 유지하세요
- 이 한도에 가까워지면 콘텐츠를 별도 파일로 분할하세요
패턴 1: 참조가 포함된 상위 수준 가이드
---
name: pdf-processing
description: Extracts text and tables from PDF files, fills forms, and merges documents.
---
# 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)에서 일반적인 패턴을 확인하세요
패턴 2: 도메인별 구성
bigquery-skill/
├── SKILL.md (개요 및 네비게이션)
└── reference/
├── finance.md (매출, 빌링 지표)
├── sales.md (기회, 파이프라인)
├── product.md (API 사용, 기능)
└── marketing.md (캠페인, 어트리뷰션)
사용자가 영업 지표에 대해 물으면 Claude는 영업 관련 스키마만 읽으면 됩니다, 재무나 마케팅 데이터는 필요 없습니다.
패턴 3: 조건부 상세 정보
# DOCX 처리
## 문서 생성
새 문서에는 docx-js를 사용하세요. [DOCX-JS.md](DOCX-JS.md)를 참조하세요.
## 문서 편집
간단한 편집은 XML을 직접 수정하세요.
**변경 추적의 경우**: [REDLINING.md](REDLINING.md) 참조
**OOXML 상세 정보**: [OOXML.md](OOXML.md) 참조
깊이 중첩된 참조 피하기
Claude는 다른 참조 파일에서 참조된 파일을 부분적으로만 읽을 수 있습니다. SKILL.md에서 한 단계 깊이의 참조를 유지하세요.
나쁨 (너무 깊음):
SKILL.md → advanced.md → details.md → 실제 정보
좋음 (한 단계):
SKILL.md → advanced.md
SKILL.md → reference.md
SKILL.md → examples.md
긴 참조 파일에 목차 구성
100줄 이상의 참조 파일에는 상단에 목차를 포함하세요:
# API 레퍼런스
## 목차
- 인증 및 설정
- 핵심 메서드 (생성, 읽기, 수정, 삭제)
- 고급 기능 (배치 작업, 웹훅)
- 오류 처리 패턴
- 코드 예제
워크플로와 피드백 루프를 위한 Agent Skills 모범 사례
복잡한 작업에 워크플로 사용
복잡한 작업을 체크리스트가 포함된 명확하고 순차적인 단계로 분해하세요:
## 연구 종합 워크플로
이 체크리스트를 복사하고 진행 상황을 추적하세요:
```
연구 진행 상황:
- [ ] 1단계: 모든 소스 문서 읽기
- [ ] 2단계: 핵심 주제 식별
- [ ] 3단계: 주장 교차 참조
- [ ] 4단계: 구조화된 요약 작성
- [ ] 5단계: 인용 확인
```
**1단계: 모든 소스 문서 읽기**
`sources/` 디렉토리의 각 문서를 검토하세요. 주요 주장을 기록하세요.
**2단계: 핵심 주제 식별**
소스 간 패턴을 찾으세요. 어떤 주제가 반복적으로 나타나나요?
**3단계: 주장 교차 참조**
각 주요 주장에 대해 소스 자료에 있는지 확인하세요.
**4단계: 구조화된 요약 작성**
발견 사항을 증거와 함께 주제별로 정리하세요.
**5단계: 인용 확인**
모든 주장이 올바른 소스를 참조하는지 확인하세요. 불완전하면 3단계로 돌아가세요.
피드백 루프 구현
일반적인 패턴: 검증기 실행 -> 오류 수정 -> 반복
## 문서 편집 프로세스
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`
콘텐츠 가이드라인
시간에 민감한 정보 피하기
나쁨 (시간이 지나면 틀림):
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>
일관된 용어 사용
하나의 용어를 선택하고 전체에서 사용하세요:
- 좋음: 항상 "API endpoint", 항상 "field", 항상 "extract"
- 나쁨: "API endpoint" / "URL" / "API route" / "path"를 혼용
일반적인 패턴
템플릿 패턴
## 보고서 구조
반드시 이 정확한 템플릿 구조를 사용하세요:
```markdown
# [분석 제목]
## 요약
[핵심 발견 사항의 한 단락 개요]
## 주요 발견 사항
- 근거 데이터가 포함된 발견 1
- 근거 데이터가 포함된 발견 2
## 권장 사항
1. 구체적이고 실행 가능한 권장 사항
2. 구체적이고 실행 가능한 권장 사항
```
예제 패턴
일반 프롬프팅과 마찬가지로 입력/출력 쌍을 제공하세요:
## 커밋 메시지 형식
**예제 1:**
입력: JWT 토큰을 사용한 사용자 인증 추가
출력:
```
feat(auth): implement JWT-based authentication
Add login endpoint and token validation middleware
```
**예제 2:**
입력: 보고서에서 날짜가 잘못 표시되는 버그 수정
출력:
```
fix(reports): correct date formatting in timezone conversion
Use UTC timestamps consistently across report generation
```
조건부 워크플로 패턴
## 문서 수정 워크플로
1. 수정 유형을 결정한다:
**새 콘텐츠를 생성하는 경우?** -> 아래 "생성 워크플로"를 따르세요
**기존 콘텐츠를 편집하는 경우?** -> 아래 "편집 워크플로"를 따르세요
2. 생성 워크플로:
- docx-js 라이브러리 사용
- 처음부터 문서 작성
- .docx 형식으로 내보내기
3. 편집 워크플로:
- 기존 문서 압축 해제
- XML을 직접 수정
- 각 변경 후 검증
- 완료 시 다시 압축
평가와 반복을 위한 Agent Skills 모범 사례
평가를 먼저 만들기
가장 중요한 Agent Skills 모범 사례 중 하나: 광범위한 문서 작성 이전에 평가를 만드세요. 이렇게 하면 Skill이 실제 문제를 해결하는지 보장할 수 있습니다.
평가 주도 개발:
- 격차 식별: Skill 없이 대표적인 작업에서 Claude를 실행하세요. 구체적인 실패를 문서화하세요
- 평가 생성: 이 격차를 테스트하는 세 가지 시나리오를 만드세요
- 기준선 설정: Skill 없이 Claude의 성능을 측정하세요
- 최소한의 지침 작성: 격차를 해결하기에 충분한 콘텐츠만 만드세요
- 반복: 평가를 실행하고 기준선과 비교하고 개선하세요
Claude와 함께 Skills를 반복적으로 개발
하나의 Claude 인스턴스("Claude A")와 작업하여 다른 인스턴스("Claude B")가 사용할 Skill을 만드세요:
- Skill 없이 작업 완료: Claude A와 함께 문제를 해결하세요. 반복적으로 제공하는 정보가 무엇인지 주목하세요.
- 재사용 가능한 패턴 식별: 작업 완료 후, 유사한 미래 작업에 유용할 컨텍스트를 식별하세요.
- Claude A에게 Skill 생성 요청: Claude 모델은 Skill 형식을 기본적으로 이해합니다.
- 간결성 검토: Claude가 불필요한 설명을 추가하지 않았는지 확인하세요.
- 유사한 작업에서 테스트: Claude B와 관련 사용 사례에서 Skill을 사용하세요.
- 관찰에 기반하여 반복: Claude B가 어려움을 겪으면, 구체적인 내용과 함께 Claude A에게 돌아가세요.
고급: 실행 가능한 코드가 포함된 Skills
떠넘기지 않고 해결하기
오류 조건을 Claude에게 떠넘기지 말고 처리하세요:
# 좋음: 오류를 명시적으로 처리
def process_file(path):
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 ""
# 나쁨: Claude에게 떠넘기기
def process_file(path):
return open(path).read()
유틸리티 스크립트 제공
미리 만들어진 스크립트는 생성된 코드에 비해 장점이 있습니다:
- 생성된 코드보다 안정적
- 토큰 절약 (컨텍스트에 코드를 포함할 필요 없음)
- 시간 절약 (코드 생성 불필요)
- 사용 간 일관성 보장
검증 가능한 중간 출력 생성
복잡한 작업에는 "계획-검증-실행" 패턴을 사용하세요:
- 분석 -> 계획 파일 생성 -> 계획 검증 -> 실행 -> 확인
이를 통해 오류를 조기에 발견하고, 기계 검증 가능한 유효성 검사를 제공하며, 명확한 디버깅을 가능하게 합니다.
피해야 할 안티 패턴
- Windows 스타일 경로: 항상 슬래시를 사용하세요 (
scripts/helper.py,scripts\helper.py가 아님) - 너무 많은 옵션: 선택 메뉴가 아닌 기본 접근 방식과 탈출구를 제공하세요
- 모호한 설명: "문서를 돕습니다"는 Claude에게 유용한 정보를 제공하지 않습니다
- 깊이 중첩된 참조: 모든 참조를 SKILL.md에서 한 단계 깊이로 유지하세요
- 매직 넘버: 설정 값이 왜 그런 값인지 문서화하세요
Agent Skills 모범 사례 체크리스트
핵심 품질
- 설명이 구체적이며 주요 용어를 포함하는가
- 설명에 Skill이 하는 일과 사용 시점이 모두 포함되어 있는가
- SKILL.md 본문이 500줄 이내인가
- 추가 상세 정보가 별도 파일에 있는가 (필요한 경우)
- 시간에 민감한 정보가 없는가
- 전체적으로 일관된 용어를 사용하는가
- 예제가 구체적인가 (추상적이지 않은가)
- 파일 참조가 한 단계 깊이인가
- 점진적 공개가 적절히 사용되었는가
- 워크플로에 명확한 단계가 있는가
코드 및 스크립트
- 스크립트가 Claude에게 떠넘기지 않고 문제를 해결하는가
- 오류 처리가 명시적이고 유용한가
- 매직 상수가 없는가 (모든 값이 정당화됨)
- 필요한 패키지가 나열되고 사용 가능한지 확인되었는가
- 중요한 작업에 대한 검증/확인 단계가 있는가
- 품질이 중요한 작업에 피드백 루프가 포함되어 있는가
테스트
- 최소 세 가지 평가가 만들어졌는가
- Haiku, Sonnet, Opus로 테스트했는가
- 실제 사용 시나리오로 테스트했는가
- 팀 피드백이 반영되었는가
