Anthropic의 Claude Skills 완전 가이드

게시 2026/03/11

By BLUEBUG

53 분읽는 시간

— 32페이지 공식 플레이북을 한국어로 깊이 파헤치다

들어가며: 왜 이 문서가 “금맥”인가

2025년 10월, Anthropic은 조용히 그러나 파괴적인 방식으로 하나의 문서를 공개했다. 바로 32페이지 분량의 The Complete Guide to Building Skills for Claude다. X(구 트위터) 커뮤니티에서는 이 문서를 두고 “gold(금맥)”라고 불렀고, “Anthropic이 조용히 떨어뜨린 혁명”이라는 표현까지 등장했다. 단순한 과장이 아니다. 이 플레이북은 Claude를 일회용 챗봇에서 당신만의 커스텀 운영체제로 전환시키는 방법을 담고 있다.

핵심 개념은 단순하다. “한 번만 가르쳐라. 그러면 Claude는 매번 그대로 실행한다.” 더 이상 같은 지시를 반복하지 않아도 되고, 더 이상 일관성 없는 출력 결과를 감수하지 않아도 된다. Skills는 당신의 워크플로우, 스타일 가이드, 도메인 지식을 폴더 하나에 캡슐화해서 Claude.ai, Claude Code, API 어디서든 동일하게 실행되게 만든다.

이 문서는 그 32페이지 플레이북의 모든 내용을 한국어로 깊이 해설하고, 공식 문서와 엔지니어링 블로그의 내용을 추가로 보강하여 개발자와 파워 유저 모두가 Skills를 완전히 이해하고 즉시 실전에 활용할 수 있도록 구성했다.

1장: Skills란 무엇인가 — 개념과 철학

Skills의 정의

Skill(스킬)은 폴더 형태로 패키징된 명령어 집합이다. 이 폴더 안에는 Claude가 특정 태스크나 워크플로우를 어떻게 처리해야 하는지를 가르치는 지시문과, 선택적으로 실행 가능한 스크립트, 참조 문서, 에셋 파일들이 포함된다.

기술적으로 더 정확하게 설명하자면, Skills는 프롬프트 기반 메타 툴 아키텍처다. 전통적인 함수 호출이나 코드 실행과 달리, Skills는 프롬프트 확장(prompt expansion)과 컨텍스트 수정(context modification)을 통해 동작한다. Claude가 특정 스킬을 활성화하면, 시스템은 해당 SKILL.md 파일을 로드하고, 그 내용을 상세한 지시문으로 확장하여 대화 컨텍스트에 새로운 메시지로 주입한다. 이는 문제를 직접 해결하는 것이 아니라, Claude가 문제를 더 잘 해결할 수 있도록 준비시키는 방식이다.

왜 Skills가 필요한가

개발자나 파워 유저라면 누구나 경험하는 공통의 고통이 있다. Claude에게 특정 작업을 맡길 때마다 긴 프롬프트를 처음부터 다시 작성해야 한다는 것, 그리고 매번 결과물의 품질과 형식이 조금씩 달라진다는 것이다. 팀 차원에서 사용할 경우엔 더 심각하다. 구성원마다 Claude를 다르게 프롬프팅하기 때문에 결과물의 일관성이 전혀 보장되지 않는다.

Skills는 이 문제를 근본적으로 해결한다. 반복적인 워크플로우가 있는 모든 상황에서 Skills는 강력하다. 프런트엔드 디자인 스펙에서 코드를 생성하는 작업, 일관된 방법론으로 리서치를 수행하는 작업, 팀의 스타일 가이드를 따르는 문서를 만드는 작업, 여러 단계로 이루어진 프로세스를 조율하는 작업 등에서 Skills는 그 진가를 발휘한다.

Skills vs MCP: 상호 보완 관계

Skills와 MCP(Model Context Protocol)를 혼동하는 사람들이 많지만, 이 둘은 상호 보완적인 레이어다.

플레이북은 이를 주방 비유로 설명한다. MCP는 전문 주방을 제공한다 — 도구, 재료, 장비에 대한 접근권이다. Skills는 레시피를 제공한다 — 가치 있는 무언가를 만들기 위한 단계별 지시문이다. 함께 사용할 때 비로소 사용자는 모든 단계를 일일이 파악하지 않고도 복잡한 태스크를 수행할 수 있게 된다.

