마켓플레이스 만들기

플러그인 마켓플레이스는 플러그인을 나열하고 각 플러그인을 가져올 위치를 지정하는 .claude-plugin/marketplace.json 파일이 있는 디렉터리 또는 저장소입니다. 디렉터리를 git 호스트에 푸시하면 액세스 권한이 있는 모든 사용자가 한 명령으로 Claude Code에 등록하고 카탈로그에서 플러그인을 설치할 수 있습니다. 팀이나 조직과 같이 선택한 그룹이 플러그인을 설치하고 제어하는 카탈로그에서 계속 업데이트를 받도록 하려면 자신의 마켓플레이스를 만듭니다. 저장소는 비공개일 수 있으며, 원하는 만큼 많은 플러그인을 나열할 수 있으며, 관리자는 모든 머신에서 이를 요구할 수 있습니다.

다음 경우는 다른 페이지에서 다룹니다:

한 플러그인을 몇 명과 공유: 플러그인의 디렉터리 또는 .zip 파일을 보냅니다. 마켓플레이스 없이 플러그인 공유를 참조하세요.
모든 사람에게 플러그인 제공: Anthropic의 디렉터리에 제출합니다. Anthropic의 디렉터리에 제출을 참조하세요.
플러그인을 직접 사용: --plugin-dir로 로드하거나 skills 디렉터리에 저장합니다. 마켓플레이스 없이 개발을 참조하세요.

마켓플레이스 만들기로 시작하여 자신의 머신에서 마켓플레이스를 구축하고 플러그인을 설치한 다음, 더 많은 플러그인 항목을 추가합니다.

다음 단계는 머신에서 마켓플레이스를 만들고, 플러그인을 추가하고, Claude Code에 등록하고, 마켓플레이스에서 플러그인을 설치합니다. 이것이 전체 루프이며, 마켓플레이스를 호스팅한 후 사용자가 거치는 루프와 동일합니다. my-marketplace/를 만들려는 디렉터리에서 셸의 모든 명령을 실행합니다. 나열할 플러그인이 필요합니다. 예제는 첫 번째 플러그인 만들기의 my-first-plugin을 사용합니다. 이는 /my-first-plugin:hello로 실행하는 하나의 skill이 있는 플러그인입니다. 아직 플러그인이 없으면 먼저 빌드합니다. 대신 자신의 플러그인을 사용하려면 단계에서 my-first-plugin이라고 하는 곳마다 해당 디렉터리와 name을 대체합니다. 플러그인 디렉터리에 포함될 수 있는 내용은 플러그인 디렉터리 탐색기를 참조하세요.

마켓플레이스 디렉터리 설정

마켓플레이스는 .claude-plugin/marketplace.json 파일이 있는 디렉터리이며, 나열하는 플러그인도 포함합니다. 마켓플레이스 디렉터리와 .claude-plugin/ 폴더를 만든 다음 플러그인을 plugins/ 아래에 복사합니다:

mkdir -p my-marketplace/.claude-plugin my-marketplace/plugins
cp -r my-first-plugin my-marketplace/plugins/

플러그인이 현재 위치에서 유효한지 확인하여 나중의 오류가 마켓플레이스가 아닌 플러그인에 대한 것이 아닌지 확인합니다:

claude plugin validate ./my-marketplace/plugins/my-first-plugin

출력의 마지막 줄은 ✔ Validation passed입니다.

마켓플레이스 파일 만들기

marketplace.json을 my-marketplace/.claude-plugin/marketplace.json에 저장합니다. 파일에는 name, owner, plugins 배열이 필요합니다.plugins의 각 객체는 플러그인 항목이며 name과 source가 필요합니다. 항목의 source를 마켓플레이스 루트에서의 경로로 작성합니다. 루트는 .claude-plugin/을 포함하는 디렉터리인 my-marketplace/입니다.

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

{
  "name": "my-marketplace",
  "description": "Plugins for my team",
  "owner": {
    "name": "Your Name"
  },
  "plugins": [
    {
      "name": "my-first-plugin",
      "source": "./plugins/my-first-plugin",
      "description": "A greeting plugin to learn the basics"
    }
  ]
}

마켓플레이스 검증

