Claude Agent Skill 제작 가이드 (심화과정)

목차

1. 핵심 원칙
2. 스킬 구조
3. 효과적인 작성 패턴
4. 콘텐츠 가이드라인
5. 평가와 반복 개선
6. 실행 가능한 코드가 포함된 스킬
7. 체크리스트

---

핵심 원칙

1. 간결함이 핵심

컨텍스트 윈도우는 공공재입니다. 스킬은 다음 요소들과 함께 컨텍스트를 공유합니다:

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

작성 시 항상 자문하세요:

• "Claude가 정말 이 설명을 필요로 할까?"
• "Claude가 이미 알고 있다고 가정할 수 있을까?"
• "이 단락이 토큰 비용을 정당화할까?"

2. 적절한 자유도 설정

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

높은 자유도 (텍스트 기반 지침) - 다음 경우에 사용:

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

중간 자유도 (구조화된 가이드라인) - 다음 경우에 사용:

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

낮은 자유도 (정확한 지침) - 다음 경우에 사용:

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

비유로 이해하기:

• 절벽 사이의 좁은 다리: 안전한 길이 하나뿐입니다. 구체적인 가드레일과 정확한 지침 제공 (낮은 자유도). 예: 정확한 순서로 실행해야 하는 데이터베이스 마이그레이션
• 장애물 없는 개활지: 많은 길이 성공으로 이어집니다. 일반적인 방향만 제시하고 Claude가 최적의 경로를 찾도록 신뢰 (높은 자유도). 예: 맥락에 따라 최선의 접근이 달라지는 코드 리뷰

3. 사용할 모든 모델로 테스트

스킬은 모델에 대한 추가 기능이므로 효과는 기본 모델에 따라 달라집니다.

모델별 테스트 고려사항:

• Claude Haiku (빠르고 경제적): 스킬이 충분한 안내를 제공하는가?
• Claude Sonnet (균형적): 스킬이 명확하고 효율적인가?
• Claude Opus (강력한 추론): 스킬이 과도하게 설명하지 않는가?

---

스킬 구조

기본 구조

스킬은 SKILL.md 파일로 구성되며, YAML 프론트매터와 본문을 포함합니다.

---
name: 스킬 이름
description: 스킬이 무엇을 하는지, 언제 사용하는지 설명
---

# 스킬 본문 내용

필수 필드

• name: 사람이 읽을 수 있는 스킬 이름 (최대 64자)
• description: 스킬의 기능과 사용 시기를 설명하는 한 줄 설명 (최대 1024자)

네이밍 규칙

일관된 네이밍 패턴을 사용하여 스킬을 쉽게 참조하고 논의할 수 있게 하세요. 동명사 형태(동사 + -ing)를 권장합니다.

좋은 예 (동명사 형태):

• "Processing PDFs" (PDF 처리하기)
• "Analyzing spreadsheets" (스프레드시트 분석하기)
• "Managing databases" (데이터베이스 관리하기)
• "Testing code" (코드 테스트하기)

피해야 할 예:

• 명사구: "PDF Processing", "Spreadsheet Analysis"
• 동작 지향: "Process PDFs", "Analyze Spreadsheets"
• 모호한 이름: "Helper", "Utils", "Tools"
• 지나치게 일반적: "Documents", "Data", "Files"

효과적인 설명 작성

description 필드는 스킬 검색을 가능하게 하며, 스킬의 기능과 사용 시기를 모두 포함해야 합니다.

좋은 예:

description: Excel 파일을 처리하고 보고서를 생성합니다

피해야 할 예:

description: Excel 파일 처리를 도와드릴 수 있습니다
description: 이것을 사용하여 Excel 파일을 처리할 수 있습니다

---

효과적인 작성 패턴

점진적 공개 (Progressive Disclosure)

SKILL.md는 개요 역할을 하며, 필요에 따라 Claude가 상세 자료를 참조하도록 안내합니다.

실용적 가이드:

