메인 콘텐츠로 건너뛰기
플러그인 마켓플레이스는 다른 사용자에게 플러그인을 배포할 수 있는 카탈로그입니다. 마켓플레이스는 중앙 집중식 검색, 버전 추적, 자동 업데이트 및 여러 소스 유형(git 저장소, 로컬 경로 등)을 지원합니다. 이 가이드에서는 팀이나 커뮤니티와 플러그인을 공유하기 위해 자신의 마켓플레이스를 만드는 방법을 보여줍니다. 기존 마켓플레이스에서 플러그인을 설치하려고 하시나요? 미리 빌드된 플러그인 검색 및 설치를 참조하세요.

개요

마켓플레이스를 생성하고 배포하는 과정은 다음과 같습니다:
  1. 플러그인 생성: skills, 에이전트, hooks, MCP 서버 또는 LSP 서버를 사용하여 하나 이상의 플러그인을 빌드합니다. 이 가이드에서는 배포할 플러그인이 이미 있다고 가정합니다. 플러그인 생성 방법에 대한 자세한 내용은 플러그인 생성을 참조하세요.
  2. 마켓플레이스 파일 생성: 플러그인을 나열하고 플러그인을 찾을 위치를 정의하는 marketplace.json을 정의합니다(마켓플레이스 파일 생성 참조).
  3. 마켓플레이스 호스팅: GitHub, GitLab 또는 다른 git 호스트에 푸시합니다(마켓플레이스 호스팅 및 배포 참조).
  4. 사용자와 공유: 사용자가 /plugin marketplace add로 마켓플레이스를 추가하고 개별 플러그인을 설치합니다(플러그인 검색 및 설치 참조).
마켓플레이스가 라이브 상태가 되면 저장소에 변경 사항을 푸시하여 업데이트할 수 있습니다. 사용자는 /plugin marketplace update로 로컬 복사본을 새로 고칩니다.

연습: 로컬 마켓플레이스 생성

이 예제에서는 하나의 플러그인으로 마켓플레이스를 생성합니다: 코드 리뷰를 위한 /quality-review skill입니다. 디렉터리 구조를 생성하고, skill을 추가하고, 플러그인 매니페스트와 마켓플레이스 카탈로그를 생성한 다음, 설치하고 테스트합니다.
1

디렉터리 구조 생성

mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review
2

skill 생성

/quality-review skill이 수행하는 작업을 정의하는 SKILL.md 파일을 생성합니다.
my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md
---
description: 버그, 보안 및 성능에 대한 코드 검토
disable-model-invocation: true
---

선택한 코드 또는 최근 변경 사항을 다음 항목에 대해 검토합니다:
- 잠재적 버그 또는 엣지 케이스
- 보안 문제
- 성능 문제
- 가독성 개선

간결하고 실행 가능한 내용을 제공합니다.
3

플러그인 매니페스트 생성

플러그인을 설명하는 plugin.json 파일을 생성합니다. 매니페스트는 .claude-plugin/ 디렉터리에 위치합니다.
my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json
{
  "name": "quality-review-plugin",
  "description": "빠른 코드 리뷰를 위한 /quality-review skill 추가",
  "version": "1.0.0"
}
version을 설정하면 사용자는 이 필드를 변경할 때만 업데이트를 받으므로, 모든 릴리스에서 이를 증가시킵니다. version을 생략하고 이 마켓플레이스를 git에서 호스팅하면, 모든 커밋이 자동으로 새 버전으로 계산됩니다. 버전 해석을 참조하여 올바른 접근 방식을 선택합니다.
4

마켓플레이스 파일 생성

플러그인을 나열하는 마켓플레이스 카탈로그를 생성합니다.
my-marketplace/.claude-plugin/marketplace.json
{
  "name": "my-plugins",
  "owner": {
    "name": "Your Name"
  },
  "plugins": [
    {
      "name": "quality-review-plugin",
      "source": "./plugins/quality-review-plugin",
      "description": "빠른 코드 리뷰를 위한 /quality-review skill 추가"
    }
  ]
}
5

추가 및 설치

마켓플레이스를 추가하고 플러그인을 설치합니다.
/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins
6

시도해보기

편집기에서 일부 코드를 선택하고 새 skill을 실행합니다.
/quality-review
플러그인이 수행할 수 있는 작업(hooks, 에이전트, MCP 서버 및 LSP 서버 포함)에 대해 자세히 알아보려면 플러그인을 참조하세요.
플러그인 설치 방법: 사용자가 플러그인을 설치하면 Claude Code는 플러그인 디렉터리를 캐시 위치에 복사합니다. 이는 ../shared-utils와 같은 경로를 사용하여 플러그인 디렉터리 외부의 파일을 참조할 수 없다는 의미입니다. 왜냐하면 해당 파일이 복사되지 않기 때문입니다.플러그인 간에 파일을 공유해야 하는 경우 symlink를 사용합니다. 자세한 내용은 플러그인 캐싱 및 파일 해석을 참조하세요.

마켓플레이스 파일 생성

저장소 루트에 .claude-plugin/marketplace.json을 생성합니다. 이 파일은 마켓플레이스의 이름, 소유자 정보 및 소스가 있는 플러그인 목록을 정의합니다. 각 플러그인 항목에는 최소한 namesource(가져올 위치)가 필요합니다. 사용 가능한 모든 필드는 아래의 전체 스키마를 참조하세요.
{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "저장 시 자동 코드 포맷팅",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "배포 자동화 도구"
    }
  ]
}

마켓플레이스 스키마

필수 필드

