Claude Code 스킬 기초 완전 가이드 — 레시피책 방식의 단계적 개시부터 skill-creator·스크립트 분담까지

디자인 규칙을 몇 번이고 설명하고, 비슷한 개발에서 매번 같은 프롬프트를 주고…. 이런 반복의 해결책으로 CLAUDE.md 에 지식을 밀어 넣는 수가 있지만, 너무 쓰면 컨텍스트가 빵빵해집니다. 규칙(.claude/rules)으로 동적으로 읽혀도, 조건에 맞으면 필요 없는 장면에서도 읽혀 버리고요.

여기서 도움이 되는 것이 스킬입니다. 스킬은 Claude 스스로 "이 지식이 필요하다"고 판단했을 때만 읽히는 구조라, 컨텍스트를 절약하면서 필요한 지식을 필요한 때에 로드할 수 있습니다.

이 글에서는 스킬의 개념 → SKILL.md → 대화 형식 작성 → 서포트 파일 → 스크립트 연계까지를 한 편에 정리했습니다.

이 글에서 알 수 있는 것

• 스킬의 개념과 "단계적 개시"의 구조
• SKILL.md 의 기본 구조와, 발동을 좌우하는 description 작성법
• skill-creator 를 이용한 대화 형식 스킬 작성
• 서포트 파일로 SKILL.md 를 가볍게 유지하는 방법
• 스크립트를 짜 넣어 AI와 기계 처리를 분담시키는 방법

제1장: 스킬이란(개념)

레시피책처럼 "필요할 때만 펼친다"

스킬은 요리 레시피책 같은 것입니다. 평소엔 책장에 책등(이름과 설명)만 보이다가, "오늘은 파스타를 만들자"고 정한 순간 그 레시피가 적힌 페이지를 펼친다. 이 "필요할 때만 펼친다"가 포인트예요.

CLAUDE.md 와 규칙이 지정한 조건에서 반드시 읽히는 것과 달리, 스킬은 Claude 스스로 필요하다고 판단했을 때 읽힌다는, 판단 방식이 근본적으로 다릅니다. 그래서 극단적으로 말하면 수백 개의 스킬을 등록해도 컨텍스트 압박은 미미하게 끝납니다.

단계적 개시(3단계)

스킬은 단계적 개시라는 방식으로 필요한 만큼만 읽힙니다.

레시피책으로 치면 제1단계가 책등, 제2단계가 "파스타의 기본 삶는 법", 제3단계가 "카르보나라/아라비아타 만드는 법" 같은 개별 페이지입니다.

CLAUDE.md·규칙·스킬의 차이

구분 사용으로는, CLAUDE.md 에는 정말 기본적인 규칙만 쓰고, 특정 작업에서만 필요한 전문 지식은 스킬로 모으는 분담이 깔끔합니다. "프런트엔드용 스킬", "백엔드용 스킬"로 나누기만 해도 효과가 있어요.

플러그인으로 남의 스킬을 빌린다

자작이 기본이지만, 플러그인이라는 구조로 다른 사람(이나 Anthropic 공식)이 만든 스킬을 설치해 빌려 옵니다. 배포 장소를 마켓플레이스라 부르고, "마켓플레이스 등록 → 플러그인 설치"라는 흐름입니다.

유명한 것이 공식 frontend-design 스킬. 흔한 "AI스러운" 디자인(묘하게 보랏빛이 도는 색·과한 그러데이션·이모지 남용)이 아니라, 디자이너가 만든 듯한 정돈된 겉모습으로 만들어 준다고 평판이 좋고, 이걸 넣기만 해도 AI 티가 꽤 빠집니다.

제2장: SKILL.md의 기본 구조

배치 장소

스킬은 하나당 폴더 하나를 마련하고, 그 바로 아래에 **SKILL.md(필수)**를 둡니다.

필수 필드는 name과 description

SKILL.md 는 YAML 프론트매터와 본문으로 구성됩니다. 본문에는 읽힌 뒤 써 주길 바라는 지식·지시를 씁니다.

---
name: material-design
description: Google 머티리얼 디자인에 준거한 UI를 작성하기 위한 스킬. 컬러 시스템·컴포넌트·레이아웃을 다룬다. UI나 컴포넌트를 디자인할 때 쓴다.
---