• SKILL.md 본문을 500줄 미만으로 유지 (최적 성능)
• 이 제한에 근접하면 콘텐츠를 별도 파일로 분리
• 아래 패턴을 사용하여 지침, 코드, 리소스를 효과적으로 구성

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

1단계: 기본 스킬

my-skill/
└── SKILL.md

2단계: 참조 파일 번들링

my-skill/
├── SKILL.md
├── reference.md
└── forms.md

3단계: 도메인별 구조

my-skill/
├── SKILL.md
├── sales/
│   └── schema.md
├── finance/
│   └── schema.md
└── marketing/
    └── schema.md

패턴 1: 참조가 있는 상위 수준 가이드

SKILL.md에서 개요를 제공하고 세부사항은 별도 파일로 분리합니다.

---
name: Database querying
description: BigQuery 데이터베이스를 쿼리하고 보고서를 생성합니다
---

# 데이터베이스 쿼리 가이드

## 테이블 스키마
자세한 스키마 정보는 `reference/schema.md`를 참조하세요.

## 쿼리 패턴
일반적인 쿼리 패턴은 `reference/patterns.md`를 참조하세요.

패턴 2: 도메인별 구조

여러 도메인이 있는 스킬의 경우, 도메인별로 콘텐츠를 구성하여 관련 없는 컨텍스트 로딩을 방지합니다.

# 보고서 생성

사용자가 어떤 보고서를 요청하는지에 따라 적절한 스키마를 읽으세요:
- 영업 메트릭: `sales/schema.md` 읽기
- 재무 데이터: `finance/schema.md` 읽기
- 마케팅 분석: `marketing/schema.md` 읽기

패턴 3: 조건부 세부사항

기본 콘텐츠를 표시하고 고급 콘텐츠에 링크합니다.

# 기본 사용법

[기본 지침 내용]

## 고급 기능
복잡한 케이스는 `advanced/complex-scenarios.md`를 참조하세요.

중요: 중첩된 참조 피하기

참조를 한 단계 깊이로 유지하세요. 모든 참조 파일은 SKILL.md에서 직접 링크해야 합니다.

나쁜 예 (너무 깊음):

SKILL.md → reference.md → details.md

좋은 예 (한 단계):

SKILL.md → reference.md
SKILL.md → details.md

긴 참조 파일의 목차 구성

100줄을 초과하는 참조 파일의 경우, 상단에 목차를 포함하세요.

# 고급 참조

