카테고리 없음

claude code skills vs agents · 클로드 코드 스킬 vs 서브에이전트: 지금 대화에서 다시 쓸 절차는 스킬, 결과만 받을 일은 서브에이전트

코드짜는아빠 2026. 10. 19. 10:49

「다시 쓸 프롬프트나 작업 흐름을 서브에이전트의 독립 컨텍스트가 아니라 메인 대화 컨텍스트에서 돌리고 싶다면, 대신 스킬을 고려하라.」 Claude Code 서브에이전트 문서의 한 줄을 옮기면 이렇다. 두 기능을 가르는 건 결국 일이 어느 컨텍스트에서 도느냐. 스킬(SKILL.md)은 Claude가 지금 대화 안에서 꺼내 쓰는 지시이고, 서브에이전트(.claude/agents/)는 자기 컨텍스트 창에서 일한 뒤 결과만 돌려주는 전문 조수다. 그래서 대화를 이어 가며 같이 쓸 절차는 스킬에, 출력이 길거나 도구를 묶어야 하거나 혼자 끝낼 수 있는 일은 서브에이전트에 둔다. 기준은 2026년 10월 19일에 읽은 Claude Code 공식 문서(Skills · Subagents).

claude code skills vs agents 한눈에 (2026-10-19 공식 문서 기준)

검색어의 agents 는 .claude/agents/ 에 두는 서브에이전트로 보고 썼다. 두 문서에 흩어진 내용을 표 하나로 모으면 이렇다.

  스킬 서브에이전트
무엇인가 SKILL.md 에 적은 지시. Claude가 도구 상자에 넣어 두고 필요할 때 쓰거나, 사람이 /스킬이름 으로 직접 부른다 정해진 종류의 일을 맡는 전문 조수. 자기 시스템 프롬프트 · 도구 · 권한을 따로 가진다
파일 위치 프로젝트 .claude/skills/<이름>/SKILL.md, 개인 ~/.claude/skills/<이름>/SKILL.md. 이름이 같으면 회사 관리 > 개인 > 프로젝트 프로젝트 .claude/agents/, 개인 ~/.claude/agents/. 이름이 같으면 회사 관리 > 실행 옵션 --agents > 프로젝트 > 개인 > 플러그인
파일 모양 스킬 폴더 하나에 SKILL.md. 위쪽 frontmatter 에 description 같은 필드, 아래 본문이 지시 Markdown 파일 하나. YAML frontmatter(필수는 name · description) 아래 본문이 그 서브에이전트의 시스템 프롬프트
컨텍스트 지금 대화 안. context: fork 를 주면 서브에이전트에서 돈다 새로 시작하는 독립 컨텍스트. 대화 기록 · 이미 쓴 스킬 · 이미 읽은 파일을 보지 못하고, Claude Code 시스템 프롬프트 대신 자기 본문과 작업 폴더 같은 환경 정보를 받는다. 예외는 포크 — 지금 대화를 통째로 물려받는 서브에이전트다
불러오는 방식 평소엔 description 만 컨텍스트에 있고, 쓸 때 본문 전체가 실린다 Claude가 요청 · description · 지금 상황을 보고 맡긴다. 이름을 말하거나 @ 로 골라 직접 맡길 수도 있다
맞는 일 메인 대화 안에서 다시 쓸 프롬프트 · 작업 흐름 메인 대화엔 필요 없는 긴 출력이 나오는 일, 도구 · 권한을 묶어야 하는 일, 혼자 끝내고 요약을 돌려줄 수 있는 일

출처는 Claude Code 스킬 문서, 서브에이전트 문서, 둘 다 2026-10-19 조회.

이름이 겹칠 때의 우선순위는 방향이 반대라 봐 둘 만하다. 스킬은 개인 것이 프로젝트 것을 이기고, 서브에이전트는 거꾸로 프로젝트 것이 먼저.

