안녕하세요! 오늘은 Anthropic의 Claude 에이전트 생태계에서 매우 중요한 개념으로 자리 잡은 **'Skill(스킬)'**을 효과적으로 작성하는 모범 사례를 공유해 보려고 합니다.
에이전트가 발전함에 따라, LLM에게 매번 거대한 시스템 프롬프트를 쥐여주는 방식은 비용과 성능 측면에서 한계에 부딪히고 있습니다. Claude가 필요할 때만 스스로 지침을 찾아 읽고 실행하게 만드는 'Skill'의 설계 원칙과 아키텍처 패턴을 함께 알아봅시다.
1. 핵심 설계 원칙
💡 간결함이 핵심입니다 (Context Window 최적화)
Claude의 컨텍스트 윈도우는 한정된 공공재입니다. 시스템 프롬프트, 대화 기록, 다른 Skill의 메타데이터와 대화 요청이 모두 이 공간을 공유하죠.
Claude는 처음에 Skill의 이름(name)과 설명(description)만 미리 로드합니다. 그리고 실제 필요성이 생겼을 때에만 내부 SKILL.md 파일과 추가 문서를 읽어 들입니다.
따라서, **"Claude는 이미 충분히 똑똑하다"**는 가정을 바탕으로 작성해야 토큰을 아낄 수 있습니다.
- ❌ 장황한 예시: PDF가 무엇인지 정의하고, 외부 라이브러리 설치법부터 구구절절 설명하는 방식 (약 150 토큰 낭비)
- ✅ 간결한 예시: Claude가 PDF와 Python 라이브러리의 기초를 안다고 가정하고 핵심 스크립트만 제공 (약 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()
🎛️ 적절한 자유도(Degrees of Freedom) 설정
작업의 성격(취약성 및 가변성)에 따라 에이전트에게 부여할 자유도를 다르게 설계해야 합니다.
| 자유도 수준 | 적합한 상황 | 예시 코드/지침 형태 |
|---|---|---|
| 높은 자유도 | 여러 접근 방식이 유효하고, 컨텍스트에 따른 판단이 필요할 때 | 텍스트 기반 가이드라인 (예: 코드 리뷰 프로세스) |
| 중간 자유도 | 선호되는 패턴이 존재하지만 일부 변형이 허용될 때 | 매개변수가 포함된 의사 코드나 템플릿 함수 스크립트 |
| 낮은 자유도 | 작업이 취약하여 오류 발생 확률이 높고 일관성이 절대적일 때 | 추가 플래그 변경이 금지된 명확한 CLI 명령어 (python migrate.py --verify) |
2. 효과적인 Skill 구조화 패턴
🏷️ 명명 규칙과 Description 작성
- 이름(
name): 소문자, 숫자, 하이픈(-)만 허용됩니다. 최대 64자 제한이 있으며anthropic이나claude같은 예약어는 사용할 수 없습니다. 가급적 활동을 명확히 동명사 형태(processing-pdfs,managing-databases)로 지정하는 것이 좋습니다. - 설명(
description): Claude가 수많은 Skill 중 현재 작업에 이것이 필요한지 판단하는 기준이 됩니다. 반드시 3인칭으로 작성해야 합니다.
# 좋은 description 예시
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.
📦 점진적 공개 패턴 (Progressive Disclosure)
SKILL.md 본문 파일은 가급적 500줄 미만으로 유지하는 것이 좋습니다.
내용이 길어지면 Claude가 처음부터 큰 파일을 읽느라 토큰을 과소비하게 됩니다.
대신 필요할 때만 하위 마크다운 파일을 로드할 수 있도록 아키텍처를 쪼개야 합니다.
# 추천하는 디렉터리 구조
pdf-processing/
├── SKILL.md # 메인 가이드 (트리거 시 최초 로드)
├── FORMS.md # 양식 작성 가이드 (필요 시 로드)
├── REFERENCE.md # 상세 API 레퍼런스 (필요 시 로드)
└── scripts/
└── analyze_form.py # 유틸리티 스크립트
⚠️ 주의 (Anti-Pattern): 중첩 구조를 너무 깊게(
SKILL.md->advanced.md->details.md) 설계하면 안 됩니다. Claude가 파일을 훑어볼 때 텍스트의 일부만 미리 보기 때문에 정보 누락이 발생할 수 있습니다. 참조는 **SKILL.md 기준 딱 한 단계 깊이(1 depth)**로만 유지하세요.
3. 워크플로 및 피드백 루프 설계
복잡한 작업을 수행할 때 Claude가 단계를 건너뛰지 않도록 체크리스트와 검증 루프를 설계 프로세스에 심어주어야 합니다. "검증기 실행 ➡️ 오류 수정 ➡️ 재시도" 루프는 결과물의 퀄리티를 비약적으로 높여줍니다.
## 🛠️ PDF 양식 작성 워크플로
이 체크리스트를 복사하여 진행 상황을 추적하세요:
- text
Task Progress:
- [ ] Step 1: 양식 분석 (run analyze_form.py)
- [ ] Step 2: 필드 매핑 생성 (edit fields.json)
- [ ] Step 3: 매핑 검증 (run validate_fields.py)
- [ ] Step 4: 양식 채우기 (run fill_form.py)
**Step 1: 양식 분석**
다음 명령어를 실행하여 PDF 내부의 필드 위치를 `fields.json`으로 추출하세요:
`python scripts/analyze_form.py input.pdf`
4. 고급: 실행 코드가 포함된 Skill 개발 팁
Claude가 직접 코드를 짜서 실행할 수도 있지만, 미리 검증된 유틸리티 스크립트를 Skill 내부에 번들링해 두면 토큰 절약, 실행 시간 단축, 안정성 확보라는 세 마리 토끼를 모두 잡을 수 있습니다.
🛡️ 에이전트에게 예외 처리를 떠넘기지 마세요
유틸리티 스크립트 내부에서 발생하는 예외를 그대로 덤프하여 Claude가 에러 메시지를 해석하게 만들지 마세요. 스크립트 자체에서 예외를 처리하고 명확하고 친절한 해결 가이드를 출력해야 합니다.
# scripts/validate_fields.py
try:
with open(field_path) as f:
# 데이터 검증 로직
pass
except FileNotFoundError:
# 무작정 크래시를 내는 대신 에이전트가 다음 행동을 취할 수 있는 힌트를 제공합니다.
print(f"[Error] {field_path} 파일이 없습니다. Step 1의 analyze_form.py를 먼저 실행했는지 확인하세요.")
sys.exit(1)
🌐 MCP(Model Context Protocol) 도구 참조 방법
만약 개발 중인 Skill이 외부 MCP 도구를 호출해야 한다면, 컨텍스트가 꼬이지 않도록 서버명을 명시한 정규화된 이름(Fully-Qualified Name)을 사용해야 에이전트가 누락 없이 도구를 찾아냅니다.
- 格式:
ServerName:tool_name - 예시:
Use the BigQuery:bigquery_schema tool to retrieve table schemas.
5. 마치며: Claude와 협력하여 Skill 빌드하기
가장 뛰어난 Skill 개발 방법은 한 명의 Claude 인스턴스(Claude A)를 테크니컬 라이터로 고용하고, 다른 인스턴스(Claude B)에게 테스트 가이드 역할을 맡기는 것입니다.
- Claude A와 대화하며 수동으로 복잡한 작업을 성공시킵니다.
- 성공적인 흐름이 정립되면 Claude A에게 *"방금 우리가 진행한 BigQuery 분석 패턴을 캡처하는 SKILL.md 구조를 만들어줘"*라고 요청합니다.
- 생성된 가이드를 들고 Claude B 에이전트 환경에 로드한 뒤 실제 업무를 맡겨보며 틈새를 보완(반복 인터랙션)합니다.
이러한 '평가 중심 반복 기법'을 적용하면 사람이 미처 예상하지 못했던 에이전트의 오작동 패턴을 사전에 차단하고 고도로 최적화된 개발 도우미를 구축할 수 있습니다.
여러분도 반복적인 에이전트 프롬프트에 지쳤다면, 이번 기회에 나만의 점진적 공개형 'Claude Skill' 아키텍처를 설계해 보시는 건 어떨까요? 궁금한 점이 있다면 댓글로 남겨주세요!