클로드코드 플러그인 완전정복 · 8편

클로드코드 플러그인 완전정복 · 8편

내 마켓플레이스 만들고 세상에 뿌리기

GitHub 저장소 하나면 끝. 팀 내부 배포부터 커뮤니티 등록까지.

마지막 편이야. 지금까지 만든 플러그인을 남이 한 줄로 설치할 수 있게 만들 거야. 그러려면 마켓플레이스가 필요한데, 거창해 보이지만 실체는 JSON 파일 하나 든 GitHub 저장소야.

마켓플레이스 = 카탈로그

2편에서 얘기했지? 마켓플레이스는 서점이고 플러그인은 책이야. 서점을 차리려면 어떤 책이 있고 어디서 가져오는지 적은 목록이 필요한데, 그게 marketplace.json이야.

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json          # 카탈로그
└── plugins/
    └── quality-review-plugin/    # 실제 플러그인
        ├── .claude-plugin/
        │   └── plugin.json
        └── skills/
            └── quality-review/
                └── SKILL.md

⚠️ 파일이 두 개, 헷갈리지 말자
marketplace.json은 서점 목록이고 plugin.json은 책 한 권의 정보야. 이름이 비슷해서 자주 헷갈려.

marketplace.json 최소 형태

my-marketplace/.claude-plugin/marketplace.json

{
  "name": "my-plugins",
  "owner": {
    "name": "내 이름"
  },
  "plugins": [
    {
      "name": "quality-review-plugin",
      "source": "./plugins/quality-review-plugin",
      "description": "빠른 코드 리뷰용 스킬"
    }
  ]
}

필수는 name, owner, plugins 셋뿐이야. 플러그인 항목은 name이랑 source만 있으면 되고.

💡 name이 곧 설치 주소 — 여기 적은 my-plugins가 /plugin install 어쩌구@my-plugins의 뒷부분이 돼. 사용자한테 보이는 이름이니까 신경 써서 짓자. 케밥케이스(소문자+하이픈)로.

⚠️ 예약된 이름이 있어 — claude-plugins-official, anthropic-plugins처럼 앤트로픽 공식용으로 예약된 이름은 못 써. 공식인 척하는 이름(official-claude-plugins 같은)도 막혀 있어.

플러그인을 어디서 가져올까 — source 종류

source는 문자열일 수도 있고 객체일 수도 있어. 상황에 따라 골라 쓰면 돼.

방식	이럴 때
상대 경로 "./plugins/my-plugin"	마켓플레이스랑 플러그인이 같은 저장소에 있을 때. 제일 흔해
github	플러그인이 별도 저장소에 있을 때
url	GitLab, Bitbucket, 자체 호스팅 git
git-subdir	모노레포 안 특정 폴더만. 부분 클론이라 가볍게 받아와
npm	npm 패키지로 배포할 때

// 다른 저장소에서 가져오기
{
  "name": "my-plugin",
  "source": {
    "source": "github",
    "repo": "내아이디/plugin-repo",
    "ref": "v1.0.0"
  }
}

⚠️ URL로 배포할 땐 상대경로 못 써
마켓플레이스를 https://.../marketplace.json 형태로 배포하면 그 JSON 파일만 다운로드돼. 플러그인 파일은 안 따라와서 상대경로가 전부 깨져. URL 배포할 거면 github나 npm 소스를 쓰자. GitHub 저장소로 배포하면 통째로 클론되니까 상대경로가 잘 동작해.

로컬에서 먼저 테스트

배포 전에 반드시 해보자. 2편에서 배운 그 명령어 그대로야.

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins
/reload-plugins
/quality-review-plugin:quality-review

여기까지 되면 남의 컴퓨터에서도 똑같이 될 거야.

claude plugin validate .

이건 마켓플레이스 폴더에서 돌리면 marketplace.json 스키마, 중복된 플러그인 이름, 경로 문제까지 잡아줘. 상대경로로 지정한 플러그인은 걔네 plugin.json까지 같이 검사해.

GitHub에 올리기

• 저장소 만들고 .claude-plugin/marketplace.json이 저장소 루트에 오게 푸시
• README에 설치 방법 적기
• 사람들한테 두 줄 알려주기

/plugin marketplace add 내아이디/내저장소
/plugin install 플러그인이름@마켓플레이스이름

✓ 끝났어. 이제 누구든 두 줄로 내 도구를 받아갈 수 있어. 업데이트하고 싶으면 그냥 저장소에 푸시하면 되고, 사용자는 /plugin marketplace update로 갱신해.

버전 관리 — 여기서 제일 많이 삽질해

3편에서 살짝 언급했던 그 함정이야. 제대로 짚고 가자. 클로드코드는 이 순서로 버전을 결정해.

• plugin.json의 version
• 마켓플레이스 항목의 version
• 둘 다 없으면 → git 커밋 SHA

