[AI][Claude] Command, Skill, Subagent

Command, Skill, Subagent

Claude Code의 확장 메커니즘 중 Command, Skill, Subagent는 형태가 비슷해서 점점 커지는 개념(Command < Skill < Subagent)으로 묶어 정리하기 쉬운데, 실제 분기점은 그 축이 아니다. 이 글은 차이를 정리하고, 어떤 상황에 무엇을 써야 하는지 짚는다.

1. 왜 이렇게 헷갈릴 수밖에 없는가

세 개념이 헷갈리는 데는 이유가 있다.

• 셋 다 .claude/ 하위 디렉토리에 markdown으로 정의한다.
• 셋 다 사용자가 직접 만드는 커스텀 확장이다.
• 셋 다 frontmatter + 본문 markdown이라는 같은 형식을 쓴다.

거기에 더해, 2026년 1월 Claude Code 2.1.0 릴리스에서 Custom slash command가 Skill로 통합됐다. 공식 릴리스 노트의 표현을 그대로 옮기면 "슬래시 커맨드와 스킬을 병합하여 멘탈 모델을 단순화한다, 동작 변화는 없다"이다. 이제 .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md는 둘 다 /deploy를 만들고 동일하게 동작한다. 같은 이름이면 skill이 우선한다.

기존 .claude/commands/ 파일은 그대로 작동한다. 하지만 새로 만든다면 skill 형태가 권장된다. 디렉토리 구조 + frontmatter 옵션이 더 풍부하기 때문이다.

Command	사용자가 /로 명시적으로 부르는 단축 진입점
Skill	모델이 description 매칭으로 자동 발견해서 끌어다 쓰는 노하우 묶음
Subagent	별도 컨텍스트에서 일하고 결과만 돌려주는 전문 동료

Command는 사실상 "user-invoked Skill"이다. Skill 정의에 disable-model-invocation: true를 켜면 사용자만 부를 수 있는 형태가 되고, 이게 사실상 예전의 Command다. 통합되기 전후로 동작이 같다는 게 이런 의미다.

2. 진짜 차이는 "크기"가 아니라 "어디서 실행되는가"

Command, Skill, Subagent를 정의 파일 분량으로 비교하면 점점 커지는 그라데이션처럼 보인다. Command는 프롬프트 한 덩어리, Skill은 디렉토리에 부속 파일까지, Subagent는 시스템 프롬프트에 도구 권한까지. 그래서 "좀 무거운 작업은 subagent 급"이라는 직관이 생기기 쉽다. 하지만 정의 파일의 길이는 부차적이다.

진짜 분기점은 크기가 아니다. 어디서 실행되느냐다. 500줄짜리 거대한 skill도 결국 skill이다. 시스템 프롬프트 10줄짜리 작은 subagent도 여전히 subagent다.

항목	Command / Skill	Subagent
실행 위치	메인 Claude 컨텍스트	별도 인스턴스, 자체 컨텍스트
읽은 파일·도구 결과	메인 컨텍스트에 누적	subagent 안에만 누적, 메인에는 요약만
호출 주체	사용자(slash) 또는 모델(auto-invoke)	메인 Claude가 위임
적합한 용도	메인 흐름에서 그대로 이어갈 작업	메인을 더럽히지 않고 격리할 작업

컨텍스트가 폭발하는 시나리오

인증 흐름을 분석한다고 해보자. 관련 파일이 30개쯤 흩어져 있다.

• Skill로 처리한 경우
  • 메인 Claude가 30개 파일을 직접 Read한다. 파일 내용 전체가 메인 컨텍스트에 쌓인다. 분석이 끝났을 때 컨텍스트의 상당 부분이 인증 코드로 차 있다. 이 상태에서 후속 질문("이제 결제 모듈도 봐줘")을 하면, 결제 파일을 읽으면서 앞서 본 인증 컨텍스트가 점점 밀려난다. 길게 가는 세션에서 이 누적이 치명적이다.

