Claude Code 플러그인 완벽 가이드: Skills, Agents, Hooks로 워크플로우 확장하기

Claude Code를 프로젝트에 도입하고 나면, 자연스럽게 .claude/ 디렉토리에 커스텀 명령어와 설정 파일이 쌓이기 시작합니다. CLAUDE.md에 프로젝트 컨텍스트를 적고, commands/ 폴더에 자주 쓰는 워크플로우를 정의하고, settings.json으로 권한을 관리하죠. 잘 동작합니다 — 한 프로젝트 안에서는요.

문제는 이 설정을 다른 프로젝트에 가져가려 할 때 시작됩니다. 팀원에게 공유하려면 파일을 복사해야 하고, 버전 관리도 안 되고, 다른 팀의 설정과 이름이 충돌하기도 합니다. 회사 전체에 코드 리뷰 표준을 배포하고 싶다면? 각 저장소마다 .claude/ 디렉토리를 수동으로 동기화해야 합니다.

2025년 10월, Anthropic은 이 문제에 대한 답으로 플러그인 시스템 을 출시했습니다. Skills, Agents, Hooks, MCP, LSP를 하나의 패키지로 묶어 한 줄 명령어로 설치하고, 마켓플레이스를 통해 공유할 수 있는 확장 체계입니다. 이 글에서는 플러그인 시스템의 구조를 이해하고, 직접 만들어 보면서 각 구성 요소를 살펴보겠습니다.

플러그인 시스템 개요

Claude Code 플러그인은 다섯 가지 핵심 구성 요소로 이루어져 있습니다.

• Skills: 슬래시 명령어(/review, /deploy 등)를 정의합니다. Markdown 파일 하나로 Claude에게 특정 작업의 수행 방법을 가르칩니다.
• Agents: 독립적인 컨텍스트 윈도우에서 실행되는 전문 AI 에이전트입니다. 도구 접근, 모델, 권한을 세밀하게 제어할 수 있습니다.
• Hooks: Claude Code의 라이프사이클 이벤트(파일 수정, 도구 실행 등)에 바인딩되는 결정론적 코드입니다. 자동 린트, 위험 명령 차단 같은 작업을 수행합니다.
• MCP Servers: Model Context Protocol 서버를 번들링하여 외부 도구와 연동합니다.
• LSP Servers: Language Server Protocol을 통해 코드 인텔리전스를 추가합니다.

이 모든 것을 .claude-plugin/plugin.json 매니페스트 파일이 하나로 엮어줍니다. 기존 .claude/ 디렉토리의 파편화된 설정 파일들과 비교하면, 플러그인은 패키징, 버전 관리, 네임스페이스 분리, 원클릭 설치 를 제공하는 셈입니다.

실습: 첫 번째 플러그인 만들기

백문이 불여일견입니다. 간단한 플러그인을 직접 만들어보면서 구조를 파악해 보겠습니다. 코드 리뷰 플러그인을 만들어 볼 건데, 먼저 최소한의 골격부터 시작하겠습니다.

디렉토리 구조

mkdir -p code-review-plugin/.claude-plugin
mkdir -p code-review-plugin/skills/review

plugin.json 작성

플러그인의 시작점은 .claude-plugin/plugin.json 입니다. 이 파일이 플러그인의 이름, 설명, 버전을 정의합니다.