마켓플레이스 디렉터리에서 claude plugin validate를 실행하여 JSON 구문, 필수 필드, .claude-plugin/marketplace.json의 각 플러그인 항목을 확인합니다.

claude plugin validate ./my-marketplace

2단계에서 작성한 파일의 경우 출력의 마지막 줄은 ✔ Validation passed입니다.

마켓플레이스 추가 및 플러그인 설치

디렉터리를 마켓플레이스로 등록합니다.

claude plugin marketplace add ./my-marketplace

명령은 ✔ Successfully added marketplace: my-marketplace (declared in user settings)를 출력합니다. 이는 마켓플레이스가 사용자 설정 파일에 기록되었음을 의미합니다.플러그인을 설치합니다. 설치 ID는 항목의 name, @, 마켓플레이스 name입니다.

claude plugin install my-first-plugin@my-marketplace

명령은 ✔ Successfully installed plugin: my-first-plugin@my-marketplace (scope: user)를 출력합니다.세션 내에서 /plugin marketplace add ./my-marketplace는 마켓플레이스를 동일한 방식으로 등록합니다. /plugin install my-first-plugin@my-marketplace는 플러그인의 세부 정보를 /plugin 패널에서 열며, 여기서 플러그인을 설치합니다. 해당 흐름은 플러그인 설치 및 관리를 참조하세요.

플러그인이 로드되었는지 확인

설치된 플러그인을 나열합니다.

claude plugin list

출력은 Status: ✔ enabled와 함께 my-first-plugin@my-marketplace를 나열합니다.플러그인이 로드한 내용을 보려면 세부 정보를 표시합니다.

claude plugin details my-first-plugin

Component inventory 섹션은 Skills (1) hello를 읽습니다.skill을 실행하려면 세션을 시작하고 /my-first-plugin:hello를 입력합니다. Claude가 인사합니다. 명령은 플러그인의 이름을 접두사로 가지며, 모든 플러그인 skill의 이름도 마찬가지입니다.

플러그인 항목 추가

배포하는 모든 플러그인은 marketplace.json의 plugins 배열의 하나의 객체입니다. 두 번째 플러그인을 추가하려면 두 번째 객체를 추가합니다. 이 필드는 대부분의 항목을 다룹니다:

name: 설치할 때 @ 앞에 입력하는 식별자입니다. 플러그인 항목에서 이름이 사용할 수 있는 문자를 확인합니다.
source: Claude Code가 플러그인을 가져오는 위치입니다. 연습에서처럼 마켓플레이스 디렉터리 내의 플러그인에 대해 상대 경로 문자열을 작성하거나, 외부의 플러그인에 대해 소스 객체를 작성합니다. 플러그인 소스 선택을 참조하세요.
description: 사용자가 /plugin에서 마켓플레이스를 탐색할 때 플러그인 옆에 표시되는 줄입니다.

전체 필드 목록은 플러그인 항목을 참조하세요. 이 문서에서는 항목이 설정할 수 있는 plugin.json 필드와 해당 필드가 적용되는 경우도 다룹니다.

플러그인 항목 규칙

새 마켓플레이스에서 대부분의 설치 실패는 잘못된 디렉터리에서 작성된 상대 경로 또는 플러그인의 plugin.json의 name과 다른 항목 이름으로 인해 발생합니다.

마켓플레이스 루트에서 상대 경로 작성

마켓플레이스 루트는 .claude-plugin/을 포함하는 디렉터리입니다. 연습에서는 my-marketplace/이므로 항목의 source는 "./plugins/my-first-plugin"입니다. 경로는 .claude-plugin/ 내부에서 시작하지 않으므로 ..를 사용하여 나가지 마세요. ..가 있는 경로와 누락된 디렉터리에 대한 경로는 다른 명령에서 실패합니다:

..가 있는 경로: claude plugin validate는 항목을 유효하지 않은 것으로 보고합니다. 메시지는 Path contains "..": ./../plugins/my-first-plugin으로 시작합니다.
존재하지 않는 디렉터리에 대한 경로: claude plugin validate는 통과합니다. claude plugin install은 Source path does not exist: <path>로 실패하며, <path>는 Claude Code가 확인한 절대 위치입니다.

항목 이름과 매니페스트 이름을 동일하게 유지

