필요할 때만 꺼내 쓰는 매뉴얼 | Skills

Overview

앞 레슨에서 Custom Command로 반복 프롬프트를 한 단어로 만들었습니다. 프롬프트 반복은 줄었지만, 프로젝트가 커지면 이번에는 지침 자체가 늘어납니다. 코드 리뷰 체크리스트, 배포 절차, 테스트 전략을 전부 CLAUDE.md에 넣으면 지침의 저주가 매 대화마다 다시 발동합니다.

이번 레슨은 전문 지침을 별도 파일로 묶어두고, 해당 작업이 시작될 때만 Claude가 스스로 꺼내 보는 Skill 의 원리를 배웁니다.

학습 목표

• 왜 CLAUDE.md에 모든 지침을 넣으면 안 되는지 설명할 수 있습니다
• Skill의 Progressive Disclosure 3단계 로드 구조를 이해합니다
• Custom Command와 Skill의 호출 방식 차이를 구분할 수 있습니다

매뉴얼이 다시 두꺼워지는 순간

Rules로 규칙을 경로별로 쪼갰고, Custom Command로 반복 프롬프트를 한 단어로 줄였습니다. 그런데 프로젝트가 커지면 이번엔 새로운 종류의 반복이 생깁니다. 작업 방식 자체가 한 페이지짜리 지침이 됩니다.

• "코드 리뷰는 이 순서로, 이 관점 5개를 체크하고, 이 형식으로 답해"
• "Todo 앱을 배포할 때는 이 체크리스트를 이 순서대로 돌리고, 실패 시 이 절차로 롤백해"
• "E2E 테스트는 이 헬퍼를 쓰고, 이 셀렉터 전략을 따르고, 실패 로그는 이 형식으로 저장해"

각각이 한 줄이 아니라 한 문단·한 페이지짜리 지침입니다. Custom Command로 저장할 수도 있지만, 호출하는 순간 본문이 통째로 컨텍스트에 들어옵니다. 한 페이지짜리 단순 프롬프트라면 괜찮지만, 참조 자료가 여러 개 딸린 다단계 작업에서는 부담입니다. CLAUDE.md에 넣으면 자동 로드는 되지만 매 대화마다 전체가 컨텍스트에 쌓입니다.

토큰 낭비보다 심각한 건 품질 저하입니다. 지침의 저주가 CLAUDE.md가 두꺼워질수록 매 대화마다 발동합니다. 버그 수정을 요청했는데 Claude가 배포 절차와 테스트 전략에도 주의력을 나눠 씁니다.

Rules가 "경로별로 켜고 끈다"는 조건으로 이 문제를 풀었다면, Skill은 다른 조건을 씁니다. 작업 주제가 맞을 때만 켭니다.

Skill: 작업이 시작될 때만 켜지는 매뉴얼

Skill은 .claude/skills/<이름>/SKILL.md 구조로 저장하는 전문 지침 묶음입니다.

CLAUDE.md는 색인 없는 손글씨 레시피 노트와 같습니다. 어디에 뭐가 적혔는지 모르니, 어떤 요리를 하려 해도 노트를 처음부터 다 펼쳐서 훑어야 합니다.

Skill은 목차와 색인이 잘 정리된 요리책에 가깝습니다. Claude는 매 대화 시작 시 책의 목차 한 장만 손에 듭니다. "김치찌개를 만들자" 라는 요청이 들어오면 목차에서 47쪽을 찾아 그 레시피 페이지만 펼쳐 봅니다. 나머지 페이지는 펴지 않습니다.

이 목차에 해당하는 것이 Skill의 이름표입니다. 매 대화가 시작될 때 Claude는 .claude/skills/ 폴더를 훑어 각 Skill의 이름표(name 한 줄과 description 한 줄)만 컨텍스트에 올려둡니다. SKILL.md 본문(실제 지침)은 이 시점엔 컨텍스트에 없습니다. 사용자가 관련 작업을 요청하면, 그때 Claude가 description을 보고 필요한 Skill을 골라 본문만 추가로 읽어 들입니다.

분량으로 보면 이름표는 Skill 하나당 50~100토큰, 본문은 보통 500~2,000토큰입니다. Skill 열 권이 있어도 평소 컨텍스트엔 표지 열 장만 떠 있는 셈입니다.

Progressive Disclosure: 세 단계로 나눠 꺼내 보기