MCP가 “Claude가 무엇을 할 수 있는가”를 정의한다면, Skills는 “Claude가 그것을 어떻게 해야 하는가”를 가르친다. MCP는 Notion, Linear, Asana 같은 외부 서비스에 대한 연결과 실시간 데이터 접근을 제공하고, Skills는 그 도구들을 효과적으로 사용하는 방법과 워크플로우, 모범 사례를 캡슐화한다.

Skills의 세 가지 핵심 설계 원칙

첫 번째는 점진적 공개(Progressive Disclosure)다. Skills는 3단계 시스템으로 동작한다. 첫 번째 레벨은 YAML 프런트매터로, 항상 Claude의 시스템 프롬프트에 로드된다. 모든 내용을 컨텍스트에 올리지 않고도 Claude가 각 스킬의 사용 시점을 파악할 수 있도록 최소한의 정보만 제공한다. 두 번째 레벨은 SKILL.md의 본문으로, Claude가 현재 태스크에 이 스킬이 관련 있다고 판단할 때 로드된다. 전체 지시문과 가이드가 담겨 있다. 세 번째 레벨은 스킬 디렉토리 안에 번들된 링크 파일들로, Claude가 필요에 따라 탐색하고 발견할 수 있는 추가 파일들이다.

이 점진적 공개 방식 덕분에 컨텍스트 창에 올라가는 토큰 사용량은 최소화되면서도, 필요한 순간엔 전문 지식을 완전히 활용할 수 있다. Anthropic의 엔지니어링 블로그에 따르면, 스킬에 번들될 수 있는 컨텍스트의 양은 사실상 무제한에 가깝다.

두 번째는 조합성(Composability)다. Claude는 여러 Skills를 동시에 로드할 수 있다. 따라서 각각의 스킬은 자신이 유일한 기능인 것처럼 가정하지 말고, 다른 스킬들과 잘 어울리도록 설계되어야 한다.

세 번째는 이식성(Portability)다. Skills는 Claude.ai, Claude Code, API 어디서든 동일하게 동작한다. 한 번 만들면 환경 수정 없이 모든 플랫폼에서 사용할 수 있다. 물론 스킬이 의존하는 환경적 요구사항(예: 특정 패키지, 네트워크 접근)은 해당 환경에서 지원되어야 한다.

2장: 폴더 구조와 기술적 요구사항

기본 폴더 구조

Skills는 단순한 폴더다. 그 구조는 다음과 같다.

your-skill-name/
├── SKILL.md          # 필수 — 메인 스킬 파일
├── scripts/          # 선택 — 실행 가능한 코드
│   ├── process_data.py
│   └── validate.sh
├── references/       # 선택 — 참조 문서
│   ├── api-guide.md
│   └── examples/
└── assets/           # 선택 — 템플릿, 폰트, 아이콘 등
    └── report-template.md

이 구조에서 유일하게 필수적인 것은 SKILL.md 파일 하나뿐이다. 나머지는 모두 선택 사항이다.

지켜야 할 규칙들

파일 이름 규칙: SKILL.md는 정확히 이 이름이어야 한다 — 대소문자 구분이 엄격하다. SKILL.MD, skill.md, Skill.md 같은 변형은 허용되지 않는다.

폴더 이름 규칙: 스킬 폴더 이름은 반드시 케밥케이스(kebab-case)를 사용해야 한다. notion-project-setup 처럼 소문자와 하이픈만 사용한다. 공백, 언더스코어, 대문자는 허용되지 않는다.

README.md 금지: 스킬 폴더 안에는 README.md를 포함시키면 안 된다. 모든 문서는 SKILL.md나 references/ 폴더에 들어가야 한다. 단, GitHub를 통해 배포할 경우엔 저장소 루트 레벨의 README는 인간 사용자를 위해 별도로 작성한다.

YAML 프런트매터: 가장 중요한 부분

YAML 프런트매터는 Claude가 스킬을 로드할지 말지를 결정하는 근거다. 이것을 제대로 작성하지 않으면 스킬이 존재해도 Claude는 절대 그것을 사용하지 않는다.

최소 필수 형식은 다음과 같다.

  
---
name: your-skill-name
description: What it does and when to use it. Include specific trigger phrases.
---

이것만으로도 시작하기에 충분하다.

name 필드: 반드시 케밥케이스여야 하며, 폴더 이름과 일치시키는 것을 권장한다. “claude”나 “anthropic”으로 시작하는 이름은 예약어로 금지된다.

description 필드: 이것이 전체 스킬에서 가장 중요한 요소다. description에는 반드시 두 가지가 포함되어야 한다 — 스킬이 무엇을 하는지, 그리고 언제 사용해야 하는지(트리거 조건). 1,024자 이하여야 하며, XML 꺾쇠괄호(< >)는 금지된다.

