Claude Code의 기능을 확장할 때 가장 핵심이 되는 세 가지 단위는 스킬(Skill), 서브에이전트(Subagent), **플러그인(Plugin)**입니다. 셋 다 설정 디렉터리와 마크다운 파일 기반으로 구성되기에 언뜻 비슷한 커스터마이징 수단처럼 보이지만, 에이전트를 어떤 차원에서 확장하는가가 근본적으로 다릅니다.
스킬은 메인 대화의 작업 기억 안에서 동작하는 지시(Instruction)의 확장이고, 서브에이전트는 완전히 격리된 별도 작업창에서 일하는 실행(Execution)의 확장이며, 플러그인은 이들을 외부 도구 및 훅과 함께 하나로 묶어 배포하는 패키징(Packaging)의 확장입니다. 이 세 단위의 경계와 동작 메커니즘을 이해하면 불필요한 토큰 낭비를 막고 프로젝트에 최적화된 확장 아키텍처를 설계할 수 있습니다.
1. 확장의 3가지 차원: 지시, 실행, 패키징
세 단위는 동작하는 컨텍스트 창(Context Window)의 위치와 생명주기가 다릅니다.
| 구분 | 스킬 (Skill) | 서브에이전트 (Subagent) | 플러그인 (Plugin) |
|---|---|---|---|
| 확장 차원 | 지시 확장 (프롬프트/절차) | 실행 확장 (격리 작업자) | 패키징 확장 (배포 번들) |
| 정의 파일 | SKILL.md | .claude/agents/*.md | .claude-plugin/plugin.json 외 디렉터리 |
| 동작 컨텍스트 | 메인 대화창 내부에 직접 주입 | 독립된 새 컨텍스트 창 (격리 실행) | 구성요소에 따라 각각의 컨텍스트에서 동작 |
| 로딩 메커니즘 | 설명(상시) → 본문(호출 시 지연 로딩) | 위임 시점에 별도 인스턴스로 생성(Spawn) | 플러그인 활성화 시 구성요소 일괄 등록 |
| 호출 방식 | /스킬명 또는 모델의 자율 도구 선택 | 모델의 작업 위임 또는 @agent-<name> | 네임스페이스 접두사 (/플러그인:스킬 등) |
| 핵심 목적 | 반복되는 워크플로 지침의 재사용 | 메인 컨텍스트 오염 방지와 비용 격리 | 여러 프로젝트·팀 간 구성요소 일괄 배포 |
2. 스킬(Skill): 메인 컨텍스트를 풍부하게 하는 지침 도구
스킬은 에이전트가 도구함에 넣어 두고 필요할 때 꺼내 쓰는 재사용 가능한 절차 지침입니다. SKILL.md 파일에 YAML 프론트매터와 마크다운 본문을 작성해 정의합니다.
---
name: deploy-preview
description: Staging 환경에 코드를 빌드하고 프리뷰 배포를 실행하는 절차
disable-model-invocation: true
---지연 로딩(Lazy Loading)과 컨텍스트 최적화
스킬의 가장 큰 강점은 설명(Description)과 본문(Body)이 서로 다른 시점에 로드된다는 점입니다.
- 설명의 상시 로딩: 스킬의
description은 세션이 시작될 때부터 항상 시스템 프롬프트(도구 정의)에 포함됩니다. Claude는 이 설명을 보고 사용자의 요청과 관련이 있는 스킬을 스스로 판단하여 호출합니다. - 본문의 온디맨드 로딩: 스킬 본문의 상세한 지침은 해당 스킬이 호출되는 순간에만 메인 대화창으로 읽혀 들어옵니다. 따라서 스킬을 수십 개 만들어 두어도 평소에는 상시 컨텍스트를 거의 차지하지 않습니다.
- 자율 호출 통제 (
disable-model-invocation): 배포나 DB 마이그레이션처럼 부작용이 큰 워크플로는disable-model-invocation: true로 설정해 모델이 멋대로 호출하지 못하게 막고, 오직 사용자가/deploy-preview처럼 명시적으로 입력했을 때만 실행되도록 통제할 수 있습니다. 이때는 상시 설명조차 컨텍스트에서 제외되어 토큰 비용이 0이 됩니다.
CLAUDE.md와의 명확한 역할 구분
- CLAUDE.md: “절대 X 하지 말 것”, “타입스크립트 엄격 모드 준수”, “빌드 명령은
npm run build”처럼 세션 내 모든 요청에서 항상 알아야 하는 전역 규칙을 담습니다. - 스킬: “릴리즈 노트 작성 절차”, “신규 API 엔드포인트 템플릿”처럼 특정 작업을 수행할 때만 일시적으로 필요한 상세 워크플로를 담습니다.
3. 서브에이전트(Subagent): 컨텍스트를 보호하는 격리된 작업자
서브에이전트는 특정 전문 작업(코드 리뷰, 로그 분석, 테스트 검증 등)을 전담하도록 설정된 독립된 AI 어시스턴트입니다.
스킬이 메인 대화창 안에 지침을 덧붙이는 방식이라면, 서브에이전트는 완전히 새로운 별도의 컨텍스트 창을 열어 작업합니다.
컨텍스트 격리의 가치
에이전트가 수천 줄의 코드베이스를 탐색하거나 방대한 테스트 로그를 분석하면 메인 대화창의 컨텍스트가 순식간에 가득 차게 됩니다. Claude Code는 매 턴마다 지금까지의 대화 전체를 모델에 다시 전송하므로, 이러한 탐색 로그가 메인 대화에 남으면 이후 단순한 질문 하나에도 막대한 토큰 비용이 발생합니다.
서브에이전트는 이 문제를 다음과 같이 해결합니다.
- 독립된 작업 공간: 서브에이전트는 자기만의 시스템 프롬프트와 허용된 도구를 가지고 격리된 상태에서 파일을 읽고 명령을 수행합니다.
- 요약 반환: 작업이 끝나면 중간 과정의 거대한 로그나 도구 출력은 서브에이전트의 컨텍스트와 함께 폐기되고, 최종 정리된 결과 요약만 메인 대화창으로 돌아옵니다.
- 부모 대화 은닉: 서브에이전트는 기본적으로 부모의 이전 대화 기록을 보지 못하므로, 위임할 때 명확하고 구체적인 프롬프트를 전달해야 합니다.
서브에이전트의 정의 문법, 호출 방식, 그리고 다중 인스턴스가 상호 대화하는 Agent Teams와의 심층 차이점은 Claude Code Agent Teams와 Subagent 차이점에서 자세히 다룹니다.
4. 플러그인(Plugin): 배포와 공유를 위한 포장재
플러그인은 스킬, 서브에이전트, 훅(Hooks), MCP 서버를 하나의 패키지로 묶어 설치하고 관리할 수 있게 만든 **배포 단위(Packaging Layer)**입니다.
디렉터리 루트의 .claude-plugin/plugin.json 매니페스트를 중심으로 다음과 같이 구성됩니다.
my-plugin/
├── .claude-plugin/plugin.json # 플러그인 메타데이터
├── skills/ # 플러그인 제공 스킬 (SKILL.md)
├── agents/ # 플러그인 제공 서브에이전트 (*.md)
├── hooks/hooks.json # 이벤트 라이프사이클 훅
└── .mcp.json # 외부 MCP 도구 서버 설정독립 단위와 플러그인의 관계
가장 중요한 사실은 스킬과 서브에이전트는 플러그인 없이도 완벽하게 단독 동작한다는 점입니다.
개인 프로젝트나 로컬 컴퓨터에서 쓸 때는 ~/.claude/skills/나 .claude/agents/에 직접 파일을 넣는 것만으로 충분합니다.
플러그인이 필요한 시점은 다음과 같습니다.
- 네임스페이스 충돌 방지: 플러그인을 통해 설치된 구성요소는
/플러그인명:스킬명이나@agent-플러그인명:에이전트명처럼 고유한 접두사가 붙어 기존 프로젝트 설정과 이름이 충돌하지 않습니다. - 다중 구성요소의 단일 번들링: 특정 도구를 활용하기 위해 필요한 “MCP 서버 + 사전 검증 훅 + 전용 서브에이전트 + 편의 스킬”을 한 번에 설치하고 토글할 수 있습니다.
- 팀 및 커뮤니티 배포: Git 저장소나 마켓플레이스를 통해 다른 개발자나 여러 저장소에 동일한 도구 환경을 일괄 배포할 수 있습니다.
마켓플레이스 활용과 설치 범위에 대한 상세 내용은 Claude Code 플러그인 정리에서 확인할 수 있습니다.
5. 단위 간의 합성(Composition)과 선택 기준
세 단위는 배타적인 것이 아니라 서로를 포함하고 호출하며 결합합니다.
- 플러그인 ⊃ 스킬, 서브에이전트, 훅, MCP: 플러그인은 이 모든 구성요소를 담는 컨테이너입니다.
- 서브에이전트 → 스킬 장착: 서브에이전트 정의 파일의
skills:필드에 특정 스킬 이름을 지정하면, 서브에이전트가 생성될 때 해당 스킬의 전문을 미리 로드하여 전용 도구처럼 활용할 수 있습니다. - 스킬 → 서브에이전트 포크: 스킬 프론트매터에
context: fork를 선언하면, 해당 스킬이 호출될 때 메인 대화창이 아니라 포크된 격리 서브에이전트 컨텍스트에서 안전하게 실행됩니다.
무엇을 만들어야 하는가? (의사결정 기준)
새로운 기능을 추가하고 싶을 때는 다음 질문을 따라 단위를 선택합니다.
- 같은 프롬프트나 체크리스트를 계속 복사해서 붙여넣고 있는가?
→ 스킬을 만듭니다. 반복되는 절차를SKILL.md로 등록해 두고 필요할 때/스킬명으로 호출합니다. - 특정 작업의 탐색 로그나 실행 출력이 대화창을 너무 지저분하게 채우는가?
→ 서브에이전트를 만듭니다. 작업을 격리된 창에서 수행하게 하고 핵심 결론만 요약으로 전달받습니다. - 만들어 둔 스킬, 에이전트, 훅, MCP 도구를 다른 동료나 여러 프로젝트에 그대로 공유하고 싶은가?
→ 플러그인으로 포장합니다. 하나의 디렉터리로 묶어 Git이나 마켓플레이스로 배포합니다.
연관 노트와 구현
이 세 가지 확장 단위를 실제 프로젝트와 다중 에이전트 환경에서 적용하는 구체적인 가이드는 아래 글에서 확인할 수 있습니다.
- Claude Code 플러그인 정리: 플러그인 매니페스트 구조와 마켓플레이스 설치 및 범위 제어
- Claude Code Agent Teams와 Subagent 차이점: 서브에이전트 정의 문법과 다중 에이전트 협업 체계
- Claude Code 기본 구조: 세션 런타임과 CLAUDE.md 및 settings.json의 상호작용
- 컨텍스트 창과 토큰 비용: 스킬의 지연 로딩과 서브에이전트의 요약 반환이 토큰 비용을 아끼는 원리