Skills 코스의 마지막 편입니다. 앞 편 SKILL.md 작성법까지 따라왔다면 Skill을 만들 줄 압니다. 이제 자주 헷갈리는 질문에 답합니다. "이 일은 Skill로 해야 하나, 서브에이전트에게 맡겨야 하나?" 두 기능의 동작 차이, 장면별 선택 기준, 서브에이전트에 Skill을 미리 실어 보내는 skills 필드, 그리고 실전 예 두 가지를 다룹니다.
원구연 과정 6주차는 "에이전트(오케스트레이터)"를 개념까지만 소개하고 끝냅니다. 여러 작업과 도구를 연결하는 지휘자라는 그림입니다. 이 글은 그 다음 단계, 실제 구성 방법입니다.
핵심 요약
- Skill은 지식을 "지금 이 대화에" 넣습니다. 서브에이전트는 작업을 "다른 대화에서" 처리하고 요약만 돌려줍니다.
- 결과를 이어서 써야 하면 Skill, 출력이 많아 본 대화를 어지럽히면 서브에이전트입니다.
- 서브에이전트는 새 컨텍스트로 시작하므로 본 대화에서 호출한 Skill을 모릅니다.
skills필드로 미리 실어 보냅니다. - 반대 방향도 있습니다. Skill에
context: fork를 붙이면 그 본문이 서브에이전트의 작업이 됩니다. - 서브에이전트는 본 대화의 컨텍스트를 아끼는 것이지 전체 토큰을 줄이는 것이 아닙니다.
두 기능은 무엇이 다른가
요리로 비유하면
Skill은 주방 벽에 붙은 레시피입니다. 요리사(Claude)가 그 자리에서 읽고 손수 조리합니다. 재료 상태, 손님 요청 같은 지금 대화의 맥락을 전부 알고 있습니다.
서브에이전트는 옆 주방의 다른 요리사입니다. 주문서 한 장을 받아 자기 주방에서 만들고 완성된 접시만 넘깁니다. 우리 주방에서 무슨 대화가 오갔는지 모릅니다. 대신 그쪽 주방이 아무리 어질러져도 우리 주방은 깨끗합니다. 그 요리사에게 우리 레시피를 따르게 하려면 주문서에 레시피를 함께 붙여 보내야 합니다. 그것이 skills 필드입니다.
기술적으로는 어떻게 동작하나
Skill이 호출되면 SKILL.md 본문이 현재 대화에 메시지 하나로 들어가고 세션이 끝날 때까지 남습니다. Claude는 그 내용을 대화 맥락과 함께 씁니다. 실행 주체는 본 대화의 Claude입니다.
서브에이전트는 ~/.claude/agents/ 또는 .claude/agents/의 마크다운 파일로 정의합니다. frontmatter에 name과 description이 필수이고, 본문이 그 에이전트의 시스템 프롬프트입니다. 호출되면 새 컨텍스트 윈도우가 열리고, 거기에는 에이전트 자신의 프롬프트, Claude가 쓴 위임 메시지, CLAUDE.md 계층, git 상태 스냅샷, 그리고 skills 필드에 적힌 Skill 전문이 들어갑니다. 본 대화 기록, 이미 읽은 파일, 이미 호출한 Skill은 보이지 않습니다. 작업이 끝나면 요약만 본 대화로 돌아옵니다. 내장 Explore·Plan 에이전트는 가볍게 가려고 CLAUDE.md와 git 상태도 건너뜁니다.
| 항목 | Skill | 서브에이전트 |
|---|---|---|
| 정의 파일 | skills/<이름>/SKILL.md |
agents/<이름>.md |
| 실행 위치 | 현재 대화 안 | 별도 컨텍스트 윈도우 |
| 대화 맥락 | 전부 봄 | 위임 메시지만 봄 |
| 결과 | 본문이 대화에 남음 | 요약만 돌아옴 |
| 모델 | 세션 모델(model 필드로 임시 변경) |
model 필드로 지정, 기본 상속 |
| 도구 제한 | allowed-tools, disallowed-tools |
tools, disallowedTools |
| 병렬 실행 | 불가 | 가능, 기본 백그라운드 |
어느 쪽을 써야 하나: 판단 차트
질문 세 개를 순서대로 던집니다.
- 결과를 이 대화에서 이어서 써야 하는가? 그렇다면 Skill입니다. 회의록 형식, 리뷰 기준, 배포 절차처럼 지금 하는 일에 규칙을 얹는 경우입니다.
- 중간 출력이 많은가? 테스트 로그 수천 줄, 문서 수십 개 조회, 로그 파일 분석처럼 결과만 필요하고 과정은 버려도 되면 서브에이전트입니다.
- 같은 종류의 일꾼을 반복해서 띄우는가? 매번 같은 프롬프트로 같은 역할을 시킨다면 사용자 정의 서브에이전트로 굳힙니다.
자주 있는 장면별 선택
| 장면 | 선택 | 이유 |
|---|---|---|
| 고객 문의 답변 초안에 우리 말투 적용 | Skill | 대화 맥락(문의 내용)이 필요 |
| 결제 코드 diff를 규칙 4개로 검토 | 서브에이전트 + Skill | 검토 기준은 Skill, 긴 diff 읽기는 격리 |
| 저장소 전체에서 특정 패턴 찾기 | 서브에이전트(Explore) | 출력이 많고 결과만 필요 |
| 배포 절차 실행 | Skill(disable-model-invocation) |
사람이 타이밍을 정해야 함 |
| 문서 30개 갱신을 병렬로 | 서브에이전트 여러 개 | 병렬, 본 대화 보호 |
| 모델 나눠 쓰기(정리는 가볍게, 구현은 강하게) | 서브에이전트 model 필드 |
6주차 4단계 흐름을 자동화 |
서브에이전트에 Skills를 얹으려면
skills 필드 쓰는 법
서브에이전트 파일의 frontmatter에 skills 목록을 적으면 시작 시 그 Skill들의 본문 전체가 에이전트 컨텍스트에 주입됩니다. 본 대화에서는 설명만 올라가고 본문은 호출 때 읽히는 것과 달리, 여기서는 처음부터 전문이 들어간다는 점이 다릅니다.
---
name: payment-reviewer
description: 결제·주문 코드 변경을 검토합니다. 결제 관련 diff 리뷰 요청 시 위임.
tools: Read, Grep, Glob, Bash
skills:
- payment-review
---
결제 코드 검토자입니다. 미리 로드된 payment-review 규칙을 번호별로 판정하고
"통과" 또는 "수정 필요(항목 번호)"로만 결론을 냅니다.
두 가지 규칙이 있습니다. 첫째, skills는 무엇을 미리 실을지만 정하며 접근을 막지 않습니다. 목록에 없는 Skill도 에이전트가 실행 중 Skill 도구로 호출할 수 있습니다. 완전히 막으려면 tools에서 Skill을 빼거나 disallowedTools에 넣습니다. 둘째, disable-model-invocation: true인 Skill은 미리 실을 수 없습니다. 미리 로드는 Claude가 스스로 호출할 수 있는 Skill 집합에서만 가져오기 때문입니다.
여러 서브에이전트에 다른 Skills 배정하기
역할이 다른 에이전트에는 다른 Skill을 줍니다. 리뷰어에게는 검토 기준을, 문서 작성자에게는 문체 규칙을, 배포 담당에게는 배포 절차를 싣습니다. 같은 Skill 파일을 여러 에이전트가 공유하므로 규칙을 한 곳에서 고치면 전부에 반영됩니다.
.claude/
├── skills/
│ ├── payment-review/SKILL.md
│ ├── house-style/SKILL.md
│ └── deploy-checklist/SKILL.md
└── agents/
├── payment-reviewer.md # skills: [payment-review]
├── doc-writer.md # skills: [house-style]
└── release-checker.md # skills: [deploy-checklist]
반대 방향도 기억해 두세요. Skill 쪽에 context: fork와 agent: Explore처럼 적으면 그 Skill 본문이 지정한 에이전트의 작업 프롬프트가 되어 격리 실행됩니다. 지식만 있고 할 일이 없는 Skill에는 의미가 없고, 명시적 작업이 적힌 Skill에만 씁니다.
실전 예 1: 코드 리뷰 자동화
BizPlan CRM에서 결제 코드는 두 번째 눈으로 검토한 뒤에만 병합합니다. 구성은 위 payment-reviewer 에이전트 그대로입니다. 흐름은 이렇습니다.
- 본 대화에서 기능 구현을 마칩니다.
- "결제 코드 diff를 payment-reviewer로 검토해 줘"라고 합니다.
- 에이전트가 새 컨텍스트에서 diff 전체를 읽습니다. 수백 줄의 diff와 grep 결과가 본 대화에 남지 않습니다.
- "수정 필요(1, 3)"처럼 번호만 돌아옵니다. 본 대화에서 해당 항목을 고치고 다시 보냅니다.
에이전트에 tools: Read, Grep, Glob, Bash만 주고 Write·Edit을 뺀 점이 핵심입니다. 검토자는 고치지 않습니다. 고치는 쪽과 판정하는 쪽을 분리하는 것이 우리 채점 루프의 원칙이기도 합니다.
실전 예 2: 문서 업데이트 워크플로
교육 사이트의 학습 문서 30편을 한 번에 갱신해야 할 때입니다. 본 대화 하나로 30편을 열면 컨텍스트가 금방 찹니다.
house-styleSkill에 문체 규칙(존댓말, 작대기 금지, 수치는 실측+조건 병기)을 둡니다.doc-writer에이전트에skills: [house-style]을 싣고tools에 Read·Write·Edit을 줍니다.- 본 대화에서 30편을 5묶음으로 나눠 에이전트 5개를 병렬로 띄웁니다. 각 에이전트는 자기 묶음만 읽고 씁니다.
- 각 에이전트는 "파일 6개 갱신, 글자 수, 확인한 출처"만 보고합니다.
- 본 대화에서 보고를 모아 빌드와 링크 검사를 돌립니다.
주의할 점은 에이전트가 본 대화의 앞선 결정을 모른다는 것입니다. "이번 주 확정된 특강 날짜는 11월 26일"처럼 대화 중 정해진 사실은 위임 메시지에 다시 적어야 합니다. 6주차 교재의 "모든 판단을 에이전트에게 맡기지 않는다"는 여기서도 유효합니다. 최종 검사는 본 대화에서 합니다.
정리
- Skill은 지금 대화에 지식을 얹고, 서브에이전트는 다른 대화에서 일을 끝내고 요약만 줍니다.
- 결과를 이어 써야 하면 Skill, 출력이 많으면 서브에이전트, 둘 다면 서브에이전트에
skills를 싣습니다. - 서브에이전트는 본 대화 기록과 이미 호출한 Skill을 모릅니다. 필요한 사실은 위임 메시지에 다시 적습니다.
- 검토자에게는 쓰기 도구를 빼서 "만드는 쪽과 판정하는 쪽"을 분리합니다.
- 병렬과 격리는 서브에이전트의 강점이지만 최종 검증은 본 대화에서 합니다.
자주 묻는 질문
Skills와 서브에이전트는 무엇이 다른가요?
Skill은 현재 대화에 절차·지식을 넣는 파일이고, 서브에이전트는 별도 컨텍스트에서 작업을 수행하는 실행 단위입니다. Skill은 대화 맥락을 전부 보고 서브에이전트는 위임 메시지만 봅니다. 하나는 "무엇을 알고 할지", 다른 하나는 "누가 어디서 할지"를 정합니다.
서브에이전트를 쓰면 토큰이 절약되나요?
본 대화의 컨텍스트는 절약됩니다. 긴 출력이 에이전트 쪽에 남고 요약만 돌아오기 때문입니다. 하지만 에이전트도 자기 컨텍스트에서 토큰을 쓰므로 전체 사용량은 오히려 늘 수 있습니다. 비용을 줄이려면 model: haiku처럼 가벼운 모델을 배정하는 편이 확실합니다.
서브에이전트는 메인 대화의 Skills를 자동으로 쓰나요?
본 대화에서 이미 호출한 Skill의 내용은 넘어가지 않습니다. 새 컨텍스트로 시작하기 때문입니다. 대신 에이전트 파일의 skills 필드에 적은 Skill은 시작 시 전문이 주입되고, 그 외 Skill도 에이전트가 실행 중 필요하면 Skill 도구로 직접 호출할 수 있습니다. 내장 Explore·Plan 에이전트는 Skill을 미리 싣지 않습니다.
서브에이전트에 파일 수정 작업을 맡겨도 되나요?
됩니다. tools에 Write·Edit을 주면 됩니다. 다만 검토와 수정을 같은 에이전트에 맡기지 말고, 수정 범위를 위임 메시지에 명확히 적고, 결과는 본 대화에서 빌드나 테스트로 확인하세요. 저장소를 격리하고 싶으면 isolation: worktree로 임시 작업 트리에서 돌릴 수 있습니다.