Claude Code 플러그인(plugin.json・marketplace.json)을 직접 제작하여 팀에 배포하는 구현 절차 —

팀에서 Claude Code를 사용할 경우, '편리한 슬래시 커맨드나 hook을 각자가 .claude/에 복사-붙여넣기 하다가 모두 버전이 제각각'인 상태가 되기 쉽다. 나 역시 리뷰용 커맨드와 편집 후 lint hook을 3개의 리포지토리에 수동으로 배포했었는데, 수정할 때마다 다시 배포하는 것이 힘들었다.

이를 해결하는 것이 Claude Code의 플러그인 기능이다. 커맨드, 서브 에이전트(Sub-agent), Skills, hook, MCP 서버 설정을 하나의 디렉터리에 모아 **marketplace (배포처 목록)**를 통해 install / update 할 수 있다.

• 예상 독자: Claude Code를 평소 사용하며, 직접 만든 커맨드나 hook을 팀에 배포하고 싶은 사람

• 전제: .claude/commands/나 settings.json의 hooks를 한 번은 작성해 본 경험이 있는 경우 - 확인 환경:
  Claude Code 2.1.285/ macOS 15(Darwin 24)/ bash

• 플러그인은 .claude-plugin/plugin.json을 위치시킨 디렉터리이다. commands/, hooks/ 등은 플러그인의 루트 바로 아래에 두는 것 (즉, .claude-plugin/ 안이 아니다) - 배포는 .claude-plugin/marketplace.json을 작성한 리포지토리를 claude plugin marketplace add로 등록하고, claude plugin install 이름@마켓플레이스명으로 설치한다 - hook의 스크립트 경로는 ${CLAUDE_PLUGIN_ROOT}로 작성한다. 개발 중에는 claude --plugin-dir로 읽어들이면, 이미 설치된 복사본과 혼동하지 않을 수 있다.

marketplace와 플러그인을 같은 리포지토리에 두는 구성을 했다.

my-mkt/
├── .claude-plugin/
│ └── marketplace.json # 배포처 목록
...

{
"name": "team-tools",
"version": "0.1.0",
... 
}

name은 kebab-case가 필수이다. 이것이 커맨드 네임스페이스가 되며, commands/review.md는 /team-tools:review로 호출할 수 있다.

commands/review.md는 일반적인 커스텀 슬래시 커맨드와 동일한 작성법을 사용하면 된다.

---
description: 변경 차분을 리뷰하는 기능
---
...

hook은 settings.json의 hooks와 같은 구조를 hooks/hooks.json에 작성한다.