• Subagent로 처리한 경우
  • 메인은 auth-researcher에 위임만 한다. subagent가 별도 컨텍스트에서 30개 파일을 읽고, 분석을 마친 뒤 요약만 메인에 돌려준다. 메인 컨텍스트에는 "인증은 이런 구조다"라는 한 덩어리만 남는다.

같은 작업, 같은 결과다. 차이는 메인 컨텍스트의 깨끗함이다. 후속 작업이 많을수록 차이가 벌어진다.

3. 차이점 및 활용 가이드

"PR 리뷰"라는 한 가지 작업을 Command, Skill, Subagent으로 각각 만들어 결과물이 어떻게 다른지 비교해보자.

Command 버전 : 사용자가 명시적으로 부른다

.claude/skills/review/SKILL.md로 만든다.

기존 .claude/commands/review.md 형태도 동일하게 동작한다.

---
name: review
description: 변경사항을 체크리스트로 리뷰
disable-model-invocation: true
---

현재 변경사항을 다음 항목으로 리뷰해줘.

1. 에러 핸들링이 빠진 곳
2. 하드코딩된 값
3. 테스트가 필요한 부분
4. 네이밍이 어색한 부분

각 항목은 `파일명:라인번호` 형태로 인용한다.

disable-model-invocation: true를 켰기 때문에 사용자가 /review를 직접 입력해야만 발동한다.

• 발동 주체: 사용자
• 실행 위치: 메인 컨텍스트
• 후속 대화로 자연스럽게 이어진다.
• 짧고 가볍다.

Skill 버전 : 모델이 알아서 발동한다

같은 형태에서 disable-model-invocation만 빼고 description을 자세히 써준다. 디렉토리에 부속 파일도 같이 둔다.

.claude/skills/review/
├── SKILL.md
├── checklist.md
└── examples/
    ├── good-review.md
    └── bad-review.md

---
name: review
description: 사용자가 코드 리뷰, PR 리뷰, 변경사항 검토를 요청할 때 자동 발동. diff, commit, pull request 키워드를 감지하면 활성화한다.
---

팀의 코드 리뷰 가이드는 checklist.md에 있다. 좋은/나쁜 리뷰 예시는 examples/ 디렉토리를 참고한다.

(체크리스트 + 톤 가이드 + 예시 reference)

/review를 명시적으로 치지 않아도, "방금 바꾼 거 한 번 봐줘" 같은 자연스러운 요청에 description 매칭으로 알아서 끌려 들어온다.

• 발동 주체: 모델 (description 매칭)
• 실행 위치: 메인 컨텍스트
• supporting 파일 덕분에 팀 가이드, 예시, 헬퍼 스크립트를 같이 묶을 수 있다.

Subagent 버전 : 별도 컨텍스트에서 처리한다

.claude/agents/code-reviewer.md로 만든다.

---
name: code-reviewer
description: 변경사항을 별도 컨텍스트에서 정밀 리뷰. PR 단위 분석에 사용.
tools: Read, Grep, Glob
---

너는 시니어 코드 리뷰어다. 다음 절차로 일한다.

1. `git diff`로 변경사항 전체를 파악
2. 영향받는 모든 파일을 Read
3. 관련 테스트 파일을 Grep으로 확인
4. 다음 구조로 보고서 반환
   - Summary
   - Issues (severity별)
   - Suggestions
   - Test gaps

Write 권한이 없다. 분석과 보고만 한다.

메인 Claude가 "code-reviewer로 이번 PR 리뷰해줘"라고 위임하면, 별도 인스턴스가 자기 컨텍스트에서 모든 파일을 읽고 분석해서 보고서만 돌려준다.

• 발동 주체: 메인 Claude의 위임
• 실행 위치: 별도 컨텍스트
• 메인은 보고서만 받는다.
• tools로 도구 권한을 제한할 수 있어서 안전하다.

활용 가이드

10개 파일 규모의 PR을 각각 처리했다고 해보자. 작업이 끝난 뒤 메인 컨텍스트에 남는 것은 다음과 같다.

