Claude Code 플러그인 만들기: 에이전트부터 커맨드까지

Claude Code는 2026년 현재 개발자 선호도 1위 AI 코딩 도구입니다. 그런데 대부분의 개발자가 기본 기능만 사용하고 있습니다. Claude Code의 진짜 힘은 플러그인 시스템에 있습니다. 커스텀 에이전트, 슬래시 커맨드, 자동화 훅, MCP 서버를 직접 만들어서 나만의 AI 개발 환경을 구축할 수 있습니다.

Claude Code 플러그인이란?

Claude Code 플러그인은 Claude Code의 기능을 확장하는 패키지입니다. 직접 만든 AI 에이전트, 슬래시 커맨드, 자동화 규칙을 하나의 플러그인으로 묶어서 프로젝트나 팀 단위로 공유할 수 있습니다. 쉽게 말하면, VS Code의 익스텐션과 비슷한 개념인데, AI 에이전트를 정의할 수 있다는 점이 다릅니다.

[IMAGE: Claude Code 플러그인 구조 다이어그램]

플러그인의 5가지 구성요소를 정리하면 이렇습니다.

구성요소	위치	역할	예시
에이전트	agents/*.md	자율적 AI 서브프로세스	코드 리뷰어, 테스트 생성기
커맨드	commands/*.md	슬래시 명령어 (/review 등)	/deploy, /test-all
스킬	skills/이름/SKILL.md	자동 활성화 지식/절차	API 설계 가이드, 테스트 패턴
훅	hooks/hooks.json	이벤트 기반 자동화	파일 저장 시 린트, 커밋 전 검사
MCP 서버	.mcp.json	외부 도구/서비스 연결	DB 조회, API 호출, 브라우저 제어

Claude Code 플러그인 디렉토리 구조

플러그인 디렉토리 구조는 정해진 규칙을 따릅니다. .claude-plugin/plugin.json 매니페스트가 필수이고, 나머지 컴포넌트는 플러그인 루트에 배치합니다.

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 필수: 플러그인 매니페스트
├── commands/                 # 슬래시 커맨드 (.md)
│   ├── review.md
│   └── deploy.md
├── agents/                   # 에이전트 정의 (.md)
│   └── code-reviewer.md
├── skills/                   # 스킬 (디렉토리/SKILL.md)
│   └── api-design/
│       └── SKILL.md
├── hooks/
│   └── hooks.json            # 이벤트 핸들러
└── .mcp.json                 # MCP 서버 설정

plugin.json 작성법

매니페스트 파일은 최소한 name 필드만 있으면 됩니다.

// .claude-plugin/plugin.json
{
  "name": "my-awesome-plugin",
  "version": "1.0.0",
  "description": "팀 코드 리뷰 자동화 플러그인",
  "author": { "name": "개발팀" }
}

커스텀 에이전트 만들기

에이전트는 플러그인의 핵심입니다. 특정 작업에 특화된 AI 서브프로세스를 정의해서, Claude Code가 상황에 맞는 에이전트를 자동으로 선택하게 할 수 있습니다. AI 에이전트 개발 도구를 활용한 실전 예제를 살펴보겠습니다.

에이전트 파일 구조

에이전트는 YAML frontmatter + 마크다운 본문으로 구성됩니다. frontmatter에 name, description, model, color 4가지 필수 필드가 있습니다.

# agents/code-reviewer.md
---
name: code-reviewer
model: sonnet
color: blue
description: >
  Use this agent when the user wants a code review.
  Examples: "코드 리뷰해줘", "이 PR 검토해줘"

  <example>
  Context: User requests code review
  user: "이 파일 코드 리뷰해줘"
  assistant: "코드 품질, 보안, 성능 관점에서 리뷰합니다."
  <commentary>Code review request triggers this agent.</commentary>
  </example>
tools: ["Read", "Grep", "Glob"]
---

You are a senior code reviewer...

**Your Core Responsibilities:**
1. Logic defects and bug detection
2. Security vulnerability scanning
3. Performance optimization suggestions

**Output Format:**
- Severity: Critical / Warning / Info
- Location: file:line
- Issue: description
- Fix: suggested solution

[IMAGE: Claude Code 에이전트 frontmatter 구조 설명]

frontmatter 필수 필드 설명

필드	필수	설명	값 예시
name	필수	에이전트 식별자 (3-50자, 소문자+하이픈)	code-reviewer
description	필수	트리거 조건 + example 블록	Use this agent when…
model	필수	사용할 모델	inherit, sonnet, opus, haiku
color	필수	UI 색상 식별	blue, cyan, green, yellow, magenta, red
tools	선택	허용 도구 제한	[“Read”, “Grep”]

슬래시 커맨드와 스킬 만들기

슬래시 커맨드

커맨드는 사용자가 직접 /플러그인명:커맨드명으로 실행하는 명령어입니다. commands/ 디렉토리에 마크다운 파일로 정의합니다.

# commands/review.md
---
name: review
description: PR 또는 파일의 코드 리뷰를 실행합니다
allowed-tools:
  - Read
  - Grep
  - Glob
---

## 코드 리뷰 커맨드

다음 절차로 코드 리뷰를 수행하세요:
1. 대상 파일/PR을 확인
2. 보안, 성능, 가독성 관점에서 분석
3. 심각도별로 이슈 분류하여 보고

이렇게 만들면 /my-plugin:review로 실행할 수 있습니다. 바이브 코딩과 결합하면 자연어로 리뷰를 요청하고, 커맨드로 정형화된 리뷰를 받는 하이브리드 워크플로우가 가능합니다.

스킬

스킬은 에이전트가 자동으로 참조하는 지식/절차입니다. 커맨드와 달리 사용자가 직접 호출하지 않고, Claude Code가 맥락에 따라 알아서 활성화합니다.

# skills/api-design/SKILL.md
---
name: API Design Standards
description: REST API 설계 시 참조하는 팀 표준 가이드
---

## API 설계 원칙
- RESTful 네이밍: 복수형 명사 사용 (/users, /posts)
- 응답 형식: JSON, snake_case
- 에러 코드: RFC 7807 Problem Details
- 페이지네이션: cursor 기반
- 버저닝: URL path (/v1/users)

에이전트와 커맨드의 차이를 정리하면 이렇습니다.

항목	에이전트	커맨드	스킬
활성화	자동 (맥락 기반)	수동 (/명령어)	자동 (맥락 기반)
용도	복잡한 자율 작업	정형화된 단일 작업	지식/가이드 참조
실행 방식	서브프로세스	현재 세션	컨텍스트 주입
모델 지정	가능	불가	불가

훅과 MCP 서버 설정

훅 (이벤트 자동화)

훅은 Claude Code 이벤트에 반응하는 자동화 규칙입니다. 파일 수정 전 검증, 커밋 전 린트 등을 자동으로 실행할 수 있습니다.

// hooks/hooks.json
{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "echo '파일 수정 전 검증 실행'",
        "timeout": 30
      }]
    }
  ]
}

사용 가능한 이벤트: PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification

MCP 서버 (외부 도구 연결)

MCP(Model Context Protocol)는 Claude Code를 외부 도구/서비스와 연결하는 표준 프로토콜입니다. Claude Code MCP 도구 검색 가이드에서 기본 개념을 확인할 수 있습니다.

// .mcp.json
{
  "mcpServers": {
    "my-database": {
      "command": "node",
      "args": ["./servers/db-server.js"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

실전 예제: 코드 리뷰 플러그인 만들기

실제로 처음부터 끝까지 만들어 보겠습니다. 간단한 코드 리뷰 플러그인입니다.

Step 1. 디렉토리 생성

mkdir -p my-review-plugin/.claude-plugin
mkdir -p my-review-plugin/commands
mkdir -p my-review-plugin/agents

Step 2. 매니페스트 작성

// my-review-plugin/.claude-plugin/plugin.json
{ "name": "my-review-plugin" }

Step 3. 에이전트 정의

# my-review-plugin/agents/reviewer.md
---
name: reviewer
model: sonnet
color: blue
description: >
  Use this agent when reviewing code quality.
  <example>
  user: "코드 리뷰해줘"
  assistant: "리뷰를 시작합니다."
  <commentary>Review request triggers this agent.</commentary>
  </example>
tools: ["Read", "Grep", "Glob"]
---

You are a code reviewer. Check for bugs, security issues, and suggest improvements.

Step 4. 테스트

# 설치 없이 즉시 테스트
claude --plugin-dir ./my-review-plugin

이 명령어로 Claude Code가 플러그인을 로드한 상태로 시작합니다. “코드 리뷰해줘”라고 입력하면 reviewer 에이전트가 자동 활성화되는 것을 확인할 수 있습니다.

[IMAGE: Claude Code 플러그인 테스트 실행 화면]

정리: 나만의 AI 개발 환경 구축하기

제 경험상, Claude Code 플러그인을 제대로 활용하기 시작하면 개발 생산성이 체감 2배 이상 올라갑니다. 특히 팀에서 코딩 표준을 스킬로 정의하고, 리뷰를 에이전트로 자동화하고, 배포 전 검증을 훅으로 걸어두면, AI가 팀원처럼 동작하는 환경이 만들어집니다. AI 코딩 도구의 다음 단계는 단순 코드 생성이 아니라, 이런 맞춤형 AI 워크플로우 구축입니다.