필드유형설명예제
namestring마켓플레이스 식별자(kebab-case, 공백 없음). 이는 공개 대면입니다: 사용자는 플러그인을 설치할 때 이를 봅니다(예: /plugin install my-tool@your-marketplace)."acme-tools"
ownerobject마켓플레이스 유지 관리자 정보(아래 필드 참조)
pluginsarray사용 가능한 플러그인 목록아래 참조
예약된 이름: 다음 마켓플레이스 이름은 공식 Anthropic 사용을 위해 예약되어 있으며 타사 마켓플레이스에서 사용할 수 없습니다: claude-code-marketplace, claude-code-plugins, claude-plugins-official, anthropic-marketplace, anthropic-plugins, agent-skills, knowledge-work-plugins, life-sciences. 공식 마켓플레이스를 사칭하는 이름(예: official-claude-plugins 또는 anthropic-tools-v2)도 차단됩니다.

소유자 필드

필드유형필수설명
namestring유지 관리자 또는 팀의 이름
emailstring아니오유지 관리자의 연락처 이메일

선택적 필드

필드유형설명
metadata.descriptionstring간단한 마켓플레이스 설명
metadata.versionstring마켓플레이스 버전
metadata.pluginRootstring상대 플러그인 소스 경로에 앞에 붙는 기본 디렉터리(예: "./plugins"를 사용하면 "source": "./plugins/formatter" 대신 "source": "formatter"를 작성할 수 있습니다)
allowCrossMarketplaceDependenciesOnarray이 마켓플레이스의 플러그인이 의존할 수 있는 다른 마켓플레이스. 여기에 나열되지 않은 마켓플레이스의 종속성은 설치 시 차단됩니다. 다른 마켓플레이스의 플러그인에 의존을 참조하세요.

플러그인 항목

plugins 배열의 각 플러그인 항목은 플러그인과 플러그인을 찾을 위치를 설명합니다. 플러그인 매니페스트 스키마의 모든 필드(예: description, version, author, commands, hooks 등)와 이러한 마켓플레이스 특정 필드를 포함할 수 있습니다: source, category, tagsstrict.

필수 필드

필드유형설명
namestring플러그인 식별자(kebab-case, 공백 없음). 이는 공개 대면입니다: 사용자는 설치할 때 이를 봅니다(예: /plugin install my-plugin@marketplace).
sourcestring|object플러그인을 가져올 위치(아래 플러그인 소스 참조)

선택적 플러그인 필드

표준 메타데이터 필드:
필드유형설명
descriptionstring간단한 플러그인 설명
versionstring플러그인 버전. 설정된 경우(여기 또는 plugin.json에서), 플러그인은 이 문자열로 고정되며 사용자는 변경될 때만 업데이트를 받습니다. 생략하면 git 커밋 SHA로 돌아갑니다. 버전 해석을 참조하세요.
authorobject플러그인 작성자 정보(name 필수, email 선택)
homepagestring플러그인 홈페이지 또는 문서 URL
repositorystring소스 코드 저장소 URL
licensestringSPDX 라이선스 식별자(예: MIT, Apache-2.0)
keywordsarray플러그인 검색 및 분류를 위한 태그
categorystring조직을 위한 플러그인 카테고리
tagsarray검색 가능성을 위한 태그
strictbooleanplugin.json이 구성 요소 정의의 권한인지 여부를 제어합니다(기본값: true). 아래의 Strict 모드를 참조하세요.
구성 요소 구성 필드:
필드유형설명
skillsstring|array<name>/SKILL.md를 포함하는 skill 디렉터리의 사용자 정의 경로
commandsstring|array평면 .md skill 파일 또는 디렉터리의 사용자 정의 경로
agentsstring|array에이전트 파일의 사용자 정의 경로
hooksstring|object사용자 정의 hooks 구성 또는 hooks 파일 경로
mcpServersstring|objectMCP 서버 구성 또는 MCP 구성 경로
lspServersstring|objectLSP 서버 구성 또는 LSP 구성 경로

플러그인 소스

플러그인 소스는 Claude Code에 마켓플레이스에 나열된 각 개별 플러그인을 가져올 위치를 알려줍니다. 이는 marketplace.json의 각 플러그인 항목의 source 필드에 설정됩니다. 플러그인이 로컬 머신에 복제되거나 복사되면 ~/.claude/plugins/cache의 로컬 버전 관리 플러그인 캐시에 복사됩니다.
소스유형필드참고
상대 경로string (예: "./my-plugin")없음마켓플레이스 저장소 내의 로컬 디렉터리. ./로 시작해야 합니다
githubobjectrepo, ref?, sha?
urlobjecturl, ref?, sha?Git URL 소스
git-subdirobjecturl, path, ref?, sha?git 저장소 내의 하위 디렉터리. 모노레포의 대역폭을 최소화하기 위해 희소하게 복제합니다
npmobjectpackage, version?, registry?npm install을 통해 설치됨
마켓플레이스 소스 vs 플러그인 소스: 이는 다양한 것을 제어하는 다양한 개념입니다.
  • 마켓플레이스 소스marketplace.json 카탈로그 자체를 가져올 위치. 사용자가 /plugin marketplace add를 실행하거나 extraKnownMarketplaces 설정에서 설정합니다. ref(분기/태그)를 지원하지만 sha는 지원하지 않습니다.
  • 플러그인 소스 — 마켓플레이스에 나열된 개별 플러그인을 가져올 위치. marketplace.json 내의 각 플러그인 항목의 source 필드에 설정됩니다. ref(분기/태그)와 sha(정확한 커밋) 모두를 지원합니다.
