Claude Code 플러그인 구조 — Agents, Commands, Skills 차이와 선택 기준

Claude Code 플러그인은 agents, commands, skills 세 가지 리소스로 구성된다. 여기에 프로젝트 전용 스킬(.claude/skills/)까지 더하면, Claude Code에서 AI의 행동을 정의하는 방법은 총 네 가지다. 이 글에서는 각 리소스의 역할, 호출 방식의 차이, 새 기능을 만들 때 어떤 유형을 선택해야 하는지를 정리한다.

Claude Code 플러그인이란

Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 에이전트다. 코드를 읽고, 수정하고, 터미널 명령을 실행할 수 있다.

플러그인은 Claude Code의 기능을 확장하는 패키지다. 마켓플레이스에서 설치하거나 직접 만들 수 있다. 플러그인의 실체는 마크다운 파일들의 모음이다. 별도의 프로그래밍 언어가 필요 없다. 마크다운으로 에이전트의 역할, 워크플로우, 참조 지식을 정의하면 Claude Code가 이를 읽고 행동한다.

플러그인의 세 가지 리소스: Agents, Commands, Skills

하나의 플러그인은 세 가지 유형의 리소스를 포함할 수 있다. 모두 포함할 수도 있고, 일부만 포함할 수도 있다.

my-plugin/
├── plugin.json        # 플러그인 메타데이터
├── agents/            # 서브에이전트 정의
├── commands/          # 슬래시 커맨드
└── skills/            # 참조용 지식 베이스

각각의 역할과 호출 방식이 다르다.

Agents — 서브에이전트 정의

agents/ 디렉터리의 마크다운 파일은 서브에이전트의 시스템 프롬프트다. Claude Code가 복잡한 작업을 만나면, 해당 분야의 전문가 에이전트를 별도 프로세스로 띄워서 위임한다. 이때 agents 파일이 그 전문가의 역할과 행동 규칙을 정의한다.

---
name: code-reviewer
description: Reviews code for security vulnerabilities and performance issues.
model: sonnet
---
 
You are a code review expert specializing in security and performance.
 
## Review Checklist
- SQL injection vulnerabilities
- XSS attack vectors
- N+1 query patterns
- Memory leak risks
...

핵심 특성:

• Claude가 알아서 판단해서 사용한다. 사용자가 "코드 리뷰해줘"라고 요청하면, Claude가 적절한 에이전트를 자동으로 선택해서 띄운다.
• 별도 서브프로세스로 실행되어 메인 대화와 컨텍스트가 분리된다. 서브에이전트가 대량의 코드를 읽어도 메인 대화의 컨텍스트 윈도우를 소비하지 않는다.
• 사용자가 /code-reviewer로 직접 호출할 수는 없다.
• model 필드로 사용할 모델을 지정할 수 있어, 간단한 작업은 가벼운 모델로 처리해 비용을 절감할 수 있다.

Commands — 슬래시 커맨드

commands/ 디렉터리의 마크다운 파일은 /slash-command 형태로 호출하는 워크플로우 스크립트다. 정해진 단계를 순서대로 실행하는 절차서 역할을 한다.

---
description: "Run tests, build, and deploy the project"
argument-hint: "<environment> [--dry-run]"
---
 
# Deploy
 
## Step 1: Run Tests
1. Find all test files related to changed files
2. Run test suite and verify all pass
 
## Step 2: Build
1. Run production build
2. Verify no build errors
 
## Step 3: Deploy
1. Push to remote repository
2. Trigger deployment pipeline

핵심 특성:

• 사용자가 /deploy production처럼 직접 트리거한다.
• 단계별 실행 절차가 정의되어 있다. Claude는 이 절차를 따라 순서대로 실행한다.
• 메인 대화 컨텍스트 안에서 실행된다.
• argument-hint로 인자를 받을 수 있다.

Skills — 참조용 지식 베이스

skills/ 디렉터리의 파일은 Claude가 작업 중 참조하는 지식이다. 실행 절차가 아니라, 의사결정을 돕는 가이드와 패턴을 담고 있다.

---
name: api-design-patterns
description: REST API design patterns and naming conventions.
---
 
# API Design Patterns
 
## Naming Conventions
 
| Resource   | Endpoint          | Method |
|------------|-------------------|--------|
| 목록 조회   | /users            | GET    |
| 단일 조회   | /users/:id        | GET    |
| 생성       | /users            | POST   |
| 수정       | /users/:id        | PATCH  |
 
## Pagination
- cursor 기반 페이지네이션을 기본으로 사용
- offset 방식은 데이터 변경이 적은 경우에만...

핵심 특성:

• 패턴, 가이드, 의사결정 기준을 담는다.
• Claude가 관련 작업을 할 때 description을 보고 필요하다고 판단하면 자동으로 로드한다.

Agents, Commands, Skills의 호출 방식

여기서 "메인 Claude"란 사용자와 직접 대화하는 세션의 Claude를 뜻하고, "서브에이전트"란 메인 Claude가 작업을 위임하기 위해 별도 프로세스로 띄운 Claude를 뜻한다.

command와 agent 사이의 호출 흐름은 항상 command → agent 방향이다. command가 워크플로우를 시작하고, 그 안에서 필요한 에이전트를 띄운다. 서브에이전트가 command를 호출하는 역방향은 없다.

실제 플러그인 디렉터리 구조 비교

설치된 두 플러그인의 디렉터리 구조를 비교하면 차이가 명확해진다.

