skill-creator

Original source / Raw SKILL.md

---
name: skill-creator
description: "**SKILL CREATOR v2.0** - '스킬 만들어', 'skill 만들어', '새 스킬', 'create skill' 요청 시 자동 발동. Anthropic 공식 베스트 프랙티스 기반 프로덕션급 스킬 생성. Progressive Disclosure, 토큰 최적화, 평가 기반 개발 지원."
allowed-tools:
  - Read
  - Write
  - Bash
  - Glob
---

# Skill Creator v2.0 - Production-Ready Skill Builder

> **Based on**: [Anthropic Official Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)

---

## Quick Start - 5분 안에 스킬 만들기

### Step 1: 스킬 폴더 생성

```bash
SKILL_NAME="my-new-skill"
mkdir -p ~/.claude/skills/$SKILL_NAME
```

### Step 2: SKILL.md 작성

```markdown
---
name: my-new-skill
description: "Does X when user asks for Y. Triggers on 'keyword1', 'keyword2'."
allowed-tools:
  - Read
  - Write
---

# My New Skill

## Quick start
[핵심 사용법]

## Detailed guide
See [reference.md](reference.md) for complete documentation.
```

### Step 3: 검증 & 동기화

```bash
# 검증
python ~/.claude/skills/skill-creator/scripts/validate_skill.py ~/.claude/skills/$SKILL_NAME

# WSL 동기화 (Windows 환경)
bash ~/.claude/skills/skill-creator/scripts/sync_skills.sh $SKILL_NAME
```

---

## Core Principles (핵심 원칙)

### 1. Progressive Disclosure (점진적 공개)

**스킬은 매뉴얼처럼 작동합니다** - 목차 → 장 → 상세 부록 순서로 필요할 때만 로드

```
Level 1: name + description (시작 시 시스템 프롬프트에 로드, ~100 토큰)
Level 2: SKILL.md 전체 (관련성 판단 시 로드, <5k 토큰)
Level 3: 참조 파일들 (필요 시에만 개별 로드)
```

**실전 적용:**
- SKILL.md는 500줄 이하 유지
- 상세 내용은 `reference/`, `examples/`로 분리
- 한 단계만 깊게 참조 (SKILL.md → file.md ✓, file.md → nested.md ✗)

### 2. Concise is Key (간결함이 핵심)

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

```markdown
# ✅ Good (50 tokens)
## PDF 텍스트 추출
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

# ❌ Bad (150 tokens)
## PDF 텍스트 추출
PDF(Portable Document Format)는 텍스트, 이미지 등을 포함하는 파일 형식입니다.
PDF에서 텍스트를 추출하려면 라이브러리가 필요합니다...
```

**자문하기:**
- "Claude가 정말 이 설명이 필요한가?"
- "이 단락이 토큰 비용을 정당화하는가?"

### 3. Degrees of Freedom (자유도 설정)

| 자유도 | 사용 시점 | 예시 |
|--------|----------|------|
| **High** | 여러 접근법 유효, 컨텍스트 의존 | 코드 리뷰, 분석 |
| **Medium** | 선호 패턴 있지만 변형 허용 | 템플릿 + 파라미터 |
| **Low** | 순서 중요, 실패 시 치명적 | DB 마이그레이션, API 키 |

---

## YAML Frontmatter 규칙

### 필수 필드만 사용

```yaml
---
name: skill-name           # 64자 이하, 소문자+숫자+하이픈만
description: "..."         # 1024자 이하, 비어있으면 안 됨
allowed-tools:             # (선택) 사용할 도구 제한
  - Read
  - Write
---
```

### Name 규칙 - Gerund Form 권장

```yaml
# ✅ 권장 (동명사형)
name: processing-pdfs
name: analyzing-data
name: testing-code

# ✓ 허용
name: pdf-processing
name: data-analyzer

# ❌ 피하기
name: helper           # 너무 모호
name: utils            # 너무 일반적
name: claude-tools     # 예약어 포함
```

### Description 규칙 - 3인칭 필수

```yaml
# ✅ 올바름 (3인칭)
description: "Processes Excel files and generates reports. Use when working with .xlsx files."

# ❌ 피하기 (1인칭/2인칭)
description: "I can help you process Excel files"
description: "You can use this to process Excel"
```

