[Claude 활용 24회 — AI에게 일을 위임하는 법] 9/24화: Claude Skills 3단계 — 반복 업무 한 번만 가르치기
3줄 요약
- Claude Skills는 반복 업무 지시를
.claude/skills/디렉터리 안 SKILL.md 한 장으로 모듈화하는 기능이다. description한 줄이 자동 호출의 열쇠 — 모호하게 쓰면 영원히 불리지 않는 유령 Skill이 된다.- 참조 파일을 분리하면 Skill을 쓰지 않을 때 토큰을 아끼고, 큰 템플릿도 부담 없이 묶을 수 있다.
Claude Skills를 모르던 시절, 나는 매주 같은 프롬프트를 복사해서 Claude에게 붙여넣었다. 3개월 동안 같은 회의록 정리 작업을 100번 넘게 시켰는데 매번 첫 만남이었다. 5화에서 CLAUDE.md를 “저장소의 헌법”이라 불렀다. 오늘 다루는 Skills는 그 헌법 아래에서 돌아가는 업무 매뉴얼이다. 한 번 쓰면 Claude가 알아서 꺼내 쓰는, 파일로 존재하는 매뉴얼.
매주 같은 프롬프트를 다시 치던 3개월
월요일 아침 10시. 주간 회의가 끝나면 내 루틴이 시작됐다. 회의록 전문을 Claude에게 붙여넣고 이렇게 말한다.
이 회의록에서 액션아이템을 추출해줘.
- 담당자, 마감일, 우선순위(상/중/하)를 분류해줘
- "~하기로 했다", "~까지 완료" 같은 결정 문구에서 뽑아줘
- 담당자가 불분명하면 "미정"으로 표시
- 출력은 마크다운 테이블로
- 열 순서: 번호 | 액션아이템 | 담당자 | 마감일 | 우선순위
결과는 훌륭하다. 한 번은.
문제는 다음 주에도, 그다음 주에도 이 프롬프트를 처음부터 다시 쳐야 한다는 것이다. Claude는 지난주의 나를 기억하지 않는다. 매 세션이 백지 상태다.
첫째 달은 괜찮았다. 어차피 복사 붙여넣기 30초면 끝이니까. 그런데 둘째 달부터 미묘한 문제가 쌓였다.
- 출력 형식이 매번 달랐다. “마크다운 테이블”이라고만 쓰면 어떤 주엔 열 순서가 뒤바뀌었다. 마감일이 두 번째 열이었다가 네 번째 열이었다가. 자동화 파이프라인에 넣으려면 형식이 고정돼야 하는데, 매주 미세하게 달랐다.
- 우선순위 기준이 제각각이었다. “상”의 기준이 내 머릿속에만 있었다. Claude는 매 세션마다 나름의 기준을 새로 만들었다. 어떤 주엔 “마감 3일 이내”를 상으로 잡았고, 다른 주엔 “긴급이라는 단어가 있으면 상”이었다.
- 팀원 이름이 바뀌면 매번 알려줘야 했다. 7월에 프론트팀에 신규 입사자가 왔다. 8월까지 매주 “정하나는 프론트팀이야”를 프롬프트에 추가해야 했다. 빼먹은 주엔 정하나가 “미정” 처리됐다.
- 예외 케이스를 매번 다시 설명해야 했다. “마감일 없이 ‘시간 될 때 해보자’라고만 한 건 우선순위 ‘하’로”라는 규칙을 4주 연속 반복했다.
셋째 달, 나는 이 프롬프트를 별도 텍스트 파일에 저장해두고 매번 복사-붙여넣기를 하고 있었다. meeting-prompt-v3.txt라는 파일이 바탕화면에 있었다. v3인 이유는 두 번 수정했기 때문이다. 그런데 이 파일을 열고, 내용을 복사하고, Claude에 붙여넣고, 회의록도 붙여넣는 과정이 매주 반복되자 문득 생각이 들었다.
이건 코드 중복이랑 뭐가 다른가.
함수를 만들어야 한다. 한 번 정의하고, 호출만 하면 되는 함수를. 매번 같은 로직을 main에 인라인으로 풀어 쓰는 코드를 우리가 코드 리뷰에서 잡듯이, 같은 프롬프트를 세션마다 반복하는 건 AI 활용에서의 DRY 원칙 위반이다.
4화에서 “프롬프트가 아니라 작업 지시서를 쓴다”고 했다. 그 작업 지시서를 매번 프롬프트 창에 타이핑하는 대신, 파일로 저장해서 Claude가 알아서 꺼내 쓰게 만들면 어떨까. 이것이 Skills다. 바탕화면의 meeting-prompt-v3.txt를 정해진 위치에 정해진 형식으로 옮기는 것, 딱 그만큼의 차이가 “매번 붙여넣기”와 “한 번 가르치면 끝”을 가른다.
아래 표를 보자. 좌우의 차이가 곧 오늘 이 글의 전부다.
| 비교 항목 | 프롬프트 복붙 | Skills |
|---|---|---|
| 반복 비용 | 매 세션마다 붙여넣기 | 최초 1회 작성 |
| 일관성 | 세션마다 출력 형식 다름 | 항상 동일한 규칙 적용 |
| 유지보수 | 텍스트 파일 수동 관리 | Git으로 버전 관리 |
| 팀 공유 | 파일 공유 → 각자 복붙 | 리포지토리에 포함 → 자동 적용 |
| 자동 호출 | 불가능 | description 매칭으로 가능 |
| 토큰 효율 | 매번 전체 지시를 컨텍스트에 올림 | 호출 시에만 로드 |
Claude Skills 구조 — SKILL.md 한 장이 업무 매뉴얼이 된다
5화에서 CLAUDE.md를 “저장소의 헌법”이라 불렀다. Claude Skills는 그 헌법 아래에서 돌아가는 업무별 표준 운영 절차서(SOP)다. 헌법이 “우리 팀은 코드 리뷰를 반드시 거친다”라는 원칙을 정한다면, Skills는 “회의록이 들어오면 이 형식으로 액션아이템을 뽑아라”라는 구체적 업무 매뉴얼이다. 헌법은 하나지만, 매뉴얼은 업무 종류만큼 만들 수 있다.
구조는 놀라울 만큼 단순하다.
.claude/
└── skills/
└── meeting-action-items/ # Skill 이름 = 디렉터리 이름
├── SKILL.md # 핵심. 이 파일 하나가 Skill의 본체다
├── templates/
│ └── action-item-format.md # 출력 템플릿 (참조 파일)
└── examples/
├── sample-input.md # 입력 예시 (참조 파일)
└── sample-output.md # 출력 예시 (참조 파일)
핵심은 SKILL.md 파일 하나다. 이 파일 안에 YAML 프론트매터(front matter)와 마크다운 본문이 들어간다. 프론트매터는 ---로 감싼 YAML 블록으로, Skill의 메타 정보를 담는다. 본문은 Claude가 따를 구체적인 처리 규칙이다.
---
description: "회의록 텍스트를 받아 액션아이템을 추출하고 담당자별로 분류한다"
files:
- templates/action-item-format.md
- examples/sample-output.md
---
# 회의록 → 액션아이템 추출
## 입력
- 회의록 텍스트 (마크다운 또는 일반 텍스트)
- 팀원 목록과 소속은 templates/action-item-format.md의 [팀 구성] 섹션 참조
## 처리 규칙
1. "~하기로 했다", "~까지 완료", "~에게 요청" 패턴에서 액션아이템을 추출
2. 담당자, 마감일, 우선순위(상/중/하)를 태깅
3. 마감일 미명시 → "다음 회의 전까지"
4. 담당자 불분명 → "미정 (회의 주최자 확인 필요)"
## 출력
- examples/sample-output.md 형식을 정확히 따른다
눈여겨볼 필드가 두 개 있다. description과 files다. 이 두 필드가 Skills를 “바탕화면 텍스트 파일”과 근본적으로 다르게 만드는 핵심이다.
저장 위치도 중요하다. 두 가지 레벨이 있다.
- 프로젝트 레벨 (
.claude/skills/): 해당 프로젝트에서만 작동한다. Git으로 팀 전체에 공유할 수 있다. 팀원이 리포지토리를 클론하면 Skills도 함께 딸려온다. - 사용자 레벨 (
~/.claude/skills/): 내가 여는 모든 프로젝트에서 작동한다. 개인 워크플로용 — 회의록 정리, 일일 보고서 생성 같은 프로젝트와 무관한 반복 업무에 적합하다.
어디에 둘지는 간단한 기준으로 판단한다. “이 Skill을 팀원도 써야 하는가?” 그렇다면 프로젝트 레벨에 넣고 Git에 커밋한다. 나만 쓴다면 사용자 레벨에 둔다.
description — 자동 호출의 열쇠
Claude는 사용자의 요청이 들어오면, 현재 프로젝트와 사용자 레벨에 등록된 모든 Skill의 description을 스캔한다. 사용자가 “이 회의록 정리해줘”라고 말하면, Claude는 등록된 description 중에서 “회의록”과 “액션아이템”이 포함된 Skill을 찾아 자동으로 로드한다. SKILL.md의 본문과 참조 파일을 읽고, 그 규칙대로 작업을 수행한다.
이건 마치 Claude Code에 내장된 라우터와 같다. REST API에서 URL 패턴이 요청을 올바른 핸들러로 보내듯, description이 사용자 요청을 올바른 Skill로 라우팅한다. 그래서 description은 그냥 설명이 아니라 매칭 키다. API 엔드포인트의 OpenAPI summary를 쓰듯이 써야 한다.
description은 짧고 구체적으로 써야 한다. 나쁜 예와 좋은 예를 비교해보자.
# ❌ 나쁜 예 1 — 너무 모호하다
description: "회의록 처리"
# 문제: "처리"가 뭔지 모른다. 요약? 번역? 액션아이템 추출?
# Claude가 매칭 확신을 갖지 못해 무시할 가능성 높음.
# ❌ 나쁜 예 2 — 너무 길다 (신호가 노이즈에 묻힌다)
description: "이 Skill은 회의록을 분석하여 주요 논의사항과 결정사항,
액션아이템을 포함한 구조화된 보고서를 생성하는 역할을 담당합니다"
# 문제: 56자. 핵심 키워드가 부사어와 수식어에 파묻힘.
# "역할을 담당합니다" 같은 빈 표현이 매칭 정확도를 낮춤.
# ❌ 나쁜 예 3 — 동사가 없다
description: "회의록, 액션아이템, 담당자, 분류"
# 문제: 키워드 나열만으로는 Claude가 "무엇을 해야 하는지" 파악할 수 없다.
# ✅ 좋은 예 — 동사+목적어+결과가 한 줄에 있다
description: "회의록 텍스트에서 액션아이템을 추출하고 담당자별로 분류한다"
# 입력(회의록 텍스트), 행동(추출), 출력(담당자별 분류) — 한 줄에 다 있다.
좋은 description의 공식이 있다.
“[입력]에서 [행동]하고 [결과]를 만든다”
이 공식을 적용한 예시를 몇 개 더 보자.
"PR diff를 받아 코드 리뷰 체크리스트를 생성한다"— 코드 리뷰 Skill"에러 로그에서 근본 원인을 분석하고 수정 방안을 제안한다"— 디버깅 Skill"API 응답 JSON을 TypeScript 인터페이스로 변환한다"— 타입 생성 Skill"고객 문의 메일을 분류하고 답변 초안을 작성한다"— 고객 응대 Skill
모두 입력-행동-결과가 한 줄에 들어 있다. Swagger 문서에 적을 법한 한 줄이 가장 좋은 description이다.
수동 호출과 자동 호출
Skills에는 두 가지 호출 방식이 있다.
수동 호출은 사용자가 Skill 이름을 직접 언급하는 것이다.
> meeting-action-items Skill을 써서 이 회의록 정리해줘
이렇게 말하면 Claude는 해당 Skill을 무조건 로드한다. description 매칭과 무관하게 강제 호출이다. 확실히 특정 Skill을 쓰고 싶을 때 쓴다.
자동 호출은 Claude가 알아서 매칭하는 것이다.
> 이 회의록에서 할 일 목록 좀 뽑아줘
사용자는 Skill의 존재를 언급하지 않았다. 하지만 Claude가 등록된 모든 Skill의 description을 스캔하고, “회의록에서 할 일 목록 뽑기”가 “회의록 텍스트에서 액션아이템을 추출하고 담당자별로 분류한다”와 의미적으로 일치한다고 판단하면 자동으로 해당 Skill을 로드한다. 사용자가 Skill의 존재를 몰라도 작동한다. 이것이 Skills의 진짜 힘이다.
자동 호출이 되려면 description이 정확해야 한다. “회의록 처리”라는 모호한 description은 “이 회의록 분석해줘”와 매칭될 수도 있고 안 될 수도 있다. 반면 “회의록 텍스트에서 액션아이템을 추출하고 담당자별로 분류한다”라면 “회의록에서 할 일 목록 좀 뽑아줘”에도, “이번 주 회의 결과 정리 좀”에도 확실하게 매칭된다. 핵심 동사와 목적어가 명확하기 때문이다.
나는 두 방식을 단계적으로 쓴다.
- 개발 중에는 수동 호출로 테스트한다. Skill을 만들고 다듬는 과정에서는 명시적으로 불러서 결과를 확인한다. 기대와 다른 출력이 나오면 SKILL.md 본문을 수정하고 다시 수동 호출한다.
- 안정화 이후에는 자동 호출에 맡긴다. description을 충분히 다듬었으면, 일상 대화에서 자연스럽게 호출되는지 확인한다. 자동 호출이 잘 되면 “Skill이 있는 줄도 모르고 쓰는” 단계에 도달한 것이다.
자동 호출이 잘 되는 상태를 나는 “투명한 Skill”이라고 부른다. 사용자 경험에서 Skill의 존재가 투명하게 사라지고, 그냥 “Claude가 원래 이렇게 잘하는 건가?”라고 느끼게 되는 것. 그 지점이 Skills 개발의 완성이다.
참조 파일 분리 — 토큰 절약의 핵심
7화에서 컨텍스트 관리를 다뤘다. 토큰은 무한하지 않다. Skills에서도 같은 원칙이 적용된다.
SKILL.md에 모든 내용을 넣는 건 함수 하나에 모든 로직을 때려박는 것과 같다. 출력 템플릿 300줄, 예시 입력 200줄, 예시 출력 150줄을 전부 SKILL.md 안에 넣으면 어떻게 될까? 호출될 때마다 650줄이 컨텍스트에 올라간다.
그것보다 더 큰 문제가 있다. Skill이 10개, 20개로 늘어나면 description 스캔 단계에서 어떤 일이 벌어지는지 이해해야 한다.
Claude의 Skill 처리는 두 단계로 나뉜다.
- 1단계 — description 스캔: YAML 프론트매터의
description필드만 읽는다. 모든 Skill의 description을 빠르게 스캔해서 매칭되는 것을 찾는다. 이 단계에서 SKILL.md 본문이나 참조 파일은 읽지 않는다. 토큰 소비가 거의 없다. - 2단계 — Skill 로드: 매칭된 Skill이 있으면, 그때서야 SKILL.md 전체 본문과
files에 지정된 참조 파일을 모두 컨텍스트에 올린다. 여기서 토큰이 소비된다.
따라서 SKILL.md 본문은 처리 규칙에 집중하고, 긴 템플릿이나 예시는 별도 파일로 빼는 게 정석이다. Skill이 호출될 때만 참조 파일이 로드되므로, 다른 Skill을 쓰는 세션에서는 이 파일들이 토큰을 잡아먹지 않는다.
# ❌ 비효율: SKILL.md에 전부 때려넣기 (800줄짜리 SKILL.md)
---
description: "회의록에서 액션아이템을 추출한다"
---
# 회의록 → 액션아이템
## 규칙 (200줄)
## 출력 템플릿 (300줄)
## 예시 입력 (200줄)
## 예시 출력 (100줄)
# ✅ 효율: SKILL.md는 규칙만, 나머지는 참조 파일
---
description: "회의록에서 액션아이템을 추출한다"
files:
- templates/action-item-format.md # 300줄 → 호출 시에만 로드
- examples/sample-output.md # 100줄 → 호출 시에만 로드
---
# 회의록 → 액션아이템
## 규칙 (200줄만 남음)
이 분리 원칙의 효과는 Skill이 늘어날수록 극대화된다. Skill이 20개인 프로젝트에서 사용자가 “이 회의록 정리해줘”라고 말하면, Claude는 20개의 description(각 1~2줄)만 스캔한다. 매칭된 1개의 Skill만 전체 로드되고, 나머지 19개의 본문과 참조 파일은 토큰을 전혀 소비하지 않는다.
5화에서 “500줄짜리 CLAUDE.md는 오히려 성능을 깎는다”고 했다. Skills도 마찬가지다. SKILL.md 하나가 500줄을 넘는다면 분리할 시점이다.
실습 — 회의록에서 액션아이템을 뽑는 Skill 완주
이론은 충분하다. 직접 만들어보자. 이 실습이 끝나면 “이 회의록 정리해줘”라고만 말해도 Claude가 정해진 형식으로 액션아이템을 뽑아주는 Skill이 완성된다. 파일 5개를 만들면 된다.
Step 1. 디렉터리 만들기
프로젝트 루트에서 시작한다. 이 Skill은 팀 공유용이므로 프로젝트 레벨에 만든다.
# 프로젝트 레벨 Skill (이 프로젝트에서만 작동, Git 추적 가능)
mkdir -p .claude/skills/meeting-action-items/templates
mkdir -p .claude/skills/meeting-action-items/examples
개인용으로 쓸 거라면 ~/.claude/skills/ 아래에 같은 구조를 만든다. 차이는 위치뿐이다.
Step 2. SKILL.md 작성 — Skill의 본체
.claude/skills/meeting-action-items/SKILL.md 파일을 만든다. 이것이 Skill의 전부다.
---
description: "회의록 텍스트에서 액션아이템을 추출하고 담당자별로 분류한다"
files:
- templates/action-item-format.md
- examples/sample-input.md
- examples/sample-output.md
---
# 회의록 → 액션아이템 추출
## 입력 조건
- 회의록 텍스트를 받는다 (마크다운, 일반 텍스트, 음성 전사 텍스트 모두 가능)
- 팀원 목록과 소속은 templates/action-item-format.md의 [팀 구성] 섹션 참조
## 추출 규칙
### 액션아이템 식별
다음 패턴을 포함하는 문장에서 액션아이템을 추출한다:
- 결정 표현: "~하기로 했다", "~로 결정", "~에 합의"
- 요청 표현: "~에게 요청", "~가 확인", "~가 진행"
- 기한 표현: "~까지 완료", "~까지 공유", "다음 회의 전까지"
- 지시 표현: "~해주세요", "~부탁드립니다"
### 담당자 매핑
- 회의록에 등장하는 이름을 templates/action-item-format.md의 팀 구성과 대조
- 이름만 나오면 풀네임으로 변환 (예: "철수" → "김철수")
- 같은 성의 팀원이 여러 명이면 맥락으로 판단, 불확실하면 괄호 주석
- 담당자가 불분명하면 "미정 (회의 주최자 확인 필요)"
### 우선순위 판정
- 상: 마감 3영업일 이내 OR 다른 작업의 선행 조건 OR "긴급"/"즉시" 표현
- 중: 이번 주 내 완료 필요 (명시적 기한이 있는 기본값)
- 하: "여유 있을 때", "시간 될 때", 다음 스프린트 이후
### 마감일 추론
- 명시된 날짜를 그대로 사용 (요일 병기)
- "다음 주" → 다음 주 금요일
- "다음 회의 전까지" → 다음 정기 회의일 (회의록에 명시돼 있다면)
- 기한 언급 없음 → "마감 미정"
## 출력
- examples/sample-output.md 형식을 정확히 따른다
- 담당자별로 그룹핑한 마크다운 테이블
- 액션아이템이 0개면 "추출된 액션아이템이 없습니다" 한 줄만 출력
- 마지막에 요약 통계: 총 N건 (상 n건 / 중 n건 / 하 n건)
주의할 점 두 가지. 첫째, description은 프론트매터 안에서 한 줄이다. 줄바꿈 없이. 둘째, files의 경로는 SKILL.md 기준 상대경로다. ./을 붙이지 않아도 된다.
Step 3. 참조 파일 — 출력 템플릿
templates/action-item-format.md를 만든다. 출력 형식과 팀 구성 정보를 담는다.
# 액션아이템 출력 형식 가이드
## 마크다운 테이블 형식
담당자별로 H3 헤더를 만들고, 각 담당자 아래 테이블을 배치한다.
### [담당자 이름] (소속팀)
| # | 액션아이템 | 마감일 | 우선순위 | 비고 |
|---|-----------|--------|---------|------|
| 1 | 구체적 행동 기술 | YYYY-MM-DD (요일) | 상/중/하 | 관련 맥락이나 의존성 |
## 요약 통계 (문서 끝에 배치)
- 총 액션아이템: N건
- 우선순위별: 상 n건 / 중 n건 / 하 n건
- 마감 미정: n건
---
## [팀 구성] — 2026년 8월 기준
### 서버팀
- 김철수 (리드)
- 박영희
### 프론트팀
- 이민수 (리드)
- 정하나 (2026-07-15 합류)
### QA팀
- 최지훈
### 기획팀
- 한소영 (리드)
- 오태준
## 업데이트 이력
- 2026-07-15: 정하나 합류 (프론트팀)
- 2026-06-01: 초기 작성
팀 구성이 바뀌면 이 파일만 수정하면 된다. SKILL.md를 건드릴 필요 없다. 관심사의 분리(Separation of Concerns)가 여기서도 통한다. 처리 규칙은 SKILL.md에, 데이터는 참조 파일에. 마치 코드와 설정 파일을 분리하는 것과 같다.
Step 4. 참조 파일 — 입출력 예시
examples/sample-input.md — Claude에게 “이런 입력이 올 것이다”를 알려주는 예시다.
# 주간 회의 — 2026-08-04 (월) 10:00
참석: 김철수, 이민수, 최지훈, 한소영
## 논의 사항
1. 결제 모듈 리팩터링
- 김철수: 현재 결제 로직이 3곳에 중복. 공통 모듈로 빼야 한다.
- 이민수: 프론트도 결제 관련 컴포넌트 정리 필요.
- → 김철수가 이번 주 금요일까지 공통 모듈 초안을 만들기로 했다.
- → 이민수는 프론트 컴포넌트 목록을 수요일까지 정리해서 공유.
2. QA 자동화 진행 상황
- 최지훈: E2E 테스트 70% 완료. 결제 플로우는 다음 주에 추가 예정.
- → 결제 모듈 리팩터링 완료 후 QA 시나리오 업데이트 필요.
3. 8월 이벤트 페이지
- 한소영: 기획안 초안 완료. 디자인팀에 요청 넣었음.
- → 이민수에게 8월 12일까지 이벤트 페이지 퍼블리싱 요청.
- → 한소영이 디자인 나오면 이민수에게 즉시 전달하기로.
4. 기타
- 다음 회의: 8월 11일 (월) 10시
examples/sample-output.md — 위 입력에 대한 기대 출력이다. Claude는 이 예시를 보고 출력 형식을 정확히 맞춘다.
# 액션아이템 — 2026-08-04 주간 회의
## 담당자별 분류
### 김철수 (서버팀)
| # | 액션아이템 | 마감일 | 우선순위 | 비고 |
|---|-----------|--------|---------|------|
| 1 | 결제 공통 모듈 초안 작성 | 2026-08-08 (금) | 상 | QA 시나리오의 선행 조건 |
### 이민수 (프론트팀)
| # | 액션아이템 | 마감일 | 우선순위 | 비고 |
|---|-----------|--------|---------|------|
| 1 | 프론트 결제 컴포넌트 목록 정리·공유 | 2026-08-06 (수) | 상 | 3영업일 이내 |
| 2 | 8월 이벤트 페이지 퍼블리싱 | 2026-08-12 (화) | 중 | 디자인 수령 후 착수 |
### 최지훈 (QA팀)
| # | 액션아이템 | 마감일 | 우선순위 | 비고 |
|---|-----------|--------|---------|------|
| 1 | 결제 플로우 E2E 테스트 시나리오 업데이트 | 마감 미정 | 중 | 결제 모듈 리팩터링 완료 후 |
### 한소영 (기획팀)
| # | 액션아이템 | 마감일 | 우선순위 | 비고 |
|---|-----------|--------|---------|------|
| 1 | 디자인 수령 즉시 이민수에게 전달 | 마감 미정 | 중 | 이벤트 페이지 일정 의존 |
---
### 요약 통계
- 총 액션아이템: 5건
- 우선순위별: 상 2건 / 중 3건 / 하 0건
- 마감 미정: 2건
예시를 넣는 이유는 명확하다. 규칙만으로는 출력 형식을 100% 통제할 수 없다. “마크다운 테이블로 담당자별 분류”라고 써도 구체적인 열 순서, 비고란 활용 방식, 요약 통계 위치는 예시를 봐야 정확히 맞출 수 있다. 한 번 만든 예시 파일이 매주 일관된 출력을 보장한다.
Step 5. 수동 호출로 테스트
파일 5개가 모두 준비됐다. Claude Code를 열고 수동으로 테스트한다.
> meeting-action-items Skill을 써서 아래 회의록을 정리해줘.
>
> # 주간 회의 — 2026-08-04 (월) 10:00
> 참석: 김철수, 이민수, 최지훈, 한소영
> ...
> (회의록 전문 붙여넣기)
이때 확인할 체크리스트 4가지:
- 출력 형식이
sample-output.md와 일치하는가? 열 순서, 요약 통계 위치, H3 헤더 형식. - 팀 구성 매핑이 맞는가? “철수”가 “김철수 (서버팀)”으로 정확히 변환됐는가?
- 우선순위 판정이 기준과 부합하는가? 금요일까지 마감인 건 “상”으로 잡혔는가?
- 마감일 추론이 합리적인가? “수요일까지”가 정확한 날짜로 변환됐는가?
결과가 기대와 다르면 SKILL.md의 규칙을 수정한다. 이 반복이 Skill 개발의 핵심이다. 프롬프트를 다듬는 게 아니라, 문서를 다듬는 것이다. 문서는 버전 관리가 된다. git diff로 뭘 바꿨는지 추적할 수 있다. 바탕화면의 meeting-prompt-v4.txt와는 격이 다르다.
내 경험상 수동 테스트를 3~5회 반복하면 규칙이 안정화된다. 처음엔 마감일 추론이 어긋나고, 두 번째엔 우선순위 기준이 모호해서 수정하고, 세 번째쯤 되면 대부분의 케이스를 커버한다.
Step 6. 자동 호출 확인 — “투명한 Skill” 달성
수동 테스트가 충분히 됐으면, 이제 Skill 이름을 언급하지 않고 자연어로 요청해본다.
> 이 회의록에서 할 일 목록 좀 뽑아줘.
>
> (회의록 붙여넣기)
Claude가 meeting-action-items Skill을 자동으로 로드하고, 정해진 형식대로 결과를 내놓으면 성공이다. Claude가 Skill을 참조했는지는 응답 과정에서 확인할 수 있다 — Skill을 로드했을 때 해당 파일을 읽었다는 표시가 나온다.
만약 자동 호출이 안 된다면 두 가지를 점검한다.
- description의 핵심 키워드: 사용자 요청에 들어 있는 단어(“할 일”, “목록”, “회의록”)가 description의 표현(“액션아이템”, “추출”, “분류”)과 의미적으로 매칭되는가? 매칭이 약하다면 description에 동의어를 추가한다. 예:
"회의록에서 액션아이템(할 일 목록)을 추출하고 담당자별로 분류한다" - 다른 Skill과의 충돌: description이 비슷한 Skill이 여러 개 있으면 Claude가 어느 것을 선택할지 불확실해진다. 각 Skill의 description을 더 구체적으로 차별화한다.
이것으로 실습이 끝났다. 파일 5개, 총 작업 시간 15~20분. 이 15분의 투자가 앞으로 매주 월요일의 30분을 되돌려준다. 1년이면 26시간. 그리고 이 Skill은 팀원 누구든 쓸 수 있다.
유령 Skill 함정 — 이렇게 쓰면 영원히 호출되지 않는다
Skills를 만들다 보면 한 가지 현상을 목격하게 된다. 분명 만들었는데 Claude가 한 번도 자동으로 불러 쓰지 않는 Skill. 나는 이걸 유령 Skill이라 부른다. 존재하지만 작동하지 않는 코드 — 죽은 코드(dead code)와 같다. 코드베이스에 남아서 공간만 차지하고, 아무도 호출하지 않는다.
실무에서 반복적으로 마주친 3가지 패턴이 있다.
패턴 1: 모호한 description — 가장 흔한 유령
# ❌ 유령 Skill을 만드는 description들
description: "문서 처리"
description: "데이터 분석"
description: "코드 정리"
description: "정리"
“문서 처리”라면 대체 무슨 문서를 어떻게 처리한다는 건가. 회의록 정리? 기술 문서 교정? PDF 요약? Claude 입장에서 이 Skill이 뭘 하는지 알 수 없다. 매칭 확신이 낮으면 Claude는 Skill을 로드하지 않고 범용 응답을 한다. 결과적으로 Skill이 있으나 마나 한 상태가 된다.
진단법: description만 보고 “이 Skill이 무엇을 입력으로 받고, 무엇을 출력하는가”를 즉시 알 수 있는가? 2초 안에 답이 안 나오면 모호한 것이다.
해법: 앞서 말한 공식을 적용한다. “[입력]에서 [행동]하고 [결과]를 만든다.” 구체적 명사와 구체적 동사를 쓴다.
패턴 2: 너무 큰 Skill — 만능 Skill의 유혹
# ❌ 하나의 Skill에 5가지 기능을 우겨넣기
description: "회의록을 분석하여 액션아이템 추출, 결정사항 요약,
논의 미완료 항목 정리, 참석률 통계, 다음 회의 안건 제안을 수행한다"
이건 함수가 아니라 프로그램이다. 단일 책임 원칙(SRP)을 떠올려보자. 하나의 함수가 5가지 일을 하면 어떤 일이 벌어지는가?
- description이 길어져서 매칭 정확도가 떨어진다. “액션아이템만 뽑아줘”라고 했을 때 이 Skill이 불릴 수도 있고 안 불릴 수도 있다.
- 호출되면 5가지 작업을 모두 수행하려 한다. 사용자가 원하는 건 하나인데.
- SKILL.md가 비대해져서 유지보수가 어렵다. 참석률 통계 로직을 수정하려다 액션아이템 규칙을 건드리는 사고가 생긴다.
해법: 하나의 Skill은 하나의 기능만. 5가지 기능이 필요하면 5개의 Skill을 만든다.
.claude/skills/
├── meeting-action-items/ # 액션아이템 추출
├── meeting-summary/ # 결정사항 요약
├── meeting-open-items/ # 미완료 항목 정리
├── meeting-attendance/ # 참석률 통계
└── meeting-next-agenda/ # 다음 안건 제안
5개로 나누면 각각의 description이 짧고 정확해진다. 필요한 것만 호출되고, 토큰도 아낀다. 공유할 데이터(팀 구성 등)가 있으면 상위 디렉터리에 공통 참조 파일을 두면 된다.
패턴 3: description 누락 — 이름 없는 함수
# ❌ description 없는 SKILL.md
---
files:
- templates/format.md
---
# 회의록 정리
...
description이 없으면 자동 호출은 절대 일어나지 않는다. 수동으로 Skill 이름을 명시할 때만 작동한다. 수동 호출만 가능한 Skill은 결국 잊혀진다. 프롬프트 파일을 바탕화면에 놓아두는 것과 다를 바 없다 — 아니, 바탕화면 파일은 적어도 눈에 보이기라도 한다.
해법: SKILL.md를 만들면 반드시 description부터 쓴다. description 없는 SKILL.md는 main 함수 없는 프로그램이다.
Skill 건강 점검 체크리스트
Skill을 만들거나 점검할 때 이 4가지를 확인한다.
- description이 있는가? 없으면 자동 호출 불가. 반드시 추가.
- description에 입력-행동-결과가 있는가? 하나라도 빠지면 매칭 정확도 저하.
- Skill이 하나의 기능만 담당하는가? 2개 이상이면 분리 검토.
- 큰 템플릿이나 예시가 참조 파일로 분리돼 있는가? SKILL.md 본문이 200줄을 넘으면 분리 시점.
이 체크리스트를 거치면 유령 Skill은 거의 생기지 않는다. 유령이 되는 Skill에는 언제나 패턴이 있고, 그 패턴은 위 3가지에 전부 걸린다.
이번 회차의 수익화 지점
잘 만든 Skill은 그 자체가 상품이다.
이번 실습에서 만든 “회의록 → 액션아이템” Skill을 생각해보자. 팀 구성과 우선순위 기준만 바꾸면 어떤 조직에서든 쓸 수 있다. 이런 Skill을 5~10개 묶으면 특정 직군에 맞춘 Skill 팩이 된다.
실제로 가능한 형태 세 가지:
- 직군별 Skill 팩: PM용(회의록 정리, 스프린트 리뷰, 이해관계자 보고서), 개발 리드용(코드 리뷰 체크리스트, 장애 보고서, 기술 부채 분류), 마케터용(캠페인 성과 분석, 경쟁사 모니터링, SNS 콘텐츠 변환). Skill 5~10개를 묶어 하나의 팩으로 구성한다. 12화에서 다룰 플러그인 패키징과 바로 연결된다.
- Skill 커스터마이징 컨설팅: 고객의 업무 프로세스를 분석하고, 그 조직에 맞는 Skill을 설계해주는 서비스. 반복 업무 3개를 Skill로 만들어주는 것만으로 시간당 과금이 가능하다.
- Skill 작성 워크숍: “description 작성법”, “참조 파일 설계”, “유령 Skill 진단” 같은 메타 지식을 반나절 워크숍이나 전자책으로 판매. 오늘 이 글에서 다룬 것 자체가 워크숍 커리큘럼이 된다.
AI가 코드를 짜주는 시대가 아니라, AI에게 일을 위임하는 시대다. 위임할 줄 아는 사람이 하나의 회사가 된다. Skill은 그 위임 능력을 파일로 고정시키는 도구다. 한 번 잘 만들어두면 매주 30분씩 절약된다. 1년이면 26시간이고, 그 26시간분의 가치를 다른 사람에게도 팔 수 있다. 위임 능력이 복제 가능한 자산이 되는 순간이다.
다음 회 예고: Skill이 Claude의 행동을 정의하는 매뉴얼이라면, MCP 서버는 Claude의 손을 늘려주는 도구다. 10화에서는 GitHub, 데이터베이스, 브라우저, 파일 시스템을 Claude에게 직접 연결하는 MCP(Model Context Protocol)를 다룬다. Skill이 “무엇을 어떻게 하라”를 정의한다면, MCP는 “무엇에 접근할 수 있는가”를 정의한다. Skill과 MCP가 만나면 진짜 자동화가 시작된다.
연재 안내
- 이전 회: 8화 — 체크포인트·플랜모드·리뷰: 되돌릴 수 있어야 과감해진다
- 다음 회: 10화 — MCP 서버: Claude의 손을 늘리는 법
- 관련 회차: 4화 — 프롬프트가 아니라 작업 지시서를 쓴다 | 5화 — CLAUDE.md: 저장소의 헌법을 쓴다
◀ 이전 8화 (다음 차수는 아직 게시되지 않았습니다)
자주 묻는 질문
Claude Skills는 CLAUDE.md와 어떻게 다른가요?
CLAUDE.md가 저장소 전체에 적용되는 “헌법”이라면, Skills는 그 헌법 아래에서 돌아가는 개별 “업무 매뉴얼”입니다. Skills는 .claude/skills/ 디렉터리에 SKILL.md 파일로 저장되며, 특정 반복 업무를 모듈화하여 Claude가 필요할 때 자동으로 꺼내 쓰도록 만든 기능입니다.
Claude Skills를 쓰면 토큰을 절약할 수 있나요?
네, 참조 파일을 분리하면 해당 Skill을 사용하지 않을 때 토큰을 아낄 수 있습니다. 큰 템플릿이나 상세 규칙을 별도 파일로 분리해두면, Skill이 호출될 때만 해당 내용을 불러오므로 불필요한 토큰 소비 없이 복잡한 업무 지시도 부담 없이 묶을 수 있습니다.
[…] 시리즈: Claude 활용 24회 — AI에게 일을 위임하는 법 (총 24화 중 10화)◀ 이전 9화 (다음 차수는 아직 게시되지 […]