2025년 5월에 출시된 Claude Code는 8개월 만에 가장 많이 쓰이는 AI 코딩 도구로 올라섰습니다. 이제 화두는 "AI를 쓸 것인가"가 아니라 "어떻게 길들일 것인가"입니다. 그 핵심에 Skill이 있습니다. 이 글은 동작 원리(progressive disclosure)부터 SKILL.md 구조, 2026년에 통합된 슬래시 커맨드와의 관계, 그리고 실제로 동작하는 Spring 리뷰 Skill을 직접 만드는 것까지 다룹니다.
1. 왜 지금 'Skill'인가
AI 코딩 도구를 어느 정도 써본 사람이라면 같은 경험을 합니다. "우리 프로젝트는 JPA 엔티티에 Lombok @Setter 안 쓰고, 응답 DTO는 record로, 트랜잭션은 서비스 레이어에만…" 같은 컨벤션을 매번 새 대화창에서 다시 설명하고 있는 자신을 발견하죠. 세션은 무상태(stateless)라서 어제 알려준 내용이 오늘은 사라집니다.
이걸 해결하려고 모든 걸 CLAUDE.md에 욱여넣으면 이번엔 다른 문제가 생깁니다. 세션을 열 때마다 그 거대한 파일 전체가 컨텍스트를 차지합니다. 정작 이번 작업과 무관한 배포 가이드, 테스트 전략, 도메인 용어집까지 전부 토큰을 먹습니다.
Skill은 바로 이 두 문제 — 반복 설명과 컨텍스트 낭비 — 를 동시에 푸는 메커니즘입니다. 한 번 만들어 두면 Claude가 관련 작업일 때만 알아서 꺼내 씁니다.
2. Skill이란 무엇인가
한 문장으로 정리하면 이렇습니다.
Skill은 SKILL.md 파일 하나(+선택적 리소스)로 구성된, 파일시스템 기반의 재사용 가능한 능력 패키지다. 새 팀원에게 건네는 온보딩 문서를 폴더로 만들어 둔 것이라고 생각하면 된다.
프롬프트와의 차이가 핵심입니다. 프롬프트는 한 번 쓰고 사라지는 일회성 지시입니다. Skill은 디스크에 남아 있고, 버전 관리되고, 팀과 공유되며, 필요할 때만 로딩됩니다. 폴더 구조는 이렇게 생겼습니다.
.claude/skills/spring-review/
├── SKILL.md # 필수: 메타데이터 + 핵심 지시
├── references/
│ ├── conventions.md # 팀 컨벤션 상세 (필요할 때만 로딩)
│ └── security.md # 보안 체크리스트
└── scripts/
└── check_naming.py # 결정적 검증 스크립트 (실행만, 코드는 미로딩)3. 핵심 원리: Progressive Disclosure (점진적 공개)
이 블로그를 보는 분들은 "왜 그렇게 동작하는가"를 궁금해할 테니, 토큰 경제학 관점에서 설명하겠습니다. Skill의 모든 설계는 점진적 공개라는 하나의 원리에서 나옵니다. 정보를 한 번에 다 펼치지 않고, 필요한 단계에서 필요한 만큼만 컨텍스트에 올립니다. 3단계로 나뉩니다.
| 레벨 | 로딩 시점 | 토큰 비용 | 내용 |
|---|---|---|---|
| L1 메타데이터 | 항상 (시작 시) | Skill당 약 100토큰 | YAML의 name + description |
| L2 지시문 | Skill이 트리거될 때 | 5k토큰 미만 | SKILL.md 본문 (워크플로·가이드) |
| L3+ 리소스 | 필요할 때만 | 사실상 무제한 | references/, scripts/ 등 번들 파일 |
핵심은 시작 비용이 지식의 총량이 아니라 Skill의 '개수'에 비례한다는 점입니다. SKILL.md 본문 300줄 + 참조 파일 1,000줄짜리 Skill 8개를 전부 컨텍스트에 올리면 대략 70,000토큰입니다. 하지만 점진적 공개에서는 시작 시 설명문만 모아 약 500토큰, 작업 중 어느 순간이든 보통 Skill 본문 하나 + 참조 파일 한두 개, 약 2,000토큰만 점유합니다.
스크립트는 한 단계 더 영리합니다. Claude가 check_naming.py를 실행하면 스크립트 코드 자체는 컨텍스트에 절대 들어오지 않고, 실행 결과("Validation passed" 같은 출력)만 토큰을 소비합니다. 결정적(deterministic) 검증을 매번 코드 생성으로 처리하는 것보다 훨씬 효율적이고 안정적인 이유입니다.
4. SKILL.md 구조 뜯어보기
모든 Skill은 YAML frontmatter가 있는 SKILL.md 하나로 시작합니다. 최소 형태는 이렇습니다.
---
name: spring-review
description: Spring/JPA 코드를 팀 컨벤션·버그·보안 관점에서 리뷰. 사용자가
PR 리뷰, 코드 점검, 머지 전 확인을 요청하거나 .java 변경분을 검토할 때 사용.
---
# Spring 코드 리뷰
## 리뷰 절차
1. 변경된 파일을 식별한다
2. 아래 항목을 순서대로 점검한다
...필수 필드는 name과 description 두 개뿐이며, 제약이 있습니다.
name: 최대 64자, 소문자·숫자·하이픈만 허용. XML 태그 불가.anthropic,claude같은 예약어 사용 불가.description: 비어 있으면 안 됨, 최대 1,024자. '무엇을 하는지'와 '언제 써야 하는지'를 모두 담아야 함.
가장 자주 하는 실수: description을 사람이 읽는 요약문으로 쓰는 것. description은 사람이 아니라 Claude가 "이 작업에 이 Skill을 꺼낼까?"를 판단하는 트리거입니다. 모호하면 발동하지 않고, 너무 좁으면 변형 요청에 발동하지 않습니다. 트리거가 될 만한 동사·키워드(리뷰, PR, 머지 전, .java 변경)를 의도적으로 박아 넣으세요.
본문은 일반 마크다운입니다. 단, 본문은 500줄 이하로 유지하는 것이 권장됩니다. 그 이상으로 길어지면 상세 내용을 references/로 분리하고 본문에서 링크만 겁니다. "복잡한 트랜잭션 경계 판단은 references/transactions.md 참고" 식으로요. 그러면 Claude는 복잡한 케이스를 만났을 때만 그 파일을 읽습니다. 이것이 점진적 공개를 실제로 구현하는 방법입니다.
5. 슬래시 커맨드 vs Skill: 2026년의 통합
이 부분이 많은 개발자를 헷갈리게 했고, 2026년에 정리됐습니다. 둘 다 /로 호출되고 둘 다 자동 발동될 수 있어서 헷갈렸는데, 원래는 별개 시스템이었습니다.
| 구분 | 레거시 커맨드 | Skill (권장) |
|---|---|---|
| 위치 | .claude/commands/ |
.claude/skills/ |
| 호출 | /review (사용자만) |
/review + Claude 자동 발동 |
| 번들 리소스 | 불가 (md 파일 하나) | 가능 (scripts/references/assets) |
| 동작 제어 frontmatter | 제한적 | 풍부 (아래 참고) |
현재 상태: 두 형식이 통합됐습니다. .claude/commands/review.md와 .claude/skills/review/SKILL.md는 둘 다 /review를 만들고 동일하게 동작합니다. 기존 .claude/commands/ 파일은 그대로 계속 작동하므로 지금 당장 마이그레이션할 필요는 없습니다. 다만 같은 이름이 충돌하면 Skill이 우선합니다(commands/review.md와 skills/review/SKILL.md가 둘 다 있으면 Skill 버전이 쓰임). 새로 만드는 것은 Skill로 가는 것이 권장됩니다.
Skill만 지원하는 frontmatter 옵션들이 통합의 실익입니다.
user-invocable/disable-model-invocation: 사용자가/로만 부를지, Claude가 자동 발동도 할지 제어allowed-tools: 이 Skill이 쓸 수 있는 도구를 화이트리스트로 제한context: fork: 격리된 서브에이전트 컨텍스트에서 실행 (메인 상태 오염 방지)model: 이 Skill을 실행할 모델 지정argument-hint:/review [파일경로]처럼 인자 힌트 제공
참고로 Claude Code의 Skill은 핫 리로드됩니다. ~/.claude/skills나 .claude/skills에서 Skill을 만들거나 수정하면 세션 재시작 없이 즉시 반영됩니다. 이전의 멈췄다 켜는 마찰이 사라져서 개발 반복이 빨라졌습니다.
6. Skill vs MCP vs CLAUDE.md vs Subagent
이 네 가지가 자주 혼동됩니다. 한 줄로 구분하면 이렇습니다.
| 메커니즘 | 한 줄 정의 | 언제 쓰나 |
|---|---|---|
| Skill | "어떻게 하는지"를 가르침 (절차·지식) | 반복되는 워크플로·팀 규칙을 패키징 |
| MCP | 외부 시스템에 "접근"을 제공 | DB·Jira·사내 API 등 연결이 필요할 때 |
| CLAUDE.md | 매 세션 로딩되는 영구 프로젝트 브리프 | 항상 필요한 최소한의 프로젝트 개요 |
| Subagent | 격리된 컨텍스트의 위임 작업자 | 메인 컨텍스트를 오염시키지 않을 병렬 조사 |
실무 감각: CLAUDE.md는 가볍게 유지하고(프로젝트 한 페이지 요약), 무거운 절차 지식은 Skill로 빼고, 외부 데이터 접근은 MCP로, 컨텍스트가 큰 탐색 작업은 Subagent로 위임합니다. "Skill은 방법을 가르치고, MCP는 접근을 준다"가 핵심 구분선입니다.
7. 실전: Spring 코드 리뷰 Skill 만들기
이론은 충분합니다. 백엔드 개발자가 바로 써먹을 수 있는, 실제로 동작하는 Skill을 만들어 봅시다. PR 머지 전 우리 팀 컨벤션·버그·보안을 점검하는 spring-review Skill입니다.
Step 1. 디렉토리 생성
프로젝트 공유용이면 .claude/skills/, 모든 프로젝트에서 쓰려면 ~/.claude/skills/ 아래에 둡니다.
mkdir -p .claude/skills/spring-review/referencesStep 2. SKILL.md 작성 (본문은 얇게)
---
name: spring-review
description: Spring/JPA 코드를 팀 컨벤션·버그·보안 관점에서 리뷰한다.
사용자가 PR 리뷰, 코드 점검, 머지 전 확인을 요청하거나, staged 된
.java 변경분을 검토해 달라고 할 때 사용한다.
---
# Spring 코드 리뷰
## 절차
1. `git diff --staged --name-only` 로 변경된 .java 파일을 식별한다.
2. 각 파일을 아래 관점으로 점검한다.
- **컨벤션**: references/conventions.md 의 규칙을 위반하지 않는가
- **버그**: null 처리, 트랜잭션 경계, N+1 쿼리, 동시성
- **보안**: references/security.md 체크리스트
3. 발견 사항을 파일·라인 기준으로 표로 정리하고,
심각도(High/Med/Low)와 구체적 수정안을 함께 제시한다.
4. 위반이 없으면 "통과"로 명확히 보고한다.
## 출력 형식
- 먼저 한 줄 요약(머지 가능 여부)
- 그다음 발견 사항 표
- 코드 제안은 diff 블록으로본문에 모든 규칙을 다 적지 않은 점에 주목하세요. 컨벤션 상세와 보안 체크리스트는 참조 파일로 분리합니다. Claude는 실제로 그 점검이 필요할 때만 해당 파일을 읽습니다.
Step 3. references/ 로 상세 분리
# references/conventions.md
- JPA 엔티티에 @Setter 금지, 변경은 의도가 드러나는 메서드로
- 응답 DTO 는 record 사용, 엔티티 직접 노출 금지
- @Transactional 은 서비스 레이어에만, readOnly 기본
- 컨트롤러는 검증/매핑만, 비즈니스 로직 금지
# references/security.md
- @RequestParam/@PathVariable 직접 쿼리 연결 금지 (인젝션)
- 응답에 엔티티 그대로 직렬화 시 민감 필드 노출 점검
- 예외 메시지에 내부 스택/SQL 노출 금지설계 팁: Skill에는 "WebSocket이 뭔지" 같은 일반 지식이 아니라 이 프로젝트가 그것을 어떻게 쓰는지(우리 컨벤션, 우리 규칙)만 담으세요. 일반 지식은 Skill을 뚱뚱하게만 만들고, 프로젝트 고유 결정이 Skill의 가치입니다. 참조는 한 단계 깊이까지만(SKILL.md → reference). 참조가 또 참조를 부르면 Claude가 길을 잃습니다.
Step 4. 테스트
Claude Code에서 /spring-review를 입력하거나, 그냥 "스테이징된 변경분 리뷰해줘"라고 말하면 됩니다. description의 트리거 키워드가 잘 잡혔다면 후자처럼 자동 발동도 됩니다. 핫 리로드 덕분에 SKILL.md를 고치고 바로 다시 시험해 볼 수 있습니다.
8. 잘 작동하는 Skill을 위한 체크리스트
- description은 트리거다. 무엇을+언제를 모두, 사용자가 실제 쓸 동사·키워드로.
- SKILL.md 본문은 500줄 이하. 넘으면 references/로 분리.
- 결정적 작업은 스크립트로. 검증 코드를 매번 생성시키지 말고
scripts/validate.py로. - 일반 지식 말고 프로젝트 고유 결정을 담을 것.
- 참조는 한 단계 깊이까지만.
- 보안: Skill은 코드를 실행할 수 있다. 신뢰할 수 있는 출처(직접 작성했거나 Anthropic 제공)만 사용하고, 외부에서 받은 Skill은 SKILL.md·스크립트·번들 파일을 전부 감사한 뒤 쓸 것. 외부 URL을 가져오는 Skill은 특히 위험.
마치며
2026년의 생산성은 타이핑 속도가 아니라 에이전트를 얼마나 잘 길들이느냐로 갈립니다. Skill은 그 길들이기를 ad-hoc 프롬프트에서 버전 관리되는 체계로 끌어올리는 도구입니다. "같은 설명을 반복하고 있다"는 신호가 보이면, 그것을 Skill로 추출하세요 — 그게 Skill의 한 줄 요약입니다. 다만 통합·핫리로드로 마찰은 줄었어도, Skill·CLAUDE.md·Subagent·MCP가 얽히는 구성은 여전히 신중한 설계를 보상하고 "일단 다 깔고 보자"는 punish합니다. 먼저 테스트하고, 항상 검증하고, 아직 이해 못 한 것을 자동화하지 않는 사람이 가장 큰 이득을 봅니다. YAGNI는 여기서도 유효합니다.
참고: Anthropic 공식 문서(Agent Skills Overview / Best practices), Claude Code 슬래시 커맨드·Skill 문서, The Pragmatic Engineer AI 툴링 설문(2026.2) 등을 토대로 정리. 버전에 따라 세부 동작은 바뀔 수 있으니 공식 문서를 함께 확인하세요.
