← today i learned

Claude 스킬 만들기: Anthropic 공식 가이드 정리

Anthropic 이 배포한 33쪽짜리 공식 문서 The Complete Guide to Building Skills for Claude 를 한글로 정리했다. 스킬의 구조와 설계 원칙부터 YAML frontmatter 작성법, 테스트, 배포, 실전 패턴 5종과 트러블슈팅까지 원문의 흐름을 따라 요약한다. (원문 기준 시점: 2026년 1월)

스킬이란 무엇인가

스킬(skill)은 특정 작업이나 워크플로를 처리하는 방법을 Claude 에게 가르치는 지시문 묶음으로, 폴더 하나로 패키징된다. 매 대화마다 선호·프로세스·도메인 지식을 다시 설명하는 대신, 한 번 가르쳐 두고 계속 써먹는 장치다. 반복 가능한 워크플로가 있을 때 가장 강력하다: 스펙 기반 프론트엔드 디자인 생성, 일관된 방법론의 리서치, 팀 스타일 가이드를 따르는 문서 작성, 멀티스텝 프로세스 오케스트레이션 등.

스킬 폴더의 구성은 다음과 같다. SKILL.md 하나만 필수다.

your-skill-name/
├── SKILL.md        # 필수: YAML frontmatter + Markdown 지시문
├── scripts/        # 선택: 실행 코드 (Python, Bash 등)
├── references/     # 선택: 필요할 때만 로드되는 문서
└── assets/         # 선택: 출력에 쓰는 템플릿·폰트·아이콘

핵심 설계 원칙: Progressive Disclosure

스킬은 3단계 로딩 시스템으로 토큰 사용을 최소화하면서 전문성을 유지한다.

그 외 두 가지 원칙:

• Composability: Claude 는 여러 스킬을 동시에 로드한다. 내 스킬이 유일한 능력이라고 가정하지 말고, 다른 스킬과 나란히 잘 동작하게 만든다.
• Portability: 스킬은 Claude.ai, Claude Code, API 어디서든 동일하게 동작한다. 한 번 만들면 수정 없이 모든 표면에서 쓸 수 있다(환경이 의존성을 지원하는 한).

MCP 와 스킬의 관계

원문은 주방 비유를 쓴다. MCP 는 전문 주방(도구·재료·장비에 대한 접근)을, 스킬은 레시피(가치 있는 결과물을 만드는 단계별 지침)를 제공한다. 이미 동작하는 MCP 서버가 있다면 어려운 일은 끝났고, 스킬은 그 위에 얹는 지식 레이어다.

스킬 없이 MCP 만 있으면: 사용자가 연결해 놓고 다음에 뭘 할지 모르고, "이 연동으로 X 는 어떻게 하나요" 지원 티켓이 쌓이고, 매 대화가 처음부터 시작되고, 프롬프트가 제각각이라 결과도 제각각이 된다. 스킬이 있으면 미리 만든 워크플로가 필요할 때 자동으로 활성화되고, 도구 사용이 일관되며, 모범 사례가 모든 상호작용에 내장된다.

계획: 유스케이스에서 시작한다

코드를 쓰기 전에 스킬이 가능하게 할 구체적 유스케이스 2-3개를 먼저 정의한다. 좋은 유스케이스 정의에는 트리거(사용자가 뭐라고 말하는가), 단계, 기대 결과가 들어간다. 스스로 물어볼 것: 사용자가 무엇을 이루려 하는가? 어떤 멀티스텝 워크플로가 필요한가? 필요한 도구는 내장인가 MCP 인가? 어떤 도메인 지식을 내장해야 하는가?

Anthropic 이 관찰한 스킬 유스케이스는 크게 세 갈래다.

성공 기준 정의

정밀한 임계값이라기보다 대략의 벤치마크다. 원문도 "vibes 기반 평가 요소가 있음을 받아들이라"고 말한다.

• 정량: 관련 쿼리의 90% 에서 스킬이 트리거되는가(테스트 쿼리 10-20개로 측정), 워크플로가 몇 번의 툴콜로 끝나는가(스킬 유무로 같은 작업을 비교), 워크플로당 API 호출 실패 0건(MCP 서버 로그로 재시도율·에러 코드 추적).
• 정성: 사용자가 다음 단계를 따로 물어볼 필요가 없는가, 사용자 교정 없이 워크플로가 완주하는가(같은 요청 3-5회 반복 실행해 구조 일관성 비교), 세션이 달라져도 결과가 일관되는가.

기술 요구사항

파일·이름 규칙 (Critical rules)