마켓플레이스 플러그인은 marketplace.json의 항목 name과 자신의 plugin.json의 name을 가지며, 이를 매니페스트 이름이라고 합니다. 각 이름은 다른 위치에 나타납니다:

항목 이름: 설치 ID인 <entry-name>@<marketplace>입니다. 사용자가 설치하기 위해 입력하는 것, claude plugin list가 표시하는 것, Claude Code가 설정 파일의 enabledPlugins 아래에 작성하는 키입니다.
매니페스트 이름: 플러그인의 skill의 접두사이며, claude plugin details가 사용하는 이름입니다.

두 이름이 다르고 누군가 매니페스트 이름으로 설치할 때 Claude Code는 Plugin "<manifest-name>" not found in marketplace "<marketplace>"를 보고합니다. 두 이름을 동일하게 유지합니다. Claude Code가 두 이름을 사용하는 방법에 대한 자세한 내용은 플러그인 로딩 참조를 참조하세요.

사용하지 않는 서브모듈을 클론에서 제외

누군가 마켓플레이스를 추가하면 Claude Code는 저장소를 클론하고 플러그인 파일을 포함하는 git 서브모듈만 가져옵니다. Claude Code v2.1.295 이상이 필요합니다. 각 플러그인을 어디에 두는지에 따라 Claude Code가 가져오는 서브모듈이 결정됩니다:

하위 디렉터리에 있는 플러그인: Claude Code는 플러그인 디렉터리 내부의 서브모듈과 플러그인을 포함하는 서브모듈을 가져옵니다. 플러그인에 필요한 서브모듈은 플러그인 디렉터리 안에 두고, 필요하지 않은 서브모듈은 밖에 두세요
마켓플레이스 루트에 있는 플러그인: 플러그인 파일 중 하나가 어느 서브모듈 내부의 경로를 참조하는 즉시 Claude Code는 저장소의 모든 서브모듈을 가져옵니다. 저장소에 빌드에서만 사용하는 대용량 서브모듈이 있다면 플러그인을 하위 디렉터리로 옮기세요

루트에 있는 플러그인이 서브모듈의 파일을 실행하는 경우, 플러그인의 훅 또는 서버 구성에 ${CLAUDE_PLUGIN_ROOT}/vendor/tool/run.sh와 같이 파일 경로를 명시적으로 작성하세요. Claude Code는 이러한 경로를 읽어 플러그인에 서브모듈이 필요한지 판단합니다. 스크립트가 실행 중에 만드는 경로는 인식할 수 없습니다. 전체 규칙은 마켓플레이스 저장소의 Git 서브모듈을 참조하세요.

플러그인 소스 선택

marketplace.json의 각 플러그인 항목에는 Claude Code에 해당 플러그인을 가져올 위치를 알려주는 source가 있습니다. 플러그인의 파일이 저장된 위치에 따라 소스를 선택합니다. 표는 대부분의 마켓플레이스 소유자가 사용하는 소스를 나열합니다.

소스	사용 시기	최소 `source` 값
상대 경로	플러그인의 파일이 마켓플레이스 디렉터리 내부에 있음	`"./plugins/my-first-plugin"`
`github`	플러그인이 자신의 GitHub 저장소임	`{ "source": "github", "repo": "your-org/my-first-plugin" }`
`git-subdir`	플러그인이 모노레포와 같은 다른 저장소의 하위 디렉터리임	`{ "source": "git-subdir", "url": "your-org/monorepo", "path": "tools/my-first-plugin" }`

git-subdir 소스에서 url은 git URL 또는 owner/repo GitHub 약식을 사용합니다. 플러그인은 또한 다음 소스 유형 중 하나에서 올 수 있습니다:

url: 모든 호스트의 git 저장소 URL
archive: HTTPS를 통해 다운로드한 zip 파일
npm: npm 패키지
command: 플러그인이 설치된 머신에서 명령을 실행하여 생성된 디렉터리

모든 소스 유형의 필드, 그리고 git 기반 소스를 ref 또는 sha에 고정하는 방법은 플러그인 소스를 참조하세요.

검증 및 테스트

플러그인을 추가할 때마다 편집 후 셸에서 claude plugin validate ./my-marketplace를 실행하고, 공유하기 전에 자신의 머신에서 마켓플레이스에서 설치합니다. 검증과 설치는 다른 문제를 포착합니다.