Skill은 Progressive Disclosure(점진적 공개) 로 Context를 아낍니다. 필요한 만큼만, 필요할 때 단계적으로 공개합니다.

Step 1: 이름표 (매 대화)

세션이 시작되면 Claude는 각 Skill의 name 과 description 만 읽습니다. Skill 하나당 한 줄 정도로 매우 짧습니다.

# Claude 가 세션 시작 시 보는 Skill 목록
- commit: 변경사항을 Conventional Commit 형식으로 커밋
- code-review: PR 코드 리뷰 (보안 / 성능 / 타입 안정성)
- deploy-checklist: Production 배포 절차와 롤백 기준

Skill이 10개 있어도 이름표 목록 전체가 짧은 한 단락 크기입니다. CLAUDE.md에 같은 내용을 전부 넣으면 수만 토큰이 쌓이니 비교가 되지 않습니다.

Step 2: 지침 본문 (호출 시)

사용자가 /commit 으로 직접 부르거나, Claude가 description을 보고 이 Skill이 필요하다고 판단하면 해당 Skill의 SKILL.md 본문을 읽습니다. CLAUDE.md와 달리 필요한 Skill의 본문만 선택적으로 로드됩니다.

Step 3: 참조 파일 (필요 시)

Skill 폴더 안에 넣어둔 긴 레퍼런스·템플릿·스크립트는 실제로 필요한 순간에만 추가로 읽습니다. breaking-change-guide.md 는 breaking change가 감지될 때만 로드됩니다.

이 구조 덕분에 Skill에 참조 자료를 아무리 묶어 넣어도 사용하기 전까지는 Context에 쌓이지 않습니다.

Command vs Skill: 호출 주체

Custom Command와 Skill은 둘 다 .claude/ 아래에 저장하고 / 로 호출할 수 있어 겉보기엔 비슷합니다. 결정적 차이는 호출 주체입니다.

핵심은 첫 줄에 있습니다. Skill은 Claude가 자동으로 필요한 것을 꺼내 씁니다. 사용자가 "작업 끝났으니 커밋해줘"라고 자연어로 말해도 Claude가 commit Skill을 알아서 로드합니다. Command는 /commit 이라고 정확히 입력해야만 동작합니다.

핵심 포인트 정리

1. 지침의 저주: 프로젝트가 커지면 지침 종류가 늘어납니다. CLAUDE.md에 전부 쌓으면 매 대화마다 전체가 로드되어 Context가 낭비되고 준수율도 떨어집니다.
2. Progressive Disclosure: 세션 시작 시엔 이름표만, 호출 시 본문, 필요 시 참조 파일을 단계별로 로드합니다.
3. 호출 주체: Command는 사용자만 호출하고, Skill은 Claude도 자동으로 꺼냅니다. "커밋해줘" 같은 자연어 요청에도 Skill이 반응합니다.

FAQ

• Q: Skill을 몇 개까지 등록할 수 있나요?

  • A: 기술적 제한은 없습니다. 이름표 한 줄이 워낙 작아서 100개를 등록해도 전체 부담은 한두 페이지 분량입니다. 단 Skill이 너무 많으면 어느 것을 고를지 Claude가 헷갈릴 수 있으므로, description 을 구체적으로 써서 자동 판단의 정확도를 높이는 게 중요합니다.

• Q: CLAUDE.md에 "배포 요청일 때만 이 섹션을 읽어라" 같은 조건문을 두면 안 되나요?

  • A: Claude는 조건을 판단하기 전에 이미 CLAUDE.md 전체를 읽어 컨텍스트에 올립니다. 조건문은 어떤 지침을 따를지만 결정하지, 로드 자체를 막지 못합니다. Skill은 조건에 맞을 때만 본문이 로드되므로 Context 소비 자체를 줄입니다.

이어서 배울 내용

Skill이 Context를 아끼는 원리를 살펴봤습니다. 이제 직접 Skill을 만들어 봅니다. 다음 레슨에서는 Custom Commands 레슨의 /commit Custom Command를 Skill로 옮겨 자동 호출이 되도록 바꾸고, 같은 Skill을 Skill Creator로 자동 생성해 보며 두 방식의 차이를 느껴 봅니다.

• .claude/skills/<이름>/SKILL.md 구조와 frontmatter
• description 작성의 긍정 / 부정 트리거
• Skill Creator로 자동 생성과 description 다듬기