Claude Skills 완전 정복: 한 번 만들고 매번 쓰는 AI 워크플로우 구축법

Skill이란 무엇인가: 한 번 가르치고 매번 써먹는 구조

매번 대화를 시작할 때마다 "우리 팀은 이런 방식으로 일해"라고 Claude에게 설명해야 한다면 시간 낭비다. Skill은 이 문제를 해결한다. 간단히 말해, skill은 Claude에게 특정 워크플로우를 가르치는 폴더 패키지다. 한 번 만들어두면 관련 요청이 들어올 때마다 자동으로 활성화된다.

Skill이 빛을 발하는 순간은 반복 작업이 있을 때다. 예를 들면:

• 디자인 스펙을 받아 프론트엔드 코드를 생성하는 작업
• 팀 스타일 가이드에 맞는 문서 작성
• 여러 단계를 거치는 고객 온보딩 프로세스
• 일관된 방법론으로 리서치 수행

Skill 폴더의 구성은 단순하다. 필수 파일은 SKILL.md 하나뿐이고, 나머지는 선택이다.

• SKILL.md (필수): YAML frontmatter가 있는 Markdown 형식의 핵심 명령 파일
• scripts/ (선택): Python, Bash 등 실행 가능한 스크립트
• references/ (선택): 필요할 때 불러오는 참고 문서
• assets/ (선택): 템플릿, 폰트, 아이콘 등

설계 핵심 원칙: Progressive Disclosure

Skill의 핵심 설계 철학은 Progressive Disclosure다. 모든 정보를 한꺼번에 Claude의 컨텍스트에 올리는 대신, 필요할 때만 단계적으로 불러온다.

• 1단계 — YAML frontmatter: 항상 시스템 프롬프트에 로드된다. Claude가 "이 skill을 언제 써야 하는지" 파악할 만큼의 최소한의 정보만 담는다.
• 2단계 — SKILL.md 본문: 현재 작업과 관련 있다고 판단될 때 로드된다. 실제 실행 지침과 워크플로우가 담긴다.
• 3단계 — 링크된 파일: references/ 등 추가 파일로, Claude가 필요하다고 판단할 때만 접근한다.

이 구조 덕분에 토큰 소비를 최소화하면서도 전문적인 워크플로우를 유지할 수 있다.

또한 skill은 동시에 여러 개가 활성화될 수 있으므로(Composability), 내가 만든 skill이 다른 skill과 충돌하지 않도록 설계해야 한다. 그리고 Claude.ai, Claude Code, API 어디서든 동일하게 작동한다(Portability).

MCP와 Skill의 관계: 주방 도구 vs 레시피

MCP(Model Context Protocol)와 skill을 함께 쓴다면 훨씬 강력해진다. 구분이 명확하다.

• MCP = 전문 주방: Notion, Linear, Asana 같은 외부 서비스에 접근하는 도구와 재료를 제공한다.
• Skill = 레시피: 그 도구들을 어떤 순서로, 어떤 방식으로 써서 가치 있는 결과물을 만들지 알려준다.

Skill 없이 MCP만 연결한 사용자는 "이걸로 뭘 어떻게 해야 하지?"에서 막힌다. Sentry가 만든 sentry-code-review skill이 좋은 예다. MCP가 GitHub PR에 접근하는 도구를 제공하면, skill은 Sentry 에러 데이터를 분석해 버그를 자동으로 찾고 수정하는 전체 워크플로우를 실행한다. MCP만 있을 때와 달리 사용자는 매번 방법을 설명할 필요가 없다.

Skill 설계: 쓰기 전에 먼저 생각할 것들

코드를 짜기 전에 2~3개의 구체적인 use case를 정의하는 게 먼저다. 좋은 use case 정의는 이렇게 생겼다:

• 트리거: 사용자가 어떤 말을 할 때 활성화되는가
• 단계: 어떤 순서로 무엇을 실행하는가
• 결과: 최종 산출물이 무엇인가

Anthropic이 관찰한 skill의 세 가지 주요 카테고리는 다음과 같다.

• 카테고리 1 — 문서 및 에셋 생성: 일관된 품질의 문서, 프레젠테이션, 앱, 코드 등을 만드는 skill. 외부 도구 없이 Claude의 내장 기능만으로 동작한다. 핵심 기법은 스타일 가이드 내장, 품질 체크리스트, 일관된 템플릿 구조다.
• 카테고리 2 — 워크플로우 자동화: 여러 단계를 거치는 반복 프로세스를 일관된 방법론으로 실행한다. Anthropic의 skill-creator skill 자체가 이 카테고리다. 단계별 검증 게이트와 반복적 개선 루프가 핵심이다.
• 카테고리 3 — MCP 강화: 기존 MCP 통합에 워크플로우 지식을 더하는 skill. 여러 MCP 호출을 순서대로 조율하고, 도메인 전문 지식과 에러 처리 로직을 내장한다.

YAML Frontmatter: 가장 중요한 부분

Skill이 제대로 작동하려면 YAML frontmatter를 잘 써야 한다. Claude가 skill을 로드할지 판단하는 근거가 바로 여기에 있기 때문이다.

