Claude Code에 Skill을 만들기 시작한 지 7개월. 처음엔 긴 프롬프트를 파일에 저장하는 정도였는데, 어느 순간 몇 개는 매일 쓰고 몇 개는 만들어놓고 쓴 적이 없다는 걸 알아챘습니다.
들어가며 — 7개월 써보고 살아남은 것만 추렸습니다
Claude Code에 Skill(슬래시 커맨드, 서브에이전트)을 만들기 시작한 지 7개월이 됐습니다. 처음엔 그냥 긴 프롬프트를 .claude/commands/ 아래 파일로 저장하는 정도였는데, 시간이 지나면서 몇 개는 거의 매일 쓰고 몇 개는 만들어놓고 한 번도 다시 찾지 않는 게 갈렸습니다.
이번에 8,041개 세션 히스토리를 훑어서 "실제로 살아남은 Skill"만 추려봤습니다. 10개 이상 프로젝트를 가로질러 반복 등장한 패턴이 5가지였습니다. 게임(Unity), 웹앱(React/Supabase), Flutter 앱, 기획·마케팅 문서 작업까지, 전혀 다른 도메인에서도 같은 구조가 계속 나왔습니다.
이 글은 그 5가지 패턴의 실물 코드와, 왜 그게 살아남았는지를 정리한 것입니다. 복붙해 쓸 수 있는 Skill 파일 구조를 함께 뒀으니, Claude Code를 쓰고 있거나 쓸 생각이 있으면 바로 적용할 수 있습니다. (여기서 Skill은 슬래시 커맨드와 서브에이전트를 포함한 포괄적인 개념입니다.)
1. Multi-Critic — 하나의 코드 변경에 비평가 4명 붙이기
가장 오래 살아남은 Skill 1위는 Multi-Critic입니다. 6개 이상의 프로젝트에 그대로 복붙해 쓰고 있는 패턴이고, 기능 구현이 끝난 직후 코드 리뷰 단계에서 매번 호출합니다.
구조는 단순합니다. 하나의 코드 변경에 대해 관점이 서로 다른 4개의 비평 에이전트를 단일 메시지에서 병렬 스폰하고, 결과를 메인 Claude가 종합합니다. 각 에이전트는 자기 영역만 봅니다. 데이터 무결성 / 로직 정합성 / 보안 리스크 / UX 품질을 독립 축으로 분리한 겁니다.
이걸 쓰는 이유는 단일 시점의 리뷰가 놓치는 사각지대를 구조적으로 제거하기 때문입니다. 4명이 각자 관점에서 훑고 나서 2명 이상이 동일 이슈를 지적하면 확정 결함으로, 1명만 지적한 건 참고 사항으로 분류합니다. 오탐(false positive)이 줄고, 과잉 수정도 방지됩니다.
아래는 실제로 쓰는 /critic Skill의 뼈대입니다. 4개 에이전트를 정의하고 메인 Claude가 결과를 종합 분석하도록 지시하는 구조입니다.
# Critic — 4 에이전트 병렬 코드 비평
## 실행 절차
1. 대상 파일 결정: $ARGUMENTS 또는 `git diff --name-only HEAD~1`
2. 변경 파일 10개 이상이면 기능별 그룹핑 → 핵심 그룹만 전달
3. **4개 에이전트를 단일 메시지에서 병렬 스폰**
4. 전체 결과를 메인 Claude가 종합 분석
## 에이전트 A — 데이터 무결성 감사
- 관점: 모든 수치는 증명되기 전까지 거짓이다
- 검증 축: 산술 정합성, 데이터 변환 손실, 캐시-원본 불일치
- 출력: 점수(N/10), 이슈 목록(파일:라인 + 심각도), 판정
## 에이전트 B — 로직 정합성 질문자
- 관점: 아무것도 모른다. 다만 질문할 뿐이다
- 검증 축: 상태 전이 일관성, 워크플로우 모순, 엣지케이스
## 에이전트 C — 보안/리스크 비관주의자
- 관점: 이 시스템은 뚫린다
- 검증 축: 권한 상승 경로, 데이터 노출, 인증 취약점
## 에이전트 D — UX/성능 파괴자
- 관점: '편리한 UI'라는 우상을 부수겠다
- 검증 축: 클릭 경제성, 에러 복구 비용, 접근성
## 종합 분석 규칙 (메인 Claude 수행)
- 2+ 에이전트 공통 지적 → 교차 패턴 테이블로 정리
- 우선순위 매트릭스: 순위 | 항목 | 지적 에이전트 | 영향도 | 수정 난이도/critic 한 번의 호출로 전체 파이프라인이 자동 실행됩니다. 대상 미지정 시에는 최근 커밋의 변경 파일을 자동으로 감지합니다.
2. Architect → Implement → Review — 설계와 구현을 분리하는 파이프라인
두 번째는 하나의 기능 요청을 설계(Architect) → 구현(Implement) → 검증(Critic) 3단계로 분리하는 패턴입니다. 각 단계에 전문화된 에이전트를 배치하고, 단계 사이에는 사용자 승인 게이트를 둡니다. 이것도 3개 이상 프로젝트에 똑같은 구조로 적용돼 있습니다.
핵심은 관심사 분리입니다. 설계 에이전트는 코드를 쓰지 않고, 구현 에이전트는 설계를 바꾸지 않습니다. 설계 문서가 사용자 명시 승인을 받기 전까진 구현 단계로 넘어가지 못합니다. 이게 의도하지 않은 구현을 구조적으로 막아줍니다. (이 분리는 제가 쓰는 CAOF(Claude Agent Orchestration Framework, 에이전트 오케스트레이션 규약)의 핵심입니다. 왜 이런 분리가 필요한지는 2026-03-27 "Claude Code 에이전트가 폭주할 때" 글에서 다뤘습니다.)
아래는 설계 에이전트 Skill 파일입니다. 코드를 못 쓰게 막고, 사용자 승인 게이트까지 강제하는 구조입니다.
# Architect — 시스템 아키텍트
## 페르소나
10년차 시니어 아키텍트. 코드를 직접 작성하지 않는다 — 설계만 한다.
5원칙: 회의적 질문자, 복잡성 감시자, 실패 시나리오 집착, 단순함 옹호, 코드 금지.
## 절차
1. 기존 코드베이스와 규칙 파일 탐색 (Read/Grep/Glob만 허용)
2. 최소 3개의 공격적 질문 (목표, 범위, 제약, 트레이드오프, 실패 시나리오)
3. 설계 문서 작성:
- 수정 대상 파일 테이블
- 핵심 함수/메서드 명세
- 재사용 가능한 기존 코드
- 경고사항 및 실패 시나리오
4. 승인 게이트 — 사용자가 "approved" 할 때까지 구현 금지
## 출력
설계 문서를 `planning/YYYY-MM-DD-기능명.md`에 저장
완료 후 안내: `/implement planning/설계문서.md` 로 구현 시작구현 에이전트는 별도 파일(/implement)로 분리돼 있고, 페르소나는 "8년차 시니어 개발자, 아키텍트의 설계를 충실히 실행한다"입니다. 핵심 제약은 세 가지입니다. 계획에 없는 코드 금지, "일단 고쳐보겠다" 금지(근본 원인 명시 + 선택지 제시 필수), 규칙 파일 위반 금지. 구현이 끝나면 변경 파일 목록과 설계 대비 이탈 사항, 자가점검 결과를 보고서로 남깁니다.
전체 체인은 /architect → (사용자 승인) → /implement 설계문서.md → /critic 순으로 진행됩니다. 각 단계 전환이 명시적 승인을 거치기 때문에, 잘못된 방향으로 15분 달리다 "아 이게 아닌데" 하고 되돌리는 일이 크게 줄었습니다.
3. Cross-Model Parallel Review — AI 모델 4개에 동시에 물어보기
세 번째는 동일한 코드 또는 기획 문서를 서로 다른 AI 모델 4개(Gemini, Claude Opus, Sonnet, Haiku)에 동시에 리뷰시키는 패턴입니다. 기획서 완성 후 구현 착수 전 Planning Review나, 대규모 코드 변경 후 Code Review에서 씁니다.
왜 모델을 나누냐면, 같은 모델이 자기 출력을 리뷰하면 자기 동의 편향(self-agreement bias)이 생겨서 사실상 쓸모없기 때문입니다. 모델마다 blind spot이 달라서, 다른 모델이 그 사각지대를 보완해줍니다. (이 문제를 페르소나 관점에서 어떻게 다뤄야 하는지는 2026-04-08 "AI 에이전트에게 넌 전문가야라고 말하면 진짜 잘할까" 글에서 다뤘습니다.)
각 모델에 역할을 다르게 줍니다. Gemini는 구조적 일관성, Claude Opus는 깊은 논리 분석, Sonnet은 실용성/구현 가능성, Haiku는 직관적 이상 탐지 필터. 아래는 실제 쓰는 /검수 Skill 구조입니다.
# 4모델 병렬 검수
## 모드 A — 기획서 검수 (기본)
1. 대상 문서 감지: specs/ 디렉토리 또는 $ARGUMENTS
2. 4개 에이전트 병렬 실행:
- Gemini (외부 CLI): 구조적 일관성 검토
- Claude Opus (서브에이전트): 깊은 논리적 분석
- Claude Sonnet (서브에이전트): 실용성/구현 가능성 검토
- Claude Haiku (서브에이전트): 직관적 이상 탐지 필터
3. 4개 보고서 수집 → 교차 분석 → 최종 보고서 저장
## 모드 B — 코드 검수 (`/검수 code`)
1. `git diff`로 변경 사항 수집
2. 동일한 4개 모델로 코드 레벨 리뷰
3. 최종 보고서 저장
## 판정 기준
- 3+ 모델 합의 → 확정적 이슈 (반드시 수정)
- 2 모델 합의 → 검토 필요 이슈
- 1 모델만 지적 → 참고 사항다수결 기반 신뢰도 판정이 실전에선 꽤 잘 작동합니다. 3개 이상 모델이 같이 지적하면 거의 확정 결함이라 그냥 고치고, 1개만 지적한 건 "참고"로만 보고 넘어갑니다. 이 분류만으로도 "우선순위 어떻게 잡지" 고민이 사라졌습니다.
4. Domain-Specific Automation — 반복 작업을 슬래시 커맨드 한 줄로
네 번째는 프로젝트에서 반복적으로 하는 작업을 하나의 Skill로 캡슐화하는 패턴입니다. 경험상 ROI가 가장 높았던 유형입니다. 5~10단계의 수동 작업이 단일 명령으로 축소됩니다.
대표 사례 두 개만 보여드리겠습니다. 첫 번째는 버전 업데이트 자동화입니다. Flutter 앱을 배포할 때마다 pubspec.yaml 버전 올리고, 관련 설정 파일 3곳 동기화하고, 릴리즈 노트 쓰는 걸 매번 수동으로 했는데, 한 번 묶어놓으니 /version-up 한 줄로 끝납니다.
# Version Up — 원클릭 버전 관리
## 절차
1. 현재 버전 읽기 (pubspec.yaml)
2. 마이너 버전 +1, 빌드 넘버 +1
3. 관련 설정 파일 3곳 동기화 (네이티브 빌드 설정 포함)
4. 클린 빌드 실행
5. 최근 10개 커밋 분석 → 릴리즈 노트 자동 생성
- 앱스토어용 영문 카피
- 다국어 4줄 업데이트 노트두 번째는 다국어 처리 자동화입니다. 하드코딩된 자국어 문자열을 찾아서 번역 키를 만들고, 영문 번역을 붙여서 번역 사전에 등록하고, 원본 코드에서 문자열을 키 호출로 교체하는 5단계 작업입니다. 이것도 /i18n 한 줄로 압축해뒀습니다.
# i18n — 하드코딩 텍스트 다국어 전환
## 절차
1. 대상 파일에서 하드코딩된 자국어 문자열 검출
2. 번역 키 자동 생성 (섹션\_의미 네이밍 규칙)
3. 영문 번역 생성
4. 번역 사전 파일에 양방향 등록
5. 원본 코드에서 문자열을 번역 키 호출로 교체
6. 결과 보고 (변환 건수, 누락 건수)이런 Automation Skill의 진짜 가치는 실수 방지입니다. 수동으로 할 때 "3곳 중 2곳만 동기화"하거나 "번역 키 등록 누락" 같은 실수가 생기는데, 이걸 명령 하나에 묶어두면 그런 누락이 사라집니다. 프로젝트 맥락을 잠시 잊은 상태에서도 명령만 실행하면 결과가 나와서 컨텍스트 복원 비용이 줄어드는 것도 큰 이점입니다.
5. Hook-Based Auto-Routing — 프롬프트 키워드로 에이전트 자동 배치
다섯 번째는 사용자가 입력하는 자연어 프롬프트의 키워드를 실시간으로 감지해서, 적절한 에이전트 조합을 자동으로 컨텍스트에 주입하는 패턴입니다. 명시적으로 에이전트를 호출하지 않아도 시스템이 키워드를 보고 알아서 올바른 워크플로우로 유도합니다.
아래는 실제 쓰는 Hook 두 개입니다. 첫 번째는 프롬프트 감지 Hook으로, 모든 사용자 입력을 받아 키워드 매칭이 되면 에이전트 조합을 주입합니다.
#!/bin/bash
# UserPromptSubmit Hook — 모든 프롬프트에서 실행
PROMPT="$1"
# 도메인 키워드 감지 → 에이전트 조합 자동 주입
if echo "$PROMPT" | grep -qE '구현해|버그|스크립트'; then
echo '{"additionalContext": "CAOF 라우팅: Designer + Implementer 배치"}'
exit 0
fi
# 이미지 생성 키워드 → 사전 승인 요청 주입
if echo "$PROMPT" | grep -qE '이미지.*만들|생성'; then
echo '{"additionalContext": "이미지 생성 전 반드시 사용자 승인 필요"}'
exit 0
fi
exit 0 # 매칭 없으면 무시두 번째는 위험 명령 차단 Hook입니다. 되돌릴 수 없는 명령(force push, hard reset 등)을 자동으로 차단합니다.
#!/bin/bash
# PreToolUse Hook — 모든 Bash 명령 실행 전 검사
COMMAND="$1"
# 되돌릴 수 없는 명령 차단
if echo "$COMMAND" | grep -qE 'git reset --hard|git push --force|git clean -f'; then
echo "BLOCKED: 되돌릴 수 없는 명령입니다. 사용자에게 확인하세요."
exit 2
fi
exit 0settings.json의 hooks 섹션에 등록해두면 모든 세션에서 자동으로 돌아갑니다. 에이전트 호출을 깜빡해도 시스템이 알아서 라우팅하고, 파괴적 명령은 실행 전에 막힙니다. 설정 후엔 가장 편하지만, 처음 세팅에는 한 번 앉아서 Hook 구조를 이해하고 붙여야 한다는 점이 주의할 부분입니다. 앞선 4개 Skill보다 진입장벽이 조금 있어서, 저도 가장 나중에 손댔습니다.
Skill 유형별 비교 요약
| 유형 | 주요 가치 | 실행 방식 | 사용 빈도 | 난이도 |
|---|---|---|---|---|
| Multi-Critic | 교차 검증으로 결함 누락 방지 | /critic → 4 에이전트 병렬 | 매 기능 완료 시 | 중 |
| Architect-Implement Pipeline | 설계/구현 분리로 품질 확보 | /architect → 승인 → /implement | 신규 기능마다 | 중 |
| Cross-Model Review | 모델 편향 상쇄 | /검수 → 4 모델 병렬 | 기획서 완성 시 | 상 |
| Domain Automation | 반복 작업 제거 | /version-up, /i18n 등 | 배포/텍스트 작업 시 | 하 |
| Hook Auto-Routing | 워크플로우 자동 유도 | 항상 (백그라운드) | 모든 세션 | 하 (설정 후) |
Skill은 "프롬프트 저장소"가 아니라 "판단 구조의 라이브러리"입니다
7개월 써보고 얻은 제일 큰 깨달음은 이겁니다. Skill은 단순히 긴 프롬프트를 저장하는 게 아니라, 누가 / 무엇을 / 어떤 기준으로 판단하는가를 구조화한 것이라는 점입니다.
같은 Multi-Critic 구조가 웹앱, 모바일앱, 게임, 데이터 분석 등 전혀 다른 도메인에 재적용되면서 검증 축만 도메인에 맞게 교체됐습니다. Architect-Implement 분리도 마찬가지입니다. 어떤 언어·프레임워크에서도 "설계자는 코드를 쓰지 않는다, 구현자는 설계를 바꾸지 않는다"는 판단 경계는 그대로 유지됩니다. 바뀌는 건 도메인 용어뿐입니다.
결국 Skill 라이브러리는 재사용 가능한 판단 구조의 저장소에 가깝습니다. 이게 제가 찾은 자동화의 3계층 구조입니다.
Layer 3: Hook (항상 실행, 키워드 감지 → 라우팅)
Layer 2: Pipeline (사용자 호출, 다단계 워크플로우)
Layer 1: Single Skill (사용자 호출, 단일 작업)이 3계층이 결합되면서 "적절한 에이전트가 적절한 타이밍에 적절한 깊이로" 개입하는 체계가 만들어집니다.
어느 것부터 시작하면 좋을까
"5개 다 해보고 싶은데 뭐부터 손대지?"라는 질문을 받으면 저는 이렇게 답합니다. Domain Automation부터 시작하는 게 제일 낫습니다. 난이도가 가장 낮고 ROI가 가장 빠릅니다. 매번 하는 반복 작업 하나를 골라서 .claude/commands/ 아래 슬래시 커맨드 파일 하나만 만들어보면, 다음 주부터 바로 체감됩니다. 버전 업데이트든 번역 키 교체든, 매번 손이 가는 작업이 있다면 그게 1순위 후보입니다.
그 다음은 Multi-Critic이나 Architect-Implement Pipeline을 얹고, Cross-Model Review는 기획서를 자주 쓰게 되는 단계에서 추가하면 됩니다. Hook-Based Auto-Routing은 가장 나중에 손대시는 걸 권합니다. 가치는 가장 크지만 세팅 한 번에 시간이 좀 들어서, 앞의 4개 Skill을 충분히 써보고 "어떤 키워드에서 어떤 에이전트가 자동 배치되면 좋을지" 감이 생겼을 때 붙이는 게 효율이 좋습니다.