**필수 포함 요소:**
1. **무엇을 하는지** (What)
2. **언제 사용하는지** (When)
3. **트리거 키워드** (Keywords)

```yaml
# 예시
description: "Extracts text and tables from PDF files, fills forms. Use when working with PDFs or document extraction."
```

### YAML 콜론 금지

```yaml
# ❌ 파싱 오류!
description: "**SKILL v1.0**: 설명..."

# ✅ 하이픈으로 대체
description: "**SKILL v1.0** - 설명..."
```

---

## 디렉토리 구조 패턴

### Pattern 1: Simple Skill (단순)

```
my-skill/
└── SKILL.md
```

### Pattern 2: With References (참조 포함)

```
my-skill/
├── SKILL.md              # 개요 + 빠른 시작
├── reference.md          # 상세 API/가이드
└── examples.md           # 사용 예제
```

### Pattern 3: Domain-Specific (도메인별)

```
bigquery-skill/
├── SKILL.md
└── reference/
    ├── finance.md        # 재무 메트릭
    ├── sales.md          # 영업 파이프라인
    └── product.md        # 제품 분석
```

### Pattern 4: With Scripts (스크립트 포함)

```
pdf-skill/
├── SKILL.md
├── FORMS.md
├── reference.md
└── scripts/
    ├── analyze_form.py   # 실행용 (컨텍스트 미소비)
    ├── fill_form.py
    └── validate.py
```

---

## 워크플로우 & 피드백 루프

### 체크리스트 패턴

```markdown
## 작업 진행 상황

이 체크리스트를 복사하여 진행 추적:

Progress:
- [ ] Step 1: 소스 파일 읽기
- [ ] Step 2: 검증 실행
- [ ] Step 3: 변환 적용
- [ ] Step 4: 결과 확인
```

### 피드백 루프 패턴

```markdown
## 문서 편집 프로세스

1. document.xml 수정
2. **즉시 검증**: python scripts/validate.py
3. 검증 실패 시:
   - 오류 메시지 확인
   - 문제 수정
   - 다시 검증
4. **검증 통과 시에만 진행**
5. 빌드: python scripts/build.py
```

---

## 예제 패턴 (Input/Output)

```markdown
## 커밋 메시지 형식

다음 예제를 따라 작성:

**Example 1:**
Input: 사용자 인증에 JWT 토큰 추가
Output: feat(auth): JWT 기반 인증 구현 - 로그인 엔드포인트와 토큰 검증 미들웨어 추가

**Example 2:**
Input: 리포트에서 날짜가 잘못 표시되는 버그 수정
Output: fix(reports): 타임존 변환 시 날짜 포맷 수정 - UTC 타임스탬프를 일관되게 사용
```

---

## 안티패턴 (피해야 할 것)

| 안티패턴 | 문제 | 해결 |
|----------|------|------|
| Windows 경로 | Unix에서 오류 | scripts\file.py → scripts/file.py |
| 너무 많은 옵션 | 혼란 | 기본값 제시 + 대안 1개 |
| 깊은 참조 체인 | 불완전 로드 | 1단계만 참조 |
| 시간 의존 정보 | 구식화 | "Old patterns" 섹션 사용 |
| 모호한 이름 | 발견 어려움 | 구체적 키워드 포함 |

---

## 평가 기반 개발 (권장)

### 1. 갭 파악
스킬 없이 Claude 실행 → 어디서 실패하는지 관찰

### 2. 평가 생성
```json
{
  "skills": ["my-skill"],
  "query": "PDF에서 텍스트 추출해서 output.txt에 저장",
  "expected_behavior": [
    "PDF 라이브러리로 파일 읽기",
    "모든 페이지에서 텍스트 추출",
    "output.txt에 저장"
  ]
}
```

### 3. 최소 지침 작성
갭을 해결할 만큼만 작성

### 4. 반복
평가 실행 → 결과 비교 → 개선

---

## Claude와 함께 스킬 개발

### 권장 워크플로우

1. **Claude A와 작업** - 스킬 없이 문제 해결
2. **패턴 식별** - 반복 제공한 컨텍스트 파악
3. **Claude에게 스킬 생성 요청**
   > "방금 사용한 BigQuery 분석 패턴으로 스킬 만들어줘"