예를 들어, acme-corp/plugin-catalog에서 호스팅되는 마켓플레이스(마켓플레이스 소스)는 acme-corp/code-formatter에서 가져온 플러그인을 나열할 수 있습니다(플러그인 소스). 마켓플레이스 소스와 플러그인 소스는 다양한 저장소를 가리키며 독립적으로 고정됩니다.

상대 경로

동일한 저장소의 플러그인의 경우 ./로 시작하는 경로를 사용합니다:
{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}
경로는 마켓플레이스 루트(.claude-plugin/을 포함하는 디렉터리)에 상대적으로 해석됩니다. 위의 예에서 ./plugins/my-pluginmarketplace.json<repo>/.claude-plugin/marketplace.json에 있더라도 <repo>/plugins/my-plugin을 가리킵니다. .claude-plugin/ 외부로 나가기 위해 ../를 사용하지 마세요.
상대 경로는 사용자가 Git(GitHub, GitLab 또는 git URL)을 통해 마켓플레이스를 추가할 때만 작동합니다. 사용자가 marketplace.json 파일에 대한 직접 URL을 통해 마켓플레이스를 추가하면 상대 경로가 올바르게 해석되지 않습니다. URL 기반 배포의 경우 GitHub, npm 또는 git URL 소스를 대신 사용합니다. 자세한 내용은 문제 해결을 참조하세요.

GitHub 저장소

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}
특정 분기, 태그 또는 커밋에 고정할 수 있습니다:
{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}
필드유형설명
repostring필수. owner/repo 형식의 GitHub 저장소
refstring선택. Git 분기 또는 태그(저장소 기본 분기로 기본값)
shastring선택. 정확한 버전에 고정하기 위한 전체 40자 git 커밋 SHA

Git 저장소

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}
특정 분기, 태그 또는 커밋에 고정할 수 있습니다:
{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git",
    "ref": "main",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}
필드유형설명
urlstring필수. 전체 git 저장소 URL(https:// 또는 git@). .git 접미사는 선택 사항이므로 Azure DevOps 및 AWS CodeCommit URL(접미사 없음)이 작동합니다
refstring선택. Git 분기 또는 태그(저장소 기본 분기로 기본값)
shastring선택. 정확한 버전에 고정하기 위한 전체 40자 git 커밋 SHA

Git 하위 디렉터리

git-subdir을 사용하여 git 저장소의 하위 디렉터리 내에 있는 플러그인을 가리킵니다. Claude Code는 희소하고 부분적인 복제를 사용하여 하위 디렉터리만 가져오므로 대규모 모노레포의 대역폭을 최소화합니다.
{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin"
  }
}
특정 분기, 태그 또는 커밋에 고정할 수 있습니다:
{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}
url 필드는 GitHub 단축형(owner/repo) 또는 SSH URL(git@github.com:owner/repo.git)도 허용합니다.
필드유형설명
urlstring필수. Git 저장소 URL, GitHub owner/repo 단축형 또는 SSH URL
pathstring필수. 플러그인을 포함하는 저장소 내의 하위 디렉터리 경로(예: "tools/claude-plugin")
refstring선택. Git 분기 또는 태그(저장소 기본 분기로 기본값)
shastring선택. 정확한 버전에 고정하기 위한 전체 40자 git 커밋 SHA

npm 패키지

npm 패키지로 배포되는 플러그인은 npm install을 사용하여 설치됩니다. 이는 공개 npm 레지스트리 또는 팀이 호스팅하는 개인 레지스트리의 모든 패키지에서 작동합니다.
{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin"
  }
}
특정 버전에 고정하려면 version 필드를 추가합니다:
{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "2.1.0"
  }
}
개인 또는 내부 레지스트리에서 설치하려면 registry 필드를 추가합니다:
{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}
필드유형설명
packagestring필수. 패키지 이름 또는 범위 지정 패키지(예: @org/plugin)
versionstring선택. 버전 또는 버전 범위(예: 2.1.0, ^2.0.0, ~1.5.0)
registrystring선택. 사용자 정의 npm 레지스트리 URL. 시스템 npm 레지스트리(일반적으로 npmjs.org)로 기본값

고급 플러그인 항목

이 예제는 명령어, 에이전트, hooks 및 MCP 서버의 사용자 정의 경로를 포함하여 많은 선택적 필드를 사용하는 플러그인 항목을 보여줍니다:
{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "엔터프라이즈 워크플로우 자동화 도구",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "enterprise@example.com"
  },
  "homepage": "https://docs.example.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "commands": [
    "./commands/core/",
    "./commands/enterprise/",
    "./commands/experimental/preview.md"
  ],
  "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}
주목할 주요 사항:
  • commandsagents: 여러 디렉터리 또는 개별 파일을 지정할 수 있습니다. 경로는 플러그인 루트에 상대적입니다.
  • ${CLAUDE_PLUGIN_ROOT}: hooks 및 MCP 서버 구성에서 이 변수를 사용하여 플러그인의 설치 디렉터리 내의 파일을 참조합니다. 플러그인이 설치될 때 캐시 위치에 복사되기 때문에 필요합니다. 플러그인 업데이트를 통해 유지되어야 하는 종속성 또는 상태의 경우 ${CLAUDE_PLUGIN_DATA}를 대신 사용합니다.
  • strict: false: 이것이 false로 설정되어 있으므로 플러그인은 자신의 plugin.json이 필요하지 않습니다. 마켓플레이스 항목이 모든 것을 정의합니다. 아래의 Strict 모드를 참조하세요.

