플러그인 게시와 배포

기준일: 2026-10-23
공식 기준: Publish and distribute a plugin

개요

Claude Code 플러그인을 게시한다는 것은 마켓플레이스(플러그인과 각 가져오는 위치를 나열한 JSON 카탈로그)에 올려 다른 사람이 이름으로 설치하고 업데이트를 받게 한다는 뜻입니다. 자체 마켓플레이스를 운영하거나 Anthropic 디렉터리에 제출할 수 있습니다. 게시 없이 공유하려면 플러그인 디렉터리나 .zip을 보내 직접 로드하게 합니다.

동작하는 플러그인을 공유할 준비가 된 작성자를 위한 페이지입니다. 플러그인이 아직 미완이면 Create a plugin, 공식 마켓에 플러그인이 있는 CLI/SDK를 유지한다면 Recommend your plugin from your CLI.

핵심 개념

개념	설명
name@marketplace	사용자가 플러그인을 설치·활성화·구성하는 식별자. 이름 변경은 다른 플러그인
version	plugin.json의 버전. 올리지 않고 push하면 업데이트가 안 됨
marketplace.json	.claude-plugin/에 두는 카탈로그. 저장소에 있으면 곧 게시된 것
renames	마켓 파일의 맵. 이름 변경 시 기존 설치를 이전
claude plugin tag	{name}--v{version} git 태그 생성

상세

배포 방식 선택

경로	설치할 수 있는 사람	필요한 것	사용자가 자동으로 업데이트를 받나
마켓플레이스 없음	플러그인 폴더나 .zip을 받은 사람	플러그인 폴더	없음. 받은 사본을 로드
자체 마켓플레이스	저장소에 접근 가능한 누구나 (팀이 clone할 수 있는 비공개 저장소 가능)	플러그인을 나열한 .claude-plugin/marketplace.json이 있는 git 저장소나 다른 호스트	꺼짐
Anthropic 디렉터리	claude.ai나 Cowork에서 추가한 사람. 계정 sync로 Claude Code 세션에도 로드	플러그인이 든 GitHub 저장소와 제출용 유료 claude.ai 플랜	예, push한 버전이 게시된 뒤

auto-update는 사용자 쪽의 마켓별 설정으로, 새 버전을 백그라운드로 가져옵니다.

릴리스 준비

이름, 버전, 검증, 마켓에서의 설치가 릴리스가 설치하는 사람에게 동작하는지를 정합니다. 첫 릴리스 전과 이후 릴리스마다 확인하세요.

1. 영구적인 이름 선택: 사용자가 name@marketplace로 설치·활성화·구성하므로 이름을 바꾸면 기존 설치에는 다른 플러그인입니다. deploy-helper 같은 kebab-case를 쓰고(claude plugin validate가 다른 형태에 경고) 영구적인 것으로 취급하세요. 사용자가 보는 레이블은 plugin.json의 displayName
2. 버전 방식 결정: plugin.json에 version을 설정해 두고 바꾸지 않은 채 commit만 push하면 claude plugin update가 <name> is already at the latest version (1.0.0).을 출력하고 사용자는 옛 사본을 유지합니다. 릴리스마다 version을 올리거나, git 호스팅 마켓에서 생략해 commit SHA를 쓰게 하세요. Versions and updates
3. 검증: 셸에서 claude plugin validate --strict ./your-plugin. 깨끗하면 ✔ Validation passed
   • CI: --strict 유지. 알 수 없는 매니페스트 필드나 누락된 version 같은 경고에도 exit code 1로 실패. 앞 단계에서 version을 생략하기로 했다면 --strict를 뺌
   • 경로: ./로 시작하지 않는 구성요소 경로를 보고. hook 명령과 MCP 서버 설정 안에서는 ${CLAUDE_PLUGIN_ROOT}/...로 파일을 참조. path rules
4. 로컬 마켓에서 설치: 셸에서 claude plugin marketplace add ./path-to-marketplace로 플러그인을 나열한 로컬 마켓을 추가하고 거기서 설치한 뒤 세션을 시작해 로드를 확인. 가장 작은 마켓은 Create a marketplace, 설치가 소스 디렉터리를 로드하는지 캐시 사본을 로드하는지는 In-place and copied plugins
5. 사용자에게 보이는 메타데이터 채우기: plugin.json의 description, author, homepage, repository와 플러그인 루트의 README.md. homepage는 URL로 파싱돼야 함. 전체 필드는 manifest reference
6. eval suite 실행: 있다면 셸에서 claude plugin eval. 플러그인 테스트 케이스를 실행해 점수를 매겨 회귀를 잡음. Test plugins with evals

