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저장소에 공식 플러그인 마켓플레이스가 포함되어 있습니다.
┌─────────────────────────────────────────────────────────────────────────────┐
│ Claude Code 확장 시스템 전체 구조 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Skills │ │ Commands │ │ Subagents │ │ Plugins │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 자동 호출 │ │ 수동 호출 │ │ 위임 실행 │ │ 배포 패키지 │ │
│ │ 참조 지식 │ │ /command │ │ 격리 컨텍스트│ │ (컨테이너) │ │
│ │ │ │ │ │ │ │ │ │
│ │ "레시피북" │ │ "단축키" │ │ "전문가" │ │ "도구상자" │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ Plugin이 포함할 수 있는 것 │
│ ┌──────────────────────────────────────┐ │
│ │ ┌────────┐ ┌────────┐ ┌────────┐ │ │
│ │ │ Skills │ │Commands│ │Subagent│ │ │
│ │ └────────┘ └────────┘ └────────┘ │ │
│ │ ┌────────┐ ┌────────┐ │ │
│ │ │ Hooks │ │ MCP │ │ │
│ │ └────────┘ └────────┘ │ │
│ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
1.2 각 요소 상세 비교#
| 요소 | 호출 방식 | 컨텍스트 | 주요 용도 | 저장 위치 |
|---|---|---|---|---|
| Skills | 자동 (description 매칭) | 메인에 주입 | 참조 지식, 패턴 | .claude/skills/ |
| Commands | 수동 (/command) |
메인에서 실행 | 반복 작업 자동화 | .claude/commands/ |
| Subagents | 명시적 위임 | 격리된 윈도우 | 독립적 작업 처리 | .claude/agents/ |
| Plugins | 설치 후 내부 요소 사용 | 해당 없음 | 배포/공유 패키지 | Marketplace |
| Hooks | 이벤트 트리거 | 자동 실행 | 강제 자동화 | .claude/settings.json |
| MCP | 외부 도구 연결 | 도구로 사용 | 외부 시스템 통합 | .mcp.json |
1.3 Plugin이 해결하는 문제#
┌─────────────────────────────────────────────────────────────────┐
│ Plugin 등장 이전 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ "팀원 A의 Claude Code 설정을 팀원 B에게 공유하려면?" │
│ │
│ 1. Skills 폴더 복사 │
│ 2. Commands 폴더 복사 │
│ 3. Agents 폴더 복사 │
│ 4. 설정 파일 수정 │
│ 5. 버전 관리 별도 │
│ 6. 업데이트 수동 반영 │
│ │
│ → 복잡하고 오류 발생 가능성 높음 │
│ │
├─────────────────────────────────────────────────────────────────┤
│ Plugin 등장 이후 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ # 한 번의 명령으로 설치 완료 │
│ /plugin marketplace add my-team/our-plugins │
│ /plugin install our-coding-standards@our-plugins │
│ │
│ → 버전 관리, 자동 업데이트, 의존성 해결 모두 자동 │
│ │
└─────────────────────────────────────────────────────────────────┘
2. Marketplace 시스템 이해#
2.1 Marketplace란?#
Marketplace는 Plugin들의 카탈로그입니다. Plugin을 검색하고 설치할 수 있는 저장소입니다.
┌─────────────────────────────────────────────────────────────────┐
│ Marketplace 구조 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Official Marketplace │ │
│ │ (anthropics/claude-plugins-official) │ │
│ │ │ │
│ │ • Anthropic이 관리 │ │
│ │ • 품질/보안 검증됨 │ │
│ │ • Claude Code 시작 시 자동 사용 가능 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────┴──────────────────┐ │
│ ▼ ▼ │
│ ┌───────────────────┐ ┌───────────────────┐ │
│ │ Community │ │ Private │ │
│ │ Marketplaces │ │ Marketplaces │ │
│ │ │ │ │ │
│ │ • VoltAgent │ │ • 회사 내부용 │ │
│ │ • obra/superpowers│ │ • 팀 전용 │ │
│ │ • 개인 개발자들 │ │ • 비공개 GitHub │ │
│ └───────────────────┘ └───────────────────┘ │
│ │
│ 분산형 구조: 누구나 Marketplace를 만들 수 있음 │
│ Anthropic 승인 불필요 │
│ │
└─────────────────────────────────────────────────────────────────┘
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) 이해#
| Scope | 위치 | 적용 범위 | 사용 시점 |
|---|---|---|---|
user |
~/.claude/ |
모든 프로젝트 | 개인 워크플로우, 범용 도구 |
project |
.claude/ |
현재 프로젝트만 | 프로젝트 특화 도구, 팀 공유 |
┌─────────────────────────────────────────────────────────────────┐
│ Scope 선택 가이드 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ "이 플러그인을 모든 프로젝트에서 사용하고 싶다" │
│ └─▶ --scope user │
│ │
│ "이 프로젝트에서만 사용하고, 팀원도 사용하게 하고 싶다" │
│ └─▶ --scope project (+ Git 커밋) │
│ │
│ "테스트 목적으로만 설치하고 싶다" │
│ └─▶ --scope project (나중에 삭제) │
│ │
└─────────────────────────────────────────────────────────────────┘
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
| Plugin | 설명 |
|---|---|
docx |
Word 문서 생성/편집, 변경 추적, 코멘트 |
pdf |
PDF 텍스트 추출, 생성, 병합, 폼 처리 |
pptx |
PowerPoint 프레젠테이션 생성/편집 |
xlsx |
Excel 스프레드시트, 수식, 차트 |
4.2 Claude Code 공식 플러그인#
Marketplace: anthropics/claude-code (⭐ 55k)
공식 저장소에 포함된 플러그인들:
| Plugin | 설명 |
|---|---|
plugin-toolkit |
플러그인 개발용 7개 전문가 Skills |
pr-review-agents |
PR 리뷰 전문 에이전트 (테스트, 에러 처리, 타입 설계) |
commit-workflows |
커밋 자동화 워크플로우 |
frontend-design |
고품질 프론트엔드 UI 생성 |
4.3 인기 커뮤니티 플러그인 (2026년 1월 기준)#
| Plugin | Stars | 설명 |
|---|---|---|
| claude-hud | 1.9k | 컨텍스트 사용량, 활성 도구, 진행 상황 표시 |
| claude-workflow-v2 | 1.1k | 범용 워크플로우 플러그인 (에이전트, 스킬, 훅, 커맨드) |
| claude-code-safety-net | 752 | 위험한 git/파일시스템 명령 차단 |
| claude-design-engineer | 1.1k | 일관된 UI 디자인 엔지니어링 |
| n-skills | 789 | Claude Code, Codex 호환 플러그인 마켓플레이스 |
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를 설치했습니다. 하지만:
┌─────────────────────────────────────────────────────────────────┐
│ golang-pro 내용 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ - Go 언어 일반 베스트 프랙티스 │
│ - 동시성 패턴 (goroutine, channel) │
│ - 표준 라이브러리 활용 │
│ - 일반적인 프로젝트 구조 │
│ │
│ ⚠️ 하지만 부족한 것: │
│ - 우리 팀의 특정 네이밍 컨벤션 │
│ - 우리가 사용하는 특정 프레임워크 규칙 (예: Gin, Echo) │
│ - 우리 회사의 에러 코드 체계 │
│ - 프로젝트 특화 패턴 │
│ │
└─────────────────────────────────────────────────────────────────┘
5.2 해결책: 3-Layer Stacking 전략#
커뮤니티 플러그인을 기반으로 하고, 그 위에 나만의 규칙을 레이어링합니다:
┌─────────────────────────────────────────────────────────────────┐
│ 3-Layer Stacking 전략 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Layer 3: 프로젝트별 CLAUDE.md [가장 구체적] │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ • 이 프로젝트만의 특수한 규칙 │ │
│ │ • 예: "internal/ 패키지 사용 금지" │ │
│ │ • 예: "Kafka 토픽 네이밍: {service}.{event}.{version}" │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ▲ │
│ │ 보완 │
│ │ │
│ Layer 2: 나만의 Custom Skill │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ • ~/.claude/skills/my-go-conventions/SKILL.md │ │
│ │ • 상세한 네이밍 컨벤션 │ │
│ │ • 우리 팀의 에러 핸들링 패턴 │ │
│ │ • 특정 프레임워크 사용 규칙 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ▲ │
│ │ 보완 │
│ │ │
│ Layer 1: 커뮤니티 Subagent (golang-pro) [가장 일반적] │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ • 일반적인 Go 베스트 프랙티스 │ │
│ │ • 동시성 패턴, 표준 라이브러리 │ │
│ │ • 커뮤니티에서 검증된 지식 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
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의 일반적인 베스트 프랙티스 위에
우리 팀만의 규칙을 추가합니다.
## 네이밍 컨벤션 (팀 규칙)
### 패키지 명명
```go
// ✅ 좋은 예
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)**
```markdown
# 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 레이어별 역할 분담 정리#
| 레이어 | 저장 위치 | 로드 시점 | 내용 |
|---|---|---|---|
| Layer 1 (커뮤니티) | Plugin (user scope) | Subagent 호출 시 | 일반적인 언어 베스트 프랙티스 |
| Layer 2 (팀 규칙) | ~/.claude/skills/ |
자동 (description 매칭) | 팀/회사 공통 컨벤션 |
| Layer 3 (프로젝트) | ./CLAUDE.md |
항상 | 프로젝트 특화 규칙 |
5.5 판단 기준: 어디에 넣을까?#
┌─────────────────────────────────────────────────────────────────┐
│ "이 규칙은 어디에 작성해야 할까?" │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Q1: 언어 자체의 일반적인 규칙인가? │
│ │ │
│ ├─ Yes → 커뮤니티 플러그인이 이미 포함하고 있을 가능성 높음 │
│ │ (추가 작성 불필요) │
│ │ │
│ └─ No → Q2로 │
│ │
│ Q2: 모든 프로젝트에 적용되는 우리 팀/회사의 규칙인가? │
│ │ │
│ ├─ Yes → Layer 2: Custom Skill로 작성 │
│ │ ~/.claude/skills/my-conventions/ │
│ │ │
│ └─ No → Q3로 │
│ │
│ Q3: 이 특정 프로젝트에만 적용되는 규칙인가? │
│ │ │
│ └─ Yes → Layer 3: 프로젝트 CLAUDE.md에 작성 │
│ │
└─────────────────────────────────────────────────────────────────┘
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. 정리#
이번 파트에서 배운 것#
- Plugin은 배포 패키지: Skills, Commands, Subagents, Hooks를 묶어서 공유
- Marketplace는 분산형: 누구나 만들 수 있고, 승인 불필요
- 설치 범위:
user(전역) vsproject(프로젝트) - 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 만들기
Read other posts