Strict 모드

strict 필드는 plugin.json이 구성 요소 정의(skills, 에이전트, hooks, MCP 서버, 출력 스타일)의 권한인지 여부를 제어합니다.
동작
true(기본값)plugin.json이 권한입니다. 마켓플레이스 항목은 추가 구성 요소로 이를 보완할 수 있으며 두 소스가 병합됩니다.
false마켓플레이스 항목이 전체 정의입니다. 플러그인에 구성 요소를 선언하는 plugin.json도 있으면 충돌이 발생하고 플러그인이 로드되지 않습니다.
각 모드를 사용할 때:
  • strict: true: 플러그인은 자신의 plugin.json을 가지고 있으며 자신의 구성 요소를 관리합니다. 마켓플레이스 항목은 맨 위에 추가 skills 또는 hooks를 추가할 수 있습니다. 이것이 기본값이며 대부분의 플러그인에서 작동합니다.
  • strict: false: 마켓플레이스 운영자가 완전한 제어를 원합니다. 플러그인 저장소는 원본 파일을 제공하고 마켓플레이스 항목은 이러한 파일 중 어느 것이 skills, 에이전트, hooks 등으로 노출되는지 정의합니다. 마켓플레이스가 플러그인 작성자의 의도와 다르게 플러그인의 구성 요소를 재구성하거나 큐레이션할 때 유용합니다.

마켓플레이스 호스팅 및 배포

GitHub에서 호스팅(권장)

GitHub는 가장 쉬운 배포 방법을 제공합니다:
  1. 저장소 생성: 마켓플레이스를 위한 새 저장소 설정
  2. 마켓플레이스 파일 추가: 플러그인 정의와 함께 .claude-plugin/marketplace.json 생성
  3. 팀과 공유: 사용자가 /plugin marketplace add owner/repo로 마켓플레이스를 추가합니다
이점: 기본 제공 버전 제어, 문제 추적 및 팀 협업 기능.

다른 git 서비스에서 호스팅

GitLab, Bitbucket 및 자체 호스팅 서버와 같은 모든 git 호스팅 서비스가 작동합니다. 사용자는 전체 저장소 URL로 추가합니다:
/plugin marketplace add https://gitlab.com/company/plugins.git

개인 저장소

Claude Code는 개인 저장소에서 플러그인 설치를 지원합니다. 수동 설치 및 업데이트의 경우 Claude Code는 기존 git 자격 증명 도우미를 사용합니다. 따라서 HTTPS 액세스는 gh auth login, macOS Keychain 또는 git-credential-store를 통해 터미널에서와 동일하게 작동합니다. SSH 액세스는 호스트가 이미 known_hosts 파일에 있고 키가 ssh-agent에 로드되어 있는 한 작동합니다. Claude Code는 호스트 지문 및 키 암호에 대한 대화형 SSH 프롬프트를 억제하기 때문입니다. 백그라운드 자동 업데이트는 대화형 프롬프트가 Claude Code 시작을 차단하므로 자격 증명 도우미 없이 시작 시 실행됩니다. 개인 마켓플레이스에 대한 자동 업데이트를 활성화하려면 환경에서 적절한 인증 토큰을 설정합니다:
공급자환경 변수참고
GitHubGITHUB_TOKEN 또는 GH_TOKEN개인 액세스 토큰 또는 GitHub App 토큰
GitLabGITLAB_TOKEN 또는 GL_TOKEN개인 액세스 토큰 또는 프로젝트 토큰
BitbucketBITBUCKET_TOKEN앱 비밀번호 또는 저장소 액세스 토큰
셸 구성(예: .bashrc, .zshrc)에서 토큰을 설정하거나 Claude Code를 실행할 때 전달합니다:
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
CI/CD 환경의 경우 토큰을 비밀 환경 변수로 구성합니다. GitHub Actions는 동일한 조직의 저장소에 대해 자동으로 GITHUB_TOKEN을 제공합니다.

배포 전에 로컬에서 테스트

공유하기 전에 마켓플레이스를 로컬에서 테스트합니다:
/plugin marketplace add ./my-local-marketplace
/plugin install test-plugin@my-local-marketplace
추가 명령어의 전체 범위(GitHub, Git URL, 로컬 경로, 원격 URL)는 마켓플레이스 추가를 참조하세요.

팀을 위한 마켓플레이스 필수

프로젝트 폴더를 신뢰할 때 팀 구성원이 자동으로 마켓플레이스를 설치하도록 저장소를 구성할 수 있습니다. 마켓플레이스를 .claude/settings.json에 추가합니다:
{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}
기본적으로 활성화해야 하는 플러그인을 지정할 수도 있습니다:
{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}
전체 구성 옵션은 플러그인 설정을 참조하세요.
로컬 directory 또는 file 소스를 상대 경로와 함께 사용하는 경우 경로는 저장소의 주 체크아웃에 대해 해석됩니다. git worktree에서 Claude Code를 실행할 때 경로는 여전히 주 체크아웃을 가리키므로 모든 worktree가 동일한 마켓플레이스 위치를 공유합니다. 마켓플레이스 상태는 프로젝트당이 아니라 사용자당 한 번 ~/.claude/plugins/known_marketplaces.json에 저장됩니다.

컨테이너에 대한 플러그인 사전 채우기