선택 필드들: license(오픈소스 라이선스), compatibility(환경 요구사항), metadata(작성자, 버전, 연관 MCP 서버 등 커스텀 키-값 쌍) 등을 추가할 수 있다.

3장: 좋은 스킬 설계하기 — 기획 단계

유스케이스로 시작하라

어떤 코드나 스크립트를 작성하기 전에, 먼저 스킬이 지원해야 할 2~3가지 구체적인 유스케이스를 명확히 정의해야 한다. 좋은 유스케이스 정의는 다음을 포함한다.

사용자가 달성하려는 목표는 무엇인가?
이를 위해 어떤 다단계 워크플로우가 필요한가?
어떤 도구들이 필요한가? (내장 기능인가, MCP인가?)
어떤 도메인 지식이나 모범 사례가 내장되어야 하는가?

예를 들어 “프로젝트 스프린트 계획” 유스케이스라면, 트리거는 “이번 스프린트 계획 도와줘”나 “태스크 만들어줘” 같은 발화이고, 단계는 Linear MCP로 현재 프로젝트 상태를 가져오고, 팀 속도와 용량을 분석하고, 태스크 우선순위를 제안하고, 올바른 라벨과 견적과 함께 Linear에 태스크를 생성하는 것이다. 결과는 모든 태스크가 생성된 완전한 스프린트 계획이다.

세 가지 유스케이스 카테고리

Anthropic이 관찰한 바에 따르면, Skills의 유스케이스는 크게 세 가지로 분류된다.

카테고리 1: 문서 및 에셋 생성. 일관성 있고 고품질인 출력물을 만드는 데 사용된다. 문서, 프레젠테이션, 앱, 디자인, 코드 등이 여기에 해당한다. 핵심 기법은 스타일 가이드와 브랜드 기준을 내장하고, 일관된 출력을 위한 템플릿 구조를 제공하며, 완성 전 품질 체크리스트를 실행하는 것이다. 외부 도구 없이 Claude의 내장 기능만으로 동작한다.

카테고리 2: 워크플로우 자동화. 일관된 방법론의 혜택을 받는 다단계 프로세스에 사용된다. 여러 MCP 서버 간의 조율도 포함된다. 핵심 기법은 검증 게이트가 있는 단계별 워크플로우, 공통 구조를 위한 템플릿, 내장된 리뷰 및 개선 제안, 반복적 정제 루프다.

카테고리 3: MCP 강화. 기존 MCP 서버가 제공하는 도구 접근을 더욱 강력하게 만드는 워크플로우 지침을 제공한다. Sentry의 sentry-code-review 스킬이 좋은 예다. 이 스킬은 Sentry의 MCP 서버를 통해 GitHub Pull Request의 버그를 자동으로 분석하고 수정한다.

성공 기준 정의

스킬이 제대로 동작하는지 어떻게 알 수 있을까? Anthropic은 다음과 같은 기준들을 제시한다.

정량적 지표: 관련 쿼리의 90%에서 스킬이 자동으로 트리거되는지, 워크플로우가 X번의 도구 호출 안에 완료되는지, API 호출 실패 횟수가 0인지를 측정한다.

정성적 지표: 사용자가 Claude에게 다음 단계를 별도로 알려줘야 하는 일이 없는지, 워크플로우가 사용자 수정 없이 완료되는지, 세션 간에 일관된 결과가 나오는지를 평가한다.

물론 이 기준들은 이상적인 목표치다. 정밀한 임계값이라기보다는 대략적인 벤치마크로 이해하는 것이 좋다.

4장: 효과적인 스킬 작성하기

description 필드 마스터하기

description은 스킬의 심장부다. Anthropic의 엔지니어링 블로그에 따르면, 이 메타데이터는 “모든 내용을 컨텍스트에 올리지 않고도 Claude가 각 스킬을 언제 사용해야 하는지 알 수 있도록 충분한 정보를 제공한다”. 이것이 점진적 공개의 첫 번째 레벨이다.

좋은 description의 구조는 다음과 같다: [무엇을 하는가] + [언제 사용하는가] + [주요 기능]

좋은 예시들을 살펴보자.

  
# 좋음 — 구체적이고 실행 가능함
description: Figma 디자인 파일을 분석하고 개발자 핸드오프 문서를 생성합니다.
  사용자가 .fig 파일을 업로드하거나 "디자인 스펙", "컴포넌트 문서", 
  "디자인-투-코드 핸드오프"를 요청할 때 사용하세요.

