마켓플레이스 만들기

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

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

한 플러그인을 몇 명과 공유: 플러그인의 디렉터리 또는 .zip 파일을 보냅니다. 마켓플레이스 없이 플러그인 공유를 참조하세요.
모든 사람에게 플러그인 제공: 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 필드가 자신의 plugin.json을 가진 플러그인에 적용되는 경우는 항목 및 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가 두 이름을 사용하는 방법에 대한 자세한 내용은 플러그인 로딩 참조를 참조하세요.

플러그인 소스 선택

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과 같은 필수 필드 누락
공백, 비ASCII 문자, 또는 claude-official과 같은 공식 Anthropic 마켓플레이스를 모방하는 형식의 마켓플레이스 이름
..를 포함하는 상대 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 호스트에 푸시합니다. 팀원들은 GitHub 저장소의 경우 셸에서 claude plugin marketplace add <owner>/<repo>를 실행하거나 저장소 URL과 함께 동일한 명령을 실행합니다. 그런 다음 연습에서처럼 이름으로 플러그인을 설치합니다. 비공개 저장소 액세스, 업데이트, 버전 관리, 항목 이름 변경 또는 제거는 마켓플레이스 호스팅 및 유지를 참조하세요.

다음 단계

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

플러그인

플러그인 사용

플러그인 만들기

마켓플레이스 실행

조직의 플러그인 관리

문제 해결

참고

마켓플레이스 만들기