4. **간결성 검토** - 불필요한 설명 제거 요청
5. **Claude B로 테스트** - 새 인스턴스에서 스킬 사용
6. **관찰 → 개선** 반복

---

## 스킬 유효성 체크리스트

### 핵심 품질
- [ ] description이 구체적이고 키워드 포함
- [ ] description이 "무엇을" + "언제" 모두 포함
- [ ] SKILL.md 500줄 이하
- [ ] 상세 내용은 별도 파일로 분리
- [ ] 시간 의존 정보 없음
- [ ] 일관된 용어 사용
- [ ] 파일 참조는 1단계만
- [ ] 3인칭으로 작성

### 코드 & 스크립트
- [ ] 스크립트가 에러를 직접 처리 (Claude에 위임 X)
- [ ] 매직 넘버 없음 (모든 값에 이유 설명)
- [ ] 필요 패키지 목록화
- [ ] Windows 경로 없음 (모두 / 사용)
- [ ] 검증/확인 단계 포함

### 테스트
- [ ] 최소 3개 평가 시나리오 생성
- [ ] Haiku, Sonnet, Opus에서 테스트
- [ ] 실제 사용 시나리오로 테스트

---

## 참조 문서

| 파일 | 설명 |
|------|------|
| [references/description-patterns.md](references/description-patterns.md) | Description 작성 패턴 & 예제 |
| [references/structure-patterns.md](references/structure-patterns.md) | 구조화 패턴 상세 |
| [references/scripts-guide.md](references/scripts-guide.md) | 스크립트 작성 가이드 |
| [references/anti-patterns.md](references/anti-patterns.md) | 피해야 할 패턴 상세 |
| [templates/simple-skill.md](templates/simple-skill.md) | 단순 스킬 템플릿 |
| [templates/code-skill.md](templates/code-skill.md) | 코드 포함 스킬 템플릿 |

---

## 환경별 경로 (Windows/WSL)

| 환경 | Skills 경로 |
|------|-------------|
| Git Bash | ~/.claude/skills/ = /c/Users/lpian/.claude/skills/ |
| WSL Ubuntu | ~/.claude/skills/ = /home/elon/.claude/skills/ |
| WSL에서 Windows | /mnt/c/Users/lpian/.claude/skills/ |

**동기화 필수**: 두 환경의 ~/.claude/skills/는 서로 다른 디렉토리!

```bash
# Windows → WSL 동기화
bash ~/.claude/skills/skill-creator/scripts/sync_skills.sh [skill-name]
```

---

**Version**: 2.0.0 | **Updated**: 2025-12-11
**Sources**: Anthropic Docs, Engineering Blog


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/description-patterns.md

```markdown
# Description 작성 패턴 & 예제

> Description은 스킬 발견의 핵심입니다. Claude가 100개 이상의 스킬 중에서 선택할 때 사용합니다.

---

## 필수 규칙

### 1. 3인칭 사용 (시스템 프롬프트에 주입됨)

```yaml
# ✅ 올바름
description: "Processes Excel files and generates reports"
description: "Analyzes code for security vulnerabilities"

# ❌ 피하기
description: "I can help you process Excel files"
description: "You can use this to analyze code"
```

### 2. What + When 포함

```yaml
# ✅ 완전함
description: "Extracts text from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."

# ❌ 불완전함
description: "Helps with documents"
description: "Processes data"
```

### 3. 1024자 이하, XML 태그 금지

---

## 도메인별 패턴

### 문서 처리

```yaml
# PDF
description: "Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."

# Excel
description: "Analyzes Excel spreadsheets, creates pivot tables, generates charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files."

# HWP
description: "Reads and modifies HWP/HWPX files, replaces text patterns. Use when working with Korean Hangul documents or .hwp files."
```

### 개발 도구

```yaml
# Git
description: "Generates descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes."

# Code Review
description: "Reviews code for quality, security, and best practices. Use when analyzing code, checking for bugs, or improving code quality."

# Testing
description: "Generates unit tests and integration tests for code. Use when creating tests, improving coverage, or implementing TDD."
```

### 데이터 분석

```yaml
# SQL/BigQuery
description: "Writes and optimizes SQL queries for BigQuery. Use when working with BigQuery, writing SQL, or analyzing large datasets."