# 좋음 — 트리거 문구 포함
description: 스프린트 계획, 태스크 생성, 상태 추적을 포함한 Linear 
  프로젝트 워크플로우를 관리합니다. 사용자가 "스프린트", "Linear 태스크", 
  "프로젝트 계획"을 언급하거나 "티켓 만들기"를 요청할 때 사용하세요.

나쁜 예시들도 알아두자.

  
# 나쁨 — 너무 모호함
description: 프로젝트를 도와줍니다.

# 나쁨 — 트리거 없음
description: 정교한 다중 페이지 문서 시스템을 만듭니다.

# 나쁨 — 너무 기술적, 사용자 트리거 없음
description: 계층적 관계를 가진 Project 엔티티 모델을 구현합니다.

메인 지시문 작성하기

YAML 프런트매터 아래에 마크다운으로 실제 지시문을 작성한다. 플레이북이 권장하는 구조는 다음과 같다.

  
---
name: your-skill
description: [설명]
---

# 스킬 이름

## 단계 1: [첫 번째 주요 단계]
수행되는 작업의 명확한 설명.

예시:
```bash
python scripts/fetch_data.py --project-id PROJECT_ID

예상 출력: [성공 시 모습 설명]

예시들

예시 1: [일반적인 시나리오]

사용자 발화: “새로운 마케팅 캠페인 설정해줘” 동작:

MCP로 기존 캠페인 가져오기
제공된 파라미터로 새 캠페인 생성 결과: 확인 링크와 함께 캠페인 생성됨

트러블슈팅

오류: [일반적인 오류 메시지] 원인: [발생 이유] 해결책: [수정 방법]

### 지시문 작성의 모범 사례

**구체적이고 실행 가능하게 써라.** "적절히 검증하라"가 아니라 "데이터 형식을 확인하려면 `python scripts/validate.py --input {filename}`을 실행하라. 검증 실패 시 일반적인 문제로는 필수 필드 누락(CSV에 추가하라), 잘못된 날짜 형식(YYYY-MM-DD 사용)이 있다"처럼 써야 한다.

**에러 핸들링을 포함하라.** "연결 거부" 오류가 나면 어떻게 해야 하는지, MCP 서버 연결이 실패하면 무엇을 확인해야 하는지를 구체적으로 기술한다.

**번들된 리소스를 명확하게 참조하라.** "쿼리를 작성하기 전에 rate limit 가이드, 페이지네이션 패턴, 오류 코드 처리를 위해 `references/api-patterns.md`를 참조하라"처럼 구체적인 파일 경로를 명시한다.

**점진적 공개를 활용하라.** SKILL.md는 핵심 지시문에 집중하고, 상세 문서는 `references/` 폴더로 이동시킨 후 링크로 연결한다. 이렇게 하면 SKILL.md를 5,000단어 이하로 유지할 수 있다.

---

## 5장: 검증 및 반복 개선

### 세 가지 핵심 테스트 영역

**트리거 테스트:** 스킬이 적절한 시점에 로드되는지 확인한다. 명확한 태스크에서 트리거되는지, 다르게 표현된 요청에서도 트리거되는지, 그리고 관련 없는 주제에서는 트리거되지 않는지를 각각 확인해야 한다. Anthropic이 권장하는 테스트 방법은 간단하다 — Claude에게 직접 "언제 [스킬 이름] 스킬을 사용할 것인가요?"라고 물어보면, Claude가 description을 그대로 인용해 답한다. 그 답변을 보고 무엇이 빠졌는지 파악한 후 description을 조정한다.

**기능 테스트:** 스킬이 올바른 출력을 생성하는지 확인한다. 유효한 출력이 생성되는지, API 호출이 성공하는지, 에러 핸들링이 작동하는지, 엣지 케이스가 커버되는지를 검증한다.

**성능 비교:** 스킬 유무에 따른 결과를 비교한다. 스킬 없이는 매번 지시를 다시 제공해야 하고, 15번의 왔다갔다가 필요하며, 3번의 API 호출 실패가 발생하고, 12,000개의 토큰이 소비될 수 있다. 스킬이 있으면 자동 워크플로우 실행, 2번의 확인 질문만, API 호출 실패 0번, 6,000개의 토큰 소비로 극적으로 개선된다.

### skill-creator 스킬 활용하기

Anthropic은 스킬을 만들기 위한 스킬, 즉 `skill-creator`를 제공한다. 이 스킬은 Claude.ai의 플러그인 디렉토리나 Claude Code에서 이용할 수 있다. MCP 서버가 있고 상위 2~3가지 워크플로우를 알고 있다면, 단 15~30분 안에 동작하는 스킬을 만들고 테스트할 수 있다.

skill-creator는 자연어 설명으로부터 스킬을 생성하고, 올바른 형식의 SKILL.md와 프런트매터를 자동으로 만들어준다. 또한 기존 스킬을 리뷰하여 모호한 description, 빠진 트리거, 구조적 문제를 찾아내고, 스킬의 목적에 맞는 테스트 케이스를 제안한다.

사용 방법은 간단하다: `"skill-creator 스킬을 사용해서 [내 유스케이스]에 대한 스킬 만들기를 도와줘"`라고 요청하면 된다.

### 반복 개선의 신호들

Skills는 살아있는 문서다. 다음과 같은 신호들을 기반으로 지속적으로 개선해야 한다.

**언더트리거링 신호:** 스킬이 사용되어야 할 때 로드되지 않는다. 사용자가 수동으로 활성화해야 한다. "언제 이 스킬을 써야 해요?"라는 지원 질문이 온다. 해결책: description에 더 많은 키워드와 트리거 문구를 추가한다.

**오버트리거링 신호:** 관련 없는 쿼리에서도 스킬이 로드된다. 사용자가 스킬을 비활성화하기 시작한다. 해결책: 네거티브 트리거를 추가하고 스코프를 더 구체화한다. 예를 들어 "간단한 데이터 탐색에는 사용하지 마세요(대신 data-viz 스킬을 사용하세요)"처럼 명시한다.

**실행 이슈 신호:** 일관성 없는 결과, API 호출 실패, 사용자의 잦은 수정. 해결책: 지시문을 개선하고 에러 핸들링을 추가한다.

---

## 6장: 5가지 핵심 패턴

이 패턴들은 초기 채택자들과 내부 팀들이 만든 스킬들에서 도출된 것으로, 잘 작동하는 것으로 검증된 접근법들이다.

### 패턴 1: 순차적 워크플로우 오케스트레이션

**사용 시기:** 사용자가 특정 순서로 다단계 프로세스를 수행해야 할 때.

이 패턴의 핵심은 각 단계가 명시적인 순서를 갖고, 단계 간의 의존성이 명확하며, 각 단계에서 검증이 이루어지고, 실패 시 롤백 지시가 있다는 것이다.

예를 들어 "신규 고객 온보딩" 워크플로우라면: ①MCP 도구 `create_customer`를 호출해 계정 생성 → ②결제 수단 검증을 기다리며 `setup_payment_method` 호출 → ③Step 1의 customer_id를 파라미터로 `create_subscription` 호출 → ④`send_email`로 환영 이메일 발송.

### 패턴 2: 다중 MCP 조율

**사용 시기:** 워크플로우가 여러 서비스에 걸쳐 있을 때.

예를 들어 디자인-개발 핸드오프 워크플로우는 네 개의 단계로 나뉜다. Phase 1(Figma MCP)에서 디자인 에셋을 내보내고, Phase 2(Drive MCP)에서 클라우드 스토리지에 업로드하며, Phase 3(Linear MCP)에서 개발 태스크를 생성하고, Phase 4(Slack MCP)에서 엔지니어링 팀에 알림을 보낸다.

이 패턴의 핵심 기법은 명확한 단계 분리, MCP 간 데이터 전달, 다음 단계로 넘어가기 전 검증, 중앙화된 에러 핸들링이다.

### 패턴 3: 반복적 정제

**사용 시기:** 출력 품질이 반복을 통해 향상될 때.

보고서 생성 워크플로우를 예로 들면: 먼저 초안을 작성하고 임시 파일에 저장한다. 그 다음 `scripts/check_report.py`를 실행해 누락된 섹션, 형식 불일치, 데이터 검증 오류를 식별한다. 확인된 각 문제를 해결하고 영향을 받은 섹션을 재생성하며 다시 검증한다. 품질 기준을 충족할 때까지 반복한다. 마지막으로 최종 형식을 적용하고 요약을 생성한 후 저장한다.

### 패턴 4: 컨텍스트 인식 도구 선택

**사용 시기:** 컨텍스트에 따라 다른 도구를 사용해 동일한 결과를 달성해야 할 때.

파일 저장 예시: 파일 유형과 크기를 확인하고, 10MB 이상이면 클라우드 스토리지 MCP, 협업 문서면 Notion/Docs MCP, 코드 파일이면 GitHub MCP, 임시 파일이면 로컬 스토리지로 라우팅한다. 중요한 것은 왜 그 저장소를 선택했는지를 사용자에게 투명하게 설명한다는 것이다.

### 패턴 5: 도메인 특화 지식

**사용 시기:** 도구 접근 이상의 전문 지식을 스킬에 내장해야 할 때.

금융 컴플라이언스 예시: 결제를 처리하기 전에 제재 목록 확인, 관할권 허용 여부 검증, 위험 수준 평가 같은 컴플라이언스 규칙을 적용하고 결정 사항을 문서화한다. 컴플라이언스 통과 시에만 결제 처리 MCP 도구를 호출하고 사기 방지 검사를 적용한다. 모든 컴플라이언스 확인과 처리 결정을 기록하고 감사 보고서를 생성한다.

---

## 7장: 배포 및 공유

### 현재 배포 모델

개인 사용자가 스킬을 설치하는 방법은 다음과 같다.

1. 스킬 폴더를 다운로드한다
2. 폴더를 압축(.zip)한다
3. Claude.ai → Settings → Capabilities → Skills에서 업로드한다
4. 또는 Claude Code의 스킬 디렉토리에 직접 배치한다

조직 수준의 배포도 가능하다. 2025년 12월 18일부터 관리자는 워크스페이스 전체에 스킬을 배포할 수 있다. 자동 업데이트와 중앙화된 관리도 지원된다.

### API를 통한 Skills 사용

프로그래밍 방식으로 사용하는 경우 — 애플리케이션, 에이전트, 자동화된 워크플로우 등 — API가 스킬 관리와 실행에 대한 직접적인 제어를 제공한다.

주요 기능으로는 `/v1/skills` 엔드포인트로 스킬 목록 조회 및 관리, Messages API 요청에 `container.skills` 파라미터로 스킬 추가, Claude Console을 통한 버전 관리 등이 있다.

```bash
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 4096,
    "container": {
      "skills": [
        {
          "type": "anthropic",
          "skill_id": "pptx",
          "version": "latest"
        }
      ]
    },
    "messages": [{"role": "user", "content": "재생에너지에 대한 프레젠테이션 만들어줘"}],
    "tools": [{"type": "code_execution_20250825", "name": "code_execution"}]
  }'

