Anthropic이 “The Complete Guide to Building Skills for Claude”를 공개했다. 30페이지짜리 PDF인데, 스킬을 만들고 배포하는 데 필요한 거의 모든 것을 다루고 있다.

다 읽을 시간이 없어서 Claude에게 읽히고 챕터별 핵심을 정리해달라고 했다. 스킬을 20개 가까이 만들어 쓰는 입장에서 보니, “감으로 해오던 것”에 체계가 붙는 느낌이었다.

Ch1. Fundamentals — 3단계 프로그레시브 디스클로저

스킬의 구조적 핵심은 3단계 프로그레시브 디스클로저다.

  1. YAML 프론트매터 — 항상 시스템 프롬프트에 로딩된다. Claude가 “이 스킬을 지금 써야 하나?” 판단하는 데만 쓰인다.
  2. SKILL.md 본문 — 관련 있다고 판단되면 로딩된다. 실제 지침이 여기에 있다.
  3. references/ 등 링크 파일 — 필요할 때만 탐색한다.

LLM 시대의 lazy loading이다. 토큰은 아끼고, 전문성은 유지하는 설계.

두 가지 설계 원칙도 짚어둘 만하다.

  • 합성성 — 여러 스킬이 동시에 로딩될 수 있다. 내 스킬이 혼자 쓰인다고 가정하면 안 된다.
  • 이식성 — Claude.ai, Claude Code, API 어디서든 동일하게 작동한다. 한 번 만들면 플랫폼을 가리지 않는다.

MCP + Skill

가이드에서 쓰는 비유가 좋다.

  • MCP = 주방 (도구 접근)
  • Skill = 레시피 (사용법)

MCP만 연결하면 사용자가 매번 “이걸 어떻게 쓰죠?”를 반복한다. Skill을 더하면 워크플로우가 자동으로 활성화되고, 일관된 결과가 나온다. 둘이 합쳐야 요리가 된다.

Ch2. Planning and Design — description이 가장 중요하다

description 필드

이 챕터에서 가장 중요한 건 description 필드다.

Claude가 스킬 로딩 여부를 결정하는 유일한 단서가 이 필드다. 시스템 프롬프트에 직접 올라가기 때문에 1024자 이내, XML 태그 금지라는 제약이 있다.

반드시 두 가지를 포함해야 한다:

  • 뭘 하는지 (what)
  • 언제 쓰는지 (when — 구체적인 트리거 문구)

좋은 예:

“Manages Linear project workflows including sprint planning, task creation, and status tracking. Use when user mentions ‘sprint’, ‘Linear tasks’, ‘project planning’, or asks to ‘create tickets’.”

나쁜 예:

“Helps with projects.” “Implements the Project entity model with hierarchical relationships.”

트리거 문구가 없으면 Claude가 언제 이 스킬을 써야 할지 모른다.

3가지 유즈케이스 카테고리

가이드는 스킬을 세 가지 카테고리로 나눈다.

  1. Document & Asset Creation — 문서, 디자인, 코드 생성. Claude 내장 기능만으로 충분한 경우.
  2. Workflow Automation — 멀티스텝 프로세스 자동화. 검증 게이트 포함.
  3. MCP Enhancement — MCP 도구 위에 워크플로우 지식을 얹는 경우.

성공 지표

정량 지표와 정성 지표를 함께 제시한다.

정량:

  • 관련 쿼리의 90%에서 트리거
  • 스킬 유무에 따른 토큰/대화 수 비교
  • API 실패 0건

정성:

  • 사용자가 다음 단계를 물어보지 않음
  • 교정 없이 워크플로우 완료
  • 세션 간 일관된 결과

가이드 스스로가 “아직 vibes 기반 평가 요소도 있다”고 솔직하게 밝힌다.

기술 요건

your-skill/
├── SKILL.md        ← 필수. 정확히 이 이름.
├── scripts/        ← 선택
├── references/     ← 선택
└── assets/         ← 선택
  • 폴더명: 하이픈 연결 소문자만 (my-skill ✅, My_Skill ❌)
  • YAML 프론트매터: name + description 필수
  • "claude" / "anthropic" 이름 사용 금지 (예약어)
  • README.md를 스킬 폴더 안에 넣지 마. 문서는 전부 SKILL.md 또는 references/에.

지시문 작성법

  • ❌ “Validate data before proceeding.”
  • ✅ "Run scripts/validate.py --input {file}"

핵심 지시는 최상단에, 상세 문서는 references/로 분리. 에러 처리도 포함해야 한다.

Ch3. Testing and Iteration — 하나 성공시킨 뒤 추출해라

테스트 3단계

  1. 트리거 테스트 — 관련 쿼리에 스킬이 뜨는지, 무관한 쿼리에 안 뜨는지.
  2. 기능 테스트 — 아웃풋 정확도, 에러 처리 작동 여부.
  3. 성능 비교 — 스킬 유무에 따른 차이 측정.