컨테이너 이미지 및 CI 환경의 경우 빌드 시간에 플러그인 디렉터리를 사전 채우므로 Claude Code가 런타임에 아무것도 복제하지 않고도 마켓플레이스 및 플러그인이 이미 사용 가능한 상태로 시작됩니다. CLAUDE_CODE_PLUGIN_SEED_DIR 환경 변수를 이 디렉터리를 가리키도록 설정합니다. 여러 시드 디렉터리를 계층화하려면 Unix에서는 :로, Windows에서는 ;로 경로를 구분합니다. Claude Code는 각 디렉터리를 순서대로 검색하고 주어진 마켓플레이스 또는 플러그인 캐시를 포함하는 첫 번째 시드가 우선합니다. 시드 디렉터리는 ~/.claude/plugins의 구조를 미러링합니다:
$CLAUDE_CODE_PLUGIN_SEED_DIR/
  known_marketplaces.json
  marketplaces/<name>/...
  cache/<marketplace>/<plugin>/<version>/...
시드 디렉터리를 구축하려면 이미지 빌드 중에 Claude Code를 한 번 실행하고, 필요한 플러그인을 설치한 다음, 결과 ~/.claude/plugins 디렉터리를 이미지에 복사하고 CLAUDE_CODE_PLUGIN_SEED_DIR을 가리킵니다. 복사 단계를 건너뛰려면 빌드 중에 CLAUDE_CODE_PLUGIN_CACHE_DIR을 대상 시드 경로로 설정하여 플러그인이 직접 설치되도록 합니다:
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins
그런 다음 런타임 환경에서 CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed를 설정하여 Claude Code가 시작 시 시드에서 읽도록 합니다. 시작 시 Claude Code는 시드의 known_marketplaces.json에서 찾은 마켓플레이스를 기본 구성에 등록하고 cache/ 아래에서 찾은 플러그인 캐시를 다시 복제하지 않고 사용합니다. 이는 대화형 모드와 -p 플래그를 사용한 비대화형 모드 모두에서 작동합니다. 동작 세부 정보:
  • 읽기 전용: 시드 디렉터리는 절대 쓰기되지 않습니다. git pull이 읽기 전용 파일 시스템에서 실패하므로 시드 마켓플레이스에 대해 자동 업데이트가 비활성화됩니다.
  • 시드 항목이 우선합니다: 시드에서 선언된 마켓플레이스는 각 시작 시 사용자 구성의 일치하는 항목을 덮어씁니다. 시드 플러그인을 거부하려면 마켓플레이스를 제거하는 대신 /plugin disable을 사용합니다.
  • 경로 해석: Claude Code는 시드의 JSON 내에 저장된 경로를 신뢰하지 않고 런타임에 $CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/을 탐색하여 마켓플레이스 콘텐츠를 찾습니다. 이는 시드가 빌드된 위치와 다른 경로에 마운트된 경우에도 시드가 올바르게 작동함을 의미합니다.
  • 변경 차단: 시드 관리 마켓플레이스에 대해 /plugin marketplace remove 또는 /plugin marketplace update를 실행하면 시드 이미지를 업데이트하도록 관리자에게 문의하라는 지침과 함께 실패합니다.
  • 설정과 구성: extraKnownMarketplaces 또는 enabledPlugins이 시드에 이미 존재하는 마켓플레이스를 선언하면 Claude Code는 복제하는 대신 시드 복사본을 사용합니다.

관리되는 마켓플레이스 제한

플러그인 소스에 대한 엄격한 제어가 필요한 조직의 경우 관리자는 관리되는 설정에서 strictKnownMarketplaces 설정을 사용하여 사용자가 추가할 수 있는 플러그인 마켓플레이스를 제한할 수 있습니다. strictKnownMarketplaces가 관리되는 설정에서 구성되면 제한 동작은 값에 따라 달라집니다:
동작
정의되지 않음(기본값)제한 없음. 사용자는 모든 마켓플레이스를 추가할 수 있습니다
빈 배열 []완전한 잠금. 사용자는 새 마켓플레이스를 추가할 수 없습니다
소스 목록사용자는 허용 목록과 정확히 일치하는 마켓플레이스만 추가할 수 있습니다

일반적인 구성

모든 마켓플레이스 추가 비활성화:
{
  "strictKnownMarketplaces": []
}
특정 마켓플레이스만 허용:
{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    }
  ]
}
호스트에 대한 정규식 패턴 일치를 사용하여 내부 git 서버의 모든 마켓플레이스 허용. 이는 GitHub Enterprise Server 또는 자체 호스팅 GitLab 인스턴스에 권장되는 방법입니다:
{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}
경로에 대한 정규식 패턴 일치를 사용하여 특정 디렉터리의 파일 시스템 기반 마켓플레이스 허용:
{
  "strictKnownMarketplaces": [
    {
      "source": "pathPattern",
      "pathPattern": "^/opt/approved/"
    }
  ]
}
pathPattern으로 모든 파일 시스템 경로를 허용하면서 hostPattern으로 네트워크 소스를 제어하려면 ".*"pathPattern으로 사용합니다.
strictKnownMarketplaces는 사용자가 추가할 수 있는 것을 제한하지만 자체적으로 마켓플레이스를 등록하지는 않습니다. 허용된 마켓플레이스를 사용자가 /plugin marketplace add를 실행하지 않고도 자동으로 사용 가능하게 하려면 동일한 managed-settings.json에서 extraKnownMarketplaces와 쌍을 이룹니다. 둘 다 함께 사용을 참조하세요.

제한 작동 방식