# Data Visualization
description: "Creates charts and visualizations from data. Use when visualizing data, creating dashboards, or generating reports with charts."
```

---

## 키워드 포함 전략

### 패턴: 동작 + 대상 + 트리거

```yaml
# 구조
description: "[동작들]. Use when [트리거 조건] or when [사용자 언급 키워드]."

# 예시
description: "Converts Markdown to HTML, PPTX, PDF. Use when converting documents or when the user mentions markdown, slides, or presentations."
```

### 한국어 + 영어 혼합 (한국 사용자용)

```yaml
description: "**CODE REVIEWER** - '리뷰해', '검토해', '피드백', 'review', 'check' 요청 시 자동 발동. Quality Gate, Code Smell, 복잡도 분석 제공."
```

---

## 피해야 할 패턴

| 패턴 | 문제 | 개선 |
|------|------|------|
| "Helps with X" | 모호함 | "Processes X, generates Y" |
| "A tool for..." | 수동적 | 직접 동작 서술 |
| 기능만 나열 | When 누락 | "Use when..." 추가 |
| 너무 김 | 핵심 희석 | 주요 기능 3-4개만 |

---

## 실전 예제

### Before/After

```yaml
# ❌ Before
description: "This is a skill that helps users with their PDF documents by providing various functionalities for processing and manipulating PDF files."

# ✅ After
description: "Extracts text from PDFs, fills forms, merges documents. Use when working with PDF files or document extraction."
```

```yaml
# ❌ Before
description: "Code review tool"

# ✅ After
description: "Reviews code for bugs, security issues, and best practices. Provides quality scores and improvement suggestions. Use when reviewing code or checking code quality."
```

```

### references/structure-patterns.md

```markdown
# 구조화 패턴 상세 가이드

> 스킬의 구조는 Progressive Disclosure를 지원해야 합니다.

---

## Pattern 1: High-Level Guide with References

**용도**: 다양한 기능이 있는 스킬

```markdown
---
name: pdf-processing
description: "Extracts text from PDFs, fills forms. Use when working with PDFs."
---

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

**핵심**: SKILL.md는 빠른 시작, 상세는 별도 파일

---

## Pattern 2: Domain-Specific Organization

**용도**: 여러 도메인을 다루는 스킬 (토큰 효율화)

```
bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
    ├── finance.md (revenue, billing)
    ├── sales.md (pipeline, accounts)
    ├── product.md (API usage, features)
    └── marketing.md (campaigns)
```

```markdown
# BigQuery Data Analysis

## Available datasets

**Finance**: Revenue, ARR, billing → See [reference/finance.md](reference/finance.md)
**Sales**: Opportunities, pipeline → See [reference/sales.md](reference/sales.md)
**Product**: API usage, features → See [reference/product.md](reference/product.md)
**Marketing**: Campaigns, email → See [reference/marketing.md](reference/marketing.md)

## Quick search

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

**핵심**: 사용자가 sales를 묻으면 sales.md만 로드됨

---

## Pattern 3: Conditional Details

**용도**: 기본 vs 고급 사용자

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

**핵심**: 고급 기능은 필요할 때만 로드

---

## Pattern 4: With Executable Scripts

**용도**: 결정론적 작업이 필요한 스킬

```
pdf-skill/
├── SKILL.md
├── FORMS.md
├── reference.md
└── scripts/
    ├── analyze_form.py
    ├── fill_form.py
    └── validate.py
```

```markdown
# PDF Form Processing

## Utility scripts

**analyze_form.py**: Extract form fields

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

**fill_form.py**: Apply values to form

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

**validate.py**: Check field mapping

```bash
python scripts/validate.py fields.json
```
```

**핵심**: 스크립트는 실행만 함 (컨텍스트 미소비)

---

## 참조 깊이 규칙

### ✅ 올바름: 1단계 참조

```
SKILL.md
├── → reference.md     (직접 참조)
├── → examples.md      (직접 참조)
└── → templates/       (직접 참조)
```

### ❌ 피하기: 깊은 참조

```
SKILL.md
└── → advanced.md
    └── → details.md       (2단계 - 불완전 로드!)
        └── → nested.md    (3단계 - 거의 로드 안 됨)