• 메인 파일 이름은 정확히 SKILL.md (대소문자 구분, SKILL.MD·skill.md 불가).
• 스킬 폴더 이름은 kebab-case: notion-project-setup ⭕ / 공백·언더스코어·대문자 ❌.
• 스킬 폴더 안에 README.md 를 넣지 않는다. 문서는 SKILL.md 또는 references/ 로. (GitHub 로 배포한다면 저장소 레벨 README 는 사람용으로 따로 둔다.)

YAML frontmatter: 가장 중요한 부분

frontmatter 는 Claude 가 스킬 로드 여부를 결정하는 근거다. 최소 필수 형태는 이게 전부다.

---
name: your-skill-name
description: 무엇을 하는지. Use when user asks to [구체적 문구].
---

• name (필수): kebab-case, 공백·대문자 불가, 폴더 이름과 일치 권장.
• description (필수): 무엇을 하는지(WHAT) 와 언제 쓰는지(WHEN·트리거 조건) 둘 다 반드시 포함. 1024자 이내, XML 태그(< >) 금지, 사용자가 실제로 말할 법한 작업 문구를 포함, 관련 있다면 파일 타입도 언급.
• 선택 필드: license, compatibility(1-500자, 환경 요구사항), metadata(author·version·mcp-server 등 임의 키-값), allowed-tools(도구 접근 제한).
• 보안 제한: frontmatter 는 시스템 프롬프트에 들어가므로 XML 꺾쇠괄호가 금지되고, "claude"·"anthropic" 으로 시작하는 스킬 이름은 예약돼 있어 쓸 수 없다. YAML 안 코드 실행도 차단된다(safe parsing).

description 의 권장 구조는 [무엇을 하는가] + [언제 쓰는가] + [핵심 능력]이다.

# 좋음 - 구체적이고 실행 가능
description: 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".

# 나쁨 - 너무 모호
description: Helps with projects.

# 나쁨 - 트리거 없음
description: Creates sophisticated multi-page documentation systems.

# 나쁨 - 기술적이기만 하고 사용자 트리거 없음
description: Implements the Project entity model with hierarchical
  relationships.

본문 지시문 작성

frontmatter 뒤에 Markdown 으로 실제 지시문을 쓴다. 권장 뼈대는 단계별 Instructions → Examples(사용자 발화 + 액션 + 결과) → Troubleshooting(에러·원인·해법) 순서다. 모범 사례:

• 구체적이고 실행 가능하게. "진행 전에 데이터를 검증하라" ❌ 대신 "python scripts/validate.py --input {filename} 을 실행해 형식을 확인하라. 실패 시 흔한 원인은 필수 필드 누락, 잘못된 날짜 형식(YYYY-MM-DD 사용)" ⭕ 처럼 쓴다.
• 에러 처리를 포함한다. "MCP Connection Failed 가 보이면 1) 서버 연결 확인 2) API 키 확인 3) 재연결 시도" 같은 Common Issues 섹션.
• 번들 리소스를 명확히 참조한다. "쿼리 작성 전 rate limiting·페이지네이션·에러 코드는 references/api-patterns.md 를 참고하라" 식으로.
• Progressive disclosure 를 활용한다. SKILL.md 는 핵심 지시문에 집중하고, 상세 문서는 references/ 로 옮겨 링크한다.

테스트와 반복

테스트 수단은 셋이다: Claude.ai 에서 수동 테스트(설정 없이 빠른 반복), Claude Code 스크립트 테스트(변경마다 반복 가능한 자동 검증), Skills API 기반 프로그래매틱 테스트(정의된 테스트셋에 대한 평가 스위트). 소규모 팀 내부용과 수천 명 규모 배포용은 요구되는 엄밀함이 다르다.

권장 테스트는 세 영역을 덮는다.

1. 트리거 테스트: 명백한 작업에서 로드되는가 ⭕, 바꿔 말한 요청에서도 로드되는가 ⭕, 무관한 주제에서는 로드되지 않는가 ❌ 를 확인한다. "Should trigger / Should NOT trigger" 목록을 만들어 돌린다.
2. 기능 테스트: 올바른 출력, API 호출 성공, 에러 처리, 엣지 케이스를 Given-When-Then 형태로 검증한다.
3. 성능 비교: 스킬이 베이스라인보다 나음을 증명한다. 원문의 예시 비교:

skill-creator 스킬(Claude.ai 내장, Claude Code 용 다운로드 가능)을 쓰면 자연어 설명에서 스킬 생성, frontmatter 형식 검증, 트리거 문구 제안, 흔한 문제(모호한 description, 트리거 누락, 구조 문제) 진단까지 도와준다. MCP 서버와 상위 2-3개 워크플로를 알고 있다면 15-30분에 동작하는 스킬 하나를 만들 수 있다는 게 원문의 추정이다. 다만 skill-creator 는 설계·개선을 돕는 도구지 자동 테스트 스위트를 실행해 주지는 않는다.

