2.4 Agent Skills

정의

프롬프트 엔지니어링 vs. 컨텍스트 엔지니어링

• 프롬프트 엔지니어링: 효과적인 지시사항을 작성하는 기술. 정적 컨텍스트
• 컨텍스트 엔지니어링: 모델에게 무엇을 보여주고 보여주지 않을지 결정하는 기술. 동적 컨텍스트

시스템 프롬프트(CLAUDE.md) vs. Skills

Skills 예시

SKILL.md 예시: email-composer

---
name: email-composer
description: 사용자의 어조와 스타일에 맞춰 전문적인 이메일을 작성합니다. 비즈니스 커뮤니케이션에 최적화.
---

# Email Composer Skill

## 목적 및 페르소나
당신은 사용자의 개인 비서로서, 사용자의 지시에 따라 전문적이고 효과적인 이메일을 작성합니다.

## 워크플로우
1. **정보 수집**: 목적, 수신자, 관계, 어조, 핵심 메시지 등을 질문해 수집
2. **초안 작성**: 간결한 제목 → 명확한 서론 → 핵심 메시지 → CTA → 마무리
3. **검토**: 수동태 최소화 / 군더더기 제거 / `references/brand_voice.md` 준수

## 제약 사항
- 문단은 2~3문장 이내로
- 기업용 전문 용어(corporate speak) 금지

## 금지 문구
- "I hope this finds you well"
- "Just circling back"

보고서 작성 스킬

고객 응대 스킬

name/description 규칙

• name: 소문자, 숫자, 하이픈만 사용, 최대 64자
• description: 최대 1024자. "무엇을 하는가" + "언제 쓰는가" 두 가지를 반드시 포함 → Claude가 스킬을 선택하는 핵심 기준
• 명명 규칙: 동명사 형태 권장 (content-writing, code-reviewing)

작동 원리: 점진적 공개 (Progressive Disclosure)

도서관 비유: Claude는 책을 한꺼번에 다 읽지 않습니다.

• Level 1: 도서 목록 확인 (메타데이터 로드)
  시스템 시작 시 모든 Skills의 name과 description만 미리 로드 (~100토큰). 어떤 스킬이 관련 있는지 빠르게 판단합니다.
• Level 2: 목차/서문 읽기 (SKILL.md 본문 로드)
  관련성이 높다고 판단되면 SKILL.md 전체를 컨텍스트에 로드 (최대 ~5,000토큰). 핵심 지침/단계/고려사항을 포함합니다.
• Level 3: 특정 장 펼치기 (추가 파일/스크립트 로드)
  scripts/, references/, templates/ 내 파일은 Claude가 실제로 필요하다고 판단할 때만 로드합니다.

Skills 구조

저장 위치

폴더 구조

my-skill/
    ├── SKILL.md          # 메타데이터(YAML) + 핵심 지침  ← 필수
    ├── reference.md      # 추가 문서 (선택)
    ├── examples.md       # 예시 모음 (선택)
    ├── scripts/          # 실행 가능한 코드 (Python, Bash 등)
    │   └── helper.py
    └── templates/        # 출력 형식 정의 파일 (JSON, Markdown 등)
        └── template.txt

• SKILL.md: 스킬의 두뇌. 목적/페르소나/단계별 워크플로우/제약사항/입출력 형식 정의
• 추가 파일들은 SKILL.md에서 링크로 참조 → Claude가 필요할 때만 로드 (점진적 공개)
• 길이 관리: SKILL.md가 500줄에 가까워지면 여러 파일로 분할

allowed-tools로 도구 접근 제한

---
name: safe-code-reviewer
description: 코드를 읽기 전용으로 리뷰합니다. 파일 수정 없이 코드 품질을 검토할 때 사용.
allowed-tools: Read, Grep, Glob
---

# Safe Code Reviewer
파일을 읽고 분석만 합니다. 어떤 파일도 수정하지 않습니다.

• 스킬이 활성화된 동안 Claude가 사용할 수 있는 도구를 명시적으로 제한
• 지정된 도구는 별도 권한 요청 없이 바로 사용 가능
• 지정하지 않으면 기존 권한 모델대로 매번 허가 요청
• 활용 시나리오: 읽기 전용 분석 스킬 / 보안 민감 워크플로우 / 범위 제한이 필요한 작업

