Claude Code 완전 정복 가이드 Part 4: Plugins & Marketplace - 재사용 가능한 확장 패키지

이 글은 Claude Opus 4.5 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

예상 소요 시간: 1시간 난이도: ⭐⭐⭐ 사전 요구사항: Part 1, 2, 3 완료 Claude Code 버전: 2.1.x (VSCode Native Plugin Management 지원)

1. Plugin이란 무엇인가?#

1.1 Skills vs Commands vs Plugins vs Subagents 개념 정리#

Claude Code의 확장 시스템은 여러 요소로 구성됩니다. 각각의 역할을 명확히 이해해야 합니다:

💡 Claude Code 2.1+ 업데이트:

• VSCode Native Plugin Management: VS Code 확장에서 플러그인을 직접 탐색하고 관리할 수 있습니다.
• Task Management System: 의존성 추적이 포함된 새로운 태스크 관리 시스템이 추가되었습니다.
• Anthropic 공식 Marketplace: anthropics/claude-code 저장소에 공식 플러그인 마켓플레이스가 포함되어 있습니다.

flowchart TB
    subgraph ExtSystem["Claude Code 확장 시스템 전체 구조"]
        direction TB

        subgraph Components["구성 요소"]
            direction LR
            Skills["🧠 Skills"]
            Commands["⌨️ Commands"]
            Subagents["👨‍💼 Subagents"]
            Plugins["📦 Plugins"]
        end

        subgraph Features["특징"]
            direction LR
            SK_F["자동 호출<br/>참조 지식<br/><br/>'레시피북'"]
            CMD_F["수동 호출<br/>/command<br/><br/>'단축키'"]
            SA_F["위임 실행<br/>격리 컨텍스트<br/><br/>'전문가'"]
            PL_F["배포 패키지<br/>(컨테이너)<br/><br/>'도구상자'"]
        end

        Skills --> SK_F
        Commands --> CMD_F
        Subagents --> SA_F
        Plugins --> PL_F

        subgraph PluginContents["Plugin이 포함할 수 있는 것"]
            direction LR
            P_Skills["Skills"]
            P_Commands["Commands"]
            P_Subagent["Subagent"]
            P_Hooks["Hooks"]
            P_MCP["MCP"]
        end
    end

    style Skills fill:#c8e6c9,color:#000000
    style Commands fill:#bbdefb,color:#000000
    style Subagents fill:#fff9c4,color:#000000
    style Plugins fill:#ffccbc,color:#000000
    style SK_F fill:#e8f5e9,color:#000000
    style CMD_F fill:#e3f2fd,color:#000000
    style SA_F fill:#fffde7,color:#000000
    style PL_F fill:#fbe9e7,color:#000000
    style PluginContents fill:#f5f5f5,color:#000000

1.2 각 요소 상세 비교#

1.3 Plugin이 해결하는 문제#

flowchart TB
    subgraph Before["❌ Plugin 등장 이전"]
        Q["'팀원 A의 Claude Code 설정을<br/>팀원 B에게 공유하려면?'"]
        B1["1. Skills 폴더 복사<br/>2. Commands 폴더 복사<br/>3. Agents 폴더 복사<br/>4. 설정 파일 수정<br/>5. 버전 관리 별도<br/>6. 업데이트 수동 반영"]
        BR["→ 복잡하고 오류 발생 가능성 높음"]
    end

    subgraph After["✅ Plugin 등장 이후"]
        A1["/plugin marketplace add my-team/our-plugins"]
        A2["/plugin install our-coding-standards@our-plugins"]
        AR["→ 버전 관리, 자동 업데이트,<br/>의존성 해결 모두 자동"]
    end

    Before --> After

    style Before fill:#ffcdd2,color:#000000
    style After fill:#c8e6c9,color:#000000
    style Q fill:#ef9a9a,color:#000000
    style BR fill:#ef9a9a,color:#000000
    style A1 fill:#a5d6a7,color:#000000
    style A2 fill:#a5d6a7,color:#000000
    style AR fill:#a5d6a7,color:#000000

2. Marketplace 시스템 이해#

2.1 Marketplace란?#

Marketplace는 Plugin들의 카탈로그입니다. Plugin을 검색하고 설치할 수 있는 저장소입니다.

