Claude 스킬 만들기 가이드

스킬의 구조: 3단계 프로그레시브 디스클로저

스킬은 한 번에 다 읽히지 않고 필요한 만큼만 단계적으로 로딩된다. LLM 버전의 지연 로딩(lazy loading)이다.

단계	내용	언제 읽히나
1	YAML 프론트매터 (`name`, `description`), 스킬당 약 100토큰	항상 시스템 프롬프트에 들어간다. 스킬을 쓸지 판단하는 데만 쓰인다
2	`SKILL.md` 본문	관련 있다고 판단될 때
3	`references/` 등 링크된 파일	본문이 가리키고, 실제로 필요할 때

설계 원칙	뜻
합성성	여러 스킬이 동시에 로딩될 수 있다. 내 스킬만 단독으로 쓰인다고 가정하지 않는다
이식성	Claude.ai, Claude Code, API에서 똑같이 동작한다. Agent Skills는 개방형 표준이라 같은 폴더를 다른 에이전트 도구도 읽는다

MCP는 주방이고 스킬은 레시피다. MCP는 도구에 접근하게 해 줄 뿐이라, MCP만 있으면 사용자가 매번 사용법을 설명해야 한다. 스킬이 그 사용법을 담으면 워크플로가 알아서 켜지고 결과도 일관된다. 그래서 스킬의 쓰임은 세 갈래로 나뉜다.

유즈케이스	내용
문서·에셋 생성	문서, 디자인, 코드. Claude 기본 능력만으로 충분한 경우
워크플로 자동화	여러 단계 프로세스에 검증 게이트를 넣는 경우
MCP 강화	MCP 도구 위에 "어떻게 쓰는지"라는 워크플로 지식을 얹는 경우

description은 Claude가 스킬을 불러올지 결정하는 유일한 단서다. 시스템 프롬프트에 그대로 들어가므로 명세상 1,024자 이내여야 하고, claude.ai·API에 올릴 때는 XML 태그를 쓸 수 없다. 무엇을 하는가(what) 와 언제 쓰는가(when, 사용자가 실제로 칠 법한 트리거 문구) 를 반드시 담고, 핵심 쓰임을 맨 앞에 둔다.

# 나쁜 예: 언제 써야 하는지 알 수 없음
description: 프로젝트 관리를 돕는다.
 
# 좋은 예: 하는 일 + 트리거 문구
description: 스프린트 계획을 세우고 태스크를 생성한다. "sprint", "스프린트 계획", "create tickets" 같은 요청에 사용.

폴더와 지시문 규칙

your-skill/
├── SKILL.md      ← 필수, 파일명 정확히
├── scripts/      ← 선택: 실행할 스크립트
├── references/   ← 선택: 필요할 때 읽을 상세 문서
└── assets/       ← 선택: 템플릿, 이미지 등

규칙	내용
이름	소문자·숫자·하이픈만, 64자 이내, 폴더명과 같게 (`my-skill` O, `My_Skill` X). claude.ai·API에 올리는 스킬은 `claude`, `anthropic`을 쓸 수 없다
프론트매터	명세상 `name`과 `description`이 필수다. Claude Code는 `name`이 없으면 폴더명을 쓰고, `allowed-tools`·`disable-model-invocation` 같은 확장 필드를 더 받는다
README	스킬 폴더 안에 두지 않는다. 설명은 `SKILL.md`나 `references/`로
분량	`SKILL.md`는 500줄 이내(본문 5,000토큰 안팎). 핵심 지시는 맨 위에, 상세는 `references/`로 빼고 참조는 한 단계 깊이까지만 건다
지시문	"데이터를 검증하라" 같은 모호한 말 대신 실행할 명령(`python scripts/validate.py input.csv`)을 적고, 실패했을 때 어떻게 할지(에러 처리)를 반드시 쓴다

테스트와 증상별 대응

처음부터 범용 스킬을 설계하지 않는다. 어려운 작업 하나를 먼저 성공시키고 그 방법을 스킬로 뽑아낸다. 구체적인 성공을 일반화하는 순서가 반대보다 훨씬 잘 된다.

테스트	확인할 것
트리거 테스트	관련 질문에선 뜨고, 무관한 질문에선 안 뜨는가
기능 테스트	결과가 정확한가, 에러를 제대로 처리하는가
성능 비교	스킬 유무에 따른 대화 횟수·토큰·API 실패 수. 가이드의 예시에서는 대화 15회 → 2회, 토큰 12,000 → 6,000, API 실패 3회 → 0회

성공 기준은 정량(관련 질문의 약 90%에서 스킬이 뜬다, API 실패 0건)과 정성(사용자가 "다음엔 뭐 해요?"라고 묻지 않고, 교정 없이 끝까지 가고, 세션이 바뀌어도 결과가 같다)으로 나눠 잡는다.