제한은 네트워크 또는 파일 시스템 작업이 발생하기 전에 확인됩니다. 확인은 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로고침 및 자동 업데이트 시 실행됩니다. 마켓플레이스가 정책 구성 전에 추가되었고 해당 소스가 더 이상 허용 목록과 일치하지 않으면 Claude Code는 해당 마켓플레이스에서 플러그인을 설치하거나 업데이트하기를 거부합니다. 동일한 적용이 blockedMarketplaces에도 적용됩니다. 허용 목록은 대부분의 소스 유형에 대해 정확한 일치를 사용합니다. 마켓플레이스가 허용되려면 지정된 모든 필드가 정확히 일치해야 합니다:
  • GitHub 소스의 경우: repo는 필수이며 허용 목록에 지정된 경우 ref 또는 path도 일치해야 합니다
  • URL 소스의 경우: 전체 URL이 정확히 일치해야 합니다
  • hostPattern 소스의 경우: 마켓플레이스 호스트가 정규식 패턴과 일치합니다
  • pathPattern 소스의 경우: 마켓플레이스의 파일 시스템 경로가 정규식 패턴과 일치합니다
strictKnownMarketplaces관리되는 설정에서 설정되므로 개별 사용자 및 프로젝트 구성은 이러한 제한을 재정의할 수 없습니다. 전체 구성 세부 정보(지원되는 모든 소스 유형 및 extraKnownMarketplaces와의 비교 포함)는 strictKnownMarketplaces 참조를 참조하세요.

버전 해석 및 릴리스 채널

플러그인 버전은 캐시 경로 및 업데이트 감지를 결정합니다. 해석된 버전이 사용자가 이미 가지고 있는 것과 일치하면 /plugin update 및 자동 업데이트는 플러그인을 건너뜁니다. Claude Code는 다음 중 설정된 첫 번째 항목에서 플러그인의 버전을 해석합니다:
  1. 플러그인의 plugin.jsonversion
  2. 플러그인의 마켓플레이스 항목의 version
  3. 플러그인 소스의 git 커밋 SHA
git 기반 소스 유형 github, url, git-subdir 및 git 호스팅 마켓플레이스 내의 상대 경로의 경우 version을 완전히 생략할 수 있으며 모든 새 커밋은 새 버전으로 취급됩니다. 이는 내부 또는 활발하게 개발 중인 플러그인에 대한 가장 간단한 설정입니다.
version을 설정하면 플러그인이 고정됩니다. plugin.json"version": "1.0.0"을 선언하면 해당 문자열을 변경하지 않고 새 커밋을 푸시해도 기존 사용자에게는 아무것도 하지 않습니다. Claude Code가 동일한 버전을 보고 캐시된 복사본을 유지하기 때문입니다. 모든 릴리스에서 필드를 범프하거나 커밋 SHA를 사용하도록 생략합니다.plugin.json 및 마켓플레이스 항목 모두에서 version을 설정하지 마세요. plugin.json 값이 항상 자동으로 우선하므로 오래된 매니페스트 버전이 marketplace.json에서 설정한 버전을 숨길 수 있습니다.

릴리스 채널 설정

플러그인에 대한 “stable” 및 “latest” 릴리스 채널을 지원하려면 동일한 저장소의 다양한 refs 또는 SHA를 가리키는 두 개의 마켓플레이스를 설정할 수 있습니다. 그런 다음 관리되는 설정을 통해 두 마켓플레이스를 다양한 사용자 그룹에 할당할 수 있습니다.
각 채널은 다른 버전으로 해석되어야 합니다. 명시적 버전을 사용하는 경우 plugin.json은 각 고정된 ref에서 다른 version을 선언해야 합니다. version을 생략하면 서로 다른 커밋 SHA가 이미 채널을 구분합니다. 두 refs가 동일한 버전 문자열로 해석되면 Claude Code는 이들을 동일한 것으로 취급하고 업데이트를 건너뜁니다.
예제
{
  "name": "stable-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "stable"
      }
    }
  ]
}
{
  "name": "latest-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "latest"
      }
    }
  ]
}
사용자 그룹에 채널 할당
관리되는 설정을 통해 각 마켓플레이스를 적절한 사용자 그룹에 할당합니다. 예를 들어 stable 그룹은 다음을 받습니다:
{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/stable-tools"
      }
    }
  }
}
early-access 그룹은 대신 latest-tools를 받습니다:
{
  "extraKnownMarketplaces": {
    "latest-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/latest-tools"
      }
    }
  }
}

의존성 버전 고정

플러그인은 의존성에 대한 semver 범위를 제한하여 의존성 업데이트가 종속 플러그인을 손상시키지 않도록 할 수 있습니다. {plugin-name}--v{version} git 태그 규칙, 범위 구문 및 동일한 의존성에 대한 여러 제약 조건이 어떻게 결합되는지에 대해서는 플러그인 의존성 버전 제한을 참조하세요.

검증 및 테스트

공유하기 전에 마켓플레이스를 테스트합니다. 마켓플레이스 JSON 구문 검증:
claude plugin validate .
또는 Claude Code 내에서:
/plugin validate .
테스트를 위해 마켓플레이스 추가:
/plugin marketplace add ./path/to/marketplace
모든 것이 작동하는지 확인하기 위해 테스트 플러그인 설치:
/plugin install test-plugin@marketplace-name
전체 플러그인 테스트 워크플로우는 플러그인을 로컬에서 테스트를 참조하세요. 기술적 문제 해결은 플러그인 참조를 참조하세요.

CLI에서 마켓플레이스 관리

Claude Code는 스크립팅 및 자동화를 위한 비대화형 claude plugin marketplace 하위 명령어를 제공합니다. 이는 대화형 세션 내에서 사용 가능한 /plugin marketplace 명령어와 동일합니다.

