얼마전, Anthropic에서 skills에 대한 pdf문서를 배포하였다.
가이드명은 ‘The Complete Guide to Building Skills for Claude’
(자료는 아래 첨부)
AI시대에 꼭 알고 넘어가야 하는 skill의 개념과 활용사례, 주의할 점들이 담겨있는 해당 가이드에 대해서 내용들을 살펴보고자 한다.
1장. 기본개념 (Introduction)
1. 스킬의 구조
- 정의: packaging된 지시사항/가이드들의 집합으로, 클로드가 어떻게 처리해야 하는지를 가르쳐주는 역할
- 활용: 디자인 생성, 팀 스타일 가이드에 맞춘 문서 작성, 단계별 프로세스 오케스트레이션 등
스킬은 아래 내용을 포함함 (skill.md, scripts, references, assets)
2. 핵심 디자인 원칙
1) 점진적 공개 (progressive disclosure)
- 1단계: (progressive disclosure) 클로드 시스템 프롬프트에 항상 로드되어 언제 이 스킬을 사용해야 하는 판단하는 정보를 제공
- 2단계: (skill.md 본문) 스킬이 필요하다고 판단될 때 로드되며 전체 지시사항 + 가이드라인 포함
- 3단계: (연결된 파일들) 스킬 디렉토리 내의 추가 파일들로 필요할 때만 탐색
2) 조합성 (Composability)
- 클로드는 여러 스킬을 동시 로드
- 단독으로만 작동한다고 가정하면 안됨
3) 이식성 (Portability)
- claude.ai, claude code, API 전반에서 동일하게 작동함
3. MCP 빌더를 위한 개념: 스킬 + 커넥터
- MCP는 도구나 재료, 장비가 갖춰진 주방이며, 스킬은 이를 가치있게 만드는 레시피에 해당.
- MCP는 서비스를 연결하고 실시간 데이터 액세스 도구 호출을 제공하는 역할을 함
- Skill은 서비스를 효과적으로 사용하는 방법을 가르치고 워크플로우를 캡처하여 클로드가 어떻게 해야하는지를 정의
2장: 기획 및 디자인 (Planning and design)
1. 유스케이스(Use Cases) 정의
코드를 작성하기 전 구체적인 유스케이스 2~3개를 정의해야 함 (예: 트리거, 단계별 절차, built-in 또는 MCP 도구 필요 여부, 도메인 지식 등 정의)
일반적인 Skill 유즈케이스 카테고리
1) 문서 및 자산 생성: 일관되고 고품질의 문서, 프레젠테이션, 코드 등을 생성 (스타일 가이드, 품질 체크리스트 활용)
2) 워크플로우 자동화: 단계별 프로세스 조율 (예: skill-creator 스킬).
3) MCP 강화: MCP 서버가 제공하는 도구 액세스를 강화하는 워크플로우 가이드
2. 성공 기준 (Success Criteria) 정의
- 정량적 지표: 관련 쿼리에 대한 스킬 트리거 비율(목표 90%), 워크플로우 완료에 필요한 도구 호출 수 및 토큰 소모량 비교, API 호출 실패율(목표 0건).
- 정성적 지표: 사용자의 추가 프롬프트 필요성 감소, 사용자 교정 없는 워크플로우 완료, 세션 간 결과의 일관성.
3. 기술적 요구사항 및 규칙
파일 및 폴더 이름 규칙
- 메인 스킬 파일은 반드시 대소문자를 구분하여 SKILL.md여야 함
- 폴더 이름은 소문자 케밥 케이스(kebab-case)만 허용(공백, 언더바, 대문자 금지)
- 스킬 폴더 내부에 README.md를 포함해서는 안 됨(모든 문서는 SKILL.md나 references/로 이동)
YAML 프론트매터 요구사항:
- name: 케밥 케이스, 폴더 이름과 일치해야 함.
- description: 스킬이 무엇을 하는지, 언제 사용되는지(트리거 조건)를 1024자 이내로 명시 (XML 태그 < > 사용 금지).
- 보안 제한으로 프론트매터에 XML 앵글 브래킷(< >) 사용 금지,
- 이름에 “claude”나 “anthropic” 접두사 사용 금지.
4. 메인 지시서(SKILL.md) 구조 템플릿
———————————————
name: your-skill-name
description: [스킬 설명 및 트리거 조건]
———————————————
# 스킬 이름
## Instructions
### Step 1: [주요 단계]
설명 및 예상 결과물
## Examples
### Example 1: [시나리오]
## Troubleshooting
### Error: [에러 메시지] – 해결책
Good Cases
Bad Cases
작성 모범 사례: 구체적이고 실행 가능하게 작성하고, references/ 디렉토리의 자산을 명확히 참조하며, 에러 핸들링을 포함해야 함
3장: 테스트 및 반복 개선 (Testing and iteration)
1. 테스트 접근 방식
- Manual Testing (Claude.ai): 직접 쿼리를 실행하고 행동을 관찰 (빠른 반복 가능).
- Scripted Testing (Claude Code): 변경 사항에 대해 반복 가능한 유효성 검사를 자동화.
- Programmatic Testing (Skills API): 정의된 테스트 세트에 대해 체계적으로 평가 실행.
- 팁: 광범위한 테스트 전에 하나의 도전적인 단일 작업에 대해 먼저 반복 수정하여 완벽히 성공시킨 후 스킬로 추출하는 것이 효과적입니다.
2. 주요 테스트 영역
- 트리거 테스트(Triggering): 명확한 작업이나 유사 문구에는 스킬이 잘 트리거되는지, 관련 없는 주제에는 트리거되지 않는지 확인.
- 기능 테스트(Functional): 올바른 출력 생성, API 호출 성공, 에러 핸들링 및 엣지 케이스 처리가 정상적인지 검증.
- 성능 비교(Performance): 스킬이 없을 때와 있을 때의 메시지 수, 토큰 소모량, API 실패율을 비교하여 가치 증명.
3. Skill-creator 활용
스킬 활용 및 피드백 기반 반복
- skill-creator를 사용하여 자연어 설명으로 스킬을 생성하고, 모범 사례 구조를 제안받거나 스킬을 리뷰
- 트리거 부족(Undertriggering): 스킬이 로드되는 일이 없도록 description에 키워드, 표현 추가
- 과도한 트리거(Overtriggering): 관련 없는 쿼리에 로드되면 부정적 트리거(Do NOT use for…)를 추가하고 범위를 명확히 함
4장: 배포 및 공유 (Distribution and sharing)
1. 현재 배포 모델 (2026년 기준)
- 개인 사용자: 스킬 폴더를 Zip으로 압축하여 Claude.ai > Settings > Capabilities > Skills에 업로드하거나, Claude Code 스킬 디렉토리에 배치
- 조직 수준: 관리자가 워크스페이스 전체에 스킬을 배포하여 자동 업데이트 및 중앙 관리를 수행
- 개방형 표준 (Agent Skills): 에이전트 스킬을 개방형 표준으로 게시하여 플랫폼 간 이식성을 지향
2. API를 통한 스킬 사용
- 프로그램 방식으로 애플리케이션이나 에이전트를 빌드할 때 유용
- /v1/skills 엔드포인트 제공, Messages API 요청 시 container.skills 파라미터로 추가 가능.
- 주의: API에서 스킬을 사용하려면 보안 환경을 제공하는 Code Execution Tool 베타가 필요
3. 추천 권장 사항
- 먼저 GitHub에 공개 저장소를 만들어 스킬을 호스팅하고, 명확한 README 파일(방문자용 – 스킬 폴더와는 별개이며, 스킬 폴더에는 README.md 파일을 포함해서는 안 됨)과 스크린샷이 포함된 사용 예시를 추가
- 그런 다음 MCP 문서에 해당 스킬 링크를 추가하고, 스킬과 MCP를 함께 사용하는 것이 왜 유용한지 설명하며, 빠른 시작 가이드를 제공
5장: 패턴 및 트러블슈팅 (Patterns and troubleshooting)
1. 접근 방식 선택
“주방 캐비닛을 고쳐야 해요”라고 말하며 문제를 안고 매장에 들어가면 직원이 적절한 도구를 알려줄 수 있음 = problem first
또는 새 드릴을 고르고 특정 작업에 어떻게 사용하는지 물어볼 수도 있음 = tool-first
- 문제 우선 (Problem-first):
“워크스페이스를 설정해야 해” -> 스킬이 여러 MCP 호출을 순서대로 오케스트레이션함. - 도구 우선 (Tool-first):
“노션 MCP가 연결되어 있어” -> 스킬이 클로드에게 최적의 워크플로우와 모범 사례를 가르침.
2. Skill의 5가지 주요 디자인 패턴
- 패턴 1: 순차적 워크플로우 오케스트레이션 (Sequential workflow): 다단계 프로세스를 특정 순서대로 실행 (명확한 단계 순서, 단계 간 의존성, 실패 시 롤백 지시 포함
- 패턴 2: 멀티 MCP 조율 (Multi-MCP coordination): 워크플로우가 여러 서비스에 걸쳐 있을 때 사용 (예: Figma에서 자산 수출 -> Drive에 저장 -> Linear에 작업 생성 -> Slack 알림).
- 패턴 3: 반복적 정제 (Iterative refinement): 검증 스크립트 실행 후 이슈를 식별하고 정제하는 루프를 돌아 출력 품질을 높임.
- 패턴 4: 컨텍스트 인식 도구 선택 (Context-aware tool selection): 파일 크기나 유형에 따라 적절한 저장소 MCP를 스스로 선택하도록 의사결정 트리 구축.
- 패턴 5: 도메인 특화 지능 (Domain-specific intelligence): 도구 액세스를 넘어 금융 규제 준수 검사 등 전문 지식 논리를 학습하여 오딧 트레일(Audit Trail)을 기록함.
3. 트러블슈팅 (Troubleshooting)
- 업로드 실패: SKILL.md 파일명이 정확하지 않거나, YAML 프론트매터의 형식이 잘못되었을 때(따옴표 미닫힘, 케밥 케이스 미준수 등) 발생
- 지시사항 미이행: 지시가 너무 장황하면 불필요한 세부 사항을 references/로 옮겨야 함. 중요 지시는 상단에 배치하고 명확한 언어를 사용해야 함. 유효성 검사 스크립트를 스킬에 바인딩하는 것도 필요
- 대규모 컨텍스트 문제: 스킬이 너무 크거나 한 번에 너무 많은 스킬이 활성화되면 속도가 느려짐. SKILL.md 크기를 5,000 단어 이하로 최적화하고 세부 문서는 참조 파일로 분리.
클로드가 스킬을 자꾸 참조하지 않고 독자적으로 움직인다면, 아래 내용 또한 함께 체크를 해보자.
6장. 리소스 및 참고 자료 (Resources and references)
- 공식 리소스: Anthropic 스킬 문서, API 레퍼런스, MCP 문서 및 anthropics/skills 공식 GitHub 저장소
- 체크리스트 요약 (Reference A): 유스케이스 정의, 정확한 파일명/폴더명 매칭, YAML < > 태그 금지, 트리거 테스트 수행 여부 확인.
- 프론트매터(frontmatter) 전체 필드 (Reference B): name, description 외에 license, allowed-tools, metadata(author, version, mcp-server) 등의 옵션 필드 활용 가능
클로드 스킬은 단순한 프롬프트 엔지니어링을 넘어, AI에게 지속 가능한 ‘레시피’를 부여하는 기술이다.
디자이너와 PM을 위한 앞으로의 중요한 기술이며, 복잡한 코딩 없이도 프로덕트 프로세스의 워크플로우와 디자인스타일 등의 가이드를 AI 시스템에 직접 내장할 수 있어, 기획자와 디자이너의 상상력을 곧바로 AI 프로세스로 전환해 준다.
이 skill가이드 문서는 AI 구축의 가장 중요한 기반인 Standalone 스킬부터 MCP와 API 연동까지, 확장 가능한 AI 아키텍처를 만들기 위한 표준 규격을 소개하고 있다. 이 가이드북에 담긴 규칙과 모범 사례들을 깊이 있게 숙지하고 AI라는 도구를 누구보다도 효율적으로 활용해나가보도록 하자. 🙂
Reference
PPT 만들 때 사용할만한 스킬: https://github.com/anthropics/skills/tree/main/skills/pptx
PDF 만들 때 활용할 스킬: https://github.com/anthropics/skills/tree/main/skills/pdf
엑셀파일 만들거나 편집시 활용 스킬: https://github.com/anthropics/skills/tree/main/skills/xlsx
프론트엔드 디자인 스킬: https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md
다양한 워크플로우 기반 스킬사례: https://github.com/anthropics/skills/tree/main/skills
해당 글은 글쓰는몽글C 님과 모비인사이드의 파트너쉽으로 제공되는 기사입니다.