{
  "name": "code-review",
  "description": "Automated code review with quality gates",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

name 필드는 단순한 식별자가 아닙니다. 이 값이 스킬의 네임스페이스 접두사로 사용됩니다. 예를 들어 이 플러그인에 review라는 스킬을 만들면, 호출 시 /code-review:review 형태가 됩니다. 다른 플러그인과 이름이 겹칠 걱정이 없죠.

첫 번째 스킬 작성

skills/review/SKILL.md 파일을 생성합니다.

---
name: review
description: Review recent code changes for quality and security
disable-model-invocation: true
allowed-tools: Read, Grep, Glob, Bash
---

Review the latest changes:
1. Run `git diff --cached` to see staged changes
2. Check each modified file for:
   - Naming conventions
   - Error handling
   - Security concerns
3. Provide feedback organized by severity

여기서 주목할 부분이 몇 가지 있습니다.

• disable-model-invocation: true는 Claude가 자동으로 이 스킬을 호출하지 못하게 합니다. 사용자가 /code-review:review를 직접 입력해야만 실행됩니다.
• allowed-tools로 이 스킬이 사용할 수 있는 도구를 제한합니다. 코드 리뷰에는 파일 읽기와 검색만 필요하니, 불필요한 도구 접근을 차단하는 것입니다.

로컬 테스트

작성한 플러그인을 바로 테스트할 수 있습니다.

claude --plugin-dir ./code-review-plugin

Claude Code가 실행되면 /code-review:review를 입력해서 스킬이 동작하는지 확인해 보세요. 이제 이 골격에 Agents와 Hooks를 추가하면서 본격적인 플러그인을 완성해 보겠습니다.

Skills 심층 분석

Skills는 Claude Code에게 특정 작업의 수행 방법을 가르치는 지침서 입니다. YAML frontmatter와 Markdown 본문으로 구성되며, 기존의 commands/ 디렉토리와 통합되었습니다.

동적 인자 활용

스킬의 강력한 기능 중 하나는 $ARGUMENTS를 통한 동적 인자 전달입니다.

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.
1. Read the issue description
2. Implement the fix
3. Write tests
4. Create a commit

/code-review:fix-issue 123을 실행하면 $ARGUMENTS가 123으로 치환됩니다. $ARGUMENTS[0], $ARGUMENTS[1] 형태로 개별 인자에 접근할 수도 있어서, 복잡한 워크플로우도 유연하게 처리할 수 있습니다.

셸 명령어로 동적 컨텍스트 주입

!`<command>` 구문을 사용하면 셸 명령어의 결과를 스킬 내용에 실시간으로 삽입할 수 있습니다. PR 요약 스킬을 예로 들어보겠습니다.

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

Summarize this pull request focusing on:
1. What changed and why
2. Potential risks or concerns
3. Suggested reviewers based on changed areas

context: fork는 이 스킬을 별도의 subagent에서 실행하도록 합니다. PR 요약은 메인 대화 흐름과 독립적으로 처리되어야 하기 때문입니다. agent: Explore는 빠른 읽기 전용 작업에 적합한 빌트인 에이전트를 지정합니다.

주요 frontmatter 옵션 정리

Agents 심층 분석

Skills가 "무엇을 해라"라는 지침이라면, Agents는 "이 전문가에게 맡겨라" 에 가깝습니다. 독립적인 컨텍스트 윈도우에서 실행되기 때문에 메인 대화의 컨텍스트를 오염시키지 않고, 도구 접근과 권한을 세밀하게 제어할 수 있습니다.

코드 리뷰 에이전트 만들기

앞서 만든 플러그인에 전문 리뷰어 에이전트를 추가해 보겠습니다. agents/reviewer.md 파일을 생성합니다.

---
name: reviewer
description: Expert code reviewer. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
memory: project
---

You are a senior code reviewer. When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Provide specific, actionable feedback

Review checklist:
- Code clarity and readability
- Error handling completeness
- Security (no exposed secrets, input validation)
- Test coverage for changed logic

Provide feedback organized by priority:
- Critical issues (must fix before merge)
- Warnings (should address)
- Suggestions (nice to have improvements)

여기서 핵심적인 설정 몇 가지를 짚어보겠습니다.

tools: Read, Grep, Glob, Bash 는 이 에이전트가 사용할 수 있는 도구를 명시적으로 제한합니다. 코드 리뷰어에게 파일 수정 권한(Write, Edit)을 주지 않는 것은 의도적인 선택입니다. 리뷰어는 읽고 분석만 해야 하니까요.

model: sonnet 은 이 에이전트의 모델을 지정합니다. 코드 리뷰처럼 분석 위주 작업에는 Sonnet이 속도와 품질의 균형이 좋습니다. opus, haiku, 또는 전체 모델 ID를 지정할 수도 있습니다.

memory: project 는 에이전트에게 영속적 메모리를 부여합니다. 이 에이전트가 리뷰하면서 발견한 패턴, 컨벤션, 반복되는 이슈를 .claude/agent-memory/reviewer/ 디렉토리에 저장합니다. 세션이 끝나도 학습이 유지되기 때문에, 프로젝트를 오래 사용할수록 리뷰 품질이 높아집니다.

에이전트 호출 방법

에이전트는 세 가지 방식으로 호출할 수 있습니다.

# 1. 자연어로 요청
"Use the reviewer agent to check my latest changes"

# 2. @-멘션
@"reviewer (agent)" look at the auth module changes

# 3. 세션 전체를 에이전트 모드로 실행
claude --agent reviewer

자연어 요청이 가장 자연스럽습니다. Claude가 description 필드를 보고 적절한 시점에 에이전트를 자동으로 위임하기도 합니다. description을 구체적으로 작성하는 것이 중요한 이유입니다.

에이전트 격리와 보안

에이전트의 가장 중요한 특성은 격리 입니다. 각 에이전트는 독립적인 컨텍스트 윈도우에서 실행되며, 다음과 같은 보안 계층을 제공합니다.

• 도구 제한 (tools/disallowedTools): 에이전트가 접근할 수 있는 도구를 명시적으로 제한
• 권한 모드 (permissionMode): plan 모드로 설정하면 읽기 전용으로만 동작
• Git worktree 격리 (isolation: worktree): 별도의 git worktree에서 실행하여 메인 브랜치를 보호

이런 격리 덕분에 데이터베이스를 다루는 에이전트에 읽기 전용 제약을 걸거나, 테스트 에이전트가 프로덕션 코드를 수정하지 못하게 막을 수 있습니다.

Hooks 심층 분석

Hooks는 Claude Code의 라이프사이클 이벤트에 결정론적 코드 를 바인딩하는 메커니즘입니다. "Claude가 파일을 수정할 때마다 린터를 돌려라", "위험한 셸 명령은 차단해라" 같은 자동화 규칙을 정의합니다.

이것이 Skills나 Agents와 다른 점은 LLM이 아닌 코드 가 실행된다는 것입니다. 결과가 매번 동일하고, 추론 비용이 들지 않습니다.

훅 이벤트

Claude Code는 20개 이상의 라이프사이클 이벤트를 제공합니다. 가장 자주 사용되는 이벤트를 살펴보겠습니다.

"차단 가능"이 예인 이벤트는 훅에서 도구 실행을 막거나 프롬프트를 거부할 수 있다는 뜻입니다. PreToolUse가 가장 강력한 이벤트인데, 위험한 명령어를 실행 전에 차단할 수 있기 때문입니다.

자동 린트 훅 (PostToolUse)

파일을 수정할 때마다 자동으로 린터를 실행하는 훅을 만들어 보겠습니다. hooks/hooks.json 파일을 생성합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs eslint --fix 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

matcher는 정규표현식으로, Write 또는 Edit 도구가 실행된 후에만 훅이 동작합니다. jq로 수정된 파일 경로를 추출하고, eslint --fix로 자동 교정합니다. || true를 붙인 이유는 린트 에러가 있더라도 훅 자체는 실패하지 않게 하기 위해서입니다.

위험 명령 차단 훅 (PreToolUse)

더 실용적인 예시를 하나 더 살펴보겠습니다. rm -rf 같은 파괴적인 명령어를 차단하는 훅입니다.

#!/bin/bash
# scripts/block-destructive.sh
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -qE 'rm -rf|:(){:|:}|DROP TABLE|TRUNCATE'; then
  jq -n '{
    "hookSpecificOutput": {
      "hookEventName": "PreToolUse",
      "permissionDecision": "deny",
      "permissionDecisionReason": "Destructive command blocked by safety hook"
    }
  }'
