같은 종류의 작업을 시킬 때마다 긴 설명을 처음부터 다시 타이핑한 적 있으신가요? "보고서는 이런 순서로, 이런 형식으로, 이 항목은 꼭 넣고..." 매번 반복하면 지치고, 빼먹기도 합니다. 이걸 한 번 적어 두고 재사용하게 만드는 것이 스킬(Skill)입니다.
스킬이란 무엇인가
스킬은 반복 작업의 순서·형식·체크리스트를 SKILL.md라는 파일 하나에 담아 둔 '재사용 업무 매뉴얼'입니다. 요리에 비유하면, 매번 재료와 조리법을 말로 부르는 대신 코팅해서 벽에 붙여 둔 '레시피 카드'와 같습니다. 한 번 잘 만들어 두면 "주간 보고서 만들어줘" 한마디에 클로드가 그 카드를 꺼내 정해진 절차대로 일합니다.
그때그때 프롬프트 vs 스킬로 굳히기
| 구분 | 그때그때 프롬프트 | 스킬(SKILL.md) |
|---|---|---|
| 재사용성 | 매번 처음부터 다시 입력 | 파일로 저장해 계속 재사용 |
| 일관성 | 부를 때마다 조금씩 달라짐 | 항상 같은 절차·형식을 보장 |
| 확장성 | 길어지면 관리가 어려움 | 참조 파일·체크리스트로 확장 가능 |
| 적합 상황 | 일회성·탐색적 작업 | 반복되는 정형 작업 |
핵심은 '2단계 로딩'
스킬이 똑똑한 이유는 컨텍스트(책상)를 아끼는 방식에 있습니다. 평소에는 스킬의 이름과 한 줄 설명(description)만 컨텍스트에 올라가 있습니다. 목차만 책상에 둔 셈이죠. 그러다 그 스킬이 필요한 요청이 들어오면, 그때 비로소 SKILL.md 본문과 참조 파일 전체를 불러옵니다. 이것을 온디맨드(필요할 때) 로딩이라고 합니다.
이 점이 CLAUDE.md와 결정적으로 다릅니다. CLAUDE.md는 매 세션 시작마다 전체가 통째로 로드되어 항상 책상에 상주합니다. 반면 스킬은 평소엔 가볍게 목차만 있다가, 호출될 때만 펼쳐집니다. 그래서 스킬을 수십 개 만들어 둬도 컨텍스트가 무거워지지 않습니다.
스킬의 2단계 로딩 vs CLAUDE.md 상시 로딩
CLAUDE.md — 상시 로딩
- 매 세션 시작마다 전체가 통째로 로드
- 항상 컨텍스트(책상)에 상주
- 개수가 늘면 그만큼 계속 무거워짐
늘 켜져 있는 형광등
스킬 — 2단계(온디맨드) 로딩
- 평소엔 이름 + 설명 한 줄만 올라감 (가벼움)
- 트리거 감지 시 그 스킬만 펼침
- 호출될 때 SKILL.md 본문 + 참조파일까지 로드
- 안 불린 스킬은 이름만 유지 = 절약
필요할 때만 켜는 스탠드
CLAUDE.md는 늘 켜져 있는 형광등, 스킬은 필요할 때만 켜는 스탠드입니다.
description을 잘 써야 스킬이 살아난다
2단계 로딩 때문에, 클로드가 '언제 이 스킬을 꺼낼지'는 오직 이름과 description만 보고 판단합니다. description이 부실하면 스킬을 만들어도 안 불려 나옵니다.
- 첫 문장에 이 스킬이 하는 핵심 기능을 명확히 쓴다. (예: "주간 업무 보고서를 팀 표준 형식으로 생성한다")
- 언제 발동할지 트리거 표현을 3개 이상 넣는다. (예: "주간 보고", "위클리 리포트", "이번 주 업무 정리")
- 너무 광범위하게 쓰지 않는다. "문서를 만든다"처럼 넓으면 엉뚱한 상황에 튀어나온다.
폴더 구조와 SKILL.md 만들기
스킬은 .claude/skills/<스킬이름>/SKILL.md 형태로 둡니다. 폴더 안에 템플릿이나 예시 같은 참조 파일을 함께 넣으면, 스킬이 호출될 때 같이 불러올 수 있습니다.
.claude/skills/weekly-report/SKILL.md 예시
---
name: weekly-report
description: 주간 업무 보고서를 팀 표준 형식으로 생성한다. "주간 보고", "위클리 리포트", "이번 주 업무 정리" 요청 시 사용.
---
# 주간 업무 보고서 생성
## 순서
1. 이번 주 커밋 로그를 확인한다: `!git log --since="7 days ago" --oneline`
2. 완료 / 진행 중 / 다음 주 계획으로 분류한다.
3. 아래 형식에 맞춰 작성한다. 상세 서식은 templates/report-template.md 참조.
## 출력 형식
- 제목: [YYYY-MM-DD] 주간 업무 보고
- 완료: 불릿 목록 (각 항목에 관련 커밋/PR 링크)
- 진행 중: 불릿 목록 (진행률 %)
- 다음 주 계획: 불릿 목록
- 이슈/도움 필요: 있을 때만
## 체크리스트
- [ ] 날짜 범위가 이번 주가 맞는가
- [ ] 완료 항목에 근거(커밋/PR)가 있는가
- [ ] 한 페이지 안에 읽히는 분량인가저장 위치에 따른 적용 범위
| 위치 | 적용 범위 | 용도 |
|---|---|---|
| .claude/skills/ (프로젝트) | 이 프로젝트에서만 (Git으로 팀 공유) | 팀 공통 업무 절차 |
| ~/.claude/skills/ (개인) | 내 컴퓨터의 모든 프로젝트 | 나만의 반복 작업 매뉴얼 |
| 플러그인으로 배포 | 마켓에서 설치한 사람 모두 | 조직·커뮤니티 배포용 |
만드는 법
스킬 만들기 3단계
- 직접 만들기: .claude/skills/이름/ 폴더를 만들고 SKILL.md에 frontmatter(name, description)와 본문을 작성한다.
- 도움받아 만들기: '스킬 크리에이터' 계열 플러그인을 설치하면, 대화로 요구사항을 말하는 것만으로 SKILL.md 초안을 만들어 준다.
- 확인: 새 세션에서 트리거 표현으로 요청해 스킬이 실제로 불려 나오는지 테스트한다.
스킬 하나에 모든 걸 넣지 말고 '한 스킬 = 한 가지 정형 작업'으로 잘게 나누세요. 보고서 스킬, 릴리스 노트 스킬, 회의록 정리 스킬처럼 나누면 description이 뾰족해져서 클로드가 정확히 골라 씁니다.
SKILL.md 본문이 길어질수록 호출될 때 컨텍스트를 많이 먹습니다. 자세한 예시나 대용량 데이터는 본문에 다 적지 말고 참조 파일로 분리해 두고, 본문에서는 '참조: templates/...' 식으로 가리키세요. 본문은 절차와 체크리스트 위주로 간결하게 유지하는 것이 좋습니다.
스킬은 클로드 코드를 '한 번 가르치면 계속 써먹는 팀원'으로 만드는 도구입니다. 반복된다고 느껴지는 작업이 생길 때마다 스킬로 굳혀 두면, 여러분의 노하우가 파일로 차곡차곡 쌓여 갑니다.