AI 에이전트 전문화 스킬을 위한 Claude Skills Framework 시스템 구축

스킬은 Claude의 기능을 특정 분야에 특화시키는 모듈형 패키지입니다.

일반적인 AI를 전문가로 변화시키는 "온보딩 가이드" 역할을 합니다.

스킬이 제공하는 것들

1. 전문화된 워크플로우: 특정 분야의 다단계 절차
2. 도구 통합: 특정 파일 형식이나 API 작업 방법
3. 도메인 전문성: 회사별 지식, 스키마, 비즈니스 로직
4. 번들 리소스: 복잡하고 반복적인 작업을 위한 스크립트, 참조자료, 자산

스킬의 구조

skill-name/
├── SKILL.md (필수)
│   ├── YAML 메타데이터 (필수)
│   │   ├── name: (필수)
│   │   └── description: (필수)
│   └── 마크다운 지침 (필수)
└── 번들 리소스 (선택)
    ├── scripts/          - 실행 가능한 코드
    ├── references/       - 참조 문서
    └── assets/           - 출력용 파일

SKILL.md (필수)

• 메타데이터 품질: YAML 프론트매터의 name과 description이 Claude가 언제 스킬을 사용할지 결정
• 작성 스타일: 3인칭 사용 ("이 스킬은 다음의 경우에 사용됩니다..." 형태)

번들 리소스 (선택사항)

Scripts (scripts/)

반복적으로 재작성되거나 결정론적 신뢰성이 필요한 실행 가능한 코드

 

언제 포함하는가

• 동일한 코드가 반복적으로 재작성될 때
• 결정론적 신뢰성이 필요할 때

예시

# scripts/rotate_pdf.py
import PyPDF2
import sys

def rotate_pdf(input_path, output_path, degrees):
    with open(input_path, 'rb') as file:
        pdf_reader = PyPDF2.PdfReader(file)
        pdf_writer = PyPDF2.PdfWriter()

        for page in pdf_reader.pages:
            rotated_page = page.rotate(degrees)
            pdf_writer.add_page(rotated_page)

        with open(output_path, 'wb') as output_file:
            pdf_writer.write(output_file)

if __name__ == "__main__":
    rotate_pdf(sys.argv[1], sys.argv[2], int(sys.argv[3]))

References (references/)

Claude가 작업 중 참조할 문서와 참조 자료

 

언제 포함하는가

• Claude가 작업하며 참조해야 할 문서가 있을 때
• 상세한 참조 자료가 필요할 때

예시

# references/api_docs.md
## 사용자 API 엔드포인트

### GET /api/users
사용자 목록을 반환합니다.

**파라미터:**
- `page`: 페이지 번호 (기본값: 1)
- `limit`: 페이지당 항목 수 (기본값: 10)