## 목차
1. [런타임 환경](#런타임-환경)
2. [의존성 관리](#의존성-관리)
3. [오류 처리](#오류-처리)

## 런타임 환경
[내용...]

---

워크플로우 및 피드백 루프

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

복잡한 작업을 명확하고 순차적인 단계로 나눕니다.

예시 1: 연구 종합 워크플로우

# 연구 프로세스

1. **검색**: web_search로 관련 소스 찾기
2. **수집**: web_fetch로 전체 문서 검색
3. **분석**: 각 소스에서 핵심 포인트 추출
4. **종합**: 결과를 일관된 보고서로 통합
5. **검증**: 모든 주장에 적절한 인용 확인

예시 2: 체크리스트 제공

작업을 진행하면서 다음 체크리스트를 응답에 복사하고 체크하세요:

- [ ] 요구사항 분석 완료
- [ ] 데이터 수집 완료
- [ ] 초안 작성 완료
- [ ] 검증 통과
- [ ] 최종 검토 완료

피드백 루프 구현

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

예시 1: 스타일 가이드 준수

# 문서 작성 프로세스

1. 초안 작성
2. `style_checker.py` 실행
3. 보고된 문제 수정
4. 모든 검사를 통과할 때까지 2-3 반복
5. 최종 버전 제출

예시 2: 코드 품질 검증

# 코드 작성 워크플로우

1. 코드 작성
2. `lint.py` 실행하여 스타일 문제 확인
3. `test.py` 실행하여 기능 검증
4. 모든 검사가 통과할 때까지 수정

---

콘텐츠 가이드라인

시간에 민감한 정보 피하기

시간이 지나면 구식이 될 정보를 포함하지 마세요.

나쁜 예 (시간에 민감):

현재 최신 버전은 3.0입니다
2024년 현재, API 엔드포인트는...

좋은 예 (시간에 독립적):

최신 버전을 확인하려면 공식 문서를 참조하세요
API 엔드포인트 목록은 `reference/endpoints.md`를 참조하세요

일관된 용어 사용

하나의 용어를 선택하고 스킬 전체에서 일관되게 사용하세요.

좋은 예 - 일관성 있음:

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

피해야 할 예 - 혼재:

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

---

일반적인 패턴

템플릿 패턴

출력 형식에 대한 템플릿을 제공합니다.

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

# 출력 형식

응답은 정확히 다음 형식을 따라야 합니다:

```json
{
  "status": "success" | "error",
  "data": { ... },
  "timestamp": "ISO 8601 형식"
}

### 예시 패턴

출력 품질이 예시를 보는 것에 의존하는 경우, 입력/출력 쌍을 제공합니다.

```markdown
# 변환 예시

**입력:**

사용자 이름: 홍길동 이메일: hong@example.com

**출력:**
```json
{
  "name": "홍길동",
  "email": "hong@example.com",
  "formatted": "홍길동 (hong@example.com)"
}

### 조건부 워크플로우 패턴

결정 지점을 통해 Claude를 안내합니다.

```markdown
# 데이터 처리 워크플로우

1. 파일 형식 확인:
   - CSV인 경우 → `process_csv.py` 사용
   - Excel인 경우 → `process_excel.py` 사용
   - JSON인 경우 → `process_json.py` 사용

2. 데이터 크기 평가:
   - 1000행 미만 → 메모리에서 처리
   - 1000행 이상 → 스트리밍 처리 사용

---

평가와 반복 개선

평가를 먼저 구축

광범위한 문서를 작성하기 전에 평가를 만드세요.

평가 주도 개발:

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

Claude와 함께 반복적으로 스킬 개발

가장 효과적인 스킬 개발 프로세스는 Claude 자체를 포함합니다.

새 스킬 생성:

1. 스킬 없이 작업 완료: Claude A와 함께 일반 프롬프팅을 사용하여 문제 해결. 작업하면서 자연스럽게 컨텍스트를 제공하고, 선호사항을 설명하고, 절차적 지식을 공유합니다.
2. 재사용 가능한 패턴 식별: 작업 완료 후, 유사한 향후 작업에 유용할 컨텍스트를 식별합니다.
3. 예: BigQuery 분석을 수행했다면, 테이블 이름, 필드 정의, 필터링 규칙(예: "항상 테스트 계정 제외"), 일반적인 쿼리 패턴을 제공했을 것입니다.
4. Claude A에게 스킬 생성 요청:
5. "방금 사용한 BigQuery 분석 패턴을 담은 스킬을 만들어줘. 테이블 스키마, 네이밍 규칙, 테스트 계정 필터링 규칙을 포함해줘."
6. 간결성 검토: Claude A가 불필요한 설명을 추가하지 않았는지 확인합니다.
7. "승률이 무엇인지에 대한 설명을 제거해줘 - Claude는 이미 알고 있어."
8. 정보 아키텍처 개선: Claude A에게 콘텐츠를 더 효과적으로 구성하도록 요청합니다.
9. "테이블 스키마를 별도 참조 파일로 구성해줘. 나중에 더 많은 테이블을 추가할 수 있어."
10. 유사한 작업으로 테스트: 스킬이 로드된 Claude B(새 인스턴스)에서 관련 사용 사례로 테스트합니다.
11. 관찰 기반 반복: Claude B가 어려움을 겪거나 무언가를 놓치면, 구체적인 내용과 함께 Claude A로 돌아갑니다.

핵심은 순환입니다:

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

Claude가 스킬을 탐색하는 방식 관찰

스킬을 반복하면서 Claude가 실제로 어떻게 사용하는지 주의 깊게 관찰하세요:

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

---

피해야 할 안티패턴

Windows 스타일 경로 피하기

Windows에서도 항상 슬래시를 사용하세요.

• ✓ 좋은 예: scripts/helper.py, reference/guide.md
• ✗ 피해야 할 예: scripts\helper.py, reference\guide.md

너무 많은 옵션 제공하지 않기

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

나쁜 예:

데이터를 처리할 수 있는 3가지 방법:
1. 방법 A: [설명]
2. 방법 B: [설명]
3. 방법 C: [설명]

원하는 방법을 선택하세요.

좋은 예:

`process_data.py`를 실행하여 데이터를 처리하세요.

특별한 경우: 1000행을 초과하는 대용량 파일의 경우,
`process_data.py --streaming` 옵션을 사용하세요.

---

실행 가능한 코드가 포함된 스킬

해결하기, 위임하지 않기

스킬용 스크립트를 작성할 때는 오류 조건을 처리하고 Claude에게 위임하지 마세요.

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

def process_file(path):
    if not os.path.exists(path):
        print(f"오류: 파일 '{path}'를 찾을 수 없습니다")
        sys.exit(1)
    
    try:
        with open(path) as f:
            return f.read()
    except PermissionError:
        print(f"오류: 파일 '{path}'에 대한 읽기 권한이 없습니다")
        sys.exit(1)

유틸리티 스크립트 제공

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

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

• 생성된 코드보다 안정적
• 토큰 절약 (컨텍스트에 코드 포함 불필요)
• 시간 절약 (코드 생성 불필요)
• 사용 간 일관성 보장

스크립트 디렉토리 구조:

my-skill/
├── SKILL.md
└── scripts/
    ├── analyze_form.py
    ├── validate_data.py
    └── generate_report.py

SKILL.md에서 스크립트 참조:

# 양식 분석

1. `python scripts/analyze_form.py input.pdf`를 실행하여 필드 추출
2. 출력을 검토하여 모든 필드가 감지되었는지 확인

시각적 분석 사용

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

# PDF 양식 처리

1. `python scripts/pdf_to_images.py form.pdf`를 실행하여 이미지 생성
2. 생성된 이미지를 검토하여 양식 구조 이해
3. 감지된 필드를 기반으로 처리 계획 수립

검증 가능한 중간 출력 생성

Claude가 복잡하고 개방적인 작업을 수행할 때는 실수할 수 있습니다. "계획-검증-실행" 패턴은 오류를 조기에 잡습니다.

예시: PDF 양식 채우기

# 양식 업데이트 워크플로우

1. **분석**: `python scripts/analyze_form.py form.pdf`로 필드 추출
2. **계획 생성**: 업데이트를 `changes.json`에 작성
3. **검증**: `python scripts/validate_changes.py changes.json`로 계획 확인
4. **실행**: 검증 통과 시 `python scripts/apply_changes.py form.pdf changes.json`로 적용
5. **확인**: 출력 PDF를 검토하여 변경사항이 올바른지 확인

changes.json 예시:

{
  "updates": [
    {"field": "name", "value": "홍길동"},
    {"field": "email", "value": "hong@example.com"}
  ]
}

이 패턴이 작동하는 이유:

• 오류를 조기에 잡음: 검증이 변경 적용 전에 문제를 발견
• 기계 검증 가능: 스크립트가 객관적인 검증 제공
• 되돌릴 수 있는 계획: Claude가 원본을 건드리지 않고 계획을 반복할 수 있음
• 명확한 디버깅: 오류 메시지가 구체적인 문제를 지적

패키지 의존성

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

• claude.ai: npm 및 PyPI에서 패키지 설치 가능, GitHub 저장소에서 가져오기 가능
• Anthropic API: 네트워크 액세스 없음, 런타임 패키지 설치 불가

자세한 내용은 코드 실행 도구 문서를 참조하세요.

런타임 환경

스킬은 파일 시스템 액세스, bash 명령, 코드 실행 기능이 있는 코드 실행 환경에서 실행됩니다.

Claude가 스킬에 액세스하는 방법:

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

저작에 미치는 영향:

• 파일 경로 중요: Claude는 스킬 디렉토리를 파일 시스템처럼 탐색합니다. 슬래시(reference/guide.md) 사용, 백슬래시 사용 안 함
• 파일 이름을 설명적으로: 내용을 나타내는 이름 사용: form_validation_rules.md, doc2.md 안 됨
• 검색을 위한 구성: 도메인이나 기능별로 디렉토리 구조화
  • 좋은 예: reference/finance.md, reference/sales.md
  • 나쁜 예: docs/file1.md, docs/file2.md
• 포괄적인 리소스 번들: 완전한 API 문서, 광범위한 예시, 대용량 데이터셋 포함; 액세스할 때까지 컨텍스트 페널티 없음
• 결정론적 작업에는 스크립트 선호: 검증 코드를 생성하도록 요청하는 대신 validate_form.py 작성

MCP 도구 참조

스킬이 MCP(Model Context Protocol) 도구를 사용하는 경우, "도구를 찾을 수 없음" 오류를 방지하기 위해 항상 정규화된 도구 이름을 사용하세요.

형식: ServerName:tool_name

예시:

보고서를 생성하려면:
1. `BigQuery:bigquery_schema`를 호출하여 테이블 구조 가져오기
2. 쿼리 작성 및 실행
3. 문제가 있으면 `GitHub:create_issue`로 이슈 생성

패키지가 설치되어 있다고 가정하지 않기

패키지 가용성을 가정하지 마세요.

나쁜 예:

pandas로 데이터를 처리하세요.

좋은 예:

데이터를 처리하려면:
1. pandas 설치: `pip install pandas --break-system-packages`
2. 스크립트 실행: `python scripts/process.py`

---

기술적 참고사항

YAML 프론트매터 요구사항

SKILL.md 프론트매터에는 name(최대 64자)과 description(최대 1024자) 필드만 포함됩니다.

---
name: Processing PDFs
description: PDF 파일을 처리하고 텍스트와 테이블을 추출합니다
---

토큰 예산

최적의 성능을 위해 SKILL.md 본문을 500줄 미만으로 유지하세요. 콘텐츠가 이를 초과하는 경우, 앞서 설명한 점진적 공개 패턴을 사용하여 별도 파일로 분리하세요.

---

체크리스트

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

핵심 품질

• [ ] 설명이 구체적이고 핵심 용어를 포함
• [ ] 설명에 스킬의 기능과 사용 시기 모두 포함
• [ ] SKILL.md 본문이 500줄 미만
• [ ] 추가 세부사항은 별도 파일에 있음 (필요한 경우)
• [ ] 시간에 민감한 정보 없음
• [ ] 전체에 걸쳐 일관된 용어 사용
• [ ] 예시가 구체적이고 추상적이지 않음
• [ ] 파일 참조가 한 단계 깊이
• [ ] 점진적 공개를 적절하게 사용
• [ ] 워크플로우에 명확한 단계 있음

코드 및 스크립트

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

테스트

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

---

추가 리소스

• 스킬 개요
• 코드 실행 도구 문서
• 프롬프트 엔지니어링 가이드

---

결론

효과적인 스킬을 만드는 것은 반복적인 프로세스입니다. 작게 시작하고, 자주 테스트하고, Claude가 실제로 어떻게 사용하는지 관찰하면서 개선하세요. 가장 좋은 스킬은 명확하고, 간결하며, 실제 사용 사례를 기반으로 합니다.

핵심 기억 사항:

• 간결함이 핵심 - 모든 단어가 가치를 정당화해야 함
• 적절한 자유도 - 작업의 특성에 맞춰 구체성 조정
• 점진적 공개 - 필요할 때만 세부사항 제공
• 실제 테스트 - Claude와 함께 실제 작업으로 반복 개선