원문 정보
- 제목: A complete guide to building skills for Claude
- 링크: claude.com/blog/complete-guide-to-building-skills-for-claude
- 발행: 2026년 1월 29일 (32-page playbook)
- 카테고리: Claude Code
글의 요지
Anthropic 공식 32페이지 Skills 플레이북 출시. Skills 출시 (2025년 10월) 3개월 후. 가장 상세한 공식 문서. fundamentals + planning + testing + distribution + patterns + YAML reference 종합 다룸. "chatbot → 커스터마이즈 운영체제" 의 변환 가이드.
32페이지 구성
플레이북이 다루는 영역:
1. Fundamentals — Skills 본질
2. Planning — Use case 우선
3. Structure — 폴더 + SKILL.md
4. Testing — triggering + output
5. Distribution — 개인 → 팀 → 조직
6. Patterns — 검증된 디자인
7. YAML Reference — frontmatter 사양
핵심 통찰 — Use Case First
본문 권장:
"Before writing any code, identify 2-3 concrete use cases your skill should enable."
Use case 정의 요소:
- Trigger: 사용자가 무엇 말하나
- Sequence: 단계
- Result: 예상 결과
이 "use-case-first" 접근이 흔한 실패 패턴 방지:
- 기술적으로 완전한 Skill 빌드
- 그러나 실제 user query에 trigger X
- 결국 사용 X
3가지 Skill 카테고리
본문 분류:
1) Document & Asset Creation
- 일관된 산출물 (보고서, 프레젠테이션, UI, 코드)
- 임베디드 표준 따름
- 예:
frontend-design,docx,pptx,xlsx
2) Workflow Automation
- 다단계 프로세스
- 일관된 방법론 적용
- 예: 스프린트 플래닝, 고객 온보딩
3) MCP Enhancement
- MCP 서버에 도메인 expertise 추가
- 원시 API → 신뢰 가이드 워크플로
- 예: Sentry sentry-code-review skill (Sentry MCP + 자동 분석/수정)
Progressive Disclosure (3단계 디테일)
본문이 강조한 토큰 효율:
Level 1 — YAML Frontmatter (50-100 토큰):
---
name: PayFlow
description: |
Handles account creation, payment setup, and
subscription management. Use when user says
"onboard new customer", "set up subscription",
or "create PayFlow account".
---- 항상 system prompt에 로드
- Claude가 "이 skill 관련?" 결정
- trigger phrases 명시 중요
Level 2 — SKILL.md Body:
- 전체 instructions
- 예시
- 에러 처리
- 관련 시 로드
Level 3 — Linked Files:
- references/ 폴더
- API 문서, 템플릿
- 필요 시만 로드
YAML Frontmatter 베스트 프랙티스
본문이 강조:
"Frontmatter appears in Claude's system prompt. Malicious content could inject instructions."
(Frontmatter가 Claude system prompt에 들어감 — 악의 콘텐츠 주입 위험)
좋은 description 패턴:
Bad: "Helps with documents"
- 모호
- 언제 trigger?
Good:
"Analyzes Figma design files and generates developer handoff documentation. Use when user uploads .fig files, asks for 'design specs', 'component documentation', or 'design-to-code handoff'."
- 구체적 트리거 phrases
- 명확한 가치
- 예시 입력
"MCP = 부엌, Skills = 레시피"
본문 비유:
"MCP gives Claude access to your tools and data. Skills tell Claude how to use them — the right order, the right checks, the right output format."
이 비유가 #74 글 (Capability vs Expertise)의 정확한 설명:
- MCP = capability (도구)
- Skills = expertise (방법)
5,000단어 제한
본문 권장:
"Keep the main SKILL.md under 5,000 words."
- 핵심 instructions만 SKILL.md
- 상세 문서 → references/ 폴더
- 필요 시만 로드
이 구조가 토큰 효율 + 유지보수성 둘 다.
Distribution Scaling
| Scale | 방식 |
|---|---|
| 개인 | 로컬 폴더 |
| 팀 | Git repository |
| 조직 | Plugin marketplace |
| 글로벌 | Skills directory (#73 글) |
2026년에 다시 읽으며 — 내가 본 것
1. "32 페이지 = 시장 표준 정의" 의 야망
이 32페이지의 의미:
- 단순 기능 가이드 X
- 새 디자인 패턴의 정의
- "Skills 잘 빌드하는 법" = 산업 표준
비교 — 디자인 패턴 책의 역사:
- Gang of Four (1994): OOP 디자인 패턴 표준 정의
- PoEAA (Fowler, 2002): 엔터프라이즈 패턴
- DDD (Evans, 2003): Domain-Driven Design
- 이 32페이지 (2026): Agent Skills 패턴
이게 AI 시대의 첫 디자인 패턴 책이다. 향후 모든 AI 빌더가 참조하는 정석.
흥미로운 점:
- Anthropic이 정의자
- 다른 AI 회사도 따를 가능성
- "Anthropic 패턴 = 표준"
이 "패턴의 정의자" 위치가 향후 5년 가장 강력한 모트가 된다.
2. "Use Case First" 의 깊은 통찰
이 권장이 일반 SW 엔지니어링 원칙의 AI 적용:
- 전통: "기능부터 빌드"
- TDD: "테스트부터 작성"
- DDD: "도메인부터 모델링"
- Skill: Use Case부터 정의
흔한 실패 패턴:
- 개발자가 "이게 멋질 것 같다" Skill 빌드
- 그러나 실제 user query가 trigger X
- 사용 0
- 매몰
해결:
- 2-3개 구체 use case 먼저
- "이 user가 이렇게 말하면 trigger"
- 빌드 → 테스트 → 정확한 trigger 확인
이 "행동 중심 디자인" 이 "AI 시대 SW 엔지니어링" 의 기반이다.
3. "Sentry Skill" 사례의 시장 시그널
본문이 인용:
"sentry-code-review skill (from Sentry): Automatically analyzes and fixes detected bugs in GitHub Pull Requests using Sentry's error monitoring data via their MCP server."
이게 3rd-party Skill 시장 형성 시그널이다.
Sentry의 결정:
- Sentry MCP 서버 빌드 (#73 글)
- 그 위에 Skill 빌드 (이 글)
- 사용자에게 "Sentry + Claude + 자동 수정" 통합 솔루션
이 패턴이 모든 SaaS의 길:
- 회사가 자기 도구의 Skill 빌드
- Claude 사용자가 즉시 통합
- 회사 도구 사용 빈도 ↑
비교 — App Store / Plugin Marketplace 패턴:
- Apple iOS 앱 = 개발자 빌드
- Salesforce AppExchange = 파트너 빌드
- Claude Skills = SaaS 회사 빌드
같은 "플랫폼 + 3rd party" 모델의 AI 시대 버전.
4. "Hands-on AI Playbook"의 교육 지원
여러 회사가 이 가이드 위에 자기 콘텐츠 빌드:
- handsonai.info: "Hands-on AI Playbook"
- Medium 글들: "Without Reading 33 Pages"
- learn-prompting.fr: "Step-by-Step Tutorial"
이게 "교육 생태계 형성" 시그널이다:
- Anthropic 공식 가이드 (32페이지)
- 외부 콘텐츠 (요약, 튜토리얼, 코스)
- 커뮤니티 자산
이 "3-tier knowledge ecosystem" 이 표준 정착의 정석:
- Tier 1 (Anthropic): 공식 32페이지
- Tier 2 (전문가): 깊은 분석 (Adithya, Amanraj)
- Tier 3 (커뮤니티): 짧은 요약 (Threads, Twitter)
각 tier가 다른 청중. 모두가 결국 Anthropic으로 수렴.
5. "5000 Words 제한" 의 토큰 경제
이 제한의 정확한 토큰 수학:
- 5,000 단어 ≈ 6,500 토큰
- Claude 200K context window의 3.25%
- 한 Skill = 작음
수학:
- 30 Skills × 5K 단어 = 150K 단어
- 그러나 Level 1 (메타데이터)만 = 1.5K 토큰 (1%)
- 나머지 = on-demand
이 효율이 "수백 Skill 동시 등록" 가능하게 만든다.
비교 — 다른 접근:
- 전체 system prompt: 50K 토큰 (25% context)
- 매번 사용 (필요 X)
- 매우 비효율
Skills의 진짜 가치 = 무한 확장 가능 expertise.
6. "보안 경고" 의 운영 디테일
본문 인용:
"Frontmatter appears in Claude's system prompt. Malicious content could inject instructions."
이게 "prompt injection" 위험의 인정:
- Skill 빌드 = system prompt 수정
- 악의 Skill = AI 행동 변조
- "trusted source만 install"
비유:
- npm 패키지 (악의 패키지 위험)
- VS Code extension (권한 남용 위험)
- Skill (prompt injection 위험)
Anthropic의 응답:
- 공식 Skills (검증)
- 파트너 Skills (review)
- 커스텀 Skills (사용자 책임)
이게 "AI 시대 supply chain security" 의 시작이다. 신뢰 구조 중요.
7. "Plugin Marketplace로 분배" 의 자연스런 진화
본문이 언급한 distribution path:
- 개인 (로컬)
- 팀 (Git)
- 조직 (Plugin marketplace)
이 진화가 #80 글 (Team plan + Plugin marketplace) 와 정확히 맞물린다.
Anthropic의 메타 전략:
1. Skills 출시 (2025년 10월) — 콘텐츠 형식
2. MCP App (2026년 1월) — 인터랙티브 인터페이스
3. Plugin Marketplace (2026년 1월) — 분배 채널
4. 이 32페이지 가이드 (2026년 1월 29일) — 빌더 표준
5. Cowork Plugins (2026년 4월) — domain 솔루션
이 일관 시퀀스가 "플랫폼 베팅" 의 정석이다. 콘텐츠 형식 → 표준 → 분배 → 마케팅 → 솔루션.
8. "70% 엔터프라이즈 채택 (2028)" 의 시장 예측
Forrester 예측 (Blockchain.news 인용):
- 2028년 70%+ 엔터프라이즈 가 customizable AI workflows 사용
이 추세에서 Skills 위치:
- 표준 형식 (Skills) = 모든 회사 채택
- Skill 빌드 능력 = 핵심 인재
- Skill 라이브러리 = 회사 자산
이게 "우리 회사의 Skills" 가 향후 회사 자산의 일부가 되는 미래다. ERP, CRM 같은 거대 자산 + Skills 라이브러리 추가.
이 자산의 가치:
- 회사 지식 캡슐화
- AI 모델 변경에도 보존
- 매각·M&A 시 가치 일부
마무리
이 글은 "32페이지 가이드" 같지만, 실제로는 AI 시대 디자인 패턴 표준 정의다.
- 32 페이지 = 산업 표준: Gang of Four AI 버전
- Use Case First: 행동 중심 디자인
- 3 카테고리: Document, Workflow, MCP Enhancement
- 3-tier Progressive Disclosure: 토큰 경제
- Sentry Skill: 3rd-party 시장 형성
- 5000단어 제한: 무한 확장 가능
- 보안 경고: AI supply chain security
- Plugin Marketplace: 분배 채널
- 2028 70%: 시장 예측
2026년 1월 29일 시점은 "Skills = 새 기능" 시대가 끝난 시점이다. Skills = 산업 디자인 표준의 공식 정착.
흥미로운 건 이 가이드가 공짜 PDF라는 점이다:
- 단기 매출 X
- 표준 정의 우선
- 모두가 Anthropic 패턴 사용 → 시장 우위
비교 — 다른 회사 패턴:
- 컨설팅 회사: 32페이지 가이드 = $50K 컨설팅
- Anthropic: 무료 다운로드
이 "무료 가이드 + 유료 도구" 패턴이 개발자 도구 마케팅의 정석이다 (Stripe, Twilio 같은). 가이드로 표준 정의 → 표준 위에서 도구 사용 → 매출.
다음 글 (#84): Cowork Plugins — Skills 위에 빌드된 domain solution. 이 32페이지 가이드의 "빌드 방법" 의 "실제 빌드된 결과". 표준 + 도구 + 솔루션 = 완전한 시장 진입 패키지. Anthropic이 enterprise AI 시장을 정복하는 정확한 메커니즘이 보인다.
