플러그인 시스템

플러그인은 Skills, Agents, Hooks, MCP/LSP 서버를 하나의 패키지로 묶어 프로젝트와 팀 간에 공유할 수 있게 합니다. 네임스페이스로 충돌을 방지하고, 마켓플레이스를 통해 배포할 수 있습니다.

플러그인 vs 단독 설정

접근 방식	Skill 이름	적합한 경우
단독 (`.claude/`)	`/hello`	개인 워크플로우, 프로젝트 전용, 빠른 실험
플러그인 (`.claude-plugin/`)	`/plugin-name:hello`	팀 공유, 커뮤니티 배포, 버전 관리, 프로젝트 간 재사용

플러그인 구조

my-plugin/
├── .claude-plugin/
│   └── plugin.json           # 매니페스트 (플러그인 정보)
├── skills/                   # Skills (SKILL.md 파일)
├── agents/                   # 커스텀 서브에이전트
├── commands/                 # Skills (마크다운 파일)
├── hooks/
│   └── hooks.json            # Hook 이벤트 핸들러
├── .mcp.json                 # MCP 서버 설정
├── .lsp.json                 # LSP 서버 설정
└── settings.json             # 플러그인 활성화 시 기본 설정

디렉토리 규칙

plugin.json만 .claude-plugin/ 안에 넣습니다. 나머지 모든 디렉토리(skills/, agents/, hooks/ 등)는 플러그인 루트 레벨에 배치합니다.

매니페스트 (plugin.json)

{
  "name": "my-awesome-plugin",
  "description": "코드 품질 자동화 도구 모음",
  "version": "1.0.0",
  "author": {
    "name": "Team Awesome"
  },
  "homepage": "https://github.com/team/my-plugin",
  "repository": "https://github.com/team/my-plugin",
  "license": "MIT"
}

필드	필수	설명
`name`	O	고유 식별자이자 Skill 네임스페이스
`description`	-	플러그인 매니저에 표시
`version`	-	시맨틱 버저닝 (마켓플레이스에서도 관리 가능)
`author`	-	저자 정보 (객체: `{"name": "이름"}`)
`homepage`	-	홈페이지 URL
`repository`	-	소스 코드 리포지토리
`license`	-	라이선스

Skills 패키징

skills/ 디렉토리에 SKILL.md 파일을 넣습니다. 폴더 이름이 Skill 이름이 되고, 플러그인 네임스페이스가 접두사로 붙습니다:

skills/
└── code-review/
    └── SKILL.md

이 Skill은 /my-awesome-plugin:code-review로 호출됩니다.

---
name: code-review
description: 코드 변경을 모범 사례와 보안 관점에서 리뷰합니다
---

코드를 리뷰할 때 확인할 사항:
1. 코드 구조와 조직
2. 에러 핸들링
3. 보안 이슈

인수 전달

$ARGUMENTS 플레이스홀더로 사용자 입력을 받습니다:

---
description: 사용자를 인사하는 Skill
---

$ARGUMENTS 사용자를 반갑게 맞이하고 도움이 필요한지 물어보세요.

사용: /my-awesome-plugin:hello Alex

Agents 패키징

agents/ 디렉토리에 커스텀 서브에이전트 마크다운 파일을 넣습니다:

---
name: security-reviewer
description: 보안 감사 전문 에이전트
tools: Read, Grep, Glob
model: sonnet
---

OWASP Top 10 기준으로 보안 취약점을 검사하세요.

Hooks 패키징

hooks/hooks.json에 이벤트 핸들러를 정의합니다:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix"
          }
        ]
      }
    ]
  }
}

MCP/LSP 서버 패키징

MCP 서버 (`.mcp.json`)

플러그인 루트에 .mcp.json 파일로 MCP 서버를 정의합니다.

LSP 서버 (`.lsp.json`)

LSP 서버는 실시간 코드 인텔리전스를 제공합니다:

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

LSP 요구사항

사용자 시스템에 언어 서버 바이너리가 설치되어 있어야 합니다.

기본 설정 (settings.json)

플러그인 활성화 시 적용될 기본 설정:

{
  "agent": "security-reviewer"
}

agents/ 디렉토리의 커스텀 에이전트를 메인 스레드로 활성화할 수 있습니다.

네임스페이스 규칙

플러그인 Skill은 항상 네임스페이스가 붙어 충돌 방지
형식: /plugin-name:skill-name
네임스페이스는 plugin.json의 name 필드로 결정
단독 Skill은 /skill-name으로 짧은 이름 사용