flowchart TB
    subgraph MarketplaceStructure["🏪 Marketplace 구조"]
        direction TB

        subgraph Official["anthropics/claude-plugins-official"]
            O1["• Anthropic이 관리<br/>• 품질/보안 검증됨<br/>• Claude Code 시작 시 자동 사용 가능"]
        end

        Official --> Community
        Official --> Private

        subgraph Community["Community Marketplaces"]
            C1["• VoltAgent<br/>• obra/superpowers<br/>• 개인 개발자들"]
        end

        subgraph Private["Private Marketplaces"]
            P1["• 회사 내부용<br/>• 팀 전용<br/>• 비공개 GitHub"]
        end

        Note["📌 분산형 구조: 누구나 Marketplace를 만들 수 있음<br/>Anthropic 승인 불필요"]
    end

    style Official fill:#bbdefb,color:#000000
    style Community fill:#c8e6c9,color:#000000
    style Private fill:#fff9c4,color:#000000
    style Note fill:#e0e0e0,color:#000000

2.2 분산형 구조의 장점#

• 누구나 생성 가능: GitHub repo만 있으면 Marketplace 운영 가능
• 승인 불필요: 중앙 검증 없이 자유롭게 배포
• 버전 관리: Git을 통한 자연스러운 버전 관리
• 자동 업데이트: Marketplace 업데이트 시 설치된 Plugin도 갱신

⚠️ 주의: 커뮤니티 Marketplace의 Plugin은 직접 코드를 검토한 후 설치하세요.

3. Marketplace 사용하기#

3.1 Marketplace 추가#

# Claude Code 실행 후

# 1. Official Marketplace (자동으로 사용 가능하지만 명시적 추가도 가능)
/plugin marketplace add anthropics/claude-plugins-official

# 2. Community Marketplace 추가
/plugin marketplace add VoltAgent/awesome-claude-code-subagents

# 3. 다른 커뮤니티 Marketplace
/plugin marketplace add obra/superpowers-marketplace

# 4. 로컬 Marketplace (개발용)
/plugin marketplace add /path/to/local/marketplace

3.2 플러그인 탐색#

# 인터랙티브 UI 열기
/plugin

# Tab으로 탭 전환:
# - Discover: 사용 가능한 플러그인 탐색
# - Installed: 설치된 플러그인 관리
# - Marketplaces: 마켓플레이스 관리
# - Errors: 로딩 오류 확인

3.3 플러그인 설치#

# 인터랙티브 UI에서 설치
/plugin
# → Discover 탭에서 원하는 플러그인 선택
# → 설치 범위 선택 (user/project)

# CLI로 직접 설치
/plugin install golang-pro@voltagent
/plugin install commit-commands@claude-plugin-directory

# 설치 범위 지정
/plugin install my-plugin@marketplace --scope user     # 전역
/plugin install my-plugin@marketplace --scope project  # 프로젝트만

3.4 설치 범위 (Scope) 이해#

flowchart LR
    subgraph ScopeGuide["🎯 Scope 선택 가이드"]
        direction TB

        Q1["이 플러그인을 모든 프로젝트에서<br/>사용하고 싶다"] --> A1["--scope user"]

        Q2["이 프로젝트에서만 사용하고,<br/>팀원도 사용하게 하고 싶다"] --> A2["--scope project<br/>(+ Git 커밋)"]

        Q3["테스트 목적으로만<br/>설치하고 싶다"] --> A3["--scope project<br/>(나중에 삭제)"]
    end

    style Q1 fill:#e3f2fd,color:#000000
    style Q2 fill:#e3f2fd,color:#000000
    style Q3 fill:#e3f2fd,color:#000000
    style A1 fill:#c8e6c9,color:#000000
    style A2 fill:#c8e6c9,color:#000000
    style A3 fill:#fff9c4,color:#000000

4. 유용한 커뮤니티 플러그인 소개#

4.1 Anthropic 공식 Skills (anthropics/skills)#

Marketplace: anthropics/skills (⭐ 37.5k)

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

4.2 Claude Code 공식 플러그인#

Marketplace: anthropics/claude-code (⭐ 55k)

공식 저장소에 포함된 플러그인들:

4.3 인기 커뮤니티 플러그인 (2026년 1월 기준)#

4.4 Skills Marketplace (SkillsMP)#

커뮤니티 Skills 검색 플랫폼: skillsmp.com

• SKILL.md 표준 호환 (Claude Code, OpenAI Codex CLI 지원)
• marketplace.json 포함 시 원클릭 설치 지원
• 최소 2 stars 품질 필터링

5. ⭐ 커뮤니티 플러그인과 나만의 규칙 조합하기#

