커맨드·스킬·서브에이전트 고르기

세 가지 확장 단위

커맨드와 스킬은 이제 거의 같은 프론트매터(description, model, allowed-tools, disable-model-invocation, user-invocable, hooks)를 받는다. 커스텀 커맨드는 스킬로 합쳐지는 흐름이고, 폴더에 자료를 둘 수 있는 스킬이 상위 호환이다. 「커맨드는 자동 호출이 안 되고 훅도 없다」는 오래된 설명은 2026-11 기준으로 맞지 않는다.

언제 무엇을

경험칙:

• 하루에 한 번 이상 하는 일은 스킬이나 커맨드로 만든다. 한두 단어로 되는 지시(「simplify it」)는 굳이 만들 필요가 없고, 두세 줄을 매번 써야 하는 지시가 대상이다.
• 범용 qa·backend 에이전트보다 기능 특화 서브에이전트 + 스킬이 낫다. 워크플로는 서브에이전트보다 커맨드로 짠다.
• 같은 코드 리뷰라도 CI에서는 커맨드로, 작업 중에는 서브에이전트로 돌린다. 작업 중 리뷰 내용은 다음 할 일과 무관하므로 맥락을 갈라 두는 게 낫다.

셋 다 있으면 무엇이 뜨나

같은 일을 하는 커맨드·에이전트·스킬을 모두 두고 「지금 몇 시야?」라고 물으면:

1. 스킬이 가장 먼저 뜬다. 인라인이라 오버헤드가 없다.
2. 스킬이 없거나 disable-model-invocation: true면 에이전트가 뜬다. 별도 맥락이라 무겁다.
3. 커맨드도 이제 스킬로 합쳐져 Claude가 스스로 부를 수 있다. 사용자가 /로 부를 때만 돌게 하려면(배포·푸시처럼) 커맨드 파일에도 disable-model-invocation: true를 넣는다.

둘 다 막으면 Claude가 직접 TZ='Asia/Karachi' date 같은 명령을 실행한다.

서브에이전트

판단 기준: 도구 출력이 다시 필요한가

서브에이전트는 무엇보다 맥락 관리 수단이다. 「이 도구 출력이 나중에 다시 필요한가, 결론만 필요한가?」를 묻는다. 결론만 필요하면 맡긴다. 파일 읽기 20번, grep 12번, 막다른 길 3개는 자식 맥락에 남고 보고서만 돌아온다.

• 스펙 파일을 기준으로 결과를 검증하기, 다른 코드베이스의 인증 흐름을 요약해 오기, git 변경으로 문서 쓰기가 전형적인 예다.
• 더 많은 계산을 쓰고 싶은 요청 끝에 「use subagents」를 붙인다. 어려운 조사는 「서브에이전트 3개(5개, 10개)로 병렬 조사」처럼 난이도에 맞춰 개수를 프롬프트로 정한다. 매번 다르므로 CLAUDE.md에 넣지 않는다.

진짜 가치는 상관없는 맥락 창

프론트엔드 개발자·백엔드 개발자·PM 같은 역할극 에이전트는 의인화가 지나치다. 가치는 역할이 아니라 서로를 모르는 맥락 창(uncorrelated context windows) 에서 나온다.

• 스킬·커맨드는 부모 맥락을 보지만(상관), 서브에이전트는 프롬프트만 받는다(비상관).
• 서로 오염되지 않은 맥락 창 여럿에 토큰을 더 쓰는 것은 일종의 테스트 타임 컴퓨트다. 같은 모델이라도 한 에이전트가 만든 버그를 다른 에이전트가 찾는다.
• 코드 리뷰 예: 서브에이전트 여럿이 병렬로 이슈를 찾고(CLAUDE.md 준수, git 기록, 명백한 버그), 서브에이전트 5개를 더 띄워 오탐만 검증하고 중복을 거른다.
• 대립 처리(opponent processor): 나를 대변하는 에이전트와 감사 쪽 에이전트가 다투게 해 결론을 낸다.
• 대규모 마이그레이션: 메인 에이전트가 큰 할 일 목록을 만들고 서브에이전트들에게 맵리듀스로 뿌린다. 자동 수정기가 없는 린트 규칙 도입, 테스트 프레임워크 교체처럼 결과 검증이 쉬운 일에 맞는다.

프론트매터 필드

claude --agent=<이름>이나 설정의 "agent"로 커스텀 에이전트를 메인 세션으로 띄우면, 시스템 프롬프트와 도구 세트가 다른 읽기 전용 에이전트·리뷰 전용 에이전트를 만들 수 있다.

내장 에이전트

자주 쓰는 커스텀 예로는 작업 뒤 코드를 단순화하는 code-simplifier, E2E 검증 절차를 담은 verify-app이 있다.

커맨드 → 에이전트 → 스킬 오케스트레이션

세 단위를 한 흐름으로 엮는 패턴이다. 커맨드는 진입점과 조율, 에이전트는 데이터 가져오기, 스킬은 결과물 만들기를 맡고, 컴포넌트마다 책임은 하나다.

flowchart LR
  U["사용자"] --> C["/weather-orchestrator<br/>(커맨드, haiku)"]
  C -->|"1. AskUserQuestion"| Q["섭씨? 화씨?"]
  C -->|"2. Agent 도구"| A["weather-agent<br/>(서브에이전트, sonnet)"]
  F["weather-fetcher<br/>(프리로드 스킬)"] -->|"시작 시 주입"| A
  A --> API["Open-Meteo API"]
  A -->|"기온 + 단위 반환"| C
  C -->|"3. Skill 도구"| S["weather-svg-creator<br/>(스킬)"]
  S --> O["weather.svg, output.md"]

이 구조에서 웹 조회의 잡음은 에이전트 맥락에만 남고 메인 대화에는 「26°C」 같은 결과만 돌아온다. 같은 패턴을 에이전트 팀으로 병렬 구축하는 예는 Claude Code 개발 워크플로에 있다.

정리

• 서브에이전트는 맥락 격리, 커맨드는 사용자 진입점, 스킬은 자동 발견되는 재사용 절차다. 커맨드는 점점 스킬로 합쳐진다.
• 서브에이전트를 쓸지는 「도구 출력이 다시 필요한가」로 판단한다. 가치는 역할극이 아니라 상관없는 맥락 창에 있다.
• 에이전트에는 skills:로 정적 지식을, memory:로 쌓이는 지식을 준다.
• 커맨드 → 에이전트 → 스킬로 나누면 가져오기와 그리기가 분리되고 메인 맥락이 깨끗하게 유지된다.

관련 노트: Claude 스킬 만들기 가이드, Claude Code 메모리, 멀티 에이전트, 내 일을 줄이는 하네스 만들기, Claude Code 개발 워크플로