# 머티리얼 디자인 UI

## 기본 규칙
- 둥근 모서리를 기조로 하고, 여백은 8dp 그리드에 맞춘다
...

• name: 소문자·하이픈·숫자만.
• description: 언제 쓰는가·무엇을 할 수 있는가를 쓴다. 이걸 바탕으로 Claude가 읽을지 말지를 판단하는 최중요 필드입니다.

description이 발동의 결정타

description 이 애매하면 필요성을 판단하지 못해 적절한 장면에서 발동하지 않습니다. "만들었는데 발동 안 한다"의 태반은 여기가 원인이에요.

• 나쁜 예: "파일을 처리한다"(너무 애매)
• 좋은 예: "Excel 파일의 분석과 그래프 작성을 한다. 스프레드시트나 피벗 테이블을 처리할 때 쓴다"

무엇을 하는가 + 언제 쓰는가 + 구체적인 키워드를 넣을수록 발동하기 쉬워집니다(이 부분은 서브에이전트의 description 과 같은 사고방식입니다).

description 은 항상 컨텍스트에 실리기 때문에, 너무 길어도 효율이 나빠집니다. 요점(주요 유스케이스)을 앞머리에 쓰는 것이 요령이에요. 또 파일 패턴으로 자동 발동시키고 싶다면 paths(글로브 패턴) 필드도 있습니다.

제3장: 대화 형식으로 만들기(skill-creator)

처음부터 description 까지 잘 쓰기는 어렵습니다. 그래서 편리한 것이 공식 플러그인 skill-creator, 말하자면 "스킬을 만들기 위한 스킬"입니다. 이걸 쓰면 작성법을 몰라도 발동하기 쉬운 스킬이 만들어져요.

도입은 "마켓플레이스 등록 → 플러그인 설치"입니다.

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

마켓플레이스명·플러그인명은 업데이트로 바뀌는 경우가 있습니다. 잘 안 되면 배포처 GitHub의 README나 /plugin 메뉴, 혹은 "skill-creator install Claude Code"로 검색해 최신 커맨드를 확인하세요.

도입 후에는 스킬명(이나 포함된 플러그인명)을 프롬프트에 넣어 의뢰합니다.

skill-creator 를 써서, Google 머티리얼 디자인에 준거한 UI를 작성하기 위한
스킬을 이 프로젝트의 .claude/skills/ 에 작성해 주세요.

대화 중에 "커버하고 싶은 기능(컬러 시스템·컴포넌트·레이아웃 등)"을 질문받고, 그에 맞춰 SKILL.md 와 서포트 파일이 생성됩니다.

확실히 발동시키는 2가지 요령

데모에서도 그대로 작업이 시작되어 스킬이 발동하지 않는 경우가 있습니다. 그럴 때는 다음 2가지가 유효해요.

1. 스킬명을 명시적으로 넣는다: "이 스킬(〇〇)을 써서 작성해 주세요". 거의 확실히 발동합니다.
2. CLAUDE.md 에 쓸 수 있는 스킬을 적어 둔다: 스킬의 존재를 항상 인식시켜 적극적으로 쓰게 하는 방법. 자주 쓰는 수입니다.

이상적인 건 description 만으로 자동 발동하는 것이지만, 확실히 부르고 싶은 장면에서는 이것들을 병용합시다.

제4장: 서포트 파일로 SKILL.md를 가볍게 유지한다

SKILL.md 가 커지면 필요 없는 지식까지 항상 읽혀 버립니다. 그걸 막는 것이 서포트 파일입니다.

SKILL.md는 "목차", 상세는 필요할 때만

레시피책에서 필요한 페이지만 펼치듯, SKILL.md 로 전체 그림(목차)을 잡고 상세는 참조할 때만 읽힙니다.

폴더 구성 예:

.claude/skills/
└── material-design/
    ├── SKILL.md          # 필수: 개요+목차(책등 역할)
    ├── reference/        # 상세 사양(필요할 때만)
    │   ├── colors.md
    │   └── components.md
    ├── examples.md       # 사용 예·템플릿
    └── scripts/
        └── check.py      # 스크립트(실행된다)

이렇게 해 두면 페이지 전체를 설계할 때는 레이아웃 자료, 컴포넌트만 만들 때는 컴포넌트 자료, 하는 식으로 필요한 지식만 단계적으로 읽힙니다.