```

---

## 긴 참조 파일 구조

100줄 이상 파일은 목차 포함:

```markdown
# 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
...
```

---

## 파일 명명 규칙

```yaml
권장:
  - form_validation_rules.md    # 내용 설명
  - api_reference.md
  - common_examples.md

피하기:
  - doc1.md                     # 내용 불명
  - file2.md
  - temp.md
```

```

### references/scripts-guide.md

```markdown
# 스크립트 작성 가이드

> 스크립트는 Claude가 컨텍스트에 로드하지 않고 직접 실행합니다.

---

## 핵심 원칙: Solve, Don't Punt

**문제를 직접 해결하고, Claude에게 떠넘기지 마세요**

```python
# ✅ Good - 에러를 직접 처리
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 ''

# ❌ Bad - 에러를 Claude에게 떠넘김
def process_file(path):
    return open(path).read()  # 실패하면 Claude가 알아서 해결?
```

---

## 매직 넘버 금지

모든 상수에 이유를 설명하세요:

```python
# ✅ Good - 자체 문서화
# HTTP 요청은 보통 30초 내 완료됨
# 느린 연결을 고려한 타임아웃
REQUEST_TIMEOUT = 30

# 3회 재시도는 신뢰성과 속도의 균형점
# 대부분 간헐적 오류는 2번째에 해결됨
MAX_RETRIES = 3

# ❌ Bad - 매직 넘버
TIMEOUT = 47  # 왜 47?
RETRIES = 5   # 왜 5?
```

---

## 스크립트 문서화

```python
#!/usr/bin/env python3
"""
analyze_form.py - PDF 폼 필드 추출

Usage:
    python analyze_form.py input.pdf > fields.json

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

Dependencies:
    pip install pypdf
"""

import sys
import json
from pypdf import PdfReader

def main():
    if len(sys.argv) != 2:
        print("Usage: python analyze_form.py input.pdf", file=sys.stderr)
        sys.exit(1)
    
    pdf_path = sys.argv[1]
    # ... 구현 ...

if __name__ == "__main__":
    main()
```

---

## 검증 스크립트 패턴

```python
#!/usr/bin/env python3
"""validate_fields.py - 필드 매핑 검증"""

import sys
import json

def validate(fields_path):
    with open(fields_path) as f:
        fields = json.load(f)
    
    errors = []
    warnings = []
    
    # 필수 필드 확인
    required = ["name", "date", "signature"]
    for field in required:
        if field not in fields:
            errors.append(f"Missing required field: {field}")
    
    # 타입 확인
    for name, props in fields.items():
        if "type" not in props:
            warnings.append(f"No type for field: {name}")
    
    # 결과 출력
    if errors:
        print("ERRORS:")
        for e in errors:
            print(f"  - {e}")
        sys.exit(1)
    
    if warnings:
        print("WARNINGS:")
        for w in warnings:
            print(f"  - {w}")
    
    print("OK")
    sys.exit(0)

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("Usage: python validate_fields.py fields.json")
        sys.exit(1)
    validate(sys.argv[1])
```

---

## 실행 vs 참조 명확화

SKILL.md에서 의도를 명확히:

```markdown
# 실행하도록 지시
Run `python scripts/analyze_form.py` to extract fields

# 참조하도록 지시
See `scripts/analyze_form.py` for the extraction algorithm
```

대부분의 경우 **실행**이 더 효율적 (토큰 절약)

---

## 의존성 명시

```markdown
## Requirements

Install before using:
```bash
pip install pypdf pdfplumber
```

Or add to requirements.txt:
```
pypdf>=4.0.0
pdfplumber>=0.9.0
```
```

---

## 에러 메시지 상세화

Claude가 수정할 수 있도록 구체적으로:

```python
# ✅ Good - 구체적 에러
if field not in available_fields:
    print(f"Field '{field}' not found. Available: {', '.join(available_fields)}")

# ❌ Bad - 모호한 에러
if field not in available_fields:
    print("Field not found")
```

---

## 크로스 플랫폼 호환

```python
import os
from pathlib import Path

# ✅ Good - pathlib 사용
file_path = Path("scripts") / "helper.py"

# ❌ Bad - 하드코딩 경로
file_path = "scripts\helper.py"  # Windows only!
```

```

### references/anti-patterns.md