주의: API에서 Skills를 사용하려면 Code Execution Tool 베타가 필요하다.

오픈 스탠더드로서의 Skills

Anthropic은 Agent Skills를 오픈 스탠더드로 공개했다. MCP와 마찬가지로, Skills는 Claude든 다른 AI 플랫폼이든 상관없이 도구와 플랫폼 간에 이식 가능해야 한다는 철학을 담고 있다. 표준에 대한 자세한 정보는 agentskills.io에서 확인할 수 있다.

GitHub를 통한 배포 권장 접근법

GitHub에 호스팅: 공개 저장소, 설치 지시가 담긴 명확한 README, 예시 사용법과 스크린샷을 갖춘다.
MCP 문서에 연결: MCP 문서에서 스킬로 링크하고, 함께 사용할 때의 가치를 설명하며, 빠른 시작 가이드를 제공한다.
설치 안내 생성: 스킬 다운로드, Claude 설치, 활성화, 테스트의 네 단계를 명확하게 문서화한다.

8장: 트러블슈팅 완전 가이드

업로드 오류들

“Could not find SKILL.md in uploaded folder” 오류: 파일 이름이 정확히 SKILL.md(대소문자 구분)인지 확인한다.

“Invalid frontmatter” 오류: YAML 형식 문제다. 가장 흔한 실수는 --- 구분자 누락이나 따옴표가 닫히지 않은 것이다.