서브에이전트 안에도 CLAUDE.md 는 실린다. 메인 대화가 읽는 단계 그대로, 내장 Explore · Plan 서브에이전트만 빼고. 빼고 싶다면 frontmatter 에 omitClaudeMd: true(v2.1.271 이상)를 둔다. 그래도 회사 관리 정책 파일과, 서브에이전트가 손대는 하위 폴더의 CLAUDE.md 는 실린다.

언제 무엇을 쓰나: 대화가 필요하면 스킬, 결과만 필요하면 서브에이전트

그럼 어느 쪽에 맡길지는 어떻게 고를까? 서브에이전트 문서가 든 기준은 이렇다.

  • 메인 대화가 맞을 때 — 주고받으며 여러 번 다듬어야 할 때, 계획 · 구현 · 테스트처럼 여러 단계가 맥락을 많이 나눌 때, 한 곳만 빠르게 고칠 때, 기다리는 시간이 중요할 때(포크가 아닌 서브에이전트는 처음부터 시작해 맥락을 모으는 데 시간이 걸릴 수 있다).
  • 서브에이전트가 맞을 때 — 메인 대화에선 다시 안 볼 긴 출력이 나올 때, 도구 제한이나 권한을 따로 걸고 싶을 때, 혼자 끝내고 요약을 돌려줄 수 있을 때.

메인 대화 쪽 일에서 같은 지시를 매번 다시 쓰고 있다면, 그걸 담아 두는 곳이 스킬이다.

문서 기준을 질문 셋으로 줄이면 이 순서.

  1. 이 일에 지금 대화 내용이 필요한가. 필요하면 스킬이나 메인 대화. 서브에이전트는 대화 기록을 보지 못하고, Claude가 일을 요약해 적은 위임 메시지에서 출발한다. 대화를 그대로 넘겨야 하는 곁가지 일이라면 문서는 포크를 따로 안내한다.
  2. 결과가 길고 다시 안 볼 내용인가. 검색 결과 · 로그 · 파일 내용이 메인 대화를 덮을 것 같으면 서브에이전트. 그 일은 서브에이전트 컨텍스트에서 끝나고 요약만 돌아온다.
  3. 도구나 권한을 묶어야 하나. 그렇다면 서브에이전트의 tools · disallowedTools 로. 같은 일을 매번 같은 지시로 하게 하는 게 목적이라면 스킬로 충분하다.

섞어 쓰는 두 방법: 스킬을 서브에이전트로 돌리거나, 서브에이전트에 스킬을 싣거나

두 기능은 서로를 불러 쓸 수도 있다.

  1. 스킬에 context: fork 를 준다. Claude Code가 agent 필드에 적은 종류의 서브에이전트를 새로 띄우고, 스킬 본문을 그 프롬프트로 넘긴다. agent 에는 내장 Explore · Plan · general-purpose 나 직접 만든 .claude/agents/ 서브에이전트를 적을 수 있고, 비우면 general-purpose. 대화 기록은 넘어가지 않으니 스킬 지시가 혼자서도 읽혀야 한다. 이름과 달리 지금 대화를 통째로 넘기는 포크가 아니라고 문서에 따로 적혀 있다.
  2. 서브에이전트에 skills 를 적는다. 적은 스킬의 본문 전체가 시작할 때 서브에이전트 컨텍스트에 들어간다(목록 앞 32개 이름까지). 미리 싣는 목록일 뿐이라, 적지 않은 프로젝트 · 개인 · 플러그인 스킬도 서브에이전트가 Skill 도구로 찾아 쓸 수 있다. 스킬 쪽에 disable-model-invocation: true 가 있으면 서브에이전트에 미리 실리지 않는다.

문서는 둘을 서로 반대 방향이라고 설명한다. 앞은 스킬 본문이 고른 서브에이전트 안으로 들어가고, 뒤는 서브에이전트가 시스템 프롬프트를 쥔 채 스킬을 싣는 쪽. 어느 쪽이든 대화 기록 없이 시작하는 건 같다.

우리 기준: 규칙은 역할 파일 하나에, 스킬과 서브에이전트는 그 파일을 부르는 입구로