5.1 문제 상황#

VoltAgent의 golang-pro와 같은 커뮤니티 Subagent를 설치했습니다. 하지만:

flowchart TB
    subgraph GolangPro["📦 golang-pro 내용"]
        direction TB

        subgraph Included["✅ 포함된 것"]
            I1["Go 언어 일반 베스트 프랙티스"]
            I2["동시성 패턴 (goroutine, channel)"]
            I3["표준 라이브러리 활용"]
            I4["일반적인 프로젝트 구조"]
        end

        subgraph Missing["⚠️ 하지만 부족한 것"]
            M1["우리 팀의 특정 네이밍 컨벤션"]
            M2["우리가 사용하는 특정 프레임워크 규칙<br/>(예: Gin, Echo)"]
            M3["우리 회사의 에러 코드 체계"]
            M4["프로젝트 특화 패턴"]
        end
    end

    style Included fill:#c8e6c9,color:#000000
    style Missing fill:#ffcdd2,color:#000000
    style I1 fill:#e8f5e9,color:#000000
    style I2 fill:#e8f5e9,color:#000000
    style I3 fill:#e8f5e9,color:#000000
    style I4 fill:#e8f5e9,color:#000000
    style M1 fill:#ffebee,color:#000000
    style M2 fill:#ffebee,color:#000000
    style M3 fill:#ffebee,color:#000000
    style M4 fill:#ffebee,color:#000000

5.2 해결책: 3-Layer Stacking 전략#

커뮤니티 플러그인을 기반으로 하고, 그 위에 나만의 규칙을 레이어링합니다:

flowchart TD 
    subgraph Stacking["🎂 3-Layer Stacking 전략"]
        subgraph Layer3["L3: 프로젝트별 CLAUDE.md"]
            L3_1["• 이 프로젝트만의 특수한 규칙"]
            L3_2["• 예: 'internal/ 패키지 사용 금지'"]
            L3_3["• 예: 'Kafka 토픽 네이밍: {service}.{event}.{version}'"]
        end

        subgraph Layer2["L2: 나만의 Custom Skill"]
            L2_1["• ~/.claude/skills/my-go-conventions/SKILL.md"]
            L2_2["• 상세한 네이밍 컨벤션"]
            L2_3["• 우리 팀의 에러 핸들링 패턴"]
            L2_4["• 특정 프레임워크 사용 규칙"]
        end

        subgraph Layer1["L1: 커뮤니티 Subagent"]
            L1_1["• 일반적인 Go 베스트 프랙티스"]
            L1_2["• 동시성 패턴, 표준 라이브러리"]
            L1_3["• 커뮤니티에서 검증된 지식"]
        end

        Layer1 -->|"보완"| Layer2
        Layer2 -->|"보완"| Layer3
    end

    style Layer3 fill:#ffccbc,color:#000000
    style Layer2 fill:#fff9c4,color:#000000
    style Layer1 fill:#c8e6c9,color:#000000
    style L3_1 fill:#fbe9e7,color:#000000
    style L3_2 fill:#fbe9e7,color:#000000
    style L3_3 fill:#fbe9e7,color:#000000
    style L2_1 fill:#fffde7,color:#000000
    style L2_2 fill:#fffde7,color:#000000
    style L2_3 fill:#fffde7,color:#000000
    style L2_4 fill:#fffde7,color:#000000
    style L1_1 fill:#e8f5e9,color:#000000
    style L1_2 fill:#e8f5e9,color:#000000
    style L1_3 fill:#e8f5e9,color:#000000

5.3 실습: VoltAgent/golang-pro + 나만의 Go 컨벤션 조합#

Step 1: 커뮤니티 플러그인 설치

/plugin marketplace add VoltAgent/awesome-claude-code-subagents
/plugin install golang-pro@voltagent --scope user

Step 2: 나만의 Custom Skill 생성 (Layer 2)

mkdir -p ~/.claude/skills/my-go-conventions

~/.claude/skills/my-go-conventions/SKILL.md:

---
name: my-go-conventions
description: 우리 팀의 Go 코딩 컨벤션. Go 코드 작성, 리뷰, 수정 시 사용.
             golang-pro subagent와 함께 사용됨.
---

# 우리 팀의 Go 코딩 컨벤션

이 Skill은 golang-pro의 일반적인 베스트 프랙티스 위에
우리 팀만의 규칙을 추가합니다.

## 네이밍 컨벤션 (팀 규칙)