증상	원인	대응
언더트리거 (안 뜸)	description에 단서 부족	키워드·트리거 문구 추가
오버트리거 (엉뚱할 때 뜸)	범위가 너무 넓음	"이럴 땐 쓰지 마라" 네거티브 트리거 추가
지시를 안 따름, 결과가 들쭉날쭉	지시가 너무 길거나, 중요한 내용이 중간에 묻혔거나, 모호함	핵심 지시를 맨 위로 올리고 `## Critical` 같은 헤더로 강조한다. 중요한 검증은 자연어 대신 스크립트로 만든다. 스크립트는 매번 같은 결과를 낸다
전반적으로 느려짐	동시에 켜진 스킬이 20~50개를 넘음	관련 스킬을 "팩"으로 묶는다

배포

범위	방법
개인	폴더를 zip으로 묶어 Claude.ai에 업로드, 또는 `~/.claude/skills/`(내 모든 프로젝트)·`.claude/skills/`(이 저장소)에 넣기
플러그인	Claude Code 플러그인에 스킬을 담아 마켓플레이스로 배포. `/플러그인명:스킬명`으로 불린다
조직	관리자가 워크스페이스 전체에 배포
API	`/v1/skills` 엔드포인트, `container.skills` 파라미터, Agent SDK 연동

공개할 때는 GitHub 저장소에 올리고 설치 가이드를 붙인다. 소개할 땐 기능보다 결과를 말한다. "YAML 프론트매터와 마크다운이 담긴 폴더"보다 "팀 워크스페이스를 몇 초 만에 세팅"이 낫다.

팀 공용 스킬을 패키지로 배포하기

코딩 컨벤션, 커밋 규칙, 디자인 시스템 사용법처럼 여러 저장소가 같이 지켜야 하는 규칙을 저장소마다 .claude/skills/에 복사해 두면 금방 어긋난다. 디자인 시스템을 패키지로 배포하는 구조(디자인 시스템: 구성, 도입, 구축과 배포)를 스킬에도 적용한다. 중앙에서 한 번 수정하고, 각 저장소는 설치·업데이트만 한다.

skill-installer/
├── package.json
├── bin/install.js        # skills/ 아래 파일을 대상 저장소의 .claude/skills/로 복사
└── skills/team-dev-guide/SKILL.md
 
$ npx @my-org/skill-installer install team-dev-guide

요소	역할
중앙 스킬 저장소	스킬의 유일한 원본. 수정은 여기서만 한다
npm 패키지 + 설치 명령	버전이 추적되고, 각 저장소는 명령 한 줄로 `.claude/skills/<skill-name>/SKILL.md`를 받는다
자동 업데이트 PR	Renovate, Dependabot, GitHub Actions 스케줄 작업이 새 버전을 감지해 PR을 만든다. 변경 내역은 PR 리뷰로 확인한다

실전 패턴 다섯 가지

패턴	핵심	예
순차 워크플로	단계마다 검증 게이트를 두고, 단계 간 의존성과 실패 시 롤백 방법을 명시한다	고객 온보딩: 계정 생성 → 결제 설정 검증 → 구독 생성 → 환영 메일
다중 MCP 조율	여러 서비스 사이에서 데이터를 넘기고, 다음 단계 전에 검증한다	디자인 핸드오프: Figma 추출 → Drive 업로드 → Linear 태스크 → Slack 알림
반복 개선	초안 → 검증 스크립트 → 수정 → 재검증 루프. 품질 기준과 언제 멈출지를 미리 정한다	보고서 초안을 검사 통과까지 다듬기
상황별 도구 선택	목표가 같아도 상황에 따라 도구를 고르고, 판단 기준과 선택 이유를 드러낸다	큰 파일은 클라우드 스토리지, 협업 문서는 Notion, 코드는 GitHub
도메인 전문 지식	도구 연결은 누구나 하므로, 차별점은 지식을 코드화하는 데 있다	결제 전 컴플라이언스: 제재 목록 확인 → 관할권 검증 → 리스크 평가 → 감사 기록

정리

스킬은 프론트매터 → 본문 → 참조 파일 순으로 필요할 때만 읽힌다. 다른 스킬과 함께 로딩돼도 충돌하지 않게 쓴다.
트리거는 description 하나에 달렸다. what과 when을 담는다.
본문은 짧게, 지시는 실행 가능한 명령으로, 중요한 검증은 스크립트로 둔다.
어려운 작업 하나를 성공시킨 뒤 스킬로 뽑고, 증상에 따라 description과 지시문을 고친다.

버그 제보