배포 후에는 신호를 보고 고친다. 언더트리거(로드가 안 됨, 사용자가 수동 활성화, "언제 쓰는 스킬이냐" 질문) → description 에 디테일과 기술 용어 키워드를 보강. 오버트리거(무관한 쿼리에 로드, 사용자가 비활성화) → 부정 트리거 추가 ("Do NOT use for simple data exploration"), 더 구체적으로, 범위 명시. 실행 문제(비일관 결과, API 실패, 사용자 교정 필요) → 지시문 개선과 에러 처리 추가. 디버깅 요령: Claude 에게 "이 스킬 언제 쓸 거야?" 라고 물으면 description 을 되읽어 주므로, 빠진 것을 기준으로 조정한다.

배포와 공유

개인 사용자는 스킬 폴더를 (필요하면 zip 으로) Claude.ai 의 Settings → Capabilities → Skills 에 업로드하거나 Claude Code 스킬 디렉터리에 놓는다. 조직 레벨로는 관리자가 워크스페이스 전체에 배포할 수 있다(2025년 12월 출시: 자동 업데이트·중앙 관리).

Anthropic 은 Agent Skills 를 오픈 스탠다드로 공개했다. MCP 처럼 스킬도 도구·플랫폼을 가로질러 이식 가능해야 한다는 입장이고, 특정 플랫폼 전용 기능을 쓰는 스킬은 compatibility 필드에 명시하면 된다.

프로그래매틱 사용은 API 로: /v1/skills 엔드포인트로 스킬을 관리하고, Messages API 요청의 container.skills 파라미터로 스킬을 붙인다. Claude Console 에서 버전 관리가 되고 Agent SDK 와도 함께 동작한다. API 에서 스킬을 쓰려면 Code Execution Tool 베타(스킬 실행에 필요한 보안 환경)가 필요하다.

MCP 제작자에게 권장하는 오늘의 접근: 1) GitHub 공개 저장소에 스킬을 호스팅(사람용 README, 사용 예시·스크린샷 포함), 2) MCP 문서에서 스킬을 링크하고 둘을 함께 쓰는 가치를 설명, 3) 설치 가이드 작성. 스킬을 소개할 때는 기능이 아니라 결과에 집중한다: "YAML frontmatter 를 담은 폴더" ❌ 가 아니라 "수동 설정 30분 대신 몇 초 만에 완전한 프로젝트 워크스페이스 구성" ⭕.

실전 패턴 5종

얼리어답터와 내부 팀의 스킬에서 관찰된, 규범이 아닌 참고용 패턴들이다. 접근법을 고를 때는 Home Depot 비유가 나온다: 문제를 들고 가서 도구를 안내받거나(problem-first: 사용자는 결과를 묘사하고 스킬이 도구를 다룬다), 도구를 사 놓고 용법을 배우거나 (tool-first: 접근은 이미 있고 스킬이 전문성을 준다). 대부분의 스킬은 한쪽으로 기운다.

트러블슈팅

언어 지시보다 코드가 결정적이라는 조언도 있다: 중요한 검증은 말로 시키지 말고 검사를 프로그래매틱하게 수행하는 스크립트를 번들하라(Office 스킬들이 이 패턴의 예).

퀵 체크리스트 요약

• 시작 전: 구체적 유스케이스 2-3개 식별, 도구(내장/MCP) 식별, 폴더 구조 계획.
• 개발 중: kebab-case 폴더명, 정확한 SKILL.md 철자, --- 구분자, name 필드 규칙, description 에 WHAT+WHEN, XML 태그 금지, 명확·실행 가능한 지시문, 에러 처리, 예시, references 링크.
• 업로드 전: 명백한 작업·바꿔 말한 요청에서 트리거 확인, 무관 주제에서 미트리거 확인, 기능 테스트 통과, (해당 시) 도구 연동 확인, zip 압축.
• 업로드 후: 실제 대화에서 테스트, 과소/과다 트리거 모니터링, 피드백 수집, description·지시문 반복 개선, metadata 버전 갱신.

참고 자료

• 원문 PDF: The Complete Guide to Building Skills for Claude
• Anthropic 공개 스킬 저장소: anthropics/skills (커스터마이즈 가능한 공식 예제·문서 스킬)
• 엔지니어링 블로그: Equipping agents for the real world with Agent Skills
• 버그 리포트: anthropics/skills/issues

이 페이지는 위 원문 PDF(33쪽, 2026년 1월 기준)를 한글로 요약·정리한 2차 저작물이다. 세부 수치·문구는 원문을 우선한다.