에이전틱 워크플로, Claude Skiils

워크플로의 이해

1. 기본형 워크플로

• 워크플로는 기본적으로 노드와 엣지(선)으로 이루어져 체인형으로 결합되어 있음.

• 트리거가 발생하면 입력을 받아 각 노드가 함수화 되어 처리되고 데이터규격에 맞춰 다음 노드로 전달됨.

• 정해진 프로그램에 따라 일정한 품질의 데이터 결과를 기대할 수 있음.

• 데이터 엔지니어링 영역에서는 Airflow, MLDL 영역에서는 Tensorflow / ScikitLearn / Kubeflow, 생성형AI 영역에서는 Langchain 프레임워크 가 모두 워크플로 파이프라이닝의 구조를 지님.

2. 지능형 AI 워크플로

• n8n과 같은 자동화 워크플로에 AI Agent 노드 처럼, 노드 단위의 에이전트로 GenAI 함수를 포함한 형태.

• 전체 워크플로는 Rule 베이스로 통제하되, 노드단위로 자율에이전트를 결합해서 스마트한 자동분석이 가능함.

3. 에이전틱 워크플로

• 메인 에이전트가 시스템 프롬프트 및 컨텍스트로 전체 워크플로를 통제함.

• 균일한 품질보다 추론기능이 강조된 형태

• 대화형 작업 중에도 워크플로를 자연스럽게 통합시킬 수 있어 매우 생산적

• 단점이라면 과도한 토큰이 발생할수 있음. 따라서, 프롬프트 지시서와 프로그래밍 스크립트의 정교함이 요구됨

Claude Skills란 무엇인가?

핵심 개념

• 📁 지침, 스크립트, 리소스를 포함하는 폴더

• 🎯 특정 작업에 특화된 전문 지식 패키지

• 🔄 한 번 만들면 어디서나 사용 가능

Skills의 작동 방식

시스템 구조

Skills의 4가지 특징

1. 조합 가능

• 예: "우리 회사 브랜드로 Excel 보고서 만들어줘"
  → Brand Guidelines Skill + Excel Processing Skill 자동 결합!

2. 이동성

• Claude Desktop, Claude Code, Claude Mobile, Claude API

3. 효율성

• 모든 Skills의 메타데이터만 먼저 로드

• 실제 필요할 때만 내용을 읽음

• 토큰 사용량 최적화

4. 강력함

• Python, Javascript, Command LIne 의 런타임 동작 스크립트 코드를 포함시킬수 있습니다.

왜 Claude Skills을 써야하는가

기존 방식의 문제점

❌ 매번 새 대화에서:
"우리 회사 브랜드 색상은 #FF6B35이고, 폰트는 Montserrat를 사용해..."
"PDF에서 텍스트 추출할 때는 pdfplumber를 쓰고..."
"데이터 분석할 때는 이 테이블 스키마를 참고해..."

MCP vs SubAgent vs Skills - 뭐가 다를까?

한눈에 비교하기

협업 시나리오 예시

각각 언제 사용하나?

✅ 외부 시스템 데이터 필요
✅ API 호출 필요
✅ 실시간 정보 조회
✅ 파일 시스템 접근

예: "GitHub 이슈 생성", "Slack 메시지 전송",
    "BigQuery 데이터 조회"

✅ 매우 복잡한 작업 분담
✅ 여러 전문 영역 동시 필요
✅ 독립적인 추론 필요
✅ 작업 병렬 처리

예: "코드 분석 + 테스트 작성 + 문서화 동시 진행"
    "여러 데이터 소스 동시 분석"

✅ 반복적인 작업 패턴
✅ 회사/팀 규칙 준수
✅ 일관된 결과물 필요
✅ 지식 공유 및 표준화

예: "회사 브랜드 가이드라인 항상 적용"
    "SQL 쿼리 시 항상 필수 필터 적용"
    "코드 리뷰 체크리스트 자동 적용"