“Invalid skill name” 오류: name 필드에 공백이나 대문자가 포함된 것이다. my-cool-skill처럼 케밥케이스만 허용된다.

스킬이 트리거되지 않을 때

description 필드를 수정해야 한다. 빠른 체크리스트: 너무 일반적이진 않은가? (“프로젝트를 도와줍니다”는 작동하지 않는다) 사용자가 실제로 말할 법한 트리거 문구가 포함되어 있는가? 관련 파일 유형이 언급되어 있는가?

디버깅 접근법: Claude에게 “언제 [스킬 이름] 스킬을 사용할 건가요?”라고 물어보면 Claude가 description을 그대로 인용한다. 빠진 것이 무엇인지 파악한 후 조정한다.

스킬이 너무 자주 트리거될 때

description에 네거티브 트리거를 추가한다. 예: “고급 데이터 분석 스킬입니다. 통계 모델링, 회귀, 클러스터링에 사용하세요. 간단한 데이터 탐색에는 사용하지 마세요(대신 data-viz 스킬 사용).” 또는 스코프를 더 구체화한다 — “문서를 처리합니다” 대신 “계약 검토를 위한 PDF 법률 문서를 처리합니다”처럼.

지시문이 따르지 않을 때

지시문이 너무 장황한 경우: 핵심 지시문은 간결하게 유지하고, 글머리 기호와 번호 목록을 활용하며, 상세 참조는 별도 파일로 이동시킨다.