분할의 요령과 주의점

• 반드시 SKILL.md 에서 참조시킨다: Markdown 링크([colors](reference/colors.md))든 @ 붙임이든 동작합니다. 참조하지 않으면 어디에 무엇이 있는지 몰라 읽히지 않아요.
• 계층은 기본 1계층까지: reference/ 아래에서 다시 프런트/백으로 깊게 나누면 복잡해집니다.
• 깊게 나뉜다면 스킬 분할의 신호: 자료가 대량·깊어지면 스킬 하나의 책무가 너무 크다는 신호. 내용별로 다른 스킬로 나누는 쪽이 관리도 컨텍스트 효율도 좋아집니다.
• SKILL.md 자체는 간결하게(기준으로 수백 행 이내) 유지합시다.

reference(상세 사양·옵션·설정·트러블 대처)와 examples(샘플 코드·템플릿)라는 구분이 정석이지만, 이름은 자유입니다(SKILL.md 에서 참조시키는 것만이 필수).

제5장: 스크립트 연계(AI × 스크립트)

스킬에는 스크립트(Python이나 셸)를 짜 넣을 수 있는데, 포인트는 자연어 처리·판단은 AI, 기계적이고 결정론적인 처리는 스크립트, 로 역할을 나누는 것입니다.

왜 역할을 나누는가

전부를 AI에 맡기면 (1) 토큰 소비가 많다, (2) 절차 누락·실수가 일어날 수 있다, (3) 재현성이 높지 않다, 는 문제가 있습니다. 한편 스크립트만으로는 맥락에 따른 판단을 못 하죠. 양쪽의 특기 분야를 조합합니다.

예를 들어 릴리스 작업이라면, 변경 이력 집필(Git 로그와 PR을 읽고 요약)은 AI, 버전 갱신·태그 생성·push는 스크립트, 라는 분담이 됩니다.

검증 → 수정의 피드백 루프

스크립트의 진가는 검증해서 오류가 나오면 AI가 고치는 루프를 돌릴 수 있다는 점입니다.

예를 들어 문서 체크라면 "JavaScript 표기 불일치 통일", "개요·사용법·주의 사항 섹션이 있는지 확인" 같은 체크를 Python 스크립트로 하고, 모자라면 AI가 고치고, 재체크… 를 반복합니다.

스크립트의 속은 읽히지 않고 "결과만"

스크립트로 잘라내면 그 속은 읽히지 않고 실행되며, 결과만 컨텍스트에 들어갑니다. 이것이 효율화의 핵심으로, 대량의 파일을 AI가 직접 읽는 것보다 고속에 토큰 절약하면서 넓게 체크할 수 있어요. 호출 순서("먼저 변경 이력 갱신 → 다음에 스크립트로 체크" 등)는 SKILL.md 에 명시적으로 써 둡시다.

참고로 이 스크립트들도 skill-creator 에게 만들게 할 수 있으니, Python이나 셸 지식이 없어도 괜찮습니다.

정리: 스킬 체크리스트

• 스킬은 Claude가 필요하다고 판단했을 때만 읽힌다(레시피책 방식)
• 단계적 개시: 메타데이터 → SKILL.md → 서포트 파일, 로 필요한 만큼만 로드
• 배치는 .claude/skills/<이름>/SKILL.md(프로젝트) / ~/.claude/skills/(사용자)
• SKILL.md 의 description 이 발동의 결정타. 언제 쓰는가+구체 키워드를 쓴다
• 헷갈리면 skill-creator 플러그인으로 대화 생성(이름·커맨드는 최신 확인)
• 발동하지 않으면 스킬명을 명시 or CLAUDE.md 에 적어 둔다
• 상세는 서포트 파일로 나눠 SKILL.md 를 가볍게(참조는 SKILL.md에서. 계층은 1개까지)
• 기계적인 처리는 스크립트로. 검증→수정 루프로 토큰 절약 & 확실성 업

스킬을 잘 다루느냐로 AI 주도 개발의 효율과 품질은 크게 달라집니다. 우선은 효과가 눈에 잘 보이는 디자인 계열 스킬부터, skill-creator 를 써서 만들어 보세요.