실무 조합 예시

Claude Skills 시작하기

사용 가능한 플랜

• ✅ Pro ($17/월)

• ✅ Max

• ✅ Team

• ✅ Enterprise

1단계: Skills 활성화하기

Claude 앱에서 활성화

1. 설정 페이지로 이동 : claude.ai → 설정(Settings) → 기능(Features)

2. Skills 토글 활성화 : Skills 섹션에서 토글 버튼 ON

Claude Code에서 설치

# 1. Claude Code에서 플러그인 마켓플레이스 등록
/plugin marketplace add anthropics/skills

# 2. 원하는 Skill 설치
/plugin install document-skills

# 3. 사용
"pdf skill을 사용해서 path/to/file.pdf의 폼 필드를 추출해줘"

• ✅ GitHub에서 직접 설치

• ✅ 버전 관리 자동

• ✅ 팀과 공유 쉬움

API에서 사용

# Messages API에 Skills 추가
# /v1/skills 엔드포인트로 관리

2단계: 기본 제공 Skills 확인하기

📄 문서 생성 Skills (Claude 내장)

• Excel (xlsx): 수식, 포맷팅, 데이터 분석, 시각화 포함

• PowerPoint (pptx): 레이아웃, 템플릿, 차트, 자동 슬라이드 생성

• Word (docx): Tracked changes, comments, 서식 보존

• PDF: 텍스트/테이블 추출, 폼 작성, 문서 병합/분할

🎨 크리에이티브 Skills

• Canvas Design: 아름다운 비주얼 아트 디자인

• Theme Factory: 10가지 전문 테마 또는 커스텀 테마

• Algorithmic Art: p5.js 기반 생성형 아트

🛠️ 개발 & 유틸리티 Skills

• Skill Creator: 새로운 Skill을 만들도록 도와주는 메타 Skill!

• Artifacts Builder: React + Tailwind + shadcn/ui artifacts

• MCP Builder: 고품질 MCP 서버 생성 가이드

• Webapp Testing: Playwright 기반 UI 테스팅

🏢 엔터프라이즈 Skills

• Brand Guidelines: 브랜드 일관성 유지

• Internal Comms: 내부 커뮤니케이션 작성

🔍 실제 예제 둘러보기

GitHub에서 예제 살펴보기

# 저장소 클론
git clone <https://github.com/anthropics/skills>
cd skills/template-skill

# SKILL.md 내용 확인
cat SKILL.md

---
name: template-skill
description: A basic template to use as a starting point for new skills
---

# Template Skill

This is a basic template for creating new skills.

## Usage
[여기에 사용 지침 작성]

## Examples
- Example 1
- Example 2

• ✅ 최소한의 구조

• ✅ Frontmatter 형식

• ✅ 기본 섹션 구성

cd ../brand-guidelines
cat SKILL.md

• ✅ 리소스 파일 포함

• ✅ 실제 회사 브랜드 적용 방법

• ✅ 템플릿 제공 패턴

cd ../document-skills/pdf
ls -la

• ✅ 점진적 공개 패턴

• ✅ 참조 문서 분리

• ✅ 실행 가능한 스크립트

• ✅ 프로덕션 레벨 구조

cd ../../algorithmic-art
cat SKILL.md

• ✅ 크리에이티브한 활용

• ✅ JavaScript/p5.js 통합

• ✅ 파라미터 기반 생성

예제에서 배운 패턴 정리

Skills 만드는 방법

방법 1: Skill Creator 사용하기 (추천!)

실제 사용 예시

사용자: "이미지 편집 Skill을 만들고 싶어"

Claude (skill-creator):
"이미지 편집 Skill을 만들어드리겠습니다.
몇 가지 질문 드릴게요:

1. 어떤 종류의 이미지 편집 작업을 주로 하시나요?
   - 리사이징
   - 필터 적용
   - 워터마크 추가
   - 기타