```markdown
# 피해야 할 패턴 (Anti-Patterns)

> 스킬 작성 시 흔히 하는 실수와 해결법

---

## 1. Windows 경로 사용

```yaml
# ❌ 피하기
scripts\helper.py
reference\guide.md

# ✅ 올바름 (모든 플랫폼 호환)
scripts/helper.py
reference/guide.md
```

**이유**: Windows 백슬래시는 Unix에서 오류 발생

---

## 2. 너무 많은 옵션 제시

```markdown
# ❌ 피하기 - 혼란
"You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or..."

# ✅ 올바름 - 기본값 + 대안
"Use pdfplumber for text extraction:
```python
import pdfplumber
```

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

**이유**: Claude가 결정하기 어려움

---

## 3. 깊은 참조 체인

```markdown
# ❌ 피하기 - 불완전 로드
SKILL.md → advanced.md → details.md → nested.md

# ✅ 올바름 - 1단계 참조만
SKILL.md
├── → reference.md
├── → examples.md
└── → templates/
```

**이유**: 2단계 이상은 `head -100`으로만 읽힐 수 있음

---

## 4. 시간 의존 정보

```markdown
# ❌ 피하기 - 구식화됨
"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>
```

---

## 5. 모호한 이름

```yaml
# ❌ 피하기
name: helper
name: utils
name: tools
name: stuff

# ✅ 올바름
name: processing-pdfs
name: analyzing-code
name: generating-tests
```

**이유**: 발견이 어려움

---

## 6. 과도한 설명

```markdown
# ❌ 피하기 - 150 토큰
## PDF 텍스트 추출
PDF(Portable Document Format)는 텍스트, 이미지 등을 포함하는 파일 형식입니다.
PDF에서 텍스트를 추출하려면 라이브러리가 필요합니다.
pdfplumber를 추천합니다. 설치 방법은...

# ✅ 올바름 - 50 토큰
## PDF 텍스트 추출
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```
```

**이유**: Claude는 이미 PDF가 뭔지 앎

---

## 7. 1인칭/2인칭 Description

```yaml
# ❌ 피하기
description: "I can help you process Excel files"
description: "You can use this to analyze code"

# ✅ 올바름 (3인칭)
description: "Processes Excel files and generates reports"
description: "Analyzes code for security vulnerabilities"
```

**이유**: 시스템 프롬프트에 주입됨

---

## 8. 일관성 없는 용어

```markdown
# ❌ 피하기 - 혼란
- "API endpoint" / "URL" / "API route" / "path"
- "field" / "box" / "element" / "control"
- "extract" / "pull" / "get" / "retrieve"

# ✅ 올바름 - 일관성
- 항상 "API endpoint"
- 항상 "field"
- 항상 "extract"
```

---

## 9. 에러를 Claude에게 떠넘기기

```python
# ❌ 피하기
def process_file(path):
    return open(path).read()  # 실패하면?

# ✅ 올바름
def process_file(path):
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        print(f"File {path} not found, creating default")
        return ''
```

---

## 10. 패키지 가정

```markdown
# ❌ 피하기
"Use the pdf library to process the file."

# ✅ 올바름
"Install required package:
```bash
pip install pypdf
```

Then use it:
```python
from pypdf import PdfReader
```"
```

---

## 11. YAML 콜론 사용

```yaml
# ❌ 파싱 오류!
description: "**SKILL v1.0**: 설명..."

# ✅ 하이픈으로 대체
description: "**SKILL v1.0** - 설명..."
```

---

## 12. CRLF 줄바꿈 (Windows)

```bash
# 문제 확인
file SKILL.md
# CRLF가 보이면 변환 필요

# 해결
sed -i 's/\r$//' SKILL.md
# 또는
dos2unix SKILL.md
```

---

## 체크리스트

작성 후 확인:

- [ ] Windows 경로 없음 (모두 `/`)
- [ ] 옵션은 기본값 + 대안 1개만
- [ ] 참조는 1단계만
- [ ] 시간 의존 정보 없음
- [ ] 이름이 구체적
- [ ] 설명이 간결
- [ ] 3인칭 사용
- [ ] 용어 일관성
- [ ] 에러 직접 처리
- [ ] 패키지 명시
- [ ] YAML 콜론 없음
- [ ] LF 줄바꿈

```