검증이 보고하는 문제

claude plugin validate는 마켓플레이스 디렉터리 내의 파일만 읽습니다. 다음을 보고합니다:

JSON 구문 오류, json: Invalid JSON syntax: <reason>로
owner: Invalid input과 같은 필수 필드 누락
마켓플레이스 참조의 명명 규칙을 위반하는 마켓플레이스 또는 플러그인 이름
..를 포함하는 상대 source
최상위 또는 플러그인 항목의 알 수 없는 필드, 경고로
상대 경로 플러그인의 plugin.json의 문제, plugins[N] plugin.json → <field>: <message>로

validate가 인쇄할 수 있는 모든 메시지는 검증 메시지를 참조하세요. 플래그 및 종료 코드는 plugin validate를 참조하세요.

마켓플레이스를 추가하거나 설치할 때 나타나는 문제

claude plugin validate가 보고하지 않는 문제는 마켓플레이스를 추가하거나 설치할 때 나타납니다:

마켓플레이스를 추가할 때: 정확한 공식 마켓플레이스 이름, 예를 들어 claude-plugins-official은 검증을 통과합니다. 이러한 이름 중 하나로 마켓플레이스를 추가할 때 Claude Code는 The name '<name>' is reserved for official Anthropic marketplaces로 시작하는 메시지로 거부합니다.
플러그인을 설치할 때:
- Claude Code는 플러그인을 설치할 때 먼저 github, git-subdir 또는 다른 원격 소스를 가져오므로 잘못된 repo 또는 path가 그때 나타납니다.
- 존재하지 않는 디렉터리의 상대 source도 Source path does not exist: <path>로 설치에서 실패합니다.

플러그인 편집 테스트

연습에서 상대 경로 source가 있는 로컬 디렉터리에서 my-marketplace를 추가했습니다. 이 설정으로 Claude Code는 my-marketplace/plugins/에서 플러그인의 파일을 직접 읽습니다. 편집은 다음 세션 시작 또는 세션에서 /reload-plugins를 실행할 때 적용되며, 플러그인의 version에는 변경이 없습니다. 호스팅된 마켓플레이스에서 설치하는 사람들은 대신 플러그인 캐시에 복사본을 받습니다. 새 버전을 받는 방법은 사용자를 최신 상태로 유지를 참조하세요.

마켓플레이스를 제거하여 다시 시작

모든 것을 제거하고 다시 시작하려면 셸에서 claude plugin marketplace remove my-marketplace를 실행합니다. 명령은 마켓플레이스와 해당 플러그인을 제거합니다.

마켓플레이스 호스팅

마켓플레이스 만들기에서처럼 자신의 머신에서 마켓플레이스에서 플러그인을 설치할 수 있으면 마켓플레이스 디렉터리를 git 호스트에 푸시합니다. 푸시하기 전에 다른 작성자가 선택할 가능성이 낮은 최상위 name을 마켓플레이스에 지정하세요. 사용자는 같은 이름의 마켓플레이스를 두 개 가질 수 없기 때문입니다. 팀원들은 GitHub 저장소의 경우 셸에서 claude plugin marketplace add <owner>/<repo>를 실행하거나 저장소 URL과 함께 동일한 명령을 실행합니다. 그런 다음 연습에서처럼 이름으로 플러그인을 설치합니다. 비공개 저장소 액세스, 업데이트, 버전 관리, 항목 이름 변경 또는 제거는 마켓플레이스 호스팅 및 유지를 참조하세요.

다음 단계

마켓플레이스 호스팅 및 유지: 호스트를 선택하고, 사용자를 최신 상태로 유지하고, 플러그인을 안전하게 이름 변경 또는 제거합니다
마켓플레이스 참조: marketplace.json 필드 및 소스 유형
조직을 위한 플러그인 관리: 모든 머신에서 마켓플레이스 및 해당 플러그인을 요구합니다
관련성별로 플러그인 제안: 세션이 일치할 때 Claude Code가 마켓플레이스에서 플러그인을 제안하도록 합니다

플러그인

플러그인 사용하기

플러그인 만들기

mod

마켓플레이스 운영하기

조직의 플러그인 관리

문제 해결

레퍼런스

마켓플레이스 만들기