2. 선호하는 이미지 포맷이 있나요?
   - JPG, PNG, WebP 등

3. 자동으로 적용할 기본 설정이 있나요?"

[대화 진행...]

Claude: "Skill을 생성했습니다!
폴더 구조와 SKILL.md 파일을 자동으로 만들었으니
확인해보세요."

방법 2: 직접 만들기

기본 구조 이해하기

SKILL.md 파일 구조

---
name: 스킬 이름 (최대 64자)
description: 스킬 설명 및 사용 시점 (최대 1024자)
version: 1.0.0
dependencies: python>=3.8, pandas>=1.5.0
---

# 스킬 제목

## 개요
이 스킬의 목적과 언제 사용해야 하는지 설명

## 주요 기능
- 기능 1
- 기능 2

## 사용 방법
구체적인 지침...

## 예제
실제 사용 예시...

## 리소스
추가 파일 참조...

실전 예제: 브랜드 가이드라인 Skill

1단계: SKILL.md 작성

---
name: 브랜드 가이드라인
description: 모든 프레젠테이션 및 문서에 Acme Corp 브랜드 가이드라인 적용. 공식 색상, 글꼴, 로고 사용 등을 포함. 대외용 자료나 문서 제작 시 사용.
version: 1.0.0
---

# Acme Corp 브랜드 가이드라인

## 개요

본 스킬은 일관되고 전문적인 자료를 제작하기 위한
Acme Corp의 공식 브랜드 가이드라인을 제공합니다.

Claude는 Acme Corp을 대표하는 대외용 자료나 문서를
제작할 때마다 본 가이드라인을 참조해야 합니다.

## 브랜드 색상

공식 브랜드 색상:
- **기본색**: #FF6B35 (코랄)
- **보조색**: #004E89 (네이비 블루)
- **액센트색**: #F7B801 (골드)
- **중성색**: #2E2E2E (차콜)

## 타이포그래피

### 폰트
- **헤더**: Montserrat Bold
- **본문 텍스트**: Open Sans Regular

### 크기 가이드라인
- H1: 32pt
- H2: 24pt
- H3: 18pt
- 본문: 11pt

## 로고 사용법

### 기본 규칙
- 밝은 배경: 풀컬러 로고 사용
- 어두운 배경: 흰색 로고 사용
- 로고 주변 최소 여백: 0.5인치

### 금지사항
❌ 로고 비율 변경 금지
❌ 로고 색상 변경 금지
❌ 로고 회전 금지

## 적용 시점

다음 자료 제작 시 이 가이드라인을 반드시 적용:
- ✅ PowerPoint 프레젠테이션
- ✅ 외부 공유용 Word 문서
- ✅ 마케팅 자료
- ✅ 고객용 보고서
- ✅ 제안서

## 문서 템플릿

### 프레젠테이션 첫 페이지
[로고 - 좌측 상단]