여기부터는 우리가 정한 기준. 역할 규칙 본문은 역할 파일 하나에 두고, 스킬과 서브에이전트 파일은 그 파일을 읽으라는 몇 줄로 끝낸다. 스킬 쪽 실물은 1편에 있고, 서브에이전트 쪽을 같은 모양으로 줄이면 아래와 같다.

---
name: reviewer
description: Reviews a finished draft against agents/reviewer.md. Use after a draft is written.
tools: Read, Grep, Glob
model: inherit
---

Read agents/reviewer.md and review the draft as that role.
Return your findings in the final message. Do not edit files.

공식 문서상 필수 필드는 name · description 둘뿐. tools 와 model 은 우리가 늘 적어 두는 필드다. tools 를 빼 두면 쓸 수 있는 도구를 전부 물려받으니까.

작성자와 다른 눈이 필요한 검토, 그러니까 QA · 반증 · 보안 같은 일은 서브에이전트에 맡긴다. 작성한 대화를 못 본다는 점이 이때는 장점.

서브에이전트가 다시 위임하지 못하게 tools 에 Agent 도 넣지 않는다. 문서 기준으로 서브에이전트는 기본값에서 메인 대화 아래 세 단계까지 자기 서브에이전트를 띄울 수 있고, tools 목록에 Agent 가 아예 없으면 띄우지 못한다. 위 예처럼 쓰기 도구가 없는 서브에이전트라면 결과는 마지막 메시지로.

실제로 겪은 일

10월 3일까지 우리 역할은 두 길로만 불렀다. 슬래시 스킬로 지금 세션이 역할을 입거나, 범용 에이전트에 긴 프롬프트를 붙여 띄우거나. 그날 내가 릴스에서 서브에이전트를 보고 「서브에이전트 진행」이라고 했고, QA · 반증 · 보안 같은 역할 다섯 개가 .claude/agents/ 에 서브에이전트 파일로 들어갔다. 파일마다 규칙은 복사하지 않고 원래 역할 파일을 읽으라는 내용만 있고, 도구 목록에 Agent 가 없다. 같은 날 시험에서는 반증 검토 서브에이전트가 이름으로 부르지 않았는데도 description 만 보고 불렸다.

내 저장소 점검표: 스킬 · 서브에이전트 나눠 쓸 때

  1. 매번 다시 붙여 넣는 지시 · 절차가 있나. 메인 대화 안에서 쓸 거라면 스킬로 옮긴다.
  2. 서브에이전트에 맡기는 일이 지금 대화 내용 없이도 서나. 서브에이전트는(포크 제외) 대화 기록 · 이미 읽은 파일을 보지 못한다.
  3. 서브에이전트 파일에 tools 를 적었나. 빼면 쓸 수 있는 도구를 전부 물려받는다. 다시 위임하지 않게 하려면 목록에 Agent 를 넣지 않는다.
  4. 스킬과 서브에이전트 모두 description 맨 앞에 언제 쓰는지가 있나. 스킬 목록에서는 description 과 when_to_use 를 합쳐 1,536자에서 잘린다.
  5. 같은 이름이 개인 · 프로젝트 양쪽에 있나. 스킬은 개인 것이, 서브에이전트는 프로젝트 것이 쓰인다.
  6. 규칙 본문이 스킬 · 서브에이전트 파일에 복사돼 있지 않나. 한 파일에만 두고 거기를 읽게 한다.
  7. 세션 중에 agents 폴더를 처음 만들었다면 Claude Code를 다시 시작했나. 이미 있던 폴더의 파일을 고친 건 몇 초 안에 다음 위임부터 반영된다.
  8. SKILL.md 가 500줄을 넘지 않나. 긴 참고 내용은 다른 파일로 뺀다.

같이 읽을 글

다음 글은 클로드 코드 텔레그램 연동. 작업이 승인을 기다릴 때 텔레그램으로 알림을 받게 한 방법을 다룬다.

다음에 다뤘으면 하는 질문은 댓글로 남기거나 codenara.contact@gmail.com 으로 보내 주세요. 받은 질문은 다음 글감으로 씁니다.