Plugins

• Skills, Agents, Hooks, MCP 서버 등을 하나의 패키지로 묶어 배포하는 확장 시스템
• 프로젝트/팀/커뮤니티 간에 재사용 가능한 형태로 공유 가능
• 네임스페이스(/plugin-name:skill-name)로 충돌 없이 여러 플러그인 동시 사용

해당 개념이 필요한 이유

• 공유 & 재사용: 한 번 만든 워크플로우를 팀 전체 또는 커뮤니티에 배포
• 버전 관리: semantic versioning으로 업데이트 추적
• 충돌 방지: 네임스페이스 기반이라 동명 스킬이 있어도 안전
• 올인원 패키징: 스킬 + 에이전트 + 훅 + MCP 서버를 하나로 묶음

AS-IS (Plugin 없이 = Standalone)

# 팀원 A가 만든 커스텀 설정 (Standalone = .claude/ 직접 설정)
~/.claude/skills/review-pr/SKILL.md
~/.claude/settings.json (hooks)
~/.claude/agents/code-reviewer.md

# 팀원 B에게 공유하려면?
→ 파일을 하나하나 복사
→ settings.json 수동 머지
→ 경로 차이로 동작 안 함
→ 버전 관리 불가

TO-BE (Plugin 사용)

# 하나의 플러그인 디렉토리로 패키징
my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 메타데이터
├── skills/
│   └── review-pr/SKILL.md   # 스킬
├── agents/
│   └── code-reviewer.md     # 에이전트
├── hooks/
│   └── hooks.json           # 훅
└── .mcp.json                # MCP 서버

# 팀원 B는 한 줄로 설치
/plugin install marketplace-url

Standalone vs Plugin

Standalone(단독 설정)이란 플러그인으로 패키징하지 않고, .claude/ 디렉토리에 직접 두는 설정 파일들을 말한다. 예: .claude/skills/, .claude/agents/, .claude/settings.json의 hooks. 해당 프로젝트 또는 해당 사용자(~/.claude/)에서만 동작하며, 별도 설치/배포 메커니즘이 없다.

항목	Standalone (.claude/)	Plugin
스킬명	/hello	/plugin-name:hello
적용 범위	한 프로젝트	설치한 모든 곳
공유	수동 파일 복사	marketplace 또는 --plugin-dir
버전 관리	없음	semantic versioning
적합한 경우	개인 워크플로우, 빠른 실험	팀 공유, 커뮤니티 배포

플러그인 디렉토리 구조

my-plugin/
├── .claude-plugin/       # plugin.json만 위치 (필수)
│   └── plugin.json       # 매니페스트 (이름, 버전, 설명)
├── commands/             # 슬래시 커맨드 (Markdown)
├── skills/               # Agent Skills (SKILL.md)
├── agents/               # 커스텀 Subagent 정의
├── hooks/                # hooks.json (이벤트 핸들러)
├── .mcp.json             # MCP 서버 설정
└── .lsp.json             # LSP 서버 설정

.claude-plugin/ 안에는 plugin.json만. commands/, agents/ 등은 플러그인 루트에 위치해야 함.

plugin.json 매니페스트

{
  "name": "my-plugin",
  "description": "코드 리뷰 자동화 플러그인",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

필드	용도
name	고유 식별자 겸 스킬 네임스페이스 (/name:skill)
description	플러그인 매니저에 표시
version	semantic versioning
author	선택. 크레딧 표시용

팀에 플러그인 공유하는 방법

방법 1: Git 레포에 플러그인 폴더 커밋 (가장 간단)

my-project/
├── .claude-plugins/           # 팀 공유 플러그인 모음
│   └── team-workflows/
│       ├── .claude-plugin/
│       │   └── plugin.json
│       ├── skills/
│       │   └── review-pr/SKILL.md
│       └── hooks/
│           └── hooks.json
├── src/
└── ...

팀원은 다음과 같이 사용:

claude --plugin-dir ./.claude-plugins/team-workflows

방법 2: 마켓플레이스 활용 (공식 배포)

# 팀원은 Claude Code에서 설치
/plugin install <marketplace-url>

방법 3: 공유 레포 (간편 공유)

# 팀 공유 레포를 clone
git clone git@github.com:team/claude-plugins.git ~/team-plugins
 
# 각자 로드
claude --plugin-dir ~/team-plugins/team-workflows

핵심은 플러그인 디렉토리 구조만 맞으면 (.claude-plugin/plugin.json 존재), 어디에 두든 --plugin-dir로 로드할 수 있다.

로컬 테스트

# 단일 플러그인 로드
claude --plugin-dir ./my-plugin
 
# 복수 플러그인 동시 로드
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

기존 Standalone 설정을 플러그인으로 변환

# 1. 플러그인 구조 생성
mkdir -p my-plugin/.claude-plugin
 
# 2. plugin.json 작성
echo '{"name":"my-plugin","version":"1.0.0"}' > my-plugin/.claude-plugin/plugin.json
 
# 3. 기존 파일 복사
cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/
cp -r .claude/skills my-plugin/
 
# 4. hooks 마이그레이션 (settings.json → hooks/hooks.json)
mkdir my-plugin/hooks
# settings.json의 hooks 객체를 hooks.json으로 이동
 
# 5. 테스트
claude --plugin-dir ./my-plugin

참고 문서

• Plugins 공식 문서
• Plugins 레퍼런스
• 플러그인 마켓플레이스
• 플러그인 설치