fi
exit 0

이 스크립트를 hooks.json에서 PreToolUse 이벤트의 Bash 도구 matcher에 연결하면, Claude가 위험한 셸 명령어를 실행하려 할 때 자동으로 차단됩니다.

훅의 exit code도 중요합니다. 0이면 성공(stdout JSON 파싱), 2이면 차단(stderr를 에러로 표시), 그 외는 비차단 에러로 verbose 모드에서만 표시됩니다.

4가지 훅 타입

훅은 네 가지 타입을 지원합니다.

command 타입이 가장 자주 쓰이지만, prompt 타입도 흥미롭습니다. LLM에게 "이 코드 변경이 보안 규칙을 위반하는지 한 줄로 판단해라"라고 물어보는 식의 가벼운 AI 검증을 추가할 수 있습니다.

실전 활용: 코드 리뷰 플러그인 완성

지금까지 만든 Skills, Agents, Hooks를 모두 합쳐서 완성된 코드 리뷰 플러그인의 구조를 확인해 보겠습니다.

code-review-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── review/
│       └── SKILL.md
├── agents/
│   └── reviewer.md
├── hooks/
│   └── hooks.json
└── scripts/
    └── block-destructive.sh

이 플러그인을 설치하면 세 가지가 동시에 활성화됩니다.