⚠️ 제일 흔한 사고
plugin.json에 "version": "1.0.0"을 박아두고 커밋만 계속 밀면, 이미 설치한 사람은 영원히 업데이트를 못 받아. 클로드코드가 보기엔 계속 같은 버전이거든.

그래서 선택지는 두 가지야.

○ version 생략하기

• 커밋 SHA가 버전 역할
• 푸시할 때마다 새 버전
• 내부용·개발 중인 플러그인에 딱

○ version 명시하기

• 릴리스할 때마다 직접 올려야 함
• 대신 배포 시점을 내가 통제
• 공개 배포용에 적합

💡 한 군데만 적자 — plugin.json이랑 마켓플레이스 항목 양쪽에 version을 적으면 안 돼. 클로드코드는 경고도 없이 plugin.json 값만 써서, 마켓플레이스에 적은 버전이 조용히 무시돼.

팀 내부에서만 쓰고 싶다면

비공개 저장소에 마켓플레이스를 두면 돼. 근데 더 좋은 방법이 있어. 프로젝트의 .claude/settings.json에 이렇게 적어두는 거야.

.claude/settings.json

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "우리회사/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "code-formatter@company-tools": true
  }
}

이 파일을 저장소에 커밋해두면, 팀원이 프로젝트를 클론하고 폴더를 신뢰하는 순간 마켓플레이스 설치를 안내받아. "이거 깔아주세요" 메시지 보낼 필요가 없어지는 거지.

💡 비공개 저장소 주의 — 수동 설치는 내 git 자격증명으로 잘 되는데, 백그라운드 자동 업데이트는 HTTPS로 인증이 안 되는 경우가 있어. SSH 리모트에 ssh-agent로 키를 올려두면 자동 업데이트도 잘 돌아가.

커뮤니티 마켓플레이스에 제출하기

더 넓게 뿌리고 싶으면 앤트로픽이 운영하는 커뮤니티 마켓플레이스에 낼 수 있어. 여긴 자동 검증과 안전성 심사를 통과한 서드파티 플러그인들이 모이는 곳이고, 사용자는 claude-community 이름으로 설치하게 돼.

• 제출 전에 claude plugin validate는 꼭 돌리자. 스키마 오류로 반려당하는 게 제일 아까워
• 제출은 앱 안의 제출 폼으로 해. 절차는 바뀔 수 있으니 공식 문서의 커뮤니티 마켓플레이스 제출 항목을 확인하는 게 정확해
• 등재되면 카탈로그에 특정 커밋 SHA로 고정돼서 올라가. 즉 내가 저장소에 뭘 밀든 사용자한테는 검증된 그 시점이 나가

💡 공식 마켓플레이스는 별개야 — claude-plugins-official은 앤트로픽이 직접 큐레이션하고 등재 여부도 앤트로픽 재량이야. 제출 폼으로 넣으면 커뮤니티 마켓플레이스로 가지 공식으로 가는 게 아니야. 독립적으로 뿌리고 싶으면 그냥 내 마켓플레이스를 공유하는 게 제일 확실해.

배포 전 최종 체크리스트

7편 체크리스트(원본 정리, 경로 ${CLAUDE_PLUGIN_ROOT}화, validate 통과)를 이미 통과했다는 전제로, 배포에만 해당하는 것만 추렸어.

• 플러그인 이름이 케밥케이스인가 — 대문자·공백·특수문자가 있으면 claude.ai 마켓플레이스 동기화에서 거부돼
• 마켓플레이스 이름이 예약어랑 겹치지 않나
• 버전 전략 정했나 — 명시 or 커밋 SHA, 반드시 한쪽만
• URL 배포라면 상대경로 대신 github/npm 소스를 썼나
• 로컬 마켓플레이스로 설치까지 실제로 해봤나
• README.md에 설치 방법·사용법 적었나
• LSP나 외부 바이너리 의존성이 있으면 README에 명시했나

여기까지 온 걸 축하해

시리즈를 마치며

폴더 하나에서 시작해서, 이제 세상에 배포되는 도구가 됐어.
내 워크플로우가 곧 남의 워크플로우가 되는 거야.

돌아보면 이 시리즈에서 한 일은 별거 없어. 폴더 만들고, JSON 두 개 쓰고, 마크다운 몇 개 넣은 게 전부야. 근데 그게 "내 컴퓨터에서만 되던 것"과 "누구나 두 줄로 받아가는 것"의 차이를 만들었지.

이제 남은 건 하나야. 지금 .claude/ 폴더에서 제일 자주 쓰는 것 하나 골라서, 오늘 밤에 플러그인으로 만들어보는 것. 그게 시작이야.

시리즈 전체 다시 보기 → 1편 개념 · 2편 설치 · 3편 첫 제작 · 4편 구조 · 5편 에이전트 · 6편 훅과 MCP · 7편 마이그레이션 · 8편 배포(현재)

만든 플러그인 있으면 댓글로 저장소 주소 남겨줘. 구경 가볼게 🙌