클로드 코드(Claude Code) 스킬과 서브에이전트, 뭐가 다르고 언제 어느 쪽을 쓸까요? 둘 다 일을 나누는 기능이라 헷갈리기 쉽지만, 하나는 “방법을 적어 두는 문서”이고 다른 하나는 “일을 따로 맡는 작업자”입니다. 이 글은 Claude Code 공식 문서(2026-10-09 열람)를 기준으로 두 기능이 무엇인지, 파일은 어디에 두는지, 어떤 일에 어느 쪽을 쓰는지를 표와 예시로 정리합니다.
먼저 한눈에 비교
| 비교 항목 | 스킬 | 서브에이전트 |
|---|---|---|
| 정체 | SKILL.md 파일 하나로 만든 지시·절차 | 자기 문맥·시스템 프롬프트·도구 권한을 가진 별도 작업자 |
| 파일 위치(개인용) | 홈 폴더 안 .claude/skills/<이름>/SKILL.md | 홈 폴더 안 .claude/agents/ 아래 마크다운 파일 |
| 파일 위치(프로젝트용) | .claude/skills/<이름>/SKILL.md | .claude/agents/ 아래 마크다운 파일 |
| 필수 항목 | 없음(description만 권장) | name, description 두 가지 |
| 실행되는 자리 | 기본은 지금 대화 안 | 자기 문맥 창 안, 끝나면 요약만 돌려줌 |
| 호출 방법 | Claude가 자동 선택하거나 /스킬이름으로 직접 호출 | Claude가 설명을 보고 위임하거나, 이름을 말하거나, @로 지정 |
| 비용이 드는 때 | 본문은 쓸 때만 문맥에 들어옴 | 자체 요청을 따로 보내서 같은 사용량 한도에 포함됨 |
스킬: 반복 절차를 문서로 고정한다
스킬은 SKILL.md 파일 하나입니다. 안에 지시나 절차를 적어 두면 Claude가 관련 상황에서 불러 쓰고, 직접 쓰고 싶으면 /스킬이름으로 부를 수 있습니다. 공식 문서는 같은 지시·체크리스트·여러 단계 절차를 채팅에 계속 붙여 넣고 있거나, CLAUDE.md의 한 부분이 사실이 아니라 절차로 자랐을 때 스킬을 만들라고 안내합니다. 스킬 본문은 쓸 때만 문맥에 들어오기 때문에, 긴 참고 자료를 넣어도 필요하기 전까지는 비용이 거의 없습니다.
스킬 파일은 어디에 두나
여기서 홈 폴더는 내 계정의 기본 폴더를 뜻하며, 터미널에서는 물결표 한 글자로 줄여 적는 곳입니다.
| 저장 위치 | 경로 | 쓰이는 범위 |
|---|---|---|
| 개인 | 홈 폴더 안 .claude/skills/<이름>/SKILL.md | 이 컴퓨터의 모든 프로젝트 |
| 프로젝트 | .claude/skills/<이름>/SKILL.md | 그 저장소에서 연 세션(저장소에 올리면 팀이 함께 씀) |
| 플러그인 | <플러그인>/skills/<이름>/SKILL.md | 플러그인이 켜진 곳 |
Anthropic이 GitHub에 공개한 예시 저장소(anthropics/skills)의 안내도 같은 구조를 보여 줍니다. 이 저장소는 스킬을 “Claude가 필요할 때 불러오는 지시·스크립트·자료의 폴더”로 소개하고, 각 스킬은 자기 폴더 안에 SKILL.md를 두며 맨 위 머리말에 name과 description을 적는 서식을 예시로 제시합니다. 또 Claude Code 공식 문서에 따르면 스킬은 Agent Skills라는 공개 표준을 따르면서 호출 제어·서브에이전트 실행 같은 Claude Code 전용 기능이 더해진 형태입니다.
예전 방식인 .claude/commands/ 안의 파일도 계속 동작합니다. 공식 문서는 사용자 지정 명령이 스킬로 합쳐졌고, 새로 만들 때는 보조 파일을 둘 수 있는 스킬을 권한다고 설명합니다.
머리말에서 자주 쓰는 항목
description: 스킬이 하는 일과 쓸 때를 적습니다. Claude가 이 글을 보고 자동으로 쓸지 정하므로 가장 중요한 항목입니다.disable-model-invocation: true: Claude가 알아서 부르지 못하게 하고 내가/이름으로 부를 때만 실행합니다. 배포·커밋처럼 타이밍을 내가 정할 일에 씁니다.allowed-tools: 스킬이 실행되는 턴에 허락 없이 쓸 도구를 미리 승인합니다. 다음 메시지를 보내면 승인은 풀립니다.context: fork: 스킬을 별도 서브에이전트에서 실행합니다. 스킬과 서브에이전트가 만나는 자리입니다.
서브에이전트: 일을 떼어 따로 맡긴다
서브에이전트는 자기만의 문맥 창과 시스템 프롬프트, 도구 권한을 가진 작업자입니다. 검색 결과·로그·파일 내용처럼 다시 안 볼 자료가 본 대화를 채울 일을 맡기면, 서브에이전트가 자기 문맥에서 처리하고 요약만 돌려줍니다. 마크다운 파일 하나에 머리말과 시스템 프롬프트를 적어 만들고, 머리말에서 name과 description은 필수입니다.
| 머리말 항목 | 필수 | 하는 일 |
|---|---|---|
name | 예 | 고유 이름. 파일 이름과 같을 필요는 없음 |
description | 예 | Claude가 언제 이 서브에이전트에게 위임할지 판단하는 설명 |
tools | 아니오 | 쓸 수 있는 도구. 빼면 서브에이전트가 쓸 수 있는 도구를 모두 물려받음 |
model | 아니오 | sonnet, opus, haiku, fable, 모델 ID, inherit 중 선택 |
skills | 아니오 | 시작할 때 문맥에 넣어 둘 스킬 |
maxTurns | 아니오 | 이 횟수를 넘기면 멈추고 결과를 “일부”로 표시 |
알아 둘 제약 네 가지
- 일반 서브에이전트는 지금까지의 대화를 보지 못합니다. 공식 문서의 기본 설명은 “새 문맥으로 시작한다”입니다. 다만 대화를 이어받는 포크 방식도 있어, 같은 문맥이 필요한 일은 포크가 신선한 서브에이전트보다 비용이 덜 든다고 안내합니다. 포크는 대화형 세션에서 기본으로 켜져 있고(v2.1.232 이상), 포크는 다시 포크를 만들지 못합니다.
- 같은 사용량 한도를 씁니다. 서브에이전트는 자체 요청을 보내며, 이 요청도 본 대화와 같은 한도에 들어갑니다.
- 짧고 잦은 일에는 느립니다. 포크가 아닌 서브에이전트는 처음부터 문맥을 모아야 해서, 공식 문서도 빠른 수정이나 지연이 중요한 일은 본 대화에서 하라고 합니다.
- 설명이 많으면 부담이 됩니다. 기본 제공을 뺀 서브에이전트 설명의 합이 15,000 토큰을 넘으면 시작할 때 경고가 나옵니다. 설명은 짧게, 자세한 내용은 시스템 프롬프트에 둡니다.
어느 쪽을 쓸까: 상황별 판단표
| 내 상황 | 고를 것 | 이유 |
|---|---|---|
| 같은 체크리스트를 매번 채팅에 붙여 넣는다 | 스킬 | 절차를 한 번 적어 두면 필요할 때만 문맥에 들어옴 |
CLAUDE.md가 절차로 길어졌다 | 스킬 | 항상 읽히는 파일에서 쓸 때만 읽히는 파일로 옮김 |
| 검색 결과·로그가 길어 본 대화가 지저분해진다 | 서브에이전트 | 과정은 자기 문맥에 두고 요약만 받음 |
| 어떤 도구든 못 쓰게 막고 읽기만 시키고 싶다 | 서브에이전트 | tools로 권한을 좁힘 |
| 가벼운 작업은 싼 모델에 맡기고 싶다 | 서브에이전트 | model: haiku처럼 따로 지정 |
| 계획·구현·시험이 같은 문맥을 공유한다 | 본 대화 | 단계마다 문맥을 다시 모으는 비용이 생김 |
| 주고받으며 계속 다듬어야 한다 | 본 대화 | 왕복이 잦은 일은 위임에 안 맞음 |
한 줄로 줄이면, 스킬은 방법을 고정하고 서브에이전트는 일을 떼어냅니다. 먼저 절차로 적어 보고, 적히지 않는 판단 작업이거나 출력이 길어 본 대화를 채우는 일일 때 떼어내면 됩니다.
둘이 만나는 두 가지 방향
| 방식 | 작업 지시는 어디에 쓰나 | 시스템 프롬프트 |
|---|---|---|
스킬에 context: fork 지정 | 스킬 본문이 곧 작업 | agent 항목으로 고른 에이전트 종류의 것 |
서브에이전트에 skills 항목 지정 | Claude가 넘겨 준 위임 메시지 | 서브에이전트 파일의 본문 |
첫째는 “이 절차를 깨끗한 문맥에서 돌려라”이고, 둘째는 “이 작업자에게 이 지식을 미리 읽혀라”입니다. context: fork를 쓸 때는 서브에이전트가 대화 기록을 보지 못하므로, 스킬 본문만 읽어도 일이 되게 적어야 합니다. “이 API 규칙을 따라라”처럼 지침만 있고 할 일이 없으면 서브에이전트가 의미 있는 결과 없이 돌아올 수 있다고 공식 문서가 경고합니다.
직접 써 보는 예시 두 개 (설명용 가상 예시)
아래는 공식 문서의 형식에 맞춰 이 글에서 만든 가상 예시입니다. 이름과 내용은 상황을 보여 주려는 것이니 그대로 쓰기보다 내 작업에 맞게 바꿔 쓰세요.
예시 1. 절차가 정해져 있어서 스킬로 둔 경우
---
name: weekly-notes
description: 이번 주 작업 메모를 정해진 양식으로 정리할 때 사용
disable-model-invocation: true
---
1. 이번 주 메모 파일을 읽는다.
2. 완료 / 진행 중 / 막힌 일 세 칸으로 나눈다.
3. 막힌 일에는 이유를 한 줄씩 붙인다.매주 같은 순서로 하는 일이라 스킬이 맞습니다. 정리 타이밍은 내가 정하려고 disable-model-invocation: true를 넣었습니다.
예시 2. 결과만 필요해서 서브에이전트로 뗀 경우
---
name: log-reader
description: 긴 오류 로그를 읽고 원인 후보만 요약할 때 사용
tools: Read, Grep
model: haiku
---
로그를 읽고 오류 종류별로 개수와 대표 줄 하나씩만 요약한다.
파일은 수정하지 않는다.로그는 수천 줄이어도 본 대화에는 요약만 남습니다. tools를 읽기 도구로 좁혀 파일을 고치지 못하게 했고, 가벼운 모델을 지정해 비용을 낮췄습니다.
막히는 지점과 풀이
| 증상 | 먼저 볼 곳 |
|---|---|
| 스킬을 만들었는데 Claude가 안 부른다 | description에 쓸 상황이 적혔는지, 머리말이 파일 첫 줄의 ---로 시작하는지 확인 |
| 스킬이 너무 자주 불린다 | description을 좁히거나 disable-model-invocation: true로 직접 호출 전용으로 바꿈 |
| 스킬이 많아 설명이 잘린다 | 스킬 목록은 컨텍스트 창의 1%를 예산으로 쓰며, 넘치면 덜 쓴 스킬의 설명부터 줄어듦 |
| 서브에이전트가 기대와 다른 일을 한다 | 위임 메시지에 필요한 정보가 있었는지 확인. 대화를 모르는 채 시작하기 때문 |
| 새 서브에이전트 파일이 안 보인다 | 세션 시작 때 없던 agents 폴더를 새로 만들었다면 재시작이 필요 |
이런 경우엔 피하세요
처음부터 서브에이전트를 여러 개 만들어 두는 방식은 관리가 어렵습니다. 반대로 스킬을 너무 잘게 쪼개면 언제 무엇이 불리는지 추적하기 힘들고, 설명 목록만 길어집니다. 서브에이전트 하나가 정말 필요한 일인지는 “결과만 필요한가, 왕복이 필요한가”로 가립니다.
업데이트
이 글은 아래 공식 문서(2026년 10월 9일 기준)와 GitHub 예시 저장소 안내(2026년 10월 18일 기준)를 바탕으로 고쳤습니다. 포크 방식, /doctor 점검, 일부 기능은 Claude Code 버전에 따라 다르고 자주 바뀌므로, 설정을 바꾸기 직전에 문서에서 현재 값을 확인하세요.
확인 자료
- Claude Code 문서: Extend Claude with skills
- Claude Code 문서: Create custom subagents
- GitHub: anthropics/skills 저장소 안내
확인 날짜: 2026-10-09 (GitHub 저장소 안내는 2026-10-18)
설정 파일이 길어졌다면 아래 글의 권한·갱신 점검도 이어서 보면 좋습니다.