중요한 지시문이 묻혀있는 경우: 핵심 지시문은 맨 위에 배치하고, ## 중요 또는 ## 필수 헤더를 사용하며, 필요하다면 핵심 포인트를 반복한다.

모호한 표현의 경우: “제대로 검증하세요” 대신 “중요: create_project를 호출하기 전에 반드시 확인하세요: 프로젝트 이름이 비어있지 않아야 하고, 팀원이 최소 한 명 이상 지정되어야 하며, 시작 날짜가 과거가 아니어야 합니다”처럼 명확하게 쓴다.

고급 팁: 중요한 검증의 경우, 언어 지시문에 의존하는 대신 검사를 프로그래밍적으로 수행하는 스크립트를 번들하는 것을 고려하라. 코드는 결정적이지만, 언어 해석은 그렇지 않다.

대형 컨텍스트 이슈

스킬이 느리거나 응답 품질이 저하되면, SKILL.md 크기를 최적화한다(상세 문서를 references/로 이동하고, 5,000단어 이하로 유지). 동시에 활성화된 스킬이 20~50개를 초과하는지 평가한다.

9장: 첫 번째 스킬 10분 만에 만들기 — 실전 가이드

X(트위터)에서 화제가 된 “10분 만에 첫 Claude Skill 만들기” 체크리스트를 플레이북의 내용으로 구체화하면 다음과 같다.

□ 반복 가능한 태스크 하나를 선택하라 (간단하게 시작하라) 너무 복잡하게 시작하지 않는다. 처음엔 단일하고 명확한 태스크를 선택한다. 회의 준비 브리프, 주간 이메일 요약, 메모에서 콘텐츠 초안 작성, 리서치 보고서 등이 좋은 출발점이다.

□ 항상 필요한 입력값을 작성하라 스킬을 실행하기 위해 사용자가 제공해야 하는 것들을 명확히 정의한다. 예를 들어 회의 준비 브리프라면, 회의 참석자, 회의 주제, 사전 자료 등이 필수 입력값이다.

□ 단계별 프로세스를 나열하라 당신이 이 태스크를 직접 할 때 어떤 순서로 무엇을 하는지를 그대로 써내려간다. 이것이 스킬의 핵심 지시문이 된다.

□ “완료”가 어떤 모습인지 정의하라 출력물의 기준을 명확히 한다. 분량, 형식, 포함해야 할 섹션, 톤 등을 구체화한다.

□ 좋은 출력의 예시 3개를 추가하라 실제 좋은 결과물의 예시를 포함시키면 Claude가 목표를 훨씬 정확하게 이해한다.

□ 품질 체크리스트를 포함하라 출력을 완성하기 전에 Claude가 확인해야 할 항목들의 목록을 만든다.

이것을 SKILL.md로 저장하라. 이제 Claude는 당신의 워크플로우를 실행한다. 매번.

10장: Anthropic 제공 사전 빌드 Skills

Anthropic은 문서 생성을 위한 사전 빌드 Agent Skills를 제공한다. 이들은 Claude.ai의 유료 플랜 사용자와 Claude API를 통해 이용할 수 있다.

pptx: PowerPoint 프레젠테이션 생성. 슬라이드, 레이아웃, 형식 지원. xlsx: 수식, 차트, 데이터 분석을 포함한 스프레드시트 생성. docx: 서식 있는 Word 문서 생성 및 편집. pdf: PDF 문서 분석 및 텍스트 추출.

이 사전 빌드 스킬들은 Claude.ai가 내부적으로 문서 생성 기능을 구현할 때 사용하는 것과 동일한 Skills다. Anthropic은 이를 개발자들에게 참고 자료로 공개했다. GitHub 저장소 anthropics/skills에서 소스를 확인할 수 있다.

