스킬이란?
CLAUDE.md가 "프로젝트 전체에 적용되는 규칙"이라면, 스킬은 "특정 작업을 위한 실행 규칙"입니다.
특정 작업이 필요한 시점에만 불러와 쓸 수 있습니다 (게임으로 치면 액티브 스킬 느낌).
| CLAUDE.md | Skill | |
|---|---|---|
| 적용 범위 | 항상 전체 컨텍스트에 로드 | 필요할 때만 호출/자동 트리거 |
| 용도 | 프로젝트 전반 컨벤션, 항상 알아야 할 것 | 특정 반복 작업의 절차/체크리스트 |
| 토큰 비용 | 매 대화마다 부담 | 안 쓰면 0 |
저장 위치
- 개인 전역:
~/.claude/skills/<skill-name>/SKILL.md— 모든 프로젝트에서 사용 - 프로젝트 전용:
.claude/skills/<skill-name>/SKILL.md— 해당 repo에서만 사용, git으로 팀과 공유 가능 - 플러그인 제공: 마켓플레이스 플러그인에 포함되어 설치 시 같이 들어옴
같은 작업 반복이 팀 전체의 컨벤션이면 프로젝트 스킬로 만들어서 커밋하는 게 좋습니다.
작성 방법
기본 구조
---
name: explain-code
description: 코드를 시각적 다이어그램과 비유로 설명합니다. "어떻게 동작해?"라고 물을 때 사용합니다.
---
코드를 설명할 때 항상 다음을 포함하세요:
1. **비유로 시작**: 코드를 일상생활의 무언가와 비교
2. **다이어그램 그리기**: ASCII 아트로 흐름, 구조, 관계 표시
3. **코드 워크스루**: 단계별로 무슨 일이 일어나는지 설명
4. **주의사항**: 흔한 실수나 오해 강조frontmatter 필드
name: 스킬 리스팅에 표시되는 표시 이름. 슬래시 명령어 이름은name이 아니라 디렉토리명에서 자동 결정됨description: 스킬의 용도와 사용 시점을 설명. Claude가 이 설명만 보고 자동 로드 여부를 판단하므로 가장 중요한 필드allowed-tools: 이 스킬 실행 중 사용 가능한 도구를 제한 (예: 읽기만 허용하고 싶으면 쓰기/실행 도구 제외). 비워두면 제한 없음
좋은 description 쓰는 법
- 트리거 문구를 그대로 포함: 사용자가 실제로 말할 법한 문장("OOO 추가해줘", "이거 검토해줘")을 넣으면 자동 트리거 정확도가 올라감
- 언제 쓰는지 + 무엇을 하는지 둘 다 명시 (둘 중 하나만 쓰면 오작동하거나 안 불려옴)
- 너무 광범위하게 쓰면 관련 없는 요청에도 끼어들고, 너무 좁으면 트리거가 안 됨 — 실제 써보면서 description을 다듬는 과정이 필요
본문(지침) 작성 팁
- 체크리스트/번호 목록으로 "빠뜨리면 안 되는 단계"를 명시 (사람도 실수하는 부분일수록 효과적)
- 코드 예시는 패턴을 보여줄 최소 분량만. 실제 프로젝트 코드 전체를 박아넣지 않기 — 토큰 낭비고 코드가 바뀌면 스킬도 같이 낡음
- 자주 참조하는 긴 레퍼런스(스키마, API 문서 등)는 본문에 넣지 말고
references/서브디렉토리에 별도 파일로 두고 필요할 때만 Claude가 읽게 함 - 반복 실행되는 스크립트가 있다면
scripts/서브디렉토리에 두고 스킬 본문에서는 호출만 안내
사용 방법
/스킬명으로 직접 호출- description에 적은 트리거 문구와 비슷한 요청을 하면 Claude가 자동으로 판단해서 로드
언제 쓰면 좋은가
특정 작업이 반복적으로 일어나지만, 매번 전체 프로젝트 컨텍스트(CLAUDE.md)에 넣어둘 필요는 없을 때 적합합니다.
예시: 프로젝트에서 API를 추가할 때의 플로우
- API 정의
- TanStack Query 훅 및 쿼리키 추가
- mutation 성공/실패 콜백에서 토스트 처리 추가
이 작업은 순서가 고정되어 있고 반복적으로 발생하기 때문에 스킬로 만들기 좋은 케이스입니다.
스킬 있을 때 vs 없을 때 (토큰 관점)
"백엔드에 추가된 API 연결해줘" 같은 요청을 예로 들면:
스킬 없이
- 컨벤션을 모르니 매번 탐색부터 함 — 폴더 구조, queryKey 패턴, 토스트 함수, 비슷한 도메인 훅을 grep/find/Read로 여러 번 호출. 파일을 통째로 여러 개 읽으면 수천~1만 토큰 이상 들어갈 수 있음
- 탐색해도 실수 여지가 있음 — 다른 방식의 토스트 함수를 잘못 가져오거나, 비슷한 폴더명을 헷갈리거나, 쿼리키 등록을 빠뜨리거나, 이미 있는 공용 훅을 모르고 재구현하는 식. 수정 왕복이 생기면 토큰이 더 늘어남
스킬 있을 때
- 요청이 description과 매칭되면 SKILL.md 내용이 자동으로 로드됨 — 파일 크기만큼 고정 비용(예: 7천 자 안팎이면 토큰 2,500~3,000 정도)
- 정확한 경로·네이밍·토스트 함수·무효화 패턴이 이미 박혀 있어서 탐색 단계(find/grep/여러 파일 Read)를 거의 스킵하고 바로 작성 가능
→ "탐색에 드는 가변 비용"(보통 더 크고 예측 불가능) vs "스킬 로드의 고정 비용"(예측 가능, 보통 더 작음)의 트레이드오프인데, 대체로 스킬 쪽이 순절감입니다. 거기에 더해 컨벤션 일관성 보장(잘못된 토스트 함수, 빠뜨린 invalidate 같은 실수 방지)이라는 부수 효과가 토큰 절감보다 더 큰 이득인 경우가 많습니다.
실제 프로젝트에서 쓰는 skill 요약
이름: frontend-api-query-hook
트리거: "OOO API 추가해줘", "쿼리훅 만들어줘" 같은 요청
역할: API 하나 추가할 때 아래 4곳을 한 번에 같이 생성/수정 — 하나라도 빠지면 캐시 무효화가 깨지거나 타입이 어긋나서, 그 순서와 규칙을 스킬에 박아둠.
- API 함수 (
_lib/apis/<domain>.ts) — 동사는 get/insert/update/delete만, async/await 전용, 항상res.data만 반환, 타입은 공통 패키지의XxxAPIInput/XxxAPIResult에서 가져옴 - 쿼리 키 등록 (
_lib/constants/queryKeys.ts) — 도메인별 계층 구조로 상위 키를 펼쳐서 확장, 끝에 항상as const, 무효화 레벨을 미리 결정 - 훅 작성 (
_lib/hooks/react-query/use<Domain>.ts) — query/mutation 패턴 고정(파라미터는{ params }로 래핑, onSuccess에 관련 키 모두 invalidate, onError는console.error패턴) - 호출부 — 컴포넌트에서 mutation 성공/실패 콜백에 토스트 처리
→ 반복되는 4단계 작업 순서와 각 단계의 세부 컨벤션을 매번 설명하지 않아도 되는 게 핵심 효용.
코드 생성형이 아닌 예시: context-feedback
스킬이 꼭 "코드/파일을 만드는" 용도일 필요는 없습니다. 현재 대화를 분석해서 사용자 본인의 대화 태도·질문 방식·문제 정의 능력을 피드백 받는 용도로도 쓸 수 있습니다.
- 트리거: "대화 피드백", "이번 대화 분석해줘", "내 대화 평가해줘"
allowed-tools: []— 도구를 전혀 안 쓰고 컨텍스트에 남아있는 대화 내용만으로 분석. 화면에 출력만 하고 파일/메모리에 저장하지 않음- 분석 대상은 Claude가 아니라 사용자 자신 — 지식 격차, 소통/질문 방식, 문제 정의·의사결정, 잘한 점을 근거(실제 발언 인용)와 함께 짚음
- 출력은 고정된 5개 섹션(지식 격차 / 소통 방식 / 문제 정의·의사결정 / 잘한 점 / 다음에 시도해볼 것)으로 매번 같은 형식 유지
- 지적하는 섹션은 "냉정한 멘토" 톤, 마지막 두 섹션은 "균형형 코치" 톤으로 의도적으로 톤을 분리
→ 반복 작업 자동화뿐 아니라, "매번 같은 기준으로 같은 형식의 회고를 받고 싶을 때"도 스킬이 적합한 케이스라는 걸 보여주는 예시.
주의할 점 / 알아두면 좋은 것
- 스킬은 많다고 좋은 게 아님: description이 비슷한 스킬이 여러 개면 Claude가 잘못 고르거나 둘 다 안 부를 수 있음. 작업 단위가 명확히 구분될 때만 쪼개기
- CLAUDE.md와 중복 금지: 항상 지켜야 하는 전역 규칙(코딩 스타일, 금지 패턴 등)은 CLAUDE.md에, "이 작업 할 때만" 필요한 절차는 스킬로 — 같은 내용을 두 곳에 적어두면 어긋날 때 헷갈림
- 코드가 바뀌면 스킬도 갱신 필요: 스킬에 박아둔 패턴(파일 경로, 함수 시그니처 등)이 실제 코드와 달라지면 오히려 잘못된 가이드가 됨. 큰 리팩토링 후엔 스킬도 같이 점검
- 버전 관리: 프로젝트 스킬은
.claude/skills/에 두고 git에 커밋하면 팀원 모두가 같은 스킬을 공유하게 됨 — 온보딩 문서 대신으로도 활용 가능