최소한의 형식은 이렇다:

• name (필수): kebab-case만 허용. notion-project-setup은 되고, Notion Project Setup이나 notion_project_setup은 안 된다.
• description (필수): "무엇을 하는가" + "언제 쓰는가"를 반드시 모두 담아야 한다. 1024자 이하, XML 태그 금지.

좋은 description과 나쁜 description의 차이는 뚜렷하다.

• ❌ 나쁜 예: "Helps with projects." — 너무 모호해서 Claude가 언제 써야 할지 모른다.
• ❌ 나쁜 예: "Creates sophisticated multi-page documentation systems." — 사용자가 실제로 쓸 트리거 문구가 없다.
• ✅ 좋은 예: "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'."

description 작성 공식: [무엇을 하는가] + [언제 쓰는가] + [핵심 기능]

선택 필드로는 license(오픈소스 라이선스), compatibility(환경 요구사항), metadata(author, version, mcp-server 등 커스텀 값)가 있다.

보안상 주의할 점: frontmatter에 XML 꺾쇠 괄호(< >)를 쓰면 안 된다. 시스템 프롬프트에 직접 삽입되기 때문에 악성 명령어 주입 위험이 있다. 또한 "claude"나 "anthropic"으로 시작하는 이름은 예약어라 사용할 수 없다.

SKILL.md 본문 작성: 구체적이고 실행 가능하게

Frontmatter 다음엔 실제 실행 지침을 Markdown으로 작성한다. 효과적인 지침의 핵심 원칙은 네 가지다.

• 구체적이고 실행 가능하게: "데이터를 검증하라"는 쓸모없다. "python scripts/validate.py --input {filename} 을 실행하고, 실패 시 누락 필드를 CSV에 추가하거나 날짜 형식을 YYYY-MM-DD로 수정하라"가 맞다.
• 에러 처리 포함: "Connection refused" 같은 흔한 에러 상황에서 어떻게 대응할지 단계별로 명시한다.
• 참조 파일 명시: 상세 문서는 references/ 폴더로 분리하고 SKILL.md에서 링크만 제공한다.
• Progressive Disclosure 활용: SKILL.md는 핵심 지침에 집중하고, 세부 사항은 references/로 넘긴다. 5,000단어 이내로 유지하는 것이 권장된다.

권장 구조는 단계별 Instructions → 시나리오별 Examples → 에러별 Troubleshooting 순이다.

테스트: 세 가지 영역을 반드시 확인하라

Anthropic이 권장하는 테스트 방법은 세 단계다. 팀 내부용 소규모 skill이라면 Claude.ai에서 직접 테스트하는 것으로 충분하고, 수천 명에게 배포하는 skill이라면 API를 통한 자동화 테스트 스위트가 필요하다.

팁: 먼저 가장 까다로운 단일 태스크에서 Claude가 성공할 때까지 반복 개선한 뒤, 그 접근법을 skill로 추출하는 방식이 가장 효율적이다.

1. 트리거 테스트 — skill이 올바른 타이밍에 활성화되는가?

• 명확한 관련 요청에서 트리거되는지 확인
• 다르게 표현된 같은 요청에서도 트리거되는지 확인
• 무관한 주제에서는 트리거되지 않는지 확인

2. 기능 테스트 — skill이 올바른 결과물을 만드는가?

• 유효한 출력이 생성되는지
• API 호출이 성공하는지
• 에러 핸들링이 작동하는지
• 엣지 케이스가 처리되는지

3. 성능 비교 — skill이 없을 때보다 실제로 나아졌는가?

• 대화 왕복 횟수가 줄었는가 (예: 15회 → 2회)
• 실패한 API 호출이 줄었는가
• 소비 토큰이 줄었는가 (예: 12,000 → 6,000)

트리거 문제 해결: 과소 vs 과잉 활성화

Skill을 배포하고 나면 두 가지 방향의 문제가 생길 수 있다.

과소 트리거(Undertriggering) — skill이 필요한데 활성화되지 않는 경우

• 증상: 사용자가 수동으로 skill을 켜거나, "언제 써야 해요?"라고 묻는다
• 해결: description에 사용자가 실제로 쓸 키워드와 문구를 더 구체적으로 추가한다
• 디버깅: Claude에게 "언제 [skill 이름] skill을 쓸 것 같아?"라고 물어보면 description을 그대로 인용한다. 거기서 빠진 것을 찾아 추가하면 된다.

과잉 트리거(Overtriggering) — 관련 없는 요청에도 활성화되는 경우

• 증상: 사용자가 skill을 비활성화하거나, 엉뚱한 상황에서 skill이 튀어나온다
• 해결: 네거티브 트리거를 추가한다. 예: "Do NOT use for simple data exploration (use data-viz skill instead)."

흔한 실수와 함정들

실제로 자주 발생하는 문제들과 해결책을 정리하면 다음과 같다.