파트너 스킬도 존재한다. Asana, Atlassian, Canva, Figma, Sentry, Zapier 등 다양한 파트너 회사들이 자신들의 서비스에 맞는 Skills를 개발하여 제공하고 있다.

11장: Skills 생태계의 미래

오픈 스탠더드의 의미

Anthropic이 Agent Skills를 오픈 스탠더드로 공개했다는 것은 단순히 문서를 공개한 것 이상의 의미를 가진다. MCP가 AI 모델과 외부 도구 간의 연결 방식을 표준화했던 것처럼, Agent Skills는 AI 에이전트에 도메인 전문 지식을 주입하는 방식을 표준화하려 한다. 이것이 성공한다면, Skills는 특정 AI 플랫폼에 종속되지 않는 이식 가능한 지식 캡슐이 될 수 있다.

skills.sh와 마켓플레이스 생태계

오픈 스탠더드 공개와 함께 Skills 마켓플레이스 생태계가 형성되고 있다. 전 세계 개발자들이 자신의 Skills를 공유하고 발견할 수 있는 플랫폼들이 등장하고 있으며, 이는 MCP 생태계가 형성되던 초기 단계와 유사한 흐름이다.

Skills vs CLI 에이전트 논쟁

AI 도구 개발 커뮤니티에서는 Skills/MCP 방식과 CLI 네이티브 에이전트 방식 사이의 활발한 논쟁이 벌어지고 있다. CLI 기반 접근법의 지지자들은 모델이 이미 터미널 명령어를 잘 이해하고 있기 때문에, MCP보다 CLI 방식이 더 단순하고 효과적인 경우가 많다고 주장한다. 반면 Skills 지지자들은 도메인 특화 지식의 캡슐화와 이식성이라는 측면에서 Skills가 독보적인 가치를 제공한다고 반박한다. 이 두 접근법은 실제로는 상호 배타적이지 않으며, 유스케이스에 따라 최적의 조합이 달라진다.

맺음말: Skills가 바꾸는 것

Skills는 단순한 프롬프트 템플릿이 아니다. 이것은 AI와 인간이 협업하는 방식의 패러다임 전환이다.

기존 방식에서 사람은 매번 Claude에게 맥락을 제공하고, 방법론을 설명하고, 기준을 가르쳐야 했다. Skills가 있으면 이 전문 지식이 한 번 정의되고 영구적으로 재사용된다. 팀 전체가 동일한 방법론을 공유하고, 조직의 지식이 사라지지 않으며, AI와의 협업이 점점 더 효율적이 된다.

플레이북의 도입부에서 Anthropic이 말한 것처럼, Skills는 “Claude를 재설명 없이, 일관성 없는 출력 결과 없이 사용하는” 세계를 가능하게 한다. 하나의 스킬 = 수백 시간의 절약. 이것이 바로 이 32페이지 플레이북이 “금맥”으로 불리는 이유다.

부록: 빠른 참조 체크리스트

시작 전

2~3가지 구체적인 유스케이스 식별
필요한 도구 확인 (내장 기능 또는 MCP)
공식 가이드 및 예시 스킬 검토
폴더 구조 계획

개발 중

폴더 이름: 케밥케이스
SKILL.md 파일 존재 (정확한 철자)
YAML 프런트매터에 --- 구분자 있음
name 필드: 케밥케이스, 공백 없음, 대문자 없음
description에 무엇을 하는지 + 언제 사용하는지 포함
XML 태그(< >) 없음
지시문이 명확하고 실행 가능함
에러 핸들링 포함
예시 제공
참조 파일 명확하게 링크됨

업로드 전

명확한 태스크에서 트리거 테스트
다르게 표현된 요청에서도 트리거 테스트
관련 없는 주제에서는 트리거 안 됨 확인
기능 테스트 통과
.zip으로 압축

업로드 후

실제 대화에서 테스트
언더/오버 트리거링 모니터링
사용자 피드백 수집
description과 지시문 반복 개선
메타데이터의 버전 업데이트

참고 자료

Anthropic 공식 플레이북: The Complete Guide to Building Skills for Claude
Agent Skills 개요: platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
Anthropic 엔지니어링 블로그: Equipping Agents for the Real World with Agent Skills
GitHub 공식 Skills 저장소: github.com/anthropics/skills
Claude Code Skills 문서: code.claude.com/docs/en/skills
Agent Skills 오픈 스탠더드: agentskills.io

작성 일자: 2026-03-11

AI, Agent Skills