SKILL.md 실전 예시 3종

---
name: generating-commit-messages
description: git diff를 보고 명확한 커밋 메시지를 생성합니다. 커밋 작성이나 staged 변경사항 검토 시 사용.
---

# Generating Commit Messages

## Instructions
1. `git diff --staged`로 변경사항 확인
2. 커밋 메시지 제안:
   - 50자 이내 요약
   - 상세 설명
   - 영향받은 컴포넌트

## Best practices
- 현재 시제 사용
- what/why를 설명, how는 생략

---
name: code-reviewer
description: 코드 품질·보안·구조를 리뷰합니다. PR 검토, 코드 품질 분석 시 사용.
allowed-tools: Read, Grep, Glob
---

# Code Reviewer

## Review checklist
1. 코드 구조 및 구성
2. 에러 핸들링
3. 성능 고려사항
4. 보안 취약점
5. 테스트 커버리지

pdf-processing/
        ├── SKILL.md
        ├── FORMS.md       ← 양식 작성 전용 문서
        ├── REFERENCE.md   ← API 레퍼런스
        └── scripts/
            ├── fill_form.py
            └── validate.py

---
name: pdf-processing
description: PDF 텍스트 추출, 양식 작성, 병합. PDF 파일·양식·문서 추출 작업 시 사용. pypdf, pdfplumber 패키지 필요.
---

# PDF Processing

## Quick start
텍스트 추출은 바로 실행 가능.
양식 작성은 [FORMS.md](FORMS.md) 참조.
상세 API는 [REFERENCE.md](REFERENCE.md) 참조.

## Requirements
pip install pypdf pdfplumber

MASTER 프레임워크 (Skills 개발 6단계)

Skills 트러블슈팅

claude --debug

Hook으로 강제 주입

• 문제: Skills는 model-invoked. description에 키워드를 아무리 써도 Claude가 스스로 스킬을 로드하지 않는 경우가 빈번
• 원인: Claude가 현재 요청과 스킬의 연관성을 판단 못하거나, 판단 자체를 건너뜀
• 해결: UserPromptSubmit hook을 활용해 Claude가 프롬프트를 읽기 전에 관련 스킬을 컨텍스트에 주입

settings.json

// .claude/settings.json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/skill_activator.py"
          }
        ]
      }
    ]
  }
}

skill_activator.py

#!/usr/bin/env python3
import json
import sys

# stdin 읽기 (훅 프로토콜상 필요)
hook_data = json.load(sys.stdin)

# 키워드 분석 없이 항상 같은 지시문 주입
instruction = """
INSTRUCTION: MANDATORY SKILL ACTIVATION
작업 구현 전 <available_skills>를 확인하세요.
관련 스킬이 있으면: Skill() 도구로 활성화 후 진행
관련 스킬이 없으면: 바로 진행
"""

print(instruction)
sys.exit(0)

활용 팁

• 모듈식 조합: 거대한 단일 스킬보다 작고 집중된 스킬 여러 개를 조합 (예: my-business-context + brand-voice + research-workflow)
• 컨텍스트 절약: Claude가 이미 아는 내용은 SKILL.md에 쓰지 않는다. 모든 토큰은 비용
• 보안 주의: 신뢰할 수 없는 출처의 Skills는 설치 전 파일 내용을 반드시 검토
• 버전 기록: SKILL.md 내에 ## Version History 섹션을 추가해 변경 이력 관리
• 팀 테스트: 스킬 배포 전 팀원에게 실제로 사용하게 하고 피드백 수집

실전 활용 사례

샘플 스킬 만들어보기

mkdir -p ~/.claude/skills/my-first-skill

cat > ~/.claude/skills/my-first-skill/SKILL.md << 'EOF'
---
name: my-first-skill
description: 간단한 코드 리뷰를 수행합니다. 코드 품질 검토나 리뷰 요청 시 사용.
allowed-tools: Read, Grep, Glob
---

# My First Skill

## Instructions
1. 대상 파일을 읽습니다
2. 코드 구조, 에러 핸들링, 네이밍을 검토합니다
3. 개선 사항을 제안합니다
EOF

claude
# 세션 내에서: "my-first-skill 스킬을 사용해서 이 파일을 리뷰해줘"

claude --debug