Claude Code Bundled Skills (/simplify /batch /debug) + /btw 기능 살펴보기
-
728x90
안녕하세요!
갓대희입니다.
오늘은 Claude Code의 Bundle Skills에 대해 살펴 보려 한다.
2026년 1월 24일(v2.1.0), Claude Code가 기존 커스텀 명령어(Custom Commands) 시스템을 업그레이드한 Skills 시스템을 도입했다. 특히 Bundled Skills(내장 스킬)인 /simplify,
/batch(이상 v2.1.0, 1월 24일), /debug(v2.1.30, 2월 3일)는 설치 없이 바로 쓸 수 있는 강력한 멀티에이전트 워크플로우다. (멀티에이전트: 여러 AI가
동시에 서로 다른 역할을 맡아 협업하는 방식)
목차
Claude Code Skills란
Skills의 개념과 등장 배경
Commands에서 Skills로: 무엇이 달라졌나
Bundled Skills vs Custom Skills
Bundled Skills: 내장 스킬 3종 완전 정복
/simplify — 실전 시나리오
/batch — 실전 시나리오
/debug — 실전 시나리오
보너스: /btw — 작업 중 사이드 질문
트러블슈팅 & FAQ
참고 자료
1. Claude Code Skills란
skills에 대해서는 다른글들에서 다뤘고, 어느정도 이해도가 있다는 가정하에 간단하게만 작성하고 넘어 간다.
Skills의 개념과
등장 배경
Skills(스킬)은 Claude Code에서 Claude의 능력을 확장하는 모듈형 지침 파일이다.
디렉토리 안에 SKILL.md 파일을 작성하면, Claude가 이를 자신의 도구 상자에
추가한다. 관련 대화가 나오면 자동으로 불러오거나, /스킬이름으로 직접 호출할 수 있다.
Skills는 Agent Skills 오픈 스탠다드를 따른다. 이 표준은 여러 AI 도구에서 공통으로 동작하도록 설계되어 있다. (출처: agentskills.io) Claude Code는 여기에 실행
제어(invocation control), 서브에이전트 실행(context: fork), 동적 컨텍스트 주입(!문법)을 추가로 제공한다.
Commands에서
Skills로: 무엇이 달라졌나
이전에는 .claude/commands/ 폴더에 마크다운 파일을 넣는 방식(Custom
Commands)을 사용했다. Skills 시스템은 이를 완전히 포함하면서 더 강력한 기능을 추가한다.
구분
기존 Commands
Skills (현재)
저장 경로
.claude/commands/review.md
.claude/skills/review/SKILL.md
호환성
그대로 동작 (하위 호환)
Skills 우선 (동명이면 Skills 승리)
보조 파일
단일 파일만
디렉토리 안에 템플릿·예시·스크립트 함께
자동 호출
제한적
description 기반 자동 감지
실행 격리
없음
context: fork로 서브에이전트 격리 실행
오픈 스탠다드
독자 방식
Agent Skills 표준 준수
기존 Commands 사용자라면?
지금 당장 바꾸지 않아도 된다. .claude/commands/ 파일은 그대로 동작한다.
다만, 새로운 스킬을 만든다면 .claude/skills/ 방식을 권장한다.
Bundled
Skills vs Custom Skills
Skills는 크게 두 종류로 나뉜다.
Bundled Skills (내장)
Custom Skills (커스텀)
Claude Code에 기본 탑재
설치·설정 불필요
/simplify, /batch, /debug
내부적으로 멀티에이전트 스폰
코드베이스에 맞게 자동 적응
직접 SKILL.md 작성
개인·프로젝트·조직 범위 선택
어떤 내용이든 패키징 가능
서브에이전트 격리 실행 지원
팀/조직 공유·배포 가능
SKILL.md 공식 프론트매터 필드 빠른 참조
커스텀 스킬 작성 시 사용할 수 있는 전체 필드
목록이다.
필드
기본값
설명
name
디렉토리명
슬래시 커맨드 이름. 소문자·숫자·하이픈, 최대 64자
description
첫 단락
스킬 설명 및 언제 사용할지. Claude가 자동 로드 여부 결정에 활용
argument-hint
없음
자동완성 시 표시되는 인수 힌트. 예: [issue-number]
disable-model-invocation
false
true이면 Claude가 자동 호출 불가. 사용자만
/이름으로 직접 호출
user-invocable
true
false이면 / 메뉴에서 숨김. Claude만
자동 호출 가능
allowed-tools
없음
권한 요청 없이 바로 사용 가능한 도구 목록
model
없음
이 스킬 활성화 시 사용할 모델 지정
context
없음
fork로 설정하면 격리된 서브에이전트 컨텍스트에서 실행 (현재
fork가 유일한 옵션)
agent
general-purpose
context: fork 사용 시 서브에이전트 타입 지정.
Explore, Plan, 커스텀 에이전트명 가능
hooks
없음
스킬 생명주기에 스코프된 훅 설정
AgentSkills 오픈 표준 공통
필드(license, compatibility, metadata)도 사용 가능. 커스텀 스킬 작성 상세는 Part 1
가이드 참고.
2. Bundled Skills: 내장 스킬 3가지 살펴보기
Bundled Skills는 Claude Code에 기본 탑재된 스킬로, 별도 설치 없이 바로 사용할 수 있다.
일반 슬래시 커맨드와 달리 고정 로직이 아닌 프롬프트
기반으로 동작하기 때문에, Claude가 에이전트를 스폰하고 파일을 읽으며 여러분의 코드베이스에 맞게 작업을 조율한다.
/simplify— 코드 품질 자동 개선
최근 변경된 파일을 코드 재사용성·품질·효율성 세 가지 관점에서 자동으로
검토하고 수정한다. 기능 구현이나 버그 수정 후 코드를 정리할 때 실행한다.
어떻게 동작하나?
/simplify 실행
│
├── 에이전트 1: 코드 재사용성 검토 ──┐
├── 에이전트 2: 코드 품질 검토 ──────┤ (병렬 실행)
└── 에이전트 3: 효율성 검토 ─────────┘
│
결과 취합 후 수정 적용
세 개의 리뷰 에이전트를 병렬로(동시에 여러 작업 처리) 스폰(생성·실행)하여 동시에
검토한 후, 결과를 통합해 수정을 적용한다.
사용 방법
// 기본 실행 (최근 변경 파일 전체 검토)
/simplify
// 특정 관점에 집중 (자유 텍스트 전달)
/simplify focus on memory efficiency
/simplify 중복 코드 제거에 집중해줘
언제 쓰면 좋을까? 기능 구현 직후, PR(Pull Request: 코드 변경사항을 팀원에게 검토 요청하는 것) 제출 전, 리팩토링(기능은 그대로 두고 코드 구조를 개선하는 작업) 완료 후
빠른 품질 체크가 필요할 때.
활용 시나리오
시나리오 1: 기능 구현 직후 PR 전 품질 체크
새 UserCard 컴포넌트를
구현했다. 기능은 동작하지만 빠르게 짜서 코드가 지저분하다. PR 올리기 전 /simplify를 실행한다.
$ /simplify
에이전트 3개가 병렬로 스폰 → 재사용성·품질·효율성 동시 검토
결과 통합 후 수정 적용: 중복 스타일 공통화, 조건부 렌더링 단순화 등
ex) 3개의 리뷰 에이전트를 병렬 스폰 하는 모습
- 하기 tip 의 /btw는 이후에 다룰 예정이다.
- 소스 리팩토링 진행
동작 원리를 클로드 코드에게 직접 설명해달라고 한 내용도 첨부
❯ simplify 기본 명령어에 대한 리뷰를 하려고 하는데 어떤 작업들을 어떤 원리에 의해서 어떤 사고과정을 통해서 무엇을으로 진행 했고 결과에 대해서도 리뷰해줘
⏺ /simplify 명령어 리뷰
명령어 구조 개요
/simplify는 3단계로 구성된 코드 품질 검증 파이프라인입니다.
---
Phase 1: 변경사항 식별
git diff HEAD --stat → 변경된 파일 목록 확인
git log --oneline -5 → 최근 커밋 파악
git diff HEAD~1 HEAD → 마지막 커밋의 전체 diff 추출
원리: 현재 작업 중인 코드가 아니라 "실제로 변경된 코드"에만 집중합니다. 전체 코드베이스를 리뷰하는 것은 비효율적이기 때문에, git diff로 스코프를 좁혀 신호 대 잡음 비율을
높입니다.
이번 실행에서는 마지막 커밋(Footer 추가, About 페이지, FAQ 확장 등 10개 파일, +480줄)이 대상이었습니다.
---
Phase 2: 3개 에이전트 병렬 실행
핵심은 단일 에이전트가 아닌 3개를 동시에 실행한다는 점입니다. 각 에이전트는 서로 다른 렌즈로 같은 코드를 봅니다.
Agent 1: Code Reuse (코드 재사용)
사고 원리: "이 코드를 새로 작성했는데, 이미 존재하는 무언가로 대체할 수 있는가?"
검사 항목:
- 새로 작성한 함수가 기존 함수와 중복되는가
- 인라인 로직을 기존 유틸리티로 대체할 수 있는가
- 상수/열거형이 있는데 raw string을 쓰고 있는가
이번 발견: Footer.tsx가 /json, /diff 등 12개 경로를 하드코딩 → ROUTES 상수가 이미 존재함
Agent 2: Code Quality (코드 품질)
사고 원리: "코드가 해키하거나 유지보수하기 어려운 패턴을 따르는가?"
검사 항목:
- 불필요한 상태 중복
- 파라미터 남발
- Copy-paste with slight variation (약간만 다른 복붙)
- 추상화 경계 위반
- Stringly-typed code (상수가 있는데 문자열 직접 사용)
- 불필요한 JSX 래퍼
이번 발견:
- Footer.tsx의 hardcoded routes (Stringly-typed 패턴)
- tarot/page.tsx의 <> fragment — 품질 에이전트는 "불필요"라고 판단했지만 이후 false positive로 확인됨
Agent 3: Efficiency (효율성)
사고 원리: "불필요한 연산, 놓친 동시성, 메모리 누수가 있는가?"
검사 항목:
- 핫패스에서의 반복 연산
- 순차 실행할 수 있는 것을 직렬로 실행
- 파일/리소스 불필요 전체 읽기
- 조건 없이 매 렌더마다 실행되는 업데이트
이번 발견: 이슈 없음 — 모든 파일이 Server Component여서 렌더당 연산 비용이 문제가 되지 않음. getAllPosts() await 제거도 올바른 수정으로 확인.
---
Phase 3: 결과 종합 및 수정
3개 에이전트 결과를 병합 후 false positive 판별이 중요합니다.
수정한 것
┌─────────────────────┬────────────┬───────────────────────────┐
│ 이슈 │ 파일 │ 수정 내용 │
├─────────────────────┼────────────┼───────────────────────────┤
│ ROUTES.HUB 누락 │ routes.ts │ /hub 상수 추가 │
├─────────────────────┼────────────┼───────────────────────────┤
│ 12개 hardcoded 경로 │ Footer.tsx │ 전부 ROUTES.* 상수로 교체 │
└─────────────────────┴────────────┴───────────────────────────┘
수정하지 않은 것 (false positive)
┌────────────────────────────────┬───────────────────┬──────────────────────────────────────────┐
│ 에이전트 발견 │ 판단 │ 이유 │
├────────────────────────────────┼───────────────────┼──────────────────────────────────────────┤
│ Tarot <> fragment 불필요 │ ❌ False positive │ 3개 sibling element이므로 fragment 필수 │
├────────────────────────────────┼───────────────────┼──────────────────────────────────────────┤
│ 스키마 생성을 함수 본문 안에서 │ ❌ False positive │ Server Component는 렌더당 비용 무시 가능 │
├────────────────────────────────┼───────────────────┼──────────────────────────────────────────┤
│ 인라인 교육 섹션 │ ❌ Skip │ 단일 사용 콘텐츠, 추상화 불필요 │
└────────────────────────────────┴───────────────────┴──────────────────────────────────────────┘
---
이번 결과의 품질 평가
잘 작동한 부분:
- 병렬 실행으로 단일 에이전트 대비 3배 빠른 분석
- Efficiency 에이전트가 Server Component 맥락을 정확히 파악해 false positive를 미리 걸러냄
- 실제 버그성 이슈(ROUTES 상수 미사용)를 정확히 포착
한계:
- Quality 에이전트가 <> fragment를 잘못 판단 — 문법 레벨 검증이 약함
- "스키마 생성 보일러플레이트 중복" 이슈는 사실이지만 현재 4개 페이지 수준에서는 과도한 추상화가 될 수 있어 skip했는데, 향후 더 많은 페이지가 생기면 의미 있는 리팩토링이 될 수
있음
핵심 원칙 요약: 찾아낸 모든 이슈를 무조건 수정하지 않고, false positive를 식별하고 "지금 수정할 가치가 있는가"를 판단하는 것이 이 명령어의 핵심입니다.
시나리오 2: 특정 관점에만 집중
데이터 처리 로직에서 메모리 효율이 걱정된다. 그
관점만 집중해서 검토받고 싶다.
$ /simplify 메모리 효율 최적화에 집중해줘
자유 텍스트 인수를 전달하면 3개 에이전트가 모두 해당 관점을 우선해
분석 방향을 조정한다.
/batch <instruction>— 대규모 병렬 리팩토링
코드베이스(프로젝트 전체 소스 코드 모음) 전체에 걸친 대규모 변경을 병렬로 조율한다. 변경 내용을
설명하면 /batch가 코드베이스를 분석해 5~30개의 독립적인 작업 단위로 분해하고, 각 단위를 별도의 git worktree(같은 저장소를 여러 폴더에서 동시에 독립적으로
작업하는 git 기능)에서 격리된 에이전트가 담당한다.
동작 흐름
/batch "migrate src/ from Solid to React"
│
├── 1. 코드베이스 분석
├── 2. 5~30개 작업 단위 분해
├── 3. 계획 제시 (사용자 승인 필요)
└── 4. (승인 후)
├── 에이전트 A: worktree-1에서 unit-1 구현 + 테스트 + PR ─┐
├── 에이전트 B: worktree-2에서 unit-2 구현 + 테스트 + PR ──┤ (병렬)
└── 에이전트 C: worktree-3에서 unit-3 구현 + 테스트 + PR ──┘
사용 예시
/batch migrate src/ from Solid to React
/batch add error handling to all API calls in src/api/
/batch convert all class components to functional components
/batch add TypeScript types to all JavaScript files in lib/
주의사항
/batch는 git 저장소가 필요하다. worktree 기반으로 작동하기 때문이다.
각 에이전트는 작업 후 PR 생성을 시도한다. (gh CLI가 설치·인증된 환경 필요 / gh는 터미널에서 GitHub를 조작하는 공식 명령줄 도구)
다수의 에이전트가 동시에 실행되므로 토큰 사용량이 크게 증가할 수 있다. 사용 플랜(Pro/Team/Enterprise)의 한도를 미리 확인하라.
언제 쓰면 좋을까? 프레임워크 마이그레이션, 전사적 코드 스타일 변경, 대규모 리팩토링처럼 수십 개 파일을 동시에 바꿔야 할 때.
활용 시나리오
시나리오 1: 전체 프로젝트 TypeScript 마이그레이션
src/ 내 JS 파일
30개에 TypeScript(JavaScript에 타입 명시를 추가한 언어. 예: count: number 처럼 변수 종류를 미리 선언) 타입을 추가해야 한다. 파일 하나씩 하면
며칠이 걸린다.
$ /batch add TypeScript types to all .js files in src/
Claude가 코드베이스를 분석 → 작업 단위(src/utils, src/api, src/components/... 등)로 분해
계획 제시 → 사용자 승인 대기. "이 계획으로 진행할까요?" 확인 단계가 있다
승인 후 각 단위별 에이전트가 별도 worktree에서 동시 작업 → 각자 PR 생성
시나리오 2: async 함수(비동기 처리 함수 - 서버 응답을 기다리는 동안 다른 작업도 계속하는 함수) 전체에 에러 핸들링 일괄 추가
src/api/ 내 async
함수들이 try-catch(오류가 발생해도 프로그램이 중단되지 않도록 처리하는 코드 구조) 없이 작성되어 있다. 전부 한 번에 수정하고 싶다.
$ /batch add try-catch error handling to all async functions in src/api/
범위를 src/api/로 한정하면 작업 단위가 작아져 더 빠르고 정확하게 처리된다
각 에이전트가 담당 파일을 수정 후 PR을 생성하므로, 리뷰도 파일 단위로 할 수 있다
/debug [description]— 세션 디버거
현재 Claude Code 세션(현재 실행 중인 Claude Code 작업 단위)의 디버그 로그(문제 파악을
위해 자동으로 기록된 실행 과정 기록)를 읽어 문제를 분석한다. Claude가 왜 이상하게 동작하는지, 어떤 도구 호출이 실패했는지 파악하고 싶을 때 사용한다.
// 전체 세션 로그 분석
/debug
// 특정 문제에 집중해서 분석
/debug Claude가 파일 쓰기를 계속 거부함
/debug tool call keeps failing on Read
활용 시나리오
시나리오 1: 도구 호출이 반복 실패할 때
Claude가 특정 파일을 계속 읽지 못하거나 같은
오류를 반복한다. 어느 시점부터 무슨 이유로 실패하는지 파악이 안 된다.
$ /debug Read tool keeps returning empty on config.json
세션 디버그 로그를 읽어 도구 호출 실패 시점과 원인을 진단한다. 파일
권한 문제인지, 경로 오류인지 구체적으로 알려준다.
ex) /debug
- 이 예시는 원하는 상황까진 아니지만 여러 상황에 활용해볼
수 있을 것 같다. ( 이후 다른 예시로 갱신하도록 하겠습니다. )
시나리오 2: 응답이 갑자기 이상해졌을 때
작업 도중 Claude가 요청과 무관한 파일을
수정하거나 뜬금없는 동작을 한다. 원인을 모르겠다.
$ /debug
설명 없이 실행하면 현재 세션 전체를 분석해 가장 최근의 이상 동작
원인을 진단한다.
Bundled Skills의 특이점: 개발자 플랫폼 스킬
Claude Code에는 개발자 플랫폼 스킬(Anthropic SDK 전용)도 내장되어 있다.
Python/TypeScript 코드에서 anthropic 또는 @anthropic-ai/sdk 패키지 임포트가 감지되면 자동으로 활성화된다. 별도로 호출할
필요 없다. (출처: Claude
Code 공식 문서)
보너스: /btw — 작업 중 사이드 질문
/btw는 현재 작업을 중단하지
않고 단발성 사이드 질문을 던질 수 있는 빌트인 커맨드다. 응답은 대화 히스토리에 추가되지 않기 때문에, 메인 작업 흐름에 영향을 주지 않는다.
에이전트 한 개가 실패해도 나머지는 계속 진행한다. 실패한 작업 단위만 수동으로 재처리하면 된다
/debug
— 분석 결과가 뜻 밖이거나 원인을 모르겠을 때
해결 방법:
설명을 추가해 범위를 좁힌다: /debug Write tool이 permission denied를 반환함
디버그 로그가 너무 방대하면 /debug 최근 10개 도구 호출만 분석해줘처럼 범위 지정
그래도 원인을 못 찾겠다면 /new-session으로 새 세션을 시작하면 대부분 해결된다
자주 묻는 질문
(FAQ)
Bundled Skills는 어디에
저장되어 있나?
Claude Code 내부에 내장(빌트인)되어 있다. 파일 시스템에 노출되지 않으며, 업데이트는
Claude Code 자체 업데이트를 통해 이뤄진다.
/simplify, /batch, /debug를 수정할 수
있나?
직접 수정은 불가하다. 같은 이름의 커스텀 스킬을 만들면 Bundled Skills보다 우선
적용된다. (커스텀 스킬 제작은 Part 1 참고)
/batch 작업 중 한 에이전트가 실패하면?
나머지 에이전트는 계속 진행한다. 실패한 작업 단위는 별도 worktree(독립 작업 폴더)에
남아 있으므로 해당 브랜치에서 수동으로 이어서 작업하면 된다.
/batch 실행 전 계획을 취소하고 싶다면?
계획 제시 단계에서 "취소" 또는 "no"로 응답하면 에이전트가 스폰되지 않고 종료된다. 일단
승인 후에는 중간에 멈추기 어려우므로 계획 단계를 꼼꼼히 확인하자.
/debug가 세션 로그를 못 찾는다고 할 때?
Claude Code 세션 로그 파일이 생성되지 않았을 수 있다. 세션이 너무 짧거나 로그
기록이 비활성화된 환경일 경우 발생한다. 로그 설정은 claude config에서 확인한다.
SKILL.md에
max-iterations 옵션이 있나?
없다. SKILL.md 공식 프론트매터 필드가 아니다. 커뮤니티 블로그 등 비공식
출처에서 잘못 전파된 정보일 가능성이 있다. 비슷한 기능이 필요하다면, 서브에이전트 설정 파일(AGENT.md)의 maxTurns 필드를 사용한다.
(출처: Claude Code 공식 문서, 2026-03-02 확인)
SKILL.md에
completion-promise 옵션이 있나?
없다. Claude Code 공식 문서와 AgentSkills 오픈 스탠다드 명세
어디에도 이 필드는 정의되어 있지 않다. 온라인에서 보았다면 비공식 출처의 오류이거나 내부 실험 기능일 수 있으니 공식 문서를 기준으로 삼을 것을 권장한다. (출처: Claude Code 공식 문서
+ agentskills.io 명세, 2026-03-02 확인)
