Skill과 Agent는 무엇인가
Claude Code는 Anthropic이 제공하는 터미널 기반 AI 코딩 도우미입니다. 이 도구를 확장하는 두 가지 핵심 메커니즘이 Skill과 Subagent(서브에이전트, 줄여서 Agent) 입니다.
| 구분 | Skill | Subagent |
|---|---|---|
| 정체 | 재사용 가능한 지시문 꾸러미 | 독립된 컨텍스트를 가진 워커 |
| 저장 위치 | ~/.claude/skills/ 또는 .claude/skills/ | ~/.claude/agents/ 또는 .claude/agents/ |
| 컨텍스트 | 현재 대화에 로드 | 별도 컨텍스트 창, 요약만 반환 |
| 도구 | 부모 세션 도구 상속 | tools 필드로 제한 가능 |
| 모델 | 부모 모델 사용 | model 필드로 지정 (sonnet/opus/haiku/inherit) |
| 쓰는 경우 | ”이렇게 하세요”라는 전문 지식 | ”이 작업을 독립적으로 수행하세요”라는 병렬 워커 |
비유하면 Skill은 책상 서랍의 매뉴얼이고, Subagent는 옆 자리에 앉은 동료입니다. 매뉴얼은 내가 꺼내 읽고 그대로 실행하지만, 동료에게는 과제를 통째로 맡기고 결과 보고만 받습니다.
Skill의 동작 구조
Skill은 SKILL.md 파일로 정의됩니다. Claude는 세션 시작 시 모든 Skill의 frontmatter(이름 + 설명) 만 미리 읽어 둡니다. 이는 Skill 하나당 약 100토큰 정도만 소비합니다. 실제 본문은 해당 Skill이 호출될 때만 로드됩니다 (평균 5k 토큰 이하).
호출 방식은 두 가지입니다.
- 자동 호출: Claude가 사용자 요청과 Skill의
description을 매칭하여 필요하면 스스로 로드 - 수동 호출: 사용자가
/skill-name형태의 슬래시 커맨드로 직접 지정
# 수동 호출 예시 (이름이 test-runner인 Skill)
/test-runner
# 인자 전달 (shell 스타일: $0, $1, ...)
/commit-helper "fix: 로그인 버그 수정"Skill은 부모 대화 안에서 실행되므로 현재 대화 도구를 그대로 사용합니다. 즉, Read/Write/Bash 같은 도구 권한이 그대로 이어집니다.
Skill의 우선순위
여러 곳에 같은 이름의 Skill이 있으면 다음 순서로 결정됩니다.
| 순서 | 위치 | 설명 |
|---|---|---|
| 1 | Enterprise | 조직 차원 배포 (설정 가능) |
| 2 | Personal | ~/.claude/skills/ 사용자 전역 |
| 3 | Project | .claude/skills/ 프로젝트 로컬 |
Subagent의 동작 구조
Subagent는 별도의 AI 세션을 띄워 작업을 맡기는 메커니즘입니다. 핵심 특징은 세 가지입니다.
- 독립 컨텍스트: 부모 대화의 길이에 영향을 주지 않음. 탐색/리서치를 분리하여 메인 컨텍스트를 보호
- 도구 제한:
tools필드에 나열한 도구만 사용 가능 — 예: 읽기 전용 에이전트는Read, Grep, Glob만 허용 - 모델 선택: 작업 난이도에 맞춰 Haiku(빠르고 저렴), Sonnet(균형), Opus(복잡한 추론) 지정 가능
Subagent는 Claude Code의 Task 도구 또는 Agent 도구를 통해 실행됩니다.
사용자: "이 PR의 보안 이슈를 찾아줘"
↓
메인 Claude: security-reviewer 에이전트 호출
↓
Subagent (별도 컨텍스트, Opus 모델, Read+Grep+Bash만)
→ 파일 30개 읽고 스캔
→ 결과 요약만 반환
↓
메인 Claude: 요약을 받아 사용자에게 보고Subagent를 쓰는 이유
| 이유 | 설명 |
|---|---|
| 컨텍스트 보호 | 파일 30개를 읽은 내용이 메인 대화에 남지 않음 |
| 병렬 처리 | 독립된 여러 에이전트를 동시에 실행 가능 |
| 비용 최적화 | 단순 조회는 Haiku로, 복잡한 분석은 Opus로 |
| 권한 분리 | 검토 에이전트는 쓰기 권한 없이 읽기만 |
제약: Subagent는 자식 Subagent를 직접 스폰할 수 없습니다. 중첩이 필요하면 메인 세션에서 체이닝하거나 headless 모드(claude -p)를 활용해야 합니다.
언제 Skill vs Subagent를 쓸까
결정 흐름은 단순합니다.
질문 1: "반복되는 작업 방법(how-to)을 정의하고 싶은가?"
예 → Skill
아니오 → 질문 2
질문 2: "독립된 워커에게 과제를 맡기고 요약만 받고 싶은가?"
예 → Subagent
아니오 → 슬래시 커맨드 또는 일반 프롬프트구체적 예시를 보겠습니다.
| 시나리오 | 선택 | 이유 |
|---|---|---|
| ”커밋 메시지 작성 규칙을 적용하고 싶다” | Skill | 규칙은 지시문, 현재 대화에서 바로 실행 |
| ”방금 쓴 코드 전체를 보안 관점에서 리뷰” | Subagent | 코드 전체를 읽어야 하므로 컨텍스트 분리 |
| ”Python PEP 8 스타일 가이드를 자동 적용” | Skill | 스타일 규칙 = 지시문 |
| ”세 가지 다른 구현 방식을 병렬로 프로토타입” | Subagent | 독립 작업, 병렬화 이득 |
| ”Docker 빌드 에러를 단계적으로 수정” | Skill + Subagent | Skill이 절차를, 에이전트가 실제 수정 |
상호 작용: Skill과 Agent를 함께
두 메커니즘은 배타적이지 않습니다. 실무에서는 Skill 안에서 “이 단계에서 code-reviewer 에이전트를 호출하세요”처럼 Skill이 에이전트 사용을 유도하는 패턴이 자주 쓰입니다. Skill 자체가 Agent 도구를 직접 실행하는 것이 아니라, 부모 대화에게 호출을 지시하는 방식입니다.
반대로 Subagent는 기본적으로 부모의 Skill을 자동 상속하지 않습니다. 필요하면 에이전트 frontmatter에 명시해야 합니다 (구현은 다음 글에서 다룹니다).
마무리
핵심을 한 줄로 요약하면 이렇습니다.
- Skill = 지시문 카탈로그: 자주 쓰는 방법을 이름으로 저장, 필요할 때 자동/수동 로드
- Subagent = 독립 워커: 별도 컨텍스트·도구·모델로 과제를 맡기고 요약만 받음
2025년 10월 Anthropic이 Skill을 공식 출시한 이후, Claude Code의 확장 생태계는 “어떤 지식을 Skill로 모듈화하고, 어떤 작업을 에이전트에게 위임할 것인가”를 설계하는 방향으로 옮겨 가고 있습니다. 다음 글에서는 실제로 Skill과 Subagent를 직접 작성하는 방법을 다룹니다.