[제목 - Montserrat Bold 32pt, #004E89]

[부제목 - Open Sans Regular 18pt, #2E2E2E]

[날짜 및 작성자 - 우측 하단]

### 일반 슬라이드
[제목 - H2 스타일]

[내용]

[하단 - 회사명 및 페이지 번호]

## 리소스

로고 파일 및 폰트는 `resources/` 폴더 참조:
- `resources/logo-full-color.png`
- `resources/logo-white.png`
- `resources/fonts/Montserrat-Bold.ttf`
- `resources/fonts/OpenSans-Regular.ttf`

2단계: 리소스 파일 추가

3단계: ZIP 파일 생성

# 올바른 구조
brand-guidelines-skill.zip
└── brand-guidelines-skill/
    ├── SKILL.md
    └── resources/

# ❌ 잘못된 구조
brand-guidelines-skill.zip
└── SKILL.md  # 루트에 직접 있으면 안됨!

4단계: 업로드 및 테스트

1. 설정 → 기능 → Skills로 이동

2. ZIP 파일 업로드

3. 테스트 프롬프트 실행:

테스트 1: "우리 회사 소개 프레젠테이션 만들어줘"
→ Claude가 브랜드 색상과 폰트 자동 적용

테스트 2: "신제품 제안서 작성해줘"
→ Claude가 브랜드 가이드라인 준수

테스트 3: "블로그 포스트 작성해줘"
→ 브랜드 가이드라인 Skill이 활성화되지 않음
   (대외용 자료가 아니므로)

5단계: Claude의 Thinking 확인

Claude의 생각:
"사용자가 프레젠테이션을 요청했습니다.
브랜드 가이드라인 Skill이 관련있어 보입니다.

Skill 로딩 중...
- ✓ 브랜드 색상 확인: #FF6B35, #004E89...
- ✓ 폰트 확인: Montserrat Bold, Open Sans...
- ✓ 로고 사용 규칙 확인

이제 가이드라인을 준수하여 프레젠테이션을
생성하겠습니다..."

고급 활용법

1. 점진적 공개 (Progressive Disclosure)

예시: PDF 처리 Skill

# PDF Processing

## 빠른 시작

기본 텍스트 추출:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

고급 기능

2. 워크플로우 체크리스트

## PDF 폼 작성 워크플로우

작업 진행 상황 체크리스트:

Task Progress:
- [ ] Step 1: 폼 분석 (analyze_form.py 실행)
- [ ] Step 2: 필드 매핑 생성 (fields.json 편집)
- [ ] Step 3: 매핑 검증 (validate_fields.py 실행)
- [ ] Step 4: 폼 작성 (fill_form.py 실행)
- [ ] Step 5: 출력 검증 (verify_output.py 실행)

**Step 1: 폼 분석**
실행: `python scripts/analyze_form.py input.pdf`
→ 폼 필드를 추출하여 `fields.json`에 저장

**Step 2: 필드 매핑 생성**
`fields.json`을 편집하여 각 필드의 값 추가

**Step 3: 매핑 검증**
실행: `python scripts/validate_fields.py fields.json`
→ 검증 오류가 있으면 수정 후 계속

**Step 4: 폼 작성**
실행: `python scripts/fill_form.py input.pdf fields.json output.pdf`

**Step 5: 출력 검증**
실행: `python scripts/verify_output.py output.pdf`
→ 검증 실패 시 Step 2로 돌아가기

3. 피드백 루프 패턴

## 문서 편집 프로세스

1. `word/document.xml` 편집
2. **즉시 검증**: `python ooxml/scripts/validate.py unpacked_dir/`
3. 검증 실패 시:
   - 에러 메시지 확인
   - XML 수정
   - 다시 검증
4. **검증 통과해야만 다음 단계 진행**
5. 재빌드: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. 출력 문서 테스트

4. 도메인별 조직

# BigQuery 데이터 분석

## 사용 가능한 데이터셋

**재무**: 매출, ARR, 청구 → [reference/finance.md](reference/finance.md) 참조
**영업**: 기회, 파이프라인 → [reference/sales.md](reference/sales.md) 참조
**제품**: API 사용량, 기능 → [reference/product.md](reference/product.md) 참조
**마케팅**: 캠페인, 어트리뷰션 → [reference/marketing.md](reference/marketing.md) 참조

사용자: "Q4 매출 보고서 만들어줘"
→ Claude: finance.md만 읽음 (sales.md, product.md 안읽음!)
→ 토큰 절약, 빠른 응답

5. 실행 가능한 코드 포함

예시: PDF 분석 스크립트

"""
PDF 폼의 모든 필드를 추출하는 유틸리티 스크립트
"""
import sys
import json
import pdfplumber

def analyze_form(pdf_path):
    """PDF 폼 분석 및 필드 정보 추출"""
    try:
        with pdfplumber.open(pdf_path) as pdf:
            fields = {}
            for page_num, page in enumerate(pdf.pages):
                # 폼 필드 추출 로직
                # ...
            return fields
    except FileNotFoundError:
        print(f"Error: {pdf_path} not found")
        sys.exit(1)
    except Exception as e:
        print(f"Error: {str(e)}")
        sys.exit(1)

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("Usage: python analyze_form.py <pdf_file>")
        sys.exit(1)

    result = analyze_form(sys.argv[1])
    print(json.dumps(result, indent=2))

## 유틸리티 스크립트

### analyze_form.py
PDF에서 모든 폼 필드 추출

사용법:
```bash
python scripts/analyze_form.py input.pdf > fields.json

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

주의사항 및 팁

✅ 좋은 Skill 작성 원칙

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

PDF (Portable Document Format) 파일은 텍스트, 이미지 및
기타 콘텐츠를 포함하는 일반적인 파일 형식입니다.
PDF에서 텍스트를 추출하려면 라이브러리를 사용해야 합니다.
PDF 처리에 사용할 수 있는 라이브러리가 많이 있지만
pdfplumber를 추천합니다. 왜냐하면 사용하기 쉽고...

## PDF 텍스트 추출

pdfplumber 사용:

```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

2. 명확한 설명 (Description) 작성

description: 문서를 도와줍니다
description: 데이터 처리
description: 파일로 뭔가 함

description: PDF 파일에서 텍스트와 테이블을 추출하고, 폼을 작성하며, 문서를 병합합니다. PDF 파일 작업, 폼, 문서 추출 언급 시 사용.

description: Excel 스프레드시트를 분석하고, 피벗 테이블을 생성하며, 차트를 만듭니다. Excel 파일, 스프레드시트, 표 형식 데이터, .xlsx 파일 분석 시 사용.

description: git diff를 분석하여 서술적인 커밋 메시지를 생성합니다. 커밋 메시지 작성 도움 또는 staged 변경사항 검토 시 사용.

• ✓ 무엇을 하는지 명확히

• ✓ 언제 사용하는지 구체적으로

• ✓ 관련 키워드 포함

3. 일관된 명명 규칙

✅ 좋은 예:
- Processing PDFs
- Analyzing Spreadsheets
- Managing Databases
- Testing Code
- Writing Documentation

❌ 피해야 할 예:
- Helper (너무 모호함)
- Utils (너무 일반적)
- Tools (구체적이지 않음)
- Documents (무엇을 하는지 불명확)

4. 예제 제공

## 커밋 메시지 형식

다음 예제를 따라 커밋 메시지를 생성하세요:

**예제 1:**
입력: JWT 토큰으로 사용자 인증 추가
출력:
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware

**예제 2:**
입력: 보고서에서 날짜가 잘못 표시되는 버그 수정
출력:
fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation

5. 적절한 자유도 설정

## 코드 리뷰 프로세스

1. 코드 구조와 조직 분석
2. 잠재적 버그나 엣지 케이스 확인
3. 가독성과 유지보수성 개선 제안
4. 프로젝트 규칙 준수 확인

## 데이터베이스 마이그레이션

정확히 이 스크립트를 실행하세요:

```bash
python scripts/migrate.py --verify --backup

⚠️ 피해야 할 안티패턴

1. Windows 스타일 경로

❌ 나쁜 예: scripts\\helper.py
✅ 좋은 예: scripts/helper.py

❌ 나쁜 예: reference\\guide.md
✅ 좋은 예: reference/guide.md

2. 너무 많은 선택지 제공

pypdf를 쓸 수도 있고, pdfplumber도 있고,
PyMuPDF도 있고, pdf2image도 있고...

텍스트 추출에는 pdfplumber 사용:

import pdfplumber

스캔된 PDF에 OCR이 필요한 경우에만

pdf2image와 pytesseract 사용.

3. 너무 깊은 중첩 참조

SKILL.md → advanced.md → details.md → 실제 정보

SKILL.md → advanced.md (실제 정보 포함)
SKILL.md → reference.md (실제 정보 포함)
SKILL.md → examples.md (실제 정보 포함)

🔒 보안 주의사항

1. 실행 코드 관련

2. 외부 서비스 접근

💡 개발 및 테스트 팁

1. 평가 기반 개발 (Evaluation-First)

1. ❌ 문서부터 쓰지 마세요

2. ✅ 먼저 테스트 시나리오 만들기

3. ✅ 최소한의 Skill 작성

4. ✅ 테스트 실행 및 개선

5. ✅ 반복

2. Claude와 함께 개발

3. Skill 네비게이션 관찰

관찰 포인트:
- 어떤 파일을 먼저 읽는가?
- 어떤 참조를 따라가는가?
- 어떤 내용을 무시하는가?
- 반복적으로 읽는 파일이 있는가?

→ 이를 바탕으로 구조 개선!

📊 성능 최적화

1. SKILL.md 크기 제한

권장: 500줄 이하
이유: 최적의 성능

500줄 초과 시:
→ 별도 파일로 분리
→ 점진적 공개 패턴 사용

2. 토큰 예산 고려

항상 로드됨:
- 모든 Skills의 name과 description (메타데이터)

필요시에만 로드됨:
- SKILL.md 본문
- 참조 파일
- 예제 파일

실행되지만 컨텍스트 미사용:
- 유틸리티 스크립트

유용한 리소스

• 📖 Claude Skills 공식 가이드

• 📖 Skills 작성 모범 사례

• 📖 API 개발자 가이드

• 🐙 공식 Skills 예제 저장소
• ⭐ 656+ stars, Apache 2.0 라이선스
• Anthropic이 직접 제공하는 13가지 예제 Skills
• 실제 프로덕션에서 사용되는 문서 Skills 소스 코드 포함

• 🎓 Anthropic Academy

💎 GitHub에서 바로 사용 가능한 공식 예제 Skills

🎨 Creative & Design

• algorithmic-art: p5.js를 사용한 생성형 아트 (flow fields, particle systems)

• canvas-design: 아름다운 PNG/PDF 비주얼 아트 디자인

• slack-gif-creator: Slack 최적화 애니메이션 GIF 생성

• theme-factory: Artifacts에 10가지 전문 테마 적용 또는 커스텀 테마 생성

💻 Development & Technical

• artifacts-builder: React, Tailwind CSS, shadcn/ui로 복잡한 HTML artifacts 빌드

• mcp-builder: 고품질 MCP 서버 생성 가이드 (외부 API/서비스 통합)

• webapp-testing: Playwright로 로컬 웹앱 UI 검증 및 디버깅

🏢 Enterprise & Communication

• brand-guidelines: Anthropic 공식 브랜드 색상 및 타이포그래피 적용

• internal-comms: 상태 보고서, 뉴스레터, FAQ 등 내부 커뮤니케이션 작성

🛠️ Meta Skills

• skill-creator: 새로운 Skill을 만드는 방법을 가르쳐주는 메타 Skill!

• template-skill: 새 Skill 시작용 기본 템플릿

📄 Document Skills (프로덕션 레벨!)

• docx: Word 문서 생성/편집 (tracked changes, comments, 포맷 보존)

• pdf: PDF 조작 (텍스트/테이블 추출, 생성, 병합/분할, 폼 처리)

• pptx: PowerPoint 프레젠테이션 (레이아웃, 템플릿, 차트, 자동 슬라이드 생성)

• xlsx: Excel 스프레드시트 (수식, 포맷팅, 데이터 분석, 시각화)

# 1. 저장소 클론
git clone <https://github.com/anthropics/skills>

# 2. 관심있는 Skill 탐색
cd skills/brand-guidelines
cat SKILL.md

# 3. 그대로 사용하거나 커스터마이즈
# 4. ZIP으로 압축하여 업로드
zip -r my-custom-skill.zip brand-guidelines/