1. /code-review:review 스킬로 온디맨드 코드 리뷰 실행
2. reviewer 에이전트가 코드 변경 시 자동으로 리뷰 수행 (영속적 메모리로 학습 축적)
3. 파일 수정 시 자동 린트, 위험 명령어 차단

각 구성 요소가 독립적으로 동작하면서도 하나의 패키지로 관리되는 것이 플러그인 시스템의 핵심 가치입니다. 팀원에게 공유할 때는 이 디렉토리를 GitHub에 올리고, 마켓플레이스에 등록하면 됩니다.

플러그인 설치와 관리

직접 만드는 것 외에도, 이미 만들어진 플러그인을 설치해서 사용할 수 있습니다.

# 공식 마켓플레이스에서 설치
/plugin install github@claude-plugins-official

# GitHub 마켓플레이스 추가 후 설치
/plugin marketplace add anthropics/claude-code
/plugin install commit-commands@anthropics-claude-code

# 로컬 플러그인 테스트
claude --plugin-dir ./my-plugin

# 플러그인 관리
/plugin                           # 대화형 플러그인 매니저
/plugin uninstall <name>@<market> # 제거
/plugin disable <name>@<market>   # 비활성화
/reload-plugins                   # 변경사항 즉시 반영

플러그인은 세 가지 범위(scope)로 설치할 수 있습니다. User 범위(~/.claude/settings.json)는 모든 프로젝트에 적용되고, Project 범위(.claude/settings.json)는 저장소 협업자와 공유되며, Local 범위(.claude/settings.local.json)는 개인용으로 공유되지 않습니다. 팀 표준 플러그인은 Project 범위로, 개인 생산성 플러그인은 User 범위로 설치하는 것을 권장합니다.

생태계 현황

2026년 3월 현재, 공식 마켓플레이스에 36개 이상의 플러그인이 등록되어 있습니다. 몇 가지 주요 카테고리를 살펴보겠습니다.

Code Intelligence: TypeScript, Python, Rust, Go 등 11개 언어의 LSP 플러그인이 제공됩니다. 설치하면 Claude Code가 해당 언어의 타입 정보, 정의 이동, 참조 찾기 등을 활용할 수 있습니다.

External Integrations: GitHub, GitLab, Jira, Linear, Notion, Slack, Vercel, Supabase 등 개발팀이 자주 쓰는 서비스와의 연동을 제공합니다.

Development Workflows: commit-commands, pr-review-toolkit 등 개발 워크플로우를 자동화하는 플러그인입니다.

커뮤니티에서도 흥미로운 플러그인이 나오고 있습니다. context-mode 는 대용량 출력을 샌드박스 처리하여 컨텍스트 소비를 98%까지 줄여주고, claude-mem 은 세션 간 컨텍스트를 자동으로 보존합니다. Composio의 connect-apps 는 500개 이상의 외부 앱과 연동을 제공합니다.

아직 초기 단계이기 때문에 플러그인 품질의 편차가 있는 것은 사실입니다. 설치 전에 README를 확인하고, 신뢰할 수 있는 소스의 플러그인을 사용하는 것이 중요합니다. 플러그인은 사용자 권한으로 임의 코드를 실행할 수 있다는 점을 기억해야 합니다.

경쟁 도구와의 비교

AI 코딩 도구의 확장 시스템은 각각 다른 철학을 가지고 있습니다. Claude Code, Cursor, GitHub Copilot의 접근 방식을 비교해 보겠습니다.

Claude Code 는 Agent-first 접근을 취합니다. Skills, Agents, Hooks를 조합하여 작업을 위임하고, 20개 이상의 라이프사이클 훅으로 세밀한 제어가 가능합니다. CLI 기반이라 터미널, VS Code, JetBrains 등 다양한 환경에서 동작합니다.