{
"hooks": {
"PostToolUse": [
...

{
"name": "my-team",
"description": "사내용 Claude Code 플러그인 모음",
... 
}

source는 marketplace.json이 있는 리포지토리의 루트로부터의 상대 경로이다. 다른 리포지토리에 둔 플러그인은 {"source": "git-subdir", "url": "...", "path": "...", "ref": "v1.0.0"}와 같은 객체 형식으로도 지정할 수 있다 (공식 marketplace에서도 이 형식이 다수).

배포하기 전에 반드시 validate를 통과시켜야 한다.

$ claude plugin validate ./my-mkt
Validating marketplace manifest: /path/to/my-mkt/.claude-plugin/marketplace.json
⚠ Found 2 warnings:
...

marketplace를 지정하면, 그 안의 플러그인 plugin.json까지 한 번에 봐준다. name에 공백을 넣으면 제대로 에러로 멈춘다.

✘ Found 1 error:
❯ name: Plugin name cannot contain spaces. Use kebab-case (e.g., "my-plugin")
✘ Validation failed

# 로컬 경로에서도 GitHub의 owner/repo에서도 추가할 수 있음
claude plugin marketplace add ./my-mkt
claude plugin install team-tools@my-team
...

세션을 다시 열면 /team-tools:review가 자동 완성 후보로 나타난다. 팀원들에게는 'marketplace add'와 'install' 두 줄만 전달하면 되었다.

증상: 설치는 성공하는데 커맨드가 하나도 안 나온다.

원인: .claude-plugin/에는 plugin.json(과 marketplace.json)만 넣어야 한다. commands/, agents/, skills/, hooks/ 등은 플러그인 루트 바로 아래에 두어야 한다. '플러그인 관련 것은 전부 .claude-plugin/로'라고 착각하면 이렇게 된다.

골치 아픈 점은, 이 배치 오류가 validate를 통과해 버린다는 것이다. 실제로 commands/를 .claude-plugin/으로 옮겨서 시도했지만, 결과는 'passed with warnings'였고, 경고는 모두 description이나 author에 관한 것이었다.

회피책: validate의 결과만 믿으면 안 된다. claude plugin details team-tools로 플러그인에 포함된 컴포넌트 목록을 볼 수 있으니, 커맨드나 hook이 제대로 카운팅되었는지 확인해야 한다.

증상: 자신의 로컬 환경(플러그인 리포지토리 내부)에서는 hook이 작동하는데, 다른 프로젝트에 설치하면 No such file or directory로 실패한다.

원인: hook의 command는 사용자가 작업하는 프로젝트 디렉터리에서 실행된다. bash hooks/after-edit.sh와 같은 상대 경로는 플러그인 리포지토리 내에서 시도할 때만 우연히 해결되었을 뿐이다.

회피책: 플러그인 내부 파일은 반드시 ${CLAUDE_PLUGIN_ROOT}를 기준으로 작성해야 한다. 경로에 공백이 들어가는 환경도 있으므로, 더블 쿼테이션으로 감싸야 한다.

"command": "bash "${CLAUDE_PLUGIN_ROOT}/hooks/after-edit.sh""

플러그인에 .mcp.json을 포함하여 MCP 서버를 시작할 때도 마찬가지로, args의 스크립트 경로는 ${CLAUDE_PLUGIN_ROOT}로 작성해야 한다. 공식 marketplace의 hook이 있는 플러그인들도 모두 이 방식으로 되어 있었다.

증상: commands/review.md를 수정해서 저장했는데, Claude Code 상의 커맨드는 이전 내용 그대로 작동한다.

원인: 설치된 플러그인은 캐시 영역에 복사되어 거기서 읽혀진다. 로컬 소스를 수정해도, 설치된 사본은 바뀌지 않는다.

회피책: 용도에 따라 두 가지 방법이 있다.

# 개발 중: 설치하지 않고, 해당 세션만 디렉터리에서 직접 읽기
claude --plugin-dir ./my-mkt/plugins/team-tools
# 배포 후: version을 올린 후에 목록과 플러그인을 업데이트
...

나는 '개발은 --plugin-dir, 배포 전에는 validate, 배포 후에는 version을 올린다'는 세 가지 규칙을 만든 이후로, 반영되지 않는 문제로 고민할 일이 없어졌다. version을 잊으면, 팀원 환경에서 업데이트되었는지 육안으로 판단할 수 없기 때문에, 변경하면 반드시 올려야 한다.

나는 24시간 가동되는 완전 자율 구현 시스템을 운영하고 있는데, 사령탑 역할과 여러 구현 에이전트가 동일한 리뷰 절차나 위험 커맨드 블록 hook을 공유한다. 이전에는 프로젝트마다 .claude/를 복사해서, 블록 대상을 하나 추가할 때마다 전부 고칠 필요가 있었다. 플러그인화한 이후로는, 수정 → version 올리기 → update로 모든 프로젝트에 전달되게 되어, '어딘가 환경만 오래된 hook 상태'라는 사고가 사라졌다.

hook이나 MCP를 포함하는 플러그인은 사용자의 권한으로 셸 명령을 실행합니다. 외부 marketplace를 추가하기 전에, 내부의 hooks.json과 .mcp.json 파일을 살펴보는 습관을 들이는 것이 좋습니다.

• 플러그인 =
  .claude-plugin/plugin.json + 루트 직하단의 commands/, hooks/ 등 - 배포는 marketplace.json을 작성하고 marketplace add → install 이름@marketplace명
• validate로는 배치 오류까지는 잡아주지 못하므로, plugin details로 내부 내용을 확인합니다. hook이나 MCP의 경로는 ${CLAUDE_PLUGIN_ROOT}를 기준으로 작성합니다. 개발 중에는 --plugin-dir, 배포 후에는 version을 올리고 update를 합니다.