설치와 관리

로컬 테스트

# 개발 중 플러그인 직접 로드
claude --plugin-dir ./my-plugin

# 여러 플러그인 동시 로드
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

변경 후에는 Claude Code를 재시작해야 적용됩니다.

플러그인 관리 커맨드

# 플러그인 관리 인터페이스
/plugin

# 설치/제거/목록
/plugin install
/plugin remove
/plugin list

# 사용 가능한 Skill 확인 (플러그인 포함)
/help

검증

/plugin-name:skill-name으로 Skill 호출 확인
/agents에서 에이전트 표시 확인
Hook이 예상대로 동작하는지 확인

의존성 (Dependencies)

플러그인이 다른 플러그인에 의존할 수 있습니다. 의존 플러그인은 설치 시 자동으로 함께 깔립니다. Claude Code v2.1.110+ 필요.

제작자 — 의존성 선언

plugin.json의 dependencies 배열로 선언. 버전 미지정이면 latest, semver 범위 지정 가능:

{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

version 필드는 npm semver range 문법 (~2.1.0·^2.0·>=1.4·=2.1.0). 의존성은 마켓플레이스에서 해당 범위 만족하는 가장 높은 git 태그로 fetch.

릴리스 태그 컨벤션: {plugin-name}--v{version} (예: secrets-vault--v2.1.0). 직접 git tag 또는 claude plugin tag --push로 plugin.json·marketplace entry 자동 검증 후 태그.

사용자 — 의존성 에러 처리

/plugin list·/doctor에 의존성 문제 표시. 자주 만나는 케이스:

에러	원인	해결
`dependency-unsatisfied`	의존 플러그인이 미설치 또는 disabled	에러에 표시된 `claude plugin install` 명령 실행. 마켓플레이스 미등록이면 `claude plugin marketplace add` 먼저
`range-conflict`	여러 플러그인이 같은 의존성에 충돌하는 버전 범위 요구	충돌 플러그인 중 하나 uninstall·update, 또는 upstream 제작자에게 범위 확장 요청
`dependency-version-unsatisfied`	설치된 의존성 버전이 본인 범위 밖	`claude plugin install <dependency>@<marketplace>`로 재해결
`no-matching-tag`	의존성 레포에 `{name}--v*` 태그가 범위 안에 없음	upstream이 태그 릴리스 안 함 — 범위 완화 또는 제작자 문의

claude plugin list --json의 errors 필드로 자동화에서 점검 가능.

Orphan 의존성 정리

플러그인 uninstall 후에도 의존성은 디스크에 남음 (재설치 가능성·직접 사용 가능성 대비). 정리:

# 어떤 플러그인도 필요로 안 하는 의존성 나열·제거 (확인 프롬프트)
claude plugin prune

# 본인 설치 시 함께 prune
claude plugin uninstall deploy-kit --prune

본인 직접 설치한 플러그인은 절대 prune 안 되고, 의존성으로 자동 설치된 것만. claude plugin prune v2.1.121+.

자세한 dependency 제약·cross-marketplace 정책은 공식 plugin-dependencies 페이지.

배포

마켓플레이스 제출

README.md 문서화
시맨틱 버저닝으로 버전 관리
다른 사용자와 테스트
마켓플레이스에 제출:
- Claude.ai: claude.ai/settings/plugins/submit
- Console: platform.claude.com/plugins/submit

단독 → 플러그인 마이그레이션

기존 .claude/ 파일을 플러그인 구조로 변환:

.claude-plugin/plugin.json 매니페스트 생성
.claude/skills/ → 플러그인 루트의 skills/로 복사
.claude/agents/ → agents/로 복사
Hook 설정 → hooks/hooks.json으로 이동
MCP 설정 → .mcp.json으로 이동

이 페이지에 오류가 있나요? 오류 제보하기 →

플러그인 vs 단독 설정​

플러그인 구조​

매니페스트 (plugin.json)​

Skills 패키징​

인수 전달​

Agents 패키징​

Hooks 패키징​

MCP/LSP 서버 패키징​

MCP 서버 (.mcp.json)​

LSP 서버 (.lsp.json)​

기본 설정 (settings.json)​

네임스페이스 규칙​

설치와 관리​

로컬 테스트​

플러그인 관리 커맨드​

검증​

의존성 (Dependencies)​

제작자 — 의존성 선언​

사용자 — 의존성 에러 처리​

Orphan 의존성 정리​

배포​

마켓플레이스 제출​

단독 → 플러그인 마이그레이션​