**응답:**
```json
{
  "users": [
    {"id": 1, "name": "홍길동", "email": "hong@example.com"}
  ],
  "total": 100,
  "page": 1
}

Assets (assets/)

최종 출력에 사용될 파일들 (컨텍스트에 로드되지 않음)

 

언제 포함하는가

• 최종 출력에 필요한 파일들이 있을 때

예시

assets/
├── logo.png              # 브랜드 로고
├── template.pptx          # 파워포인트 템플릿
├── frontend-template/     # HTML/React 보일러플레이트
│   ├── index.html
│   ├── style.css
│   └── script.js
└── font.ttf              # 폰트 파일

단계별 스킬 제작 과정

1단계: 구체적인 예시로 스킬 이해하기

목적: 스킬이 어떻게 사용될지 명확히 파악

질문 예시

• "이미지 편집 스킬은 어떤 기능을 지원해야 할까요? 편집, 회전 외에 다른 기능도 있나요?"
• "이 스킬이 어떻게 사용될지 구체적인 예시를 들어주세요"
• "'이 이미지의 적목 현상을 제거해주세요' 또는 '이 이미지를 회전시켜주세요' 같은 요청을 상상할 수 있는데, 다른 용도도 있을까요?"

실제 예시

사용자 요청: "PDF를 90도 회전시켜주세요"
사용자 요청: "이 이미지를 흑백으로 변환해주세요"
사용자 요청: "할 일 관리 웹앱을 만들어주세요"

2단계: 재사용 가능한 스킬 콘텐츠 계획하기

각 예시를 분석하여 필요한 리소스 파악

 

PDF 편집 스킬 예시

1. PDF 회전은 매번 동일한 코드 재작성 필요
2. scripts/rotate_pdf.py 스크립트가 도움될 것

프론트엔드 웹앱 빌더 스킬 예시

1. 웹앱 제작시 매번 동일한 보일러플레이트 필요
2. assets/hello-world/ 템플릿이 도움될 것

BigQuery 스킬 예시

1. 쿼리 작성시 매번 테이블 스키마 재발견 필요
2. references/schema.md 파일이 도움될 것

3단계: 스킬 초기화하기

스킬 생성 명령어

scripts/init_skill.py <스킬-이름> --path <출력-디렉토리>

예시

scripts/init_skill.py pdf-editor --path ./my-skills/

생성되는 구조

pdf-editor/
├── SKILL.md                    # 템플릿과 TODO 자리표시자
├── scripts/
│   └── example_script.py      # 예시 스크립트
├── references/
│   └── example_reference.md   # 예시 참조 문서
└── assets/
    └── example_asset.txt      # 예시 자산

4단계: 스킬 편집하기

SKILL.md 작성 가이드

작성 스타일: 명령형/부정사 형태 사용

• ✅ 좋은 예시: "X를 달성하려면 Y를 수행하세요"
• ❌ 나쁜 예시: "당신은 X를 해야 합니다" 또는 "X가 필요하면"

완성해야 할 내용

1. 스킬의 목적 (몇 문장으로)
2. 언제 사용해야 하는지
3. 실제로 Claude가 어떻게 사용해야 하는지

실제 SKILL.md 예시

---
name: pdf-editor
description: PDF 파일 편집, 회전, 병합, 분할 작업을 위한 스킬. PDF 조작 요청이 있을 때 사용됩니다.
---

# PDF 편집 스킬

이 스킬은 PDF 파일의 다양한 편집 작업을 효율적으로 수행하기 위한 도구와 워크플로우를 제공합니다.

## 언제 사용하는가

다음과 같은 요청이 있을 때 이 스킬을 사용하세요:
- PDF 페이지 회전
- PDF 파일 병합
- PDF 파일 분할
- PDF 메타데이터 수정

## 사용 방법

### PDF 회전
`scripts/rotate_pdf.py` 스크립트를 사용하여 PDF를 회전시킵니다:
```bash
python scripts/rotate_pdf.py input.pdf output.pdf 90
```

### 참조 자료
- `references/pdf_operations.md`: PDF 조작에 대한 상세 가이드
- `references/troubleshooting.md`: 일반적인 문제 해결 방법

## 워크플로우

1. 사용자 요청 파악
2. 적절한 스크립트 또는 라이브러리 선택
3. 필요시 참조 문서 확인
4. 작업 실행 및 결과 검증

References 파일 예시

# references/pdf_operations.md

## PDF 조작 가이드

### 회전 각도
- 90도: 시계방향 90도
- 180도: 180도 회전
- 270도: 시계방향 270도 (반시계방향 90도와 동일)

### 일반적인 오류
1. **파일을 찾을 수 없음**: 파일 경로 확인
2. **권한 오류**: 파일 읽기/쓰기 권한 확인
3. **손상된 PDF**: 원본 파일 무결성 검증

### 성능 최적화
- 큰 파일의 경우 메모리 사용량 모니터링
- 배치 처리시 임시 파일 정리

5단계: 스킬 패키징하기

패키징 명령어

scripts/package_skill.py <스킬-폴더-경로>

출력 디렉토리 지정

scripts/package_skill.py ./pdf-editor ./dist

자동 검증 항목

• YAML 프론트매터 형식 및 필수 필드
• 스킬 명명 규칙 및 디렉토리 구조
• 설명의 완성도와 품질
• 파일 구조 및 리소스 참조

성공시 생성: pdf-editor.zip 파일

6단계: 반복 개선하기

개선 워크플로우

1. 실제 작업에서 스킬 사용
2. 어려움이나 비효율성 발견
3. SKILL.md나 번들 리소스 개선 방안 식별
4. 변경사항 구현 및 재테스트

300x250

고급 스킬 제작 팁

프로그레시브 공개 설계 원칙

3단계 로딩 시스템 활용

1. 메타데이터 (이름 + 설명) - 항상 컨텍스트에 (~100단어)
2. SKILL.md 본문 - 스킬 트리거시 (<5k단어)
3. 번들 리소스 - Claude가 필요시 (무제한*)

효과적인 스킬 설계 원칙

1. 단일 책임 원칙

각 스킬은 하나의 명확한 목적을 가져야 합니다.

✅ 좋은 예: pdf-editor (PDF 편집 전문)
❌ 나쁜 예: document-processor (PDF, Word, Excel 모두 처리)

2. 재사용성 우선

반복적으로 사용될 수 있는 요소들을 식별하고 추상화합니다.

3. 문서화 우선주의

다른 Claude 인스턴스가 쉽게 이해하고 사용할 수 있도록 명확히 문서화합니다.

실제 사용 사례별 스킬 예시

1. 데이터 분석 스킬

data-analyzer/
├── SKILL.md
├── scripts/
│   ├── clean_data.py
│   ├── generate_report.py
│   └── visualize.py
├── references/
│   ├── data_schemas.md
│   └── analysis_patterns.md
└── assets/
    ├── report_template.html
    └── chart_styles.css

2. 웹 개발 스킬

webapp-builder/
├── SKILL.md
├── scripts/
│   └── setup_project.sh
├── references/
│   ├── best_practices.md
│   └── security_guidelines.md
└── assets/
    ├── templates/
    │   ├── react-starter/
    │   └── vanilla-js/
    └── components/
        ├── header.jsx
        └── footer.jsx

3. 보안 감사 스킬

security-auditor/
├── SKILL.md
├── scripts/
│   ├── scan_vulnerabilities.py
│   ├── check_compliance.py
│   └── generate_audit_report.py
├── references/
│   ├── owasp_guidelines.md
│   ├── compliance_frameworks.md
│   └── vulnerability_database.md
└── assets/
    └── report_templates/
        ├── executive_summary.docx
        └── technical_details.xlsx

이러한 체계적인 접근을 통해 효과적이고 재사용 가능한 스킬을 제작할 수 있습니다. 각 단계를 차근차근 따라가며 사용자의 구체적인 요구사항에 맞는 전문화된 스킬을 만들어보세요.