### templates/simple-skill.md

```markdown
# Simple Skill Template

코드 없이 지침만 제공하는 단순 스킬용

---

## SKILL.md 예시

```markdown
---
name: writing-commit-messages
description: "Generates descriptive commit messages from git diffs. Use when writing commits or reviewing staged changes."
allowed-tools:
  - Bash
  - Read
---

# Commit Message Generator

## Quick start

1. Stage your changes: `git add .`
2. Review diff: `git diff --staged`
3. Generate message following the format below

## Message format

```
type(scope): brief description

Detailed explanation of changes
```

**Types**: feat, fix, docs, style, refactor, test, chore

## Examples

**Input**: Added user authentication with JWT
**Output**:
```
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware
```

**Input**: Fixed date display bug in reports
**Output**:
```
fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation
```

## Guidelines

- First line: 50 chars max
- Body: 72 chars per line
- Use imperative mood ("Add" not "Added")
- Explain why, not just what
```

---

## 핵심 포인트

1. **Quick start**: 핵심 사용법 바로 보여주기
2. **Format**: 기대하는 형식 명확히
3. **Examples**: Input/Output 쌍으로 제시
4. **Guidelines**: 간결한 규칙

```

### templates/code-skill.md

```markdown
# Code Skill Template

스크립트를 포함하는 스킬용

---

## 디렉토리 구조

```
my-code-skill/
├── SKILL.md
├── reference.md
└── scripts/
    ├── analyze.py
    ├── process.py
    └── validate.py
```

---

## SKILL.md 예시

```markdown
---
name: processing-pdfs
description: "Extracts text from PDFs, fills forms, merges documents. Use when working with PDF files or document extraction."
allowed-tools:
  - Bash
  - Read
  - Write
---

# PDF Processing

## Quick start

Extract text:
```bash
python scripts/extract_text.py input.pdf > output.txt
```

## Workflow

Copy this checklist:
```
Progress:
- [ ] Step 1: Analyze PDF structure
- [ ] Step 2: Extract content
- [ ] Step 3: Validate output
```

### Step 1: Analyze PDF

```bash
python scripts/analyze.py input.pdf
```

Output shows page count, form fields, and structure.

### Step 2: Extract content

```bash
python scripts/extract_text.py input.pdf > output.txt
```

### Step 3: Validate

```bash
python scripts/validate.py output.txt
```

Fix any issues before proceeding.

## Scripts reference

| Script | Purpose |
|--------|---------|
| analyze.py | PDF 구조 분석 |
| extract_text.py | 텍스트 추출 |
| fill_form.py | 폼 필드 채우기 |
| validate.py | 결과 검증 |

For detailed API: See [reference.md](reference.md)

## Dependencies

```bash
pip install pypdf pdfplumber
```
```

---

## scripts/analyze.py 예시

```python
#!/usr/bin/env python3
"""
analyze.py - PDF 구조 분석

Usage:
    python analyze.py input.pdf

Output:
    - Page count
    - Form fields
    - Text/image ratio
"""

import sys
import json
from pypdf import PdfReader

def main():
    if len(sys.argv) != 2:
        print("Usage: python analyze.py input.pdf", file=sys.stderr)
        sys.exit(1)
    
    pdf_path = sys.argv[1]
    
    try:
        reader = PdfReader(pdf_path)
    except Exception as e:
        print(f"Error reading PDF: {e}", file=sys.stderr)
        sys.exit(1)
    
    result = {
        "page_count": len(reader.pages),
        "form_fields": [],
        "has_text": False
    }
    
    # Form fields
    if reader.get_form_text_fields():
        result["form_fields"] = list(reader.get_form_text_fields().keys())
    
    # Check for text
    for page in reader.pages:
        if page.extract_text().strip():
            result["has_text"] = True
            break
    
    print(json.dumps(result, indent=2))

if __name__ == "__main__":
    main()
```

---

## 핵심 포인트

1. **워크플로우 체크리스트**: 진행 추적
2. **피드백 루프**: 검증 → 수정 → 재검증
3. **스크립트 문서화**: Usage, Output 명시
4. **에러 직접 처리**: Claude에 떠넘기지 않기
5. **의존성 명시**: pip install 명령 포함

```