가이드가 제시하는 비교 예시:

스킬 없이스킬 있으면
대화 수15번2번
API 실패3번0번
토큰12,0006,000

핵심 조언

“어려운 태스크 하나에 집중해서 성공시킨 다음, 그 접근법을 스킬로 추출해라.”

처음부터 범용 스킬을 설계하지 마. 구체적 성공 → 일반화. 이게 순서.

반복 개선 신호

  • 언더트리거 (스킬이 안 뜸) → description에 키워드/트리거 문구 추가
  • 오버트리거 (엉뚱한 데서 뜸) → “Do NOT use for ~” 네거티브 트리거 추가
  • 실행 오류 (결과 불일관) → 지시문 개선 + 에러 핸들링 추가

Ch4. Distribution — 스킬이 인프라가 되고 있다

배포 모델 3단계

  • 개인: 폴더를 zip으로 압축해서 Claude.ai에 업로드하거나, .claude/skills/에 배치 (Claude Code).
  • 조직: 관리자가 워크스페이스 전체에 배포 (2025년 12월 출시).
  • API: /v1/skills 엔드포인트 + container.skills 파라미터 + Agent SDK 연동.

오픈 스탠다드

Anthropic은 스킬을 MCP처럼 오픈 스탠다드로 공개했다. 같은 스킬이 Claude든 다른 AI 플랫폼이든 작동하게 하겠다는 것이다.

현재 권장하는 배포 패턴:

  1. GitHub에 공개 리포로 호스팅
  2. MCP 문서에서 스킬로 링크
  3. 설치 가이드 제공

포지셔닝 원칙: 기능이 아니라 결과를 강조하라.

✅ “팀 프로젝트 워크스페이스를 수 초 만에 세팅한다” ❌ “YAML 프론트매터와 마크다운 지시문이 담긴 폴더다”

Ch5. Patterns — 실전 패턴 5가지

1. Sequential Workflow

순서대로 실행. 각 단계에 검증 게이트를 둔다.

예: 고객 온보딩 — 계정 생성 → 결제 설정(검증 대기) → 구독 생성 → 환영 이메일. 단계 간 의존성을 명시하고, 실패 시 롤백 지침을 포함해야 한다.

2. Multi-MCP Coordination

여러 서비스를 걸쳐 작업한다.

예: 디자인→개발 핸드오프 — Figma에서 추출 → Drive에 업로드 → Linear에 태스크 생성 → Slack에 알림. 페이즈를 분리하고, MCP 간 데이터 전달과 다음 단계 전 검증이 핵심.

3. Iterative Refinement

품질을 반복적으로 개선한다.

초안 생성 → 검증 스크립트 실행 → 이슈 수정 → 재검증 → 반복. 명시적 품질 기준과 “언제 멈출지”를 정해야 한다.

4. Context-Aware Tool Selection

같은 목표인데 상황에 따라 다른 도구를 선택한다.

파일이 10MB 넘으면 클라우드 스토리지, 협업 문서면 Notion, 코드 파일이면 GitHub. 판단 기준을 명시하고, 왜 그걸 골랐는지 투명하게 보여줘야 한다.

5. Domain-Specific Intelligence

스킬의 진짜 가치다. 도구 연결이 아니라 전문 지식을 코드화하는 것.

예: 결제 처리 전 컴플라이언스 체크 — 제재 목록 확인 → 관할권 검증 → 리스크 평가 → 감사 추적. 도구는 누구나 연결한다. 지식이 차별화다.

트러블슈팅 + 최적화

Claude가 지시를 안 따를 때

원인은 대부분 세 가지: 지시가 너무 길거나, 중요한 내용이 묻혀있거나, 모호하기 때문이다.

해결법:

  • 핵심 지시를 최상단에 배치
  • ## Critical 같은 헤더로 강조
  • 중요한 검증은 자연어 지시 대신 스크립트로 — 스크립트는 매번 같은 결과를 내지만, 자연어 지시는 매번 다르게 해석될 수 있다.

성능 최적화

  • SKILL.md는 5,000단어 이내로 유지. 나머지는 references/로 분리.
  • 스킬 20~50개 동시 활성화를 넘으면 성능 저하.
  • 관련 스킬끼리 “팩”으로 묶는 것을 권장.

마무리

나는 박사논문 프로젝트에서 스킬 20개 가까이 만들어 쓰고 있다. 역사 사료 크롤러, OCR, 문서 생성, 리딩로그 자동화, 아이디어 투척 도구까지. skill-creator 스킬을 써서 만든 것들이라 대체로 가이드 구조에 맞춰져 있긴 한데, 이번에 읽으면서 시간 날 때 한 번 리팩토링 해봐야겠다 싶었다. 가이드를 제대로 준수하고 있는지 점검하는 차원에서.