코드 작성/분석 관점에서 실용적으로 정리하면 이렇습니다.
핵심 구분: "무엇을 재사용하는가" vs "어디서 실행되는가"
스킬(Skill) = 재사용 가능한 지식/워크플로우를 담은 마크다운 파일. 메인 대화 컨텍스트 안에서 로드됨. 서브에이전트(Subagent) = 독립된 컨텍스트에서 실행되는 별도의 작업자. 작업 결과만 요약해서 돌려줌.
즉 스킬은 "무엇을 어떻게 하는지"에 대한 지식이고, 서브에이전트는 "어디서, 누가" 그 작업을 수행하는지에 대한 문제입니다. 실제로는 이 둘이 자주 결합됩니다 (서브에이전트가 특정 스킬을 preload해서 실행).
판단 기준표
기준 스킬을 써야 할 때 서브에이전트를 써야 할 때
| 목적 | 반복되는 지식/체크리스트/워크플로우를 재사용 | 메인 컨텍스트를 오염시키지 않고 격리된 작업 수행 |
| 예시 | API 스타일 가이드, /deploy 배포 체크리스트, 코드 리뷰 체크리스트 | 코드베이스 전체를 뒤지는 리서치, 대규모 리팩터링 실행, 병렬 검증 |
| 컨텍스트 영향 | 메인 대화창에 그대로 쌓임 (설명은 항상, 본문은 사용 시) | 별도 창에서 처리되고 요약만 돌아옴 |
| 적합한 작업 규모 | 짧고 명확한 절차, 참고 자료 | 파일을 수십 개 읽어야 하거나, 탐색적이고 결과가 불확실한 작업 |
실용적 규칙
- "같은 프롬프트를 세 번째 붙여넣고 있다" → 스킬로 만드세요.
- "이 작업이 끝나면 중간 과정은 볼 필요 없고 결론만 필요하다" → 서브에이전트로 위임하세요.
- "파일을 수십 개 읽어야 하는데 메인 대화가 그걸로 꽉 찰 것 같다" → 서브에이전트.
- "이건 지식이지 실행 단위가 아니다" (예: DB 스키마, 코딩 컨벤션) → 스킬.
- 둘은 배타적이지 않습니다. 예: /audit 스킬이 보안·성능·스타일 검사용 서브에이전트 3개를 동시에 띄우는 패턴이 흔합니다.
만들 때 실전 팁
스킬 만들 때:
- ~/.claude/skills/이름/SKILL.md에 name, description(트리거 조건을 명확히!)을 프론트매터로 작성
- description이 모호하면 Claude가 스킬을 안 부르거나 잘못 부름 — "언제 쓰는지"를 구체적으로 명시
- 부작용(side effect)이 있는 스킬(배포, 삭제 등)은 disable-model-invocation: true로 설정해서 자동 트리거 막고 /이름으로만 수동 실행
서브에이전트 만들 때:
- 자체 시스템 프롬프트, 도구 허용 목록, 필요시 모델까지 별도 지정 가능
- skills: 필드로 특정 스킬을 미리 로드시킬 수 있음
- 읽기 전용 작업(코드 리뷰, 조사)엔 쓰기 도구를 아예 빼서 안전하게 격리 가능
CLAUDE.md와 헷갈릴 때는: "항상 지켜야 하는 규칙"이면 CLAUDE.md, "가끔 필요한 참고자료/절차"면 스킬입니다.
서브에이전트는 YAML frontmatter가 있는 마크다운 파일입니다. 만드는 방법과 호출 방법을 나눠서 설명할게요.
1. 만드는 방법
파일 위치
- .claude/agents/이름.md — 프로젝트 단위 (팀과 공유, git에 커밋)
- ~/.claude/agents/이름.md — 사용자 단위 (모든 프로젝트에서 사용)
- 우선순위: managed > project > user (같은 이름이면 상위가 이김)
만드는 두 가지 방법
- Claude에게 직접 만들어달라고 요청 — "code-reviewer라는 서브에이전트를 만들어줘, Read/Grep/Glob만 쓰고 보안·버그 위주로 검토하게" 라고 프롬프트로 말하면 됨
- 직접 파일 작성
참고: v2.1.198부터 /agents 명령이 대화형 생성 마법사를 열지 않습니다. 대신 Claude에게 요청하거나 .claude/agents/를 직접 편집하라는 안내만 출력됩니다.
예시 파일
---
name: code-reviewer
description: 코드 변경 후 버그, 보안 이슈, 컨벤션 위반을 검토. 코드 작성/수정 직후 사용.
tools: Read, Grep, Glob
model: sonnet
permissionMode: default
skills: code-review-standards
---
당신은 시니어 코드 리뷰어입니다. diff나 파일 묶음이 주어지면:
1. 정확성 버그, 보안 취약점, 놓친 엣지 케이스를 찾는다
2. 코딩 컨벤션 위반을 지적한다
3. 발견 사항을 우선순위별로 요약해서 보고한다
주요 frontmatter 필드
필드 필수 설명
| name | ✅ | 소문자+하이픈 |
| description | ✅ | 자동 위임의 핵심. Claude가 이 설명을 보고 언제 이 서브에이전트를 부를지 판단하므로, 구체적인 트리거 조건을 써야 함 |
| tools | ❌ | 생략 시 전체 도구 상속. 필요한 것만 좁게 지정 권장 (읽기 전용 작업이면 쓰기 도구 아예 빼기) |
| model | ❌ | sonnet/opus/haiku/inherit |
| permissionMode | ❌ | default/acceptEdits/bypassPermissions/plan |
| skills | ❌ | 이 서브에이전트에 미리 로드할 스킬 목록 |
| disallowedTools | ❌ | 명시적으로 금지할 도구 |
| mcpServers, hooks, maxTurns, memory, effort | ❌ | 고급 설정 |
2. 호출하는 방법
(1) 자동 위임 — 가장 일반적
아무 지시 없이 그냥 작업을 요청하면, Claude가 description을 보고 알아서 적절한 서브에이전트에게 위임합니다. description에 "proactively" 같은 키워드를 넣으면 더 적극적으로 자동 위임하도록 유도할 수 있습니다.
(2) 명시적으로 지정
프롬프트에서 이름을 직접 언급하면 됩니다.
code-reviewer 서브에이전트로 이 diff 검토해줘
(3) /agents 명령
현재 등록된 서브에이전트 목록 확인, 실행 중인 서브에이전트 확인/중지에 사용 (생성 마법사는 이제 없음).
(4) --agent 플래그로 세션 전체를 특정 에이전트로 실행
claude --agent code-reviewer
이건 "위임"이 아니라 메인 세션 자체가 그 에이전트의 시스템 프롬프트/도구 제약을 그대로 쓰는 방식입니다.
(5) --agents 플래그로 즉석 정의 (파일 없이)
claude --agents '{"reviewer": {"description": "...", "prompt": "...", "tools": "Read,Grep"}}'
실전 팁
- description을 구체적으로 쓰세요. "코드 리뷰 담당" 같은 애매한 설명은 자동 트리거가 잘 안 됩니다. "코드 작성/수정 직후 버그와 보안 이슈를 검토, 사용해야 함"처럼 트리거 조건을 명시하세요.
- tools는 최소한으로. 읽기 전용 리서치 에이전트라면 Write/Edit을 아예 빼서 실수로 파일을 건드리지 못하게 하세요.
- description이 모호하거나 여러 에이전트 범위가 겹치면 Claude가 잘못 위임하는 게 가장 흔한 실패 사례입니다.
클로드 코드에 붙여넣을 프롬프트 예시입니다.
기본 프롬프트
.claude/agents/ 에 code-analyzer 라는 서브에이전트를 만들어줘.
역할: 이 프로�트의 특정 파일이나 디렉토리, 또는 최근 변경된 diff를
받으면 다음 두 가지를 수행한다:
1. 코드 동작 설명 - 이 코드가 무엇을 하는지, 주요 함수/모듈의
흐름과 책임을 초보자도 이해할 수 있게 설명
2. 코드 리뷰 - 버그 가능성, 보안 이슈, 성능 문제, 컨벤션 위반,
가독성/유지보수성 문제를 찾아서 우선순위(심각/보통/사소)별로 정리
동작 방식:
- 먼저 관련 파일들을 읽고 프로젝트의 전체 구조(디렉토리 구성,
주요 의존성, 아키텍처 패턴)를 파악한다
- 파일 간 의존관계(어디서 호출되고 어디서 임포트되는지)도 함께 확인한다
- 결과는 "동작 설명" 섹션과 "리뷰 결과" 섹션으로 나눠서 보고한다
- 리뷰 결과에는 구체적인 파일명:라인번호와 함께 무엇을, 왜 고쳐야 하는지 제시
- 코드를 직접 수정하지 않고 읽기 전용으로만 분석한다
이 서브에이전트는 코드 리뷰가 필요하거나, 특정 파일/모듈이 무엇을
하는지 설명이 필요할 때 자동으로 위임되도록 description을 작성해줘.
tools는 읽기 전용(Read, Grep, Glob 등)으로 제한해줘.
더 간단한 버전 (빠르게 시작하고 싶을 때)
이 프로젝트를 분석해서 코드 리뷰와 동작 설명을 해주는 서브에이전트를
.claude/agents/code-analyzer.md 로 만들어줘. 읽기 전용 도구만 쓰게
하고, description에는 코드 리뷰나 코드 설명이 필요할 때 자동으로
호출되도록 구체적인 트리거 조건을 넣어줘.
만든 후 사용법
생성이 끝나면 이렇게 호출하면 됩니다.
code-analyzer로 src/auth 디렉토리 분석하고 리뷰해줘
또는 아무 언급 없이 "이 함수 뭐 하는 건지 설명해줘" / "이 PR 리뷰해줘"라고만 해도 description이 잘 작성되어 있으면 Claude가 자동으로 위임합니다.
팁: 프로젝트가 특정 언어/프레임워크(예: TypeScript+React, Django 등)라면 프롬프트에 그 스택을 명시해주면 리뷰 기준(예: React 훅 규칙, Django ORM 쿼리 최적화 등)이 훨씬 정확해집니다.