Command	변경된 파일 10개 내용 + 체크리스트 응답
Skill	변경된 파일 10개 내용 + 가이드 + 예시 + 체크리스트 응답
Subagent	보고서 한 덩어리

Command와 Skill은 메인에서 직접 처리하기 때문에 읽은 파일이 컨텍스트에 그대로 쌓인다. Subagent는 별도 컨텍스트에서 처리하고 결과만 던져주기 때문에 메인은 깔끔하게 유지된다.

짧은 체크리스트, 결과를 바로 메인 대화에서 이어 쓸 작업	Command (= user-invoked Skill)
자동으로 끌려 들어왔으면 좋겠고, 가이드/예시가 풍부한 작업	Skill (auto-invoke)
큰 코드베이스 분석, 메인 컨텍스트 보호가 중요한 작업	Subagent
도구 권한을 제한해야 하는 작업 (Write 금지 등)	Subagent
매번 같은 30개 파일을 읽어야 하는 리서치성 작업	Subagent

의심스러우면 두 질문만 던지면 된다. "메인 컨텍스트에 결과 디테일이 남아있어야 하나?" "예"면 Skill, "아니오, 요약만 있으면 됨"이면 Subagent다.

4. 자주 빠지는 함정

Subagent 남발하면 디테일을 잃는다

격리가 좋다고 해서 모든 걸 subagent로 보내면, 메인은 매번 깔끔한 요약만 받게 된다. 깔끔한데 정작 후속 작업이 안 된다. 예를 들어 리뷰 보고서를 받았는데 "auth.py:42에 race condition 가능성"이라는 줄이 있다. 메인 Claude는 그 코드를 본 적이 없어서 후속 질문에 답하려면 다시 파일을 읽어야 한다. 즉, 격리는 컨텍스트를 절약하는 대신 디테일에 대한 직접 접근을 잃는 거래다.

description이 너무 generic하면 엉뚱한 상황에 발동한다

Skill의 auto-invoke는 description 매칭이다. "코드 분석"처럼 광범위한 description을 쓰면, 단순한 코드 질문에도 skill이 끌려 들어온다. 매번 불필요하게 supporting 파일까지 컨텍스트로 들어오니까 토큰만 낭비된다. description은 "언제 발동해야 하는지" 와 "언제 발동하면 안 되는지" 가 모두 명확해야 한다.

Subagent에 도구 권한을 너무 많이 주면 격리의 의미가 흐려진다

Subagent의 가치 중 하나는 도구 권한을 제한할 수 있다는 점이다. tools: Read, Grep, Glob만 준 reviewer는 코드를 절대 수정할 수 없다. 그런데 "혹시 모르니까" Write까지 다 풀어주면 격리된 일꾼이 아니라 그냥 또 다른 메인 에이전트가 된다. 권한 최소화는 subagent의 핵심 효용이다.

같은 이름의 command/skill 충돌

.claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md가 둘 다 있으면 skill이 우선한다. 마이그레이션 중간에 이걸 모르고 양쪽을 다 두면, 자기가 의도한 command가 안 불리고 다른 skill이 동작하는 경우가 생긴다. 옮길 때는 한쪽을 깔끔히 비워두자.

5. 같이 알면 좋은 확장들

본문에서 다룬 기능 외에도 Claude Code의 확장 메커니즘은 더 있다.

CLAUDE.md	가장 단순한 baseline. 항상 적용되는 프로젝트 컨벤션 저장소
Hooks	이벤트 기반 발동 (PreToolUse, PostToolUse 등). 발동 방식이 다른 카테고리
Plugins	Skills + Subagents + Commands를 묶어 배포하는 패키지 단위
MCP	외부 도구·데이터 연결. 본 글의 셋과는 다른 축의 확장

참고

Extend Claude with skills - Claude Code Docs

Extend Claude with skills - Claude Code Docs

Subagents - Claude Code Docs

Create custom subagents - Claude Code Docs

claude-code GitHub

GitHub - anthropics/claude-code: Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, a

Claude Code Release Notes (2.1.0 - Commands/Skills 통합)

claude-code/CHANGELOG.md at main · anthropics/claude-code