마켓플레이스 없이 공유

플러그인이 git 저장소에 있으면 clone해서 체크아웃을 로드하거나, release에 첨부한 .zip을 가리키는 --plugin-url로 셸에서 Claude Code를 시작할 수 있습니다. 다음 버전은 pull하거나 다시 내려받습니다. 저장소가 아니면 디렉터리나 .zip을 보냅니다. 로드 방법 둘:

• 한 세션: 셸에서 claude --plugin-dir ./deploy-helper (경로는 clone, 압축 푼 폴더, .zip 자체). Flags that load a plugin for one session
• 모든 세션: .claude-plugin/plugin.json이 든 플러그인 디렉터리를 ~/.claude/skills/ 아래로 이동. 이후 시작 때마다 로드. 관리자가 skills-directory 플러그인을 차단했다면 제외

같은 저장소에 .claude-plugin/marketplace.json을 추가하면 이름으로 설치하고 명령으로 업데이트할 수 있습니다 (자체 마켓플레이스로 게시).

자체 도구와 함께 배포

CLI나 SDK를 유지한다면 플러그인을 마켓에 게시하고 설치 프로그램이나 post-install 메시지가 사용자에게 필요한 두 명령을 실행하거나 출력하게 합니다: claude plugin marketplace add <source>, 이어서 claude plugin install <name>@<marketplace>. 도구 사용 중 세션 안 발견은 Recommend your plugin from your CLI.

자체 마켓플레이스로 게시

자체 마켓플레이스는 플러그인을 나열한 .claude-plugin/marketplace.json을 git 저장소에 추가한 것입니다. 파일이 저장소에 들어가면 제출 양식 없이 게시된 것입니다. 플러그인 자체 저장소나 별도 저장소에 둘 수 있습니다.

저장소에 마켓 파일 추가

플러그인 자체 저장소에서 게시하려면 .claude-plugin/의 plugin.json 옆에 마켓 파일을 두고, source가 저장소 루트 "./"인 항목 하나를 둡니다. 항목 name은 plugin.json과 같게 (Keep the entry name and the manifest name the same):

{
  "name": "your-marketplace",
  "owner": { "name": "Your Name" },
  "plugins": [
    { "name": "deploy-helper", "source": "./" }
  ]
}

push 전에 저장소에서 claude plugin validate .를 실행하세요. 검사 내용은 Validate a directory. 한 저장소에 플러그인 여럿을 두는 구조는 Create a marketplace.

설치할 수 있는 사람 제어

저장소를 clone할 수 있는 누구나 거기서 설치할 수 있으므로 저장소가 비공개면 마켓도 비공개입니다. git 저장소 외 호스트는 Host a marketplace, git을 쓰지 않는 사람 포함 회사 전체는 Roll out to a whole company.

설치 방법 안내

사용자에게 셸에서 마켓을 추가한 뒤 플러그인을 설치하도록 안내하세요 (소스와 이름은 본인 것으로).

• 마켓 추가(한 번): claude plugin marketplace add your-org/your-marketplace (인자는 GitHub owner/repo 단축형, URL, 또는 경로)
• 플러그인 설치: claude plugin install deploy-helper@your-marketplace
• 세션 안에서 둘 다: /plugin install deploy-helper --marketplace your-org/your-marketplace. Claude Code v2.1.275 이상. Add a marketplace and install in one command
• 셸에서 한 명령으로 둘 다: claude plugin install deploy-helper --marketplace your-org/your-marketplace. Claude Code v2.1.292 이상

사용자에게 업데이트 전달

사용자는 요청하거나 마켓의 auto-update가 켜져 있을 때 릴리스를 받습니다.

• 요청 시: 사용자 셸에서 claude plugin update deploy-helper@your-marketplace. 마켓을 갱신하고 플러그인 버전이 바뀌었으면 새 사본을 설치
• Auto-update: 마켓에서 기본 꺼짐. Turn on auto-update. 켜면 세션 시작 후 지연을 두고 claude plugin update와 같은 일을 함

사용자 쪽 명령은 Install plugins, 시점은 when auto-update runs.

Anthropic 디렉터리 제출

Anthropic's directory는 사람들이 claude.ai와 Cowork에서 플러그인과 connector를 추가하려고 둘러보는 카탈로그입니다. 여기 한 번의 등록이 claude.ai, Cowork, Claude Code 사용자에게 닿습니다. 개발자 포털 claude.ai/directory/manage에서 제출하며 포털 안내는 claude.com의 Submit a plugin. Anthropic 공식 마켓 claude-plugins-official은 디렉터리 포털로 제출을 받지 않습니다. Anthropic 파트너 담당자가 있다면 공식 마켓 등록을 문의하세요.