### 패키지 명명

// ✅ 좋은 예
package userservice
package paymentgateway

// ❌ 나쁜 예
package user_service    // 언더스코어 금지
package userService     // camelCase 금지

### 인터페이스 명명

// 단일 메서드 인터페이스: -er 접미사
type Reader interface { Read() }
type Processor interface { Process() }

// 다중 메서드 인터페이스: 역할을 나타내는 명사
type UserRepository interface { ... }
type PaymentGateway interface { ... }

### 변수 명명

// 로컬 변수: 짧고 명확하게
for i, u := range users { }  // u for user

// 패키지 변수: 명확하게
var DefaultTimeout = 30 * time.Second

## 에러 처리 (팀 규칙)

### 에러 코드 체계

// 우리 팀의 에러 코드 형식: {도메인}{숫자}
// USR001 - 사용자 도메인, 001번 에러
var (
    ErrUserNotFound     = NewError("USR001", "user not found")
    ErrInvalidEmail     = NewError("USR002", "invalid email format")
    ErrPaymentFailed    = NewError("PAY001", "payment processing failed")
)

### 에러 래핑 규칙

// 항상 컨텍스트 추가 + 에러 코드 포함
if err != nil {
    return fmt.Errorf("[USR001] failed to get user %d: %w", userID, err)
}

## 프로젝트 구조 (팀 규칙)

cmd/
├── api/            # REST API 서버
└── worker/         # 백그라운드 워커

internal/
├── domain/         # 도메인 모델, 비즈니스 로직
├── port/           # 인터페이스 정의 (Hexagonal)
│   ├── in/         # 인바운드 포트 (Use Cases)
│   └── out/        # 아웃바운드 포트 (Repositories)
├── adapter/        # 포트 구현체
│   ├── in/         # 인바운드 어댑터 (HTTP handlers)
│   └── out/        # 아웃바운드 어댑터 (DB, External API)
└── config/         # 설정

pkg/                # 외부 공개 패키지 (재사용 가능)

## Gin 프레임워크 규칙 (팀 규칙)

### 핸들러 구조

// 핸들러는 adapter/in/http/ 에 위치
type UserHandler struct {
    userService port.UserService
}

func NewUserHandler(us port.UserService) *UserHandler {
    return &UserHandler{userService: us}
}

// 메서드명: HTTP메서드 + 리소스
func (h *UserHandler) GetUser(c *gin.Context) { ... }
func (h *UserHandler) CreateUser(c *gin.Context) { ... }

### 응답 형식

// 성공 응답
c.JSON(http.StatusOK, gin.H{
    "success": true,
    "data":    result,
})

// 에러 응답
c.JSON(http.StatusBadRequest, gin.H{
    "success": false,
    "error": gin.H{
        "code":    "USR001",
        "message": "user not found",
    },
})

## 테스트 규칙 (팀 규칙)

### Mock 생성

# mockgen 사용
mockgen -source=internal/port/out/user_repository.go \
        -destination=internal/port/out/mock/user_repository_mock.go

### 테스트 파일 위치
- 유닛 테스트: 같은 패키지에 `_test.go`
- 통합 테스트: `test/integration/`

Step 3: 프로젝트별 CLAUDE.md에 특수 규칙 추가 (Layer 3)

# User Service

Go 기반 사용자 관리 마이크로서비스

## 빌드 및 테스트
- 빌드: `go build ./cmd/api`
- 테스트: `go test ./...`
- 린트: `golangci-lint run`

## 이 프로젝트만의 특수 규칙

IMPORTANT: 다음 규칙은 이 프로젝트에만 적용됩니다.

1. internal/legacy/ 패키지는 수정하지 마세요 (deprecated 예정)
2. Kafka 토픽 네이밍: `user-service.{event}.v1`
   - 예: `user-service.user-created.v1`
3. Redis 키 프리픽스: `user-svc:`
4. 모든 API는 `/api/v1/` 프리픽스 사용

## 환경별 설정
- 로컬: `config/local.yaml`
- 테스트: `config/test.yaml`
- 프로덕션: 환경 변수로 주입

5.4 레이어별 역할 분담 정리#

5.5 판단 기준: 어디에 넣을까?#