Cursor 는 IDE-first 접근입니다. VS Code 마켓플레이스 기반의 확장과 .cursorrules 파일로 커스터마이징합니다. GUI 기반이라 진입 장벽이 낮지만, Claude Code 수준의 라이프사이클 훅 시스템은 제공하지 않습니다. MCP를 지원하지만 40개 도구 제한이 있습니다.

GitHub Copilot 역시 IDE-first이며, Extensions와 .agent.md 파일로 확장합니다. GitHub MCP가 기본 포함되어 GitHub 생태계와의 통합이 강점이지만, 이벤트 훅 시스템은 제한적입니다.

Claude Code 플러그인 시스템의 차별점을 정리하면 다음과 같습니다.

1. 훅 시스템의 깊이: 20개 이상의 라이프사이클 이벤트에 결정론적 코드를 바인딩할 수 있습니다. Cursor나 Copilot에는 이에 상응하는 시스템이 없습니다.
2. 에이전트 격리: 도구 제한, 권한 모드, 독립 컨텍스트 윈도우, git worktree 격리까지 다층 보안을 제공합니다.
3. 영속적 메모리: 에이전트가 세션을 넘어 학습을 축적하는 메모리 시스템은 Claude Code만의 고유한 기능입니다.
4. 조합 가능성: 스킬에서 에이전트를 호출하고, 에이전트에 훅을 걸고, 훅에서 MCP를 사용하는 레이어드 구조가 가능합니다.

반면 CLI 기반이라 Cursor의 GUI 확장 설치에 비해 진입 장벽이 높을 수 있다 는 점, 마켓플레이스가 아직 초기 단계 라는 점은 고려해야 합니다.

실용적 팁

플러그인 시스템을 실무에 적용할 때 알아두면 좋은 팁들을 정리했습니다.

기존 설정에서 마이그레이션

이미 .claude/commands/에 커스텀 명령어를 사용하고 있다면, 점진적으로 마이그레이션할 수 있습니다. 기존 commands/deploy.md는 skills/deploy/SKILL.md와 동일하게 동작합니다. 먼저 skills 디렉토리로 파일을 옮기고, plugin.json을 추가하면 플러그인으로 전환됩니다.

네임스페이스 전략

플러그인 이름이 네임스페이스가 되므로, 너무 길면 사용이 불편합니다. /my-awesome-code-review-toolkit:review 같은 이름 대신 /cr:review 처럼 짧고 직관적인 이름을 선택하세요.

에이전트에 적절한 권한 부여

에이전트를 만들 때 가장 흔한 실수는 모든 도구 접근을 허용하는 것입니다. 최소 권한 원칙 을 따르세요. 읽기 전용 분석 에이전트에는 Read, Grep, Glob만, 코드 수정 에이전트에는 Read, Write, Edit, Bash를 부여하는 식입니다.

보안 주의사항

플러그인은 사용자 권한으로 임의 코드를 실행할 수 있습니다. 공식 마켓플레이스나 신뢰할 수 있는 소스의 플러그인만 설치하고, 설치 전에 hooks.json과 스크립트 내용을 반드시 검토하세요. 플러그인의 subagent에서는 hooks, mcpServers, permissionMode 사용이 제한되어 있는데, 이는 보안을 위한 의도적인 설계입니다.

마무리

Claude Code 플러그인 시스템은 .claude/ 디렉토리의 수동 관리를 넘어, AI 코딩 워크플로우를 패키징하고, 공유하고, 자동화하는 체계적인 방법을 제공합니다. Skills로 반복 작업을 명령어화하고, Agents로 전문적인 분석을 위임하며, Hooks로 품질 게이트를 자동화할 수 있습니다.

이미 Claude Code를 사용하고 있다면, 먼저 자주 반복하는 작업을 Skill 하나로 만들어 보는 것을 추천합니다. 그다음 팀에서 공유할 가치가 있는 것들을 플러그인으로 묶어보세요. 마켓플레이스도 둘러보면서 이미 누군가 만들어 놓은 플러그인이 있는지 확인하는 것도 좋습니다.

CLI 기반 도구에 익숙한 개발자, 팀 워크플로우를 표준화하고 싶은 테크 리드, 그리고 AI 코딩 도구의 확장 가능성에 관심 있는 분들에게 플러그인 시스템은 Claude Code를 한 단계 더 활용할 수 있는 열쇠가 될 것입니다.