Claude 스킬 만들기 가이드

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

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

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

description이 전부다

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

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

Claude Code에서는 트리거 문구를 when_to_use 필드로 따로 적을 수 있다. 스킬 목록에는 description 뒤에 when_to_use가 붙어 합쳐서 1,536자(skillListingMaxDescChars)에서 잘린다. 스킬 목록 전체도 맥락의 일정 비율(skillListingBudgetFraction, 예 0.01) 안에 들어가야 해서, 넘치면 덜 쓰는 스킬은 이름만 남는다. /context에서 제외 경고를 보고, /skills에서 t로 토큰순 정렬하고, /skill-doctor로 안 쓰는 스킬과 맥락 비용을 확인한다.

폴더와 지시문 규칙

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

Claude Code 프론트매터 필드

본문에 !`명령`을 넣으면 스킬을 부를 때 그 셸 출력이 프롬프트에 주입되고 모델은 결과만 본다. 명령·스킬·서브에이전트 중 무엇을 고를지는 커맨드·스킬·서브에이전트 고르기에 정리했다.

모노레포에서 스킬 찾기

스킬은 네 곳에서 읽힌다: 조직(관리 설정), 개인 ~/.claude/skills/, 프로젝트 .claude/skills/, 플러그인 <plugin>/skills/. 이름이 겹치면 조직 > 개인 > 프로젝트 순으로 이기고, 플러그인 스킬은 플러그인:스킬 이름공간이라 겹치지 않는다.

모노레포에서는 CLAUDE.md와 규칙이 다르다(Claude Code 메모리).

예를 들어 루트에서 시작하면 루트 .claude/skills/의 shared-conventions만 보이고, packages/frontend/src/App.tsx를 편집한 뒤에야 react-patterns가 더해진다. 반대로 packages/frontend에서 시작하면 둘 다 처음부터 보인다. 그래서 공용 워크플로는 루트에, 패키지 전용 스킬은 패키지 폴더에 두고, 이름에 패키지 접두사(frontend-review, backend-deploy)를 붙인다.

스킬의 아홉 가지 유형

좋은 스킬은 한 유형에 깔끔히 들어가고, 헷갈리는 스킬은 여러 유형에 걸쳐 있다.

제품 검증 스킬은 엔지니어 한 명이 일주일을 들여도 아깝지 않을 만큼 효과가 크다.

쓰는 법

테스트와 증상별 대응

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

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

배포

규모에 따라 배포 방식이 바뀐다. 작은 팀·소수 저장소는 .claude/skills에 커밋하면 충분하다. 하지만 커밋된 스킬마다 description이 맥락을 조금씩 차지하므로, 규모가 커지면 사내 플러그인 마켓플레이스에 올려 각자 골라 설치하게 한다. 큐레이션은 중앙 팀 없이도 된다: GitHub 샌드박스 폴더에 올리고 Slack에 알린 뒤, 반응이 오면 소유자가 마켓플레이스로 옮기는 PR을 연다. 스킬 사이 의존성은 아직 네이티브로 관리되지 않는다. 다른 스킬을 이름으로 언급하면 설치돼 있을 때 모델이 부른다.

공개할 때는 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

지식을 원격 MCP로 제공하기

책이나 강의처럼 내용 자체가 자산인 전문 지식(보안 점검 기준, 클라우드 IaC 검수 규칙 등)은 로컬 스킬 파일 대신 원격 MCP 서버로 제공하는 방식도 있다. 코딩 에이전트는 코드 작성·리뷰·리팩터링 중에 그 서버를 도구로 불러 지식을 참고한다.

절차·워크플로처럼 에이전트의 행동을 바꾸는 것은 스킬이, 자주 바뀌거나 여러 환경에서 공유할 참고 지식은 원격 MCP가 맞다.

실전 패턴 다섯 가지

정리

• 스킬은 프론트매터 → 본문 → 참조 파일 순으로 필요할 때만 읽힌다. 다른 스킬과 함께 로딩돼도 충돌하지 않게 쓴다.
• 트리거는 description 하나에 달렸다. what과 when을 담는다.
• 본문은 짧게, 지시는 실행 가능한 명령으로, 중요한 검증은 스크립트로 둔다.
• 어려운 작업 하나를 성공시킨 뒤 스킬로 뽑고, 증상에 따라 description과 지시문을 고친다.
• 스킬은 한 유형에 맞추고, Claude가 실패한 지점을 gotchas로 쌓아 키운다. 모노레포에서는 패키지 폴더에 두고 접두사를 붙인다.

관련 노트: Claude Code 활용 가이드, 커맨드·스킬·서브에이전트 고르기, 디자인 시스템을 아는 화면 생성 에이전트 설계하기, 디자인 시스템: 구성, 도입, 구축과 배포