flowchart TD
    Title["🤔 '이 규칙은 어디에 작성해야 할까?'"]

    Title --> Q1{"Q1: 언어 자체의<br/>일반적인 규칙인가?"}

    Q1 -->|Yes| A1["커뮤니티 플러그인이 이미<br/>포함하고 있을 가능성 높음<br/>(추가 작성 불필요)"]

    Q1 -->|No| Q2{"Q2: 모든 프로젝트에 적용되는<br/>우리 팀/회사의 규칙인가?"}

    Q2 -->|Yes| A2["Layer 2: Custom Skill로 작성<br/>~/.claude/skills/my-conventions/"]

    Q2 -->|No| Q3{"Q3: 이 특정 프로젝트에만<br/>적용되는 규칙인가?"}

    Q3 -->|Yes| A3["Layer 3: 프로젝트<br/>CLAUDE.md에 작성"]

    style Title fill:#e3f2fd,color:#000000
    style Q1 fill:#fff9c4,color:#000000
    style Q2 fill:#fff9c4,color:#000000
    style Q3 fill:#fff9c4,color:#000000
    style A1 fill:#e0e0e0,color:#000000
    style A2 fill:#c8e6c9,color:#000000
    style A3 fill:#ffccbc,color:#000000

6. 플러그인 관리#

6.1 설치된 플러그인 확인 및 비활성화#

# 설치된 플러그인 목록
/plugin
# → Installed 탭으로 이동

# 플러그인 비활성화 (삭제 없이)
/plugin disable golang-pro@voltagent

# 플러그인 활성화
/plugin enable golang-pro@voltagent

# 플러그인 삭제
/plugin uninstall golang-pro@voltagent

6.2 자동 업데이트 설정#

# 마켓플레이스 자동 업데이트 활성화
/plugin marketplace update voltagent --auto-update

# 수동 업데이트
/plugin marketplace update voltagent

6.3 Marketplace 제거 시 주의사항#

⚠️ Marketplace를 제거하면 해당 Marketplace에서 설치한 모든 플러그인도 삭제됩니다.

# 주의: 이 명령은 voltagent에서 설치한 모든 플러그인을 삭제합니다
/plugin marketplace remove voltagent

7. 실습: 프로젝트에 유용한 플러그인 설치하고 활용하기#

7.1 시나리오#

새로운 Go 마이크로서비스 프로젝트를 시작합니다. 다음 플러그인들을 조합하여 설정합니다.

7.2 Step-by-Step#

Step 1: Marketplace 추가

claude
/plugin marketplace add VoltAgent/awesome-claude-code-subagents
/plugin marketplace add anthropics/skills

Step 2: 필요한 플러그인 설치

# Language specialist
/plugin install golang-pro@voltagent --scope user

# Code quality
/plugin install code-reviewer@voltagent --scope user

# Documentation
/plugin install docx@anthropics --scope user

Step 3: Custom Skill 생성

앞서 만든 my-go-conventions Skill을 ~/.claude/skills/에 생성합니다.

Step 4: 프로젝트 CLAUDE.md 작성

프로젝트 루트에 프로젝트 특화 규칙을 담은 CLAUDE.md를 작성합니다.

Step 5: 동작 확인

사용자: "새로운 UserService 만들어줘"

Claude의 동작:
1. CLAUDE.md 로드 (프로젝트 기본 정보)
2. my-go-conventions Skill 자동 활성화 (Go 코드 작성 감지)
3. golang-pro Subagent의 지식 참조 가능
4. 3-Layer의 규칙을 모두 적용하여 코드 생성

8. 정리#

이번 파트에서 배운 것#

1. Plugin은 배포 패키지: Skills, Commands, Subagents, Hooks를 묶어서 공유
2. Marketplace는 분산형: 누구나 만들 수 있고, 승인 불필요
3. 설치 범위: user (전역) vs project (프로젝트)
4. 3-Layer Stacking: 커뮤니티 + Custom Skill + 프로젝트 CLAUDE.md 조합

핵심 전략#

커뮤니티 플러그인을 기반으로, 팀 규칙을 Skill로, 프로젝트 규칙을 CLAUDE.md로 레이어링하세요.

다음 파트 예고#

이제 나만의 Plugin을 만들어 GitHub으로 배포하는 방법을 배웁니다. Part 5에서는 Custom Marketplace를 구축합니다.

📚 참고 자료#

• Claude Code Plugins 공식 문서
• VoltAgent Subagents Collection
• Anthropic Skills Repository
• Skills vs Subagents 비교
• Claude Code Plugin 워크플로우

이전: Part 3: Skills 시스템 다음: Part 5: 나만의 Plugin Marketplace 만들기