플러그인 마켓플레이스 추가

GitHub 저장소, git URL, 원격 URL 또는 로컬 경로에서 마켓플레이스를 추가합니다.
claude plugin marketplace add <source> [options]
인수:
  • <source>: GitHub owner/repo 단축형, git URL, marketplace.json 파일에 대한 원격 URL 또는 로컬 디렉터리 경로. 분기 또는 태그에 고정하려면 GitHub 단축형에 @ref를 추가하거나 git URL에 #ref를 추가합니다
옵션:
옵션설명기본값
--scope <scope>마켓플레이스를 선언할 위치: user, project 또는 local. 플러그인 설치 범위 참조user
--sparse <paths...>git sparse-checkout을 통해 특정 디렉터리로 체크아웃 제한. 모노레포에 유용
GitHub에서 owner/repo 단축형을 사용하여 마켓플레이스 추가:
claude plugin marketplace add acme-corp/claude-plugins
@ref를 사용하여 특정 분기 또는 태그에 고정:
claude plugin marketplace add acme-corp/claude-plugins@v2.0
비 GitHub 호스트의 git URL에서 추가:
claude plugin marketplace add https://gitlab.example.com/team/plugins.git
marketplace.json 파일을 직접 제공하는 원격 URL에서 추가:
claude plugin marketplace add https://example.com/marketplace.json
테스트를 위해 로컬 디렉터리에서 추가:
claude plugin marketplace add ./my-marketplace
마켓플레이스를 프로젝트 범위에서 선언하여 .claude/settings.json을 통해 팀과 공유:
claude plugin marketplace add acme-corp/claude-plugins --scope project
모노레포의 경우 플러그인 콘텐츠를 포함하는 디렉터리로 체크아웃 제한:
claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

플러그인 마켓플레이스 목록

구성된 모든 마켓플레이스를 나열합니다.
claude plugin marketplace list [options]
옵션:
옵션설명
--jsonJSON으로 출력

플러그인 마켓플레이스 제거

구성된 마켓플레이스를 제거합니다. 별칭 rm도 허용됩니다.
claude plugin marketplace remove <name>
인수:
  • <name>: claude plugin marketplace list에 표시된 마켓플레이스 이름을 제거합니다. 이는 add에 전달한 소스가 아니라 marketplace.jsonname입니다
마켓플레이스를 제거하면 해당 마켓플레이스에서 설치한 모든 플러그인도 제거됩니다. 설치된 플러그인을 잃지 않고 마켓플레이스를 새로 고치려면 claude plugin marketplace update를 대신 사용합니다.

플러그인 마켓플레이스 업데이트

소스에서 마켓플레이스를 새로 고쳐 새 플러그인 및 버전 변경을 검색합니다.
claude plugin marketplace update [name]
인수:
  • [name]: claude plugin marketplace list에 표시된 마켓플레이스 이름을 업데이트합니다. 생략하면 모든 마켓플레이스를 업데이트합니다
removeupdate 모두 시드 관리 마켓플레이스에 대해 실행할 때 실패합니다. 이는 읽기 전용입니다. 모든 마켓플레이스를 업데이트할 때 시드 관리 항목은 건너뛰고 다른 마켓플레이스는 여전히 업데이트됩니다. 시드 제공 플러그인을 변경하려면 관리자에게 시드 이미지를 업데이트하도록 요청합니다. 컨테이너에 대한 플러그인 사전 채우기를 참조하세요.

문제 해결

마켓플레이스가 로드되지 않음

증상: 마켓플레이스를 추가할 수 없거나 플러그인을 볼 수 없습니다 해결책:
  • 마켓플레이스 URL이 액세스 가능한지 확인합니다
  • .claude-plugin/marketplace.json이 지정된 경로에 있는지 확인합니다
  • claude plugin validate 또는 /plugin validate를 사용하여 JSON 구문이 유효한지 확인합니다
  • 개인 저장소의 경우 액세스 권한이 있는지 확인합니다

마켓플레이스 검증 오류

마켓플레이스 디렉터리에서 claude plugin validate . 또는 /plugin validate .를 실행하여 문제를 확인합니다. 검증자는 plugin.json, skill/agent/command frontmatter 및 hooks/hooks.json에서 구문 및 스키마 오류를 확인합니다. 일반적인 오류:
오류원인해결책
File not found: .claude-plugin/marketplace.json누락된 매니페스트필수 필드를 사용하여 .claude-plugin/marketplace.json 생성
Invalid JSON syntax: Unexpected token...JSON 구문 오류 marketplace.json에서누락된 쉼표, 추가 쉼표 또는 인용되지 않은 문자열 확인
Duplicate plugin name "x" found in marketplace두 플러그인이 동일한 이름을 공유합니다각 플러그인에 고유한 name 값 지정
plugins[0].source: Path contains ".."소스 경로에 .. 포함마켓플레이스 루트에 상대적인 경로를 .. 없이 사용합니다. 상대 경로 참조
YAML frontmatter failed to parse: ...skill, agent 또는 command 파일의 YAML 무효frontmatter 블록의 YAML 구문을 수정합니다. 런타임에 이 파일은 메타데이터 없이 로드됩니다.
Invalid JSON syntax: ... (hooks.json)형식이 잘못된 hooks/hooks.jsonJSON 구문을 수정합니다. 형식이 잘못된 hooks/hooks.json은 전체 플러그인이 로드되지 않도록 합니다.
경고(차단하지 않음):
  • Marketplace has no plugins defined: plugins 배열에 최소한 하나의 플러그인 추가
  • No marketplace description provided: 사용자가 마켓플레이스를 이해하도록 돕기 위해 metadata.description 추가
  • Plugin name "x" is not kebab-case: 플러그인 이름에 대문자, 공백 또는 특수 문자가 포함되어 있습니다. 소문자, 숫자 및 하이픈만 사용하도록 이름을 바꿉니다(예: my-plugin). Claude Code는 다른 형식을 허용하지만 Claude.ai 마켓플레이스 동기화는 이를 거부합니다.