플러그인 A — agents만 존재

seo-content-creation/
├── plugin.json
└── agents/
    ├── seo-content-auditor.md
    ├── seo-content-planner.md
    └── seo-content-writer.md

agents만 정의된 플러그인이다. "콘텐츠 전략을 세워줘"라고 요청하면 Claude가 seo-content-planner 에이전트를 자동으로 띄운다. commands가 없으므로 /seo-content-planner로 직접 호출할 수는 없고, / 메뉴에도 나타나지 않는다.

플러그인 B — 세 가지 모두 존재

agent-teams/
├── plugin.json
├── agents/
│   ├── team-implementer.md
│   ├── team-reviewer.md
│   └── team-lead.md
├── commands/
│   ├── team-feature.md
│   ├── team-review.md
│   └── team-debug.md
└── skills/
    ├── team-composition-patterns/
    └── task-coordination-strategies/

세 가지를 모두 갖고 있다:

• agents: 각 팀원(구현자, 리뷰어, 리더)의 역할 정의
• commands: /team-feature로 병렬 개발 워크플로우를 트리거
• skills: 팀 규모 결정, 작업 분배 전략 같은 참조 지식

/team-feature를 실행하면, command가 워크플로우를 시작하고, 그 안에서 agents에 정의된 에이전트들이 서브프로세스로 띄워지며, skills의 지식을 참조해서 팀을 구성한다. 세 리소스가 협업하는 구조다.

프로젝트 스킬과 플러그인의 차이

플러그인 외에 프로젝트 스킬이라는 개념이 있다. 프로젝트 루트의 .claude/skills/ 디렉터리에 SKILL.md 파일을 두면, 해당 프로젝트에서만 동작하는 스킬이 된다.

my-project/.claude/skills/
├── deploy/SKILL.md        # 이 프로젝트의 배포 워크플로우
├── test-runner/SKILL.md   # 이 프로젝트의 테스트 실행 절차
└── conventions/SKILL.md   # 이 프로젝트의 코딩 컨벤션

프로젝트 스킬은 해당 프로젝트의 스크립트, 파일 구조, 빌드 도구에 의존한다. 다른 프로젝트로 옮기면 동작하지 않는다. 플러그인은 어떤 프로젝트에서든 동일하게 동작하는 범용 기능이라는 점에서 다르다.

프로젝트 스킬은 하나의 SKILL.md 파일이 플러그인의 commands와 skills 역할을 모두 수행한다. frontmatter 옵션으로 제어한다.

user-invocable: true로 설정하면 사용자가 /deploy처럼 슬래시 커맨드로 트리거할 수 있다 — 플러그인의 commands와 같은 역할이다. user-invocable: false로 설정하면 Claude만 자동으로 참조한다 — 플러그인의 skills와 같은 역할이다. allowed-tools로 사용할 수 있는 도구도 제한할 수 있다.

플러그인 리소스 선택 기준

새 기능을 만들 때 어떤 유형을 선택할지, 세 가지 질문으로 결정할 수 있다.

질문 1: 이 프로젝트에서만 쓰는가?

해당 프로젝트의 스크립트, 디렉터리 구조, 빌드 도구에 의존하는 기능이라면 프로젝트 스킬(.claude/skills/)로 만든다. 예를 들어:

• 이 프로젝트의 테스트 스크립트를 실행하는 워크플로우
• 이 프로젝트의 디렉터리 구조에 맞게 파일을 생성하는 템플릿
• 이 프로젝트의 배포 파이프라인을 트리거하는 절차

어떤 프로젝트에서든 동일하게 동작하는 기능이라면 플러그인으로 만든다. 다음 질문으로 넘어간다.

질문 2: Claude가 알아서 쓰게 할 것인가, 사용자가 트리거할 것인가?

Claude가 상황에 맞게 자동으로 사용하게 하려면 agents/로 만든다. 사용자가 "코드 리뷰해줘"라고 요청하면 Claude가 보안 리뷰어 에이전트를 알아서 선택하는 식이다.

사용자가 /command-name으로 명시적으로 트리거하게 하려면 commands/로 만든다. 정해진 단계를 순서대로 실행하는 워크플로우에 적합하다.

질문 3: 실행하는 것인가, 참조하는 것인가?

실행 절차도 아니고 전문가 역할도 아닌, 참조용 지식(패턴 가이드, 의사결정 기준표)이라면 skills/로 만든다. agents나 commands가 작업 중 이 지식을 자동으로 참조한다.

정리

이 프로젝트에서만 쓰는가?
├── 예 → 프로젝트 스킬 (.claude/skills/)
└── 아니오 (범용) → 플러그인으로 만든다
    ├── Claude가 자동으로 사용? → agents/
    ├── 사용자가 트리거?       → commands/
    └── 참조용 지식?           → skills/

마무리

Claude Code에서 AI의 행동을 정의하는 방법은 크게 두 갈래다.

• 프로젝트 스킬 (.claude/skills/) — 이 프로젝트에서만 동작하는 워크플로우와 지식
• 플러그인 — 범용적으로 배포 가능한 패키지. 세 가지 리소스로 구성된다:
  • agents/ — Claude가 자동 판단하여 띄우는 전문가 역할
  • commands/ — 사용자가 /로 트리거하는 실행 절차
  • skills/ — 자동으로 참조되는 지식 베이스

References

• Skills — Claude Code Docs
• Claude Code Plugins — Anthropic Docs
• Subagents — Claude Code Docs