• SKILL.md 파일명 오류: 반드시 대소문자 정확히 SKILL.md여야 한다. skill.md, SKILL.MD 모두 인식되지 않는다.
• 폴더명 규칙 위반: kebab-case만 허용. 공백, 언더스코어, 대문자 모두 금지다.
• README.md 포함: skill 폴더 안에 README.md를 넣으면 안 된다. 문서는 SKILL.md나 references/에 넣어야 한다. GitHub 배포 시 repo 최상위 README는 별도로 작성한다.
• YAML frontmatter 구분자 누락: ---로 시작하고 ---로 닫는 구분자가 없으면 frontmatter로 인식되지 않는다.
• 지나치게 장황한 SKILL.md: 내용이 너무 많으면 Claude가 지침을 놓치기 쉽다. 중요한 것은 위에 두고, 세부 내용은 references/로 분리한다. 핵심 검증 로직은 언어 지침 대신 스크립트로 구현하는 것이 더 안정적이다. 언어는 해석의 여지가 있지만 코드는 결정론적으로 작동하기 때문이다.
• 컨텍스트 과부하: 동시에 20~50개 이상의 skill이 활성화되면 응답 품질이 저하될 수 있다. 연관된 skill끼리 "pack"으로 묶어 선택적으로 활성화하는 방식을 권장한다.

5가지 실전 패턴

Anthropic 초기 도입자들이 검증한 패턴들이다. 상황에 따라 골라서 쓰면 된다.

• 패턴 1 — 순차 워크플로우 오케스트레이션: 정해진 순서대로 여러 단계를 처리해야 할 때. 각 단계 간 의존성, 검증 게이트, 실패 시 롤백 지침을 명시한다. 예: 신규 고객 온보딩 (계정 생성 → 결제 설정 → 구독 생성 → 환영 이메일).
• 패턴 2 — 멀티 MCP 조율: 여러 서비스에 걸친 워크플로우. 예: 디자인-개발 핸드오프 (Figma MCP → Drive MCP → Linear MCP → Slack MCP).
• 패턴 3 — 반복적 품질 개선: 초안 생성 → 품질 검증 → 개선 루프를 명확한 종료 조건과 함께 구성. 보고서 생성이나 코드 리뷰에 적합하다.
• 패턴 4 — 컨텍스트 기반 도구 선택: 상황에 따라 다른 도구를 써야 할 때. 의사결정 트리를 명시하고, 선택 이유를 사용자에게 투명하게 알린다. 예: 파일 크기와 유형에 따라 최적 스토리지 MCP를 자동 선택.
• 패턴 5 — 도메인 특화 지식 내장: 단순 도구 접근을 넘어 전문 지식이 필요한 경우. 예: 금융 결제 처리 skill에 제재 목록 확인, 관할권 검증, 감사 추적 로직을 내장.

배포: 개인 → 팀 → 오픈 생태계

현재(2026년 1월 기준) 배포 방식은 세 가지다.

• 개인 사용: skill 폴더를 zip으로 압축해 Claude.ai의 Settings → Capabilities → Skills에서 업로드, 또는 Claude Code의 skills 디렉토리에 배치한다.
• 조직 배포: 관리자가 2025년 12월 18일 출시된 워크스페이스 전체 배포 기능으로 중앙 관리 및 자동 업데이트를 할 수 있다.
• API 활용: /v1/skills 엔드포인트와 container.skills 파라미터로 프로그래매틱하게 관리. 프로덕션 배포, 자동화 파이프라인, agent 시스템 구축에 적합하다. 단, Code Execution Tool 베타 활성화가 필요하다.

Anthropic은 Agent Skills를 오픈 스탠다드로 공개했다. MCP처럼, 동일한 skill이 Claude뿐 아니라 다른 AI 플랫폼에서도 작동하도록 이식성을 보장하는 방향을 지향한다. 현재 Asana, Atlassian, Canva, Figma, Sentry, Zapier 등 파트너사 skill이 공개되어 있다.

GitHub에 배포할 때는 레포지토리 최상위에 README(설치 가이드, 스크린샷 포함)를 두되, skill 폴더 안에는 README.md를 넣지 않는 것이 규칙이다.

Skill 배포 전 최종 체크리스트

업로드 전에 이 항목들을 확인하자.

• 폴더명이 kebab-case인가
• 파일명이 정확히 SKILL.md인가 (대소문자 구분)
• YAML frontmatter에 --- 구분자가 있는가
• name이 kebab-case, 소문자인가
• description에 "무엇을" + "언제"가 모두 있는가
• XML 태그(< >)가 없는가
• 지침이 구체적이고 실행 가능한가
• 에러 처리가 포함되어 있는가
• 명확한 트리거에서 활성화되는지 테스트했는가
• 무관한 요청에서 활성화되지 않는지 확인했는가
• .zip 파일로 압축했는가

처음 skill을 만든다면 Claude.ai나 Claude Code에 내장된 skill-creator skill을 활용하자. 자연어로 use case를 설명하면 SKILL.md 초안을 자동으로 생성해주고, 트리거 문구 제안과 구조 검토도 해준다. 15~30분이면 첫 번째 작동하는 skill을 만들 수 있다.