1. 제출 가능 확인: 유료 claude.ai 플랜 필요. Pro와 Max는 본인 계정에서, Team과 Enterprise는 Owner가 제출. Enterprise Owner는 Organization settings > Roles의 커스텀 역할로 다른 구성원에게 Directory 권한도 부여 가능. Confirm you can submit to the directory
2. 로컬 검증: 셸에서 claude plugin validate ./your-plugin --strict (./your-plugin은 플러그인 디렉터리 경로). 매니페스트 오류를 로컬에서 잡음. 각 실행이 읽는 파일은 plugin validate. 포털은 CLI가 검사하지 않는 추가 디렉터리 규칙을 적용하므로 로컬 통과가 포털 검증 통과를 보장하지 않음. 제출 전 실행·수정할 검사는 claude.com의 plugin pre-submission checklist
3. 어디서 무엇이 로드되는지 확인: 일부 구성요소는 Claude Code 전용이라 claude.ai나 Cowork에 로드되지 않음. component support table
4. 개발자 포털에서 제출: claude.ai/directory/manage를 열고 Submit a plugin을 따름

나머지 절차는 claude.com 문서에 있습니다.

• Prepare for review: 게시 전 각 버전에 일어나는 일
• Update a published plugin: 새 버전이 사용자에게 닿는 방식
• Submit your plugin, and your MCP server as a connector: 제출할 수 있는 것
• Move an earlier submission to the developer portal: 포털 이전의 제출 양식으로 제출했을 때

등록된 플러그인이 Claude Code 사용자에게 닿는 방식

claude.ai 디렉터리에서 설치한 사람은 계정에 플러그인을 갖고, Claude Code는 이를 <name>@synced로 로드합니다. 보이는 것과 끄는 방법은 Plugins synced from claude.ai.

업데이트, rename, 제거

새 버전 릴리스

자체 마켓으로 게시하고 plugin.json에 version이 있으면 올리고 push하세요. claude plugin update를 실행하거나 auto-update가 켜진 사용자가 새 버전을 받습니다 (사용자에게 업데이트 전달). 디렉터리 등록은 Update a published plugin.

릴리스 태그

다른 플러그인이 내 플러그인에 버전 범위를 선언하면 그 범위가 태그로 해석되므로 git 태그를 붙입니다. 그렇지 않으면 태그는 필요 없습니다. 플러그인 디렉터리에서 셸로 claude plugin tag를 실행하면 {name}--v{version} 태그가 생성되고, --push는 origin으로 태그를 보냅니다. 플래그는 plugin tag reference. 범위 규칙은 플러그인 의존성 버전 제약.

플러그인 rename 또는 제거

게시된 플러그인의 name을 바꾸지 마세요. 이미 설치한 사용자는 옛 이름으로 기록돼 있어 rename 후 플러그인을 잃습니다. 마켓 파일의 renames 항목이 대신 그들을 이전합니다. 다른 레이블이 필요하면 displayName을 바꾸세요. rename이 불가피하면 마켓 파일의 renames 맵을 써서 기존 설치가 Plugin "<name>" not found in marketplace로 실패하는 대신 이전되게 하세요. 플러그인 제거나 renames 세부는 호스팅 페이지의 Rename or remove a plugin, 필드는 marketplace reference.

의존성 선언

같은 마켓의 다른 플러그인이 활성화돼 있어야 한다면 plugin.json의 dependencies 배열에 나열합니다. 항목은 이름만이거나 semver version 범위를 가진 객체입니다. 사용자가 플러그인을 설치하면 Claude Code가 의존성도 설치·활성화합니다. 범위 문법, 크로스 마켓 의존성, 불필요해진 의존성 prune는 플러그인 의존성 버전 제약.

체크리스트

• kebab-case 영구 이름 확정, displayName 설정
• version을 릴리스마다 올리거나 git 마켓에서 생략
• claude plugin validate --strict가 ✔ Validation passed
• 로컬 마켓에서 설치해 세션에서 로드 확인
• description, author, homepage, repository, README.md
• claude plugin eval 실행 (suite가 있으면)
• 사용자에게 claude plugin marketplace add / claude plugin install 안내

함께 보기

• Host and maintain a marketplace
• 플러그인 의존성 버전 제약
• Recommend your plugin from your CLI
• Measure plugin cost and usage

기준일

• 문서 작성·동기화 기준일: 2026-10-23 (v2.1.309 반영)
• 원문: https://code.claude.com/docs/en/plugins/publish