플러그인 설치 실패

증상: 마켓플레이스가 나타나지만 플러그인 설치가 실패합니다 해결책:
  • 플러그인 소스 URL이 액세스 가능한지 확인합니다
  • 플러그인 디렉터리에 필수 파일이 포함되어 있는지 확인합니다
  • GitHub 소스의 경우 저장소가 공개이거나 액세스 권한이 있는지 확인합니다
  • 플러그인 소스를 수동으로 복제/다운로드하여 테스트합니다

개인 저장소 인증 실패

증상: 개인 저장소에서 플러그인을 설치할 때 인증 오류 해결책: 수동 설치 및 업데이트의 경우:
  • git 공급자로 인증되었는지 확인합니다(예: GitHub의 경우 gh auth status 실행).
  • 자격 증명 도우미가 올바르게 구성되었는지 확인합니다: git config --global credential.helper
  • 저장소를 수동으로 복제하여 자격 증명이 작동하는지 확인합니다
백그라운드 자동 업데이트의 경우:
  • 환경에서 적절한 토큰이 설정되었는지 확인합니다: echo $GITHUB_TOKEN
  • 토큰에 필수 권한이 있는지 확인합니다(저장소에 대한 읽기 액세스)
  • GitHub의 경우 토큰에 개인 저장소에 대한 repo 범위가 있는지 확인합니다
  • GitLab의 경우 토큰에 최소한 read_repository 범위가 있는지 확인합니다
  • 토큰이 만료되지 않았는지 확인합니다

마켓플레이스 업데이트가 오프라인 환경에서 실패합니다

증상: 마켓플레이스 git pull이 실패하고 Claude Code가 기존 캐시를 삭제하여 플러그인을 사용할 수 없게 됩니다. 원인: 기본적으로 git pull이 실패하면 Claude Code는 오래된 복제본을 제거하고 다시 복제를 시도합니다. 오프라인 또는 에어갭 환경에서 다시 복제가 동일한 방식으로 실패하여 마켓플레이스 디렉터리가 비어 있게 됩니다. 해결책: CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1을 설정하여 pull이 실패할 때 기존 캐시를 삭제하는 대신 유지합니다:
export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1
이 변수가 설정되면 Claude Code는 git pull 실패 시 오래된 마켓플레이스 복제본을 유지하고 마지막으로 알려진 좋은 상태를 계속 사용합니다. 저장소에 절대 도달할 수 없는 완전히 오프라인 배포의 경우 대신 CLAUDE_CODE_PLUGIN_SEED_DIR을 사용하여 빌드 시간에 플러그인 디렉터리를 사전 채웁니다.

Git 작업 시간 초과

증상: 플러그인 설치 또는 마켓플레이스 업데이트가 “Git clone timed out after 120s” 또는 “Git pull timed out after 120s”와 같은 시간 초과 오류로 실패합니다. 원인: Claude Code는 플러그인 저장소 복제 및 마켓플레이스 업데이트 끌어오기를 포함한 모든 git 작업에 120초 시간 초과를 사용합니다. 대규모 저장소 또는 느린 네트워크 연결이 이 제한을 초과할 수 있습니다. 해결책: CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS 환경 변수를 사용하여 시간 초과를 늘립니다. 값은 밀리초 단위입니다:
export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5분

상대 경로가 있는 플러그인이 URL 기반 마켓플레이스에서 실패합니다

증상: URL을 통해 마켓플레이스를 추가했습니다(예: https://example.com/marketplace.json). 하지만 "./plugins/my-plugin"과 같은 상대 경로 소스가 있는 플러그인이 “path not found” 오류로 설치되지 않습니다. 원인: URL 기반 마켓플레이스는 marketplace.json 파일 자체만 다운로드합니다. 서버에서 플러그인 파일을 다운로드하지 않습니다. 마켓플레이스 항목의 상대 경로는 다운로드되지 않은 원격 서버의 파일을 참조합니다. 해결책:
  • 외부 소스 사용: 플러그인 항목을 상대 경로 대신 GitHub, npm 또는 git URL 소스를 사용하도록 변경합니다:
    { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
    
  • Git 기반 마켓플레이스 사용: 마켓플레이스를 Git 저장소에서 호스팅하고 git URL로 추가합니다. Git 기반 마켓플레이스는 전체 저장소를 복제하므로 상대 경로가 올바르게 작동합니다.

설치 후 파일을 찾을 수 없음

증상: 플러그인이 설치되지만 파일 참조가 실패합니다. 특히 플러그인 디렉터리 외부의 파일 원인: 플러그인은 제자리에 사용되지 않고 캐시 디렉터리에 복사됩니다. 플러그인 디렉터리 외부의 파일을 참조하는 경로(예: ../shared-utils)는 해당 파일이 복사되지 않기 때문에 작동하지 않습니다. 해결책: symlink 및 디렉터리 재구성을 포함한 해결 방법은 플러그인 캐싱 및 파일 해석을 참조하세요. 추가 디버깅 도구 및 일반적인 문제는 디버깅 및 개발 도구를 참조하세요.

참고 항목