플러그인 marketplace 생성 및 배포

팀과 커뮤니티에 Claude Code extension을 배포하기 위한 플러그인 marketplace를 빌드하고 호스팅하세요.

플러그인 marketplace는 다른 사람에게 플러그인을 배포할 수 있는 카탈로그입니다. Marketplace는 중앙 집중식 검색, 버전 추적, 자동 업데이트, 다양한 소스 유형(git 저장소, 로컬 경로 등) 지원을 제공합니다. 이 가이드에서는 팀이나 커뮤니티와 플러그인을 공유하기 위해 자체 marketplace를 만드는 방법을 보여줍니다.

기존 marketplace에서 플러그인을 설치하려면 사전 빌드된 플러그인 검색 및 설치를 참조하세요.

개요

marketplace 생성 및 배포에는 다음이 포함됩니다:

플러그인 생성: 명령어, 에이전트, hook, MCP 서버 또는 LSP 서버가 포함된 하나 이상의 플러그인을 빌드합니다. 이 가이드는 배포할 플러그인이 이미 있다고 가정합니다. 플러그인 만드는 방법에 대해서는 플러그인 생성을 참조하세요.
Marketplace 파일 생성: 플러그인과 찾을 위치를 나열하는 marketplace.json을 정의합니다 (marketplace 파일 생성 참조).
Marketplace 호스팅: GitHub, GitLab 또는 다른 git 호스트에 푸시합니다 (marketplace 호스팅 및 배포 참조).
사용자와 공유: 사용자가 /plugin marketplace add로 marketplace를 추가하고 개별 플러그인을 설치합니다 (플러그인 검색 및 설치 참조).

marketplace가 라이브되면 저장소에 변경 사항을 푸시하여 업데이트할 수 있습니다. 사용자는 /plugin marketplace update로 로컬 복사본을 새로고침합니다.

연습: 로컬 marketplace 만들기

이 예시에서는 코드 리뷰를 위한 /review skill이 포함된 하나의 플러그인으로 marketplace를 만듭니다. 디렉토리 구조를 만들고, skill을 추가하고, 플러그인 매니페스트와 marketplace 카탈로그를 만든 후 설치하고 테스트합니다.

Step 1: 디렉토리 구조 생성

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

Step 2: Skill 생성

/review skill이 수행하는 작업을 정의하는 SKILL.md 파일을 만듭니다.

---
description: Review code for bugs, security, and performance
disable-model-invocation: true
---

Review the code I've selected or the recent changes for:
- Potential bugs or edge cases
- Security concerns
- Performance issues
- Readability improvements

Be concise and actionable.

Step 3: 플러그인 매니페스트 생성

플러그인을 설명하는 plugin.json 파일을 만듭니다. 매니페스트는 .claude-plugin/ 디렉토리에 위치합니다.

{
  "name": "review-plugin",
  "description": "Adds a /review skill for quick code reviews",
  "version": "1.0.0"
}

Step 4: Marketplace 파일 생성

플러그인을 나열하는 marketplace 카탈로그를 만듭니다.

{
  "name": "my-plugins",
  "owner": {
    "name": "Your Name"
  },
  "plugins": [
    {
      "name": "review-plugin",
      "source": "./plugins/review-plugin",
      "description": "Adds a /review skill for quick code reviews"
    }
  ]
}

Step 5: 추가 및 설치

marketplace를 추가하고 플러그인을 설치합니다.

/plugin marketplace add ./my-marketplace
/plugin install review-plugin@my-plugins

Step 6: 사용해 보기

에디터에서 코드를 선택하고 새 명령어를 실행합니다.

/review

hook, 에이전트, MCP 서버, LSP 서버를 포함하여 플러그인이 할 수 있는 것에 대해 더 알아보려면 Plugins를 참조하세요.

참고:

플러그인 설치 방식: 사용자가 플러그인을 설치하면 Claude Code는 플러그인 디렉토리를 캐시 위치에 복사합니다. 이는 플러그인이 ../shared-utils와 같은 경로를 사용하여 디렉토리 외부의 파일을 참조할 수 없다는 것을 의미합니다. 해당 파일은 복사되지 않기 때문입니다.

플러그인 간에 파일을 공유해야 하는 경우 심볼릭 링크를 사용하세요 (복사 시 따라갑니다). 자세한 내용은 플러그인 캐싱 및 파일 해석을 참조하세요.

Marketplace 파일 생성

저장소 루트에 .claude-plugin/marketplace.json을 만듭니다. 이 파일은 marketplace의 이름, 소유자 정보, 소스와 함께 플러그인 목록을 정의합니다.

각 플러그인 항목에는 최소한 name과 source(가져올 위치)가 필요합니다. 사용 가능한 모든 필드에 대해서는 아래 전체 스키마를 참조하세요.

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "[email protected]"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

Marketplace 스키마

필수 필드

필드	타입	설명	예시
`name`	string	Marketplace 식별자 (kebab-case, 공백 없음). 이것은 공개적으로 표시됩니다: 사용자가 플러그인 설치 시 확인합니다 (예: `/plugin install my-tool@your-marketplace`).	`"acme-tools"`
`owner`	object	Marketplace 관리자 정보 (아래 필드 참조)
`plugins`	array	사용 가능한 플러그인 목록	아래 참조

참고:

예약된 이름: 다음 marketplace 이름은 공식 Anthropic용으로 예약되어 있으며 서드파티 marketplace에서 사용할 수 없습니다: claude-code-marketplace, claude-code-plugins, claude-plugins-official, anthropic-marketplace, anthropic-plugins, agent-skills, life-sciences. 공식 marketplace를 사칭하는 이름(예: official-claude-plugins 또는 anthropic-tools-v2)도 차단됩니다.

Owner 필드

필드	타입	필수	설명
`name`	string	예	관리자 또는 팀 이름
`email`	string	아니오	관리자 연락 이메일

선택적 메타데이터

필드	타입	설명
`metadata.description`	string	간단한 marketplace 설명
`metadata.version`	string	Marketplace 버전
`metadata.pluginRoot`	string	상대 플러그인 소스 경로 앞에 추가되는 기본 디렉토리 (예: `"./plugins"`로 설정하면 `"source": "./plugins/formatter"` 대신 `"source": "formatter"`로 작성 가능)

플러그인 항목

plugins 배열의 각 플러그인 항목은 플러그인과 찾을 위치를 설명합니다. 플러그인 매니페스트 스키마의 모든 필드(description, version, author, commands, hooks 등)를 포함할 수 있으며, marketplace 전용 필드인 source, category, tags, strict도 추가할 수 있습니다.

필수 필드

필드	타입	설명
`name`	string	플러그인 식별자 (kebab-case, 공백 없음). 이것은 공개적으로 표시됩니다: 사용자가 설치 시 확인합니다 (예: `/plugin install my-plugin@marketplace`).
`source`	string\|object	플러그인을 가져올 위치 (아래 플러그인 소스 참조)

선택적 플러그인 필드

표준 메타데이터 필드:

필드	타입	설명
`description`	string	간단한 플러그인 설명
`version`	string	플러그인 버전
`author`	object	플러그인 작성자 정보 (`name` 필수, `email` 선택)
`homepage`	string	플러그인 홈페이지 또는 문서 URL
`repository`	string	소스 코드 저장소 URL
`license`	string	SPDX 라이선스 식별자 (예: MIT, Apache-2.0)
`keywords`	array	플러그인 검색 및 분류를 위한 태그
`category`	string	정리를 위한 플러그인 카테고리
`tags`	array	검색을 위한 태그
`strict`	boolean	`plugin.json`이 컴포넌트 정의의 권한을 가지는지 제어합니다 (기본값: true). 아래 Strict 모드 참조.

컴포넌트 구성 필드:

필드	타입	설명
`commands`	string\|array	명령어 파일 또는 디렉토리의 커스텀 경로
`agents`	string\|array	에이전트 파일의 커스텀 경로
`hooks`	string\|object	커스텀 hook 구성 또는 hook 파일 경로
`mcpServers`	string\|object	MCP 서버 구성 또는 MCP 설정 경로
`lspServers`	string\|object	LSP 서버 구성 또는 LSP 설정 경로

플러그인 소스

플러그인 소스는 Claude Code에 marketplace에 나열된 각 개별 플러그인을 가져올 위치를 알려줍니다. 이것은 marketplace.json의 각 플러그인 항목에서 source 필드에 설정됩니다.

플러그인이 로컬 머신에 클론되거나 복사되면 ~/.claude/plugins/cache의 로컬 버전 관리 플러그인 캐시에 복사됩니다.

소스	타입	필드	참고
상대 경로	`string` (예: `"./my-plugin"`)	—	marketplace 저장소 내의 로컬 디렉토리. `./`로 시작해야 합니다
`github`	object	`repo`, `ref?`, `sha?`
`url`	object	`url` (.git으로 끝나야 함), `ref?`, `sha?`	Git URL 소스
`git-subdir`	object	`url`, `path`, `ref?`, `sha?`	git 저장소 내의 하위 디렉토리. 모노레포의 대역폭을 최소화하기 위해 sparse clone 사용
`npm`	object	`package`, `version?`, `registry?`	`npm install`로 설치
`pip`	object	`package`, `version?`, `registry?`	pip으로 설치

참고:

Marketplace 소스 vs 플러그인 소스: 이것은 서로 다른 것을 제어하는 서로 다른 개념입니다.

Marketplace 소스 — marketplace.json 카탈로그 자체를 가져올 위치. 사용자가 /plugin marketplace add를 실행하거나 extraKnownMarketplaces 설정에서 설정됩니다. ref(브랜치/태그)를 지원하지만 sha는 지원하지 않습니다.

플러그인 소스 — marketplace에 나열된 개별 플러그인을 가져올 위치. marketplace.json 내 각 플러그인 항목의 source 필드에 설정됩니다. ref(브랜치/태그)와 sha(정확한 커밋) 모두 지원합니다.

예를 들어, acme-corp/plugin-catalog(marketplace 소스)에 호스팅된 marketplace가 acme-corp/code-formatter(플러그인 소스)에서 가져오는 플러그인을 나열할 수 있습니다. marketplace 소스와 플러그인 소스는 서로 다른 저장소를 가리키며 독립적으로 고정됩니다.

상대 경로

같은 저장소의 플러그인:

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

참고:

상대 경로는 사용자가 Git(GitHub, GitLab 또는 git URL)을 통해 marketplace를 추가할 때만 작동합니다. 사용자가 marketplace.json 파일에 대한 직접 URL로 marketplace를 추가하면 상대 경로가 올바르게 해석되지 않습니다. 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"
  }
}

필드	타입	설명
`repo`	string	필수. `owner/repo` 형식의 GitHub 저장소
`ref`	string	선택. Git 브랜치 또는 태그 (기본값은 저장소의 기본 브랜치)
`sha`	string	선택. 정확한 버전에 고정하기 위한 40자 git commit 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"
  }
}

필드	타입	설명
`url`	string	필수. 전체 git 저장소 URL (`.git`으로 끝나야 함)
`ref`	string	선택. Git 브랜치 또는 태그 (기본값은 저장소의 기본 브랜치)
`sha`	string	선택. 정확한 버전에 고정하기 위한 40자 git commit SHA

Git 하위 디렉토리

git-subdir를 사용하여 git 저장소의 하위 디렉토리에 있는 플러그인을 가리킵니다. Claude Code는 sparse, partial clone을 사용하여 하위 디렉토리만 가져오므로 대규모 모노레포의 대역폭을 최소화합니다.

{
  "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([email protected]:owner/repo.git)도 허용합니다.

필드	타입	설명
`url`	string	필수. Git 저장소 URL, GitHub `owner/repo` 단축 형식 또는 SSH URL
`path`	string	필수. 플러그인이 포함된 저장소 내 하위 디렉토리 경로 (예: `"tools/claude-plugin"`)
`ref`	string	선택. Git 브랜치 또는 태그 (기본값은 저장소의 기본 브랜치)
`sha`	string	선택. 정확한 버전에 고정하기 위한 40자 git commit SHA

npm 패키지

npm 패키지로 배포되는 플러그인은 npm install로 설치됩니다. 공개 npm registry 또는 팀이 호스팅하는 프라이빗 registry의 모든 패키지에서 작동합니다.

{
  "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에서 설치하려면 registry 필드를 추가합니다:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

필드	타입	설명
`package`	string	필수. 패키지 이름 또는 scoped 패키지 (예: `@org/plugin`)
`version`	string	선택. 버전 또는 버전 범위 (예: `2.1.0`, `^2.0.0`, `~1.5.0`)
`registry`	string	선택. 커스텀 npm registry URL. 기본값은 시스템 npm registry (일반적으로 npmjs.org)

고급 플러그인 항목

이 예시는 명령어, 에이전트, hook, MCP 서버의 커스텀 경로를 포함한 많은 선택적 필드를 사용하는 플러그인 항목을 보여줍니다:

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "[email protected]"
  },
  "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
}

주요 사항:

commands와 agents: 여러 디렉토리 또는 개별 파일을 지정할 수 있습니다. 경로는 플러그인 루트를 기준으로 합니다.
${CLAUDE_PLUGIN_ROOT}: hook과 MCP 서버 구성에서 플러그인 설치 디렉토리 내의 파일을 참조하기 위해 이 변수를 사용합니다. 플러그인은 설치 시 캐시 위치에 복사되므로 이것이 필요합니다.
strict: false: false로 설정되었으므로 플러그인에 자체 plugin.json이 필요하지 않습니다. marketplace 항목이 모든 것을 정의합니다. 아래 Strict 모드를 참조하세요.

Strict 모드

strict 필드는 plugin.json이 컴포넌트 정의(명령어, 에이전트, hook, skill, MCP 서버, 출력 스타일)에 대한 권한을 가지는지 제어합니다.

값	동작
`true` (기본값)	`plugin.json`이 권한입니다. marketplace 항목은 추가 컴포넌트로 보완할 수 있으며, 두 소스가 병합됩니다.
`false`	marketplace 항목이 전체 정의입니다. 플러그인에도 컴포넌트를 선언하는 `plugin.json`이 있으면 충돌이 발생하고 플러그인이 로드에 실패합니다.

각 모드를 사용할 때:

strict: true: 플러그인이 자체 plugin.json을 가지고 자체 컴포넌트를 관리합니다. marketplace 항목은 추가 명령어나 hook을 위에 추가할 수 있습니다. 이것이 기본값이며 대부분의 플러그인에 적합합니다.
strict: false: marketplace 운영자가 완전한 제어를 원합니다. 플러그인 저장소는 원시 파일을 제공하고 marketplace 항목이 해당 파일 중 어떤 것이 명령어, 에이전트, hook 등으로 노출되는지 정의합니다. marketplace가 플러그인 작성자의 의도와 다르게 플러그인의 컴포넌트를 재구성하거나 큐레이션할 때 유용합니다.

Marketplace 호스팅 및 배포

GitHub에서 호스팅 (권장)

GitHub은 가장 쉬운 배포 방법을 제공합니다:

저장소 생성: marketplace를 위한 새 저장소를 설정합니다
Marketplace 파일 추가: 플러그인 정의가 포함된 .claude-plugin/marketplace.json을 만듭니다
팀과 공유: 사용자가 /plugin marketplace add owner/repo로 marketplace를 추가합니다

장점: 내장된 버전 관리, 이슈 추적, 팀 협업 기능.

다른 git 서비스에서 호스팅

GitLab, Bitbucket, 자체 호스팅 서버 등 모든 git 호스팅 서비스에서 작동합니다. 사용자는 전체 저장소 URL로 추가합니다:

/plugin marketplace add https://gitlab.com/company/plugins.git

프라이빗 저장소

Claude Code는 프라이빗 저장소에서 플러그인 설치를 지원합니다. 수동 설치 및 업데이트의 경우 Claude Code는 기존 git 자격 증명 도우미를 사용합니다. 터미널에서 프라이빗 저장소에 대해 git clone이 작동하면 Claude Code에서도 작동합니다. 일반적인 자격 증명 도우미에는 GitHub용 gh auth login, macOS Keychain, git-credential-store가 포함됩니다.

백그라운드 자동 업데이트는 시작 시 자격 증명 도우미 없이 실행됩니다. 대화형 프롬프트가 Claude Code 시작을 차단할 수 있기 때문입니다. 프라이빗 marketplace의 자동 업데이트를 활성화하려면 환경에 적절한 인증 토큰을 설정하세요:

제공자	환경 변수	참고
GitHub	`GITHUB_TOKEN` 또는 `GH_TOKEN`	Personal access token 또는 GitHub App token
GitLab	`GITLAB_TOKEN` 또는 `GL_TOKEN`	Personal access token 또는 project token
Bitbucket	`BITBUCKET_TOKEN`	App password 또는 repository access token

셸 구성 파일(예: .bashrc, .zshrc)에서 토큰을 설정하거나 Claude Code 실행 시 전달합니다:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

참고:

CI/CD 환경에서는 토큰을 시크릿 환경 변수로 구성하세요. GitHub Actions는 같은 조직의 저장소에 대해 자동으로 GITHUB_TOKEN을 제공합니다.

배포 전 로컬 테스트

공유하기 전에 marketplace를 로컬로 테스트하세요:

/plugin marketplace add ./my-local-marketplace
/plugin install test-plugin@my-local-marketplace

추가 명령(GitHub, Git URL, 로컬 경로, 원격 URL)의 전체 범위에 대해서는 Marketplace 추가를 참조하세요.

팀에 marketplace 필수화

팀 멤버가 프로젝트 폴더를 신뢰할 때 marketplace를 자동으로 설치하라는 메시지가 표시되도록 저장소를 구성할 수 있습니다. .claude/settings.json에 marketplace를 추가하세요:

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

기본적으로 활성화할 플러그인도 지정할 수 있습니다:

{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

전체 구성 옵션에 대해서는 플러그인 설정을 참조하세요.

Managed marketplace 제한

플러그인 소스에 대한 엄격한 제어가 필요한 조직의 경우 관리자는 managed settings의 strictKnownMarketplaces 설정을 사용하여 사용자가 추가할 수 있는 플러그인 marketplace를 제한할 수 있습니다.

managed settings에서 strictKnownMarketplaces가 구성되면 제한 동작은 값에 따라 달라집니다:

값	동작
미정의 (기본값)	제한 없음. 사용자가 모든 marketplace를 추가할 수 있음
빈 배열 `[]`	완전 잠금. 사용자가 새 marketplace를 추가할 수 없음
소스 목록	사용자가 허용 목록과 정확히 일치하는 marketplace만 추가 가능

일반적인 구성

모든 marketplace 추가 비활성화:

{
  "strictKnownMarketplaces": []
}

특정 marketplace만 허용:

{
  "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 서버의 모든 marketplace 허용:

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

경로에 대한 정규식 패턴 매칭을 사용하여 특정 디렉토리의 파일 시스템 기반 marketplace 허용:

{
  "strictKnownMarketplaces": [
    {
      "source": "pathPattern",
      "pathPattern": "^/opt/approved/"
    }
  ]
}

pathPattern으로 ".*"를 사용하면 네트워크 소스는 hostPattern으로 제어하면서 모든 파일 시스템 경로를 허용할 수 있습니다.

제한 작동 방식

제한은 네트워크 요청이나 파일 시스템 작업이 발생하기 전 플러그인 설치 프로세스 초기에 검증됩니다. 이를 통해 무단 marketplace 접근 시도를 방지합니다.

허용 목록은 대부분의 소스 유형에 대해 정확한 매칭을 사용합니다. marketplace가 허용되려면 지정된 모든 필드가 정확히 일치해야 합니다:

GitHub 소스: repo가 필수이며, 허용 목록에 지정된 경우 ref 또는 path도 일치해야 합니다
URL 소스: 전체 URL이 정확히 일치해야 합니다
hostPattern 소스: marketplace 호스트가 정규식 패턴과 매칭됩니다
pathPattern 소스: marketplace의 파일 시스템 경로가 정규식 패턴과 매칭됩니다

strictKnownMarketplaces는 managed settings에서 설정되므로 개별 사용자 및 프로젝트 구성은 이러한 제한을 재정의할 수 없습니다.

지원되는 모든 소스 유형과 extraKnownMarketplaces와의 비교를 포함한 전체 구성 세부 사항은 strictKnownMarketplaces 레퍼런스를 참조하세요.

버전 해석 및 릴리스 채널

플러그인 버전은 캐시 경로와 업데이트 감지를 결정합니다. 플러그인 매니페스트(plugin.json) 또는 marketplace 항목(marketplace.json)에서 버전을 지정할 수 있습니다.

주의:

가능하면 두 곳 모두에서 버전을 설정하지 마세요. 플러그인 매니페스트가 항상 조용히 우선하므로 marketplace 버전이 무시될 수 있습니다. 상대 경로 플러그인의 경우 marketplace 항목에 버전을 설정하세요. 다른 모든 플러그인 소스의 경우 플러그인 매니페스트에 설정하세요.

릴리스 채널 설정

플러그인의 "stable"과 "latest" 릴리스 채널을 지원하려면 같은 저장소의 다른 ref 또는 SHA를 가리키는 두 개의 marketplace를 설정할 수 있습니다. 그런 다음 managed settings를 통해 두 marketplace를 다른 사용자 그룹에 할당할 수 있습니다.

주의:

플러그인의 plugin.json은 각 고정된 ref 또는 커밋에서 다른 version을 선언해야 합니다. 두 ref 또는 커밋이 같은 매니페스트 버전을 가지면 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"
      }
    }
  ]
}

사용자 그룹에 채널 할당

managed settings를 통해 각 marketplace를 적절한 사용자 그룹에 할당합니다. 예를 들어, stable 그룹은 다음을 받습니다:

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/stable-tools"
      }
    }
  }
}

얼리 액세스 그룹은 대신 latest-tools를 받습니다:

{
  "extraKnownMarketplaces": {
    "latest-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/latest-tools"
      }
    }
  }
}

검증 및 테스트

공유하기 전에 marketplace를 테스트하세요.

marketplace JSON 구문 검증:

claude plugin validate .

또는 Claude Code 내에서:

/plugin validate .

테스트를 위해 marketplace 추가:

/plugin marketplace add ./path/to/marketplace

모든 것이 작동하는지 확인하기 위해 테스트 플러그인 설치:

/plugin install test-plugin@marketplace-name

전체 플러그인 테스트 워크플로우에 대해서는 플러그인 로컬 테스트를 참조하세요. 기술적 문제 해결에 대해서는 Plugins reference를 참조하세요.

문제 해결

Marketplace가 로드되지 않음

증상: marketplace를 추가하거나 플러그인을 볼 수 없음

해결 방법:

marketplace URL이 접근 가능한지 확인
지정된 경로에 .claude-plugin/marketplace.json이 존재하는지 확인
claude plugin validate 또는 /plugin validate를 사용하여 JSON 구문이 유효한지 확인
프라이빗 저장소의 경우 접근 권한이 있는지 확인

Marketplace 검증 오류

marketplace 디렉토리에서 claude plugin validate . 또는 /plugin validate .를 실행하여 문제를 확인합니다. 일반적인 오류:

오류	원인	해결 방법
`File not found: .claude-plugin/marketplace.json`	매니페스트 누락	필수 필드가 포함된 `.claude-plugin/marketplace.json` 생성
`Invalid JSON syntax: Unexpected token...`	JSON 구문 오류	누락된 쉼표, 추가 쉼표 또는 따옴표 없는 문자열 확인
`Duplicate plugin name "x" found in marketplace`	두 플러그인이 같은 이름을 공유	각 플러그인에 고유한 `name` 값 부여
`plugins[0].source: Path traversal not allowed`	소스 경로에 `..` 포함	`..` 없이 marketplace 루트 기준 상대 경로 사용

경고 (비차단):

Marketplace has no plugins defined: plugins 배열에 최소 하나의 플러그인을 추가
No marketplace description provided: 사용자가 marketplace를 이해할 수 있도록 metadata.description 추가

플러그인 설치 실패

증상: marketplace는 나타나지만 플러그인 설치가 실패

해결 방법:

플러그인 소스 URL이 접근 가능한지 확인
플러그인 디렉토리에 필요한 파일이 포함되어 있는지 확인
GitHub 소스의 경우 저장소가 공개되어 있거나 접근 권한이 있는지 확인
수동으로 클론/다운로드하여 플러그인 소스를 테스트

프라이빗 저장소 인증 실패

증상: 프라이빗 저장소에서 플러그인 설치 시 인증 오류

해결 방법:

수동 설치 및 업데이트:

git 제공자에 인증되어 있는지 확인 (예: GitHub의 경우 gh auth status 실행)
자격 증명 도우미가 올바르게 구성되어 있는지 확인: git config --global credential.helper
자격 증명이 작동하는지 확인하기 위해 저장소를 수동으로 클론 시도

백그라운드 자동 업데이트:

환경에 적절한 토큰이 설정되어 있는지 확인: echo $GITHUB_TOKEN
토큰에 필요한 권한(저장소 읽기 접근)이 있는지 확인
GitHub의 경우 프라이빗 저장소에 대해 토큰에 repo scope가 있는지 확인
GitLab의 경우 토큰에 최소 read_repository scope가 있는지 확인
토큰이 만료되지 않았는지 확인

Git 작업 시간 초과

증상: 플러그인 설치 또는 marketplace 업데이트가 "Git clone timed out after 120s" 또는 "Git pull timed out after 120s"와 같은 타임아웃 오류로 실패.

원인: Claude Code는 플러그인 저장소 클론 및 marketplace 업데이트 풀을 포함한 모든 git 작업에 120초 타임아웃을 사용합니다. 대규모 저장소나 느린 네트워크 연결은 이 제한을 초과할 수 있습니다.

해결 방법: CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS 환경 변수를 사용하여 타임아웃을 늘립니다. 값은 밀리초 단위입니다:

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5분

URL 기반 marketplace에서 상대 경로 플러그인 실패

증상: URL(예: https://example.com/marketplace.json)로 marketplace를 추가했지만 "./plugins/my-plugin"과 같은 상대 경로 소스를 가진 플러그인이 "path not found" 오류로 설치 실패.

원인: URL 기반 marketplace는 marketplace.json 파일 자체만 다운로드합니다. 서버에서 플러그인 파일을 다운로드하지 않습니다. marketplace 항목의 상대 경로는 다운로드되지 않은 원격 서버의 파일을 참조합니다.

해결 방법:

외부 소스 사용: 플러그인 항목을 상대 경로 대신 GitHub, npm 또는 git URL 소스를 사용하도록 변경:
```
{ "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
```
Git 기반 marketplace 사용: Git 저장소에 marketplace를 호스팅하고 git URL로 추가합니다. Git 기반 marketplace는 전체 저장소를 클론하므로 상대 경로가 올바르게 작동합니다.

설치 후 파일을 찾을 수 없음

증상: 플러그인이 설치되었지만 파일에 대한 참조가 실패, 특히 플러그인 디렉토리 외부의 파일

원인: 플러그인은 제자리에서 사용되지 않고 캐시 디렉토리에 복사됩니다. 플러그인 디렉토리 외부의 파일을 참조하는 경로(../shared-utils 등)는 해당 파일이 복사되지 않으므로 작동하지 않습니다.

해결 방법: 심볼릭 링크 및 디렉토리 재구성을 포함한 해결 방법은 플러그인 캐싱 및 파일 해석을 참조하세요.

추가 디버깅 도구와 일반적인 문제에 대해서는 디버깅 및 개발 도구를 참조하세요.

참고 자료

사전 빌드된 플러그인 검색 및 설치 - 기존 marketplace에서 플러그인 설치
Plugins - 자체 플러그인 만들기
Plugins reference - 전체 기술 사양 및 스키마
플러그인 설정 - 플러그인 구성 옵션
strictKnownMarketplaces 레퍼런스 - managed marketplace 제한

플러그인 marketplace 생성 및 배포

팀과 커뮤니티에 Claude Code extension을 배포하기 위한 플러그인 marketplace를 빌드하고 호스팅하세요.

기존 marketplace에서 플러그인을 설치하려면 사전 빌드된 플러그인 검색 및 설치를 참조하세요.

개요

marketplace 생성 및 배포에는 다음이 포함됩니다:

플러그인 생성: 명령어, 에이전트, hook, MCP 서버 또는 LSP 서버가 포함된 하나 이상의 플러그인을 빌드합니다. 이 가이드는 배포할 플러그인이 이미 있다고 가정합니다. 플러그인 만드는 방법에 대해서는 플러그인 생성을 참조하세요.
Marketplace 파일 생성: 플러그인과 찾을 위치를 나열하는 marketplace.json을 정의합니다 (marketplace 파일 생성 참조).
Marketplace 호스팅: GitHub, GitLab 또는 다른 git 호스트에 푸시합니다 (marketplace 호스팅 및 배포 참조).
사용자와 공유: 사용자가 /plugin marketplace add로 marketplace를 추가하고 개별 플러그인을 설치합니다 (플러그인 검색 및 설치 참조).

marketplace가 라이브되면 저장소에 변경 사항을 푸시하여 업데이트할 수 있습니다. 사용자는 /plugin marketplace update로 로컬 복사본을 새로고침합니다.

연습: 로컬 marketplace 만들기

Step 1: 디렉토리 구조 생성

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

Step 2: Skill 생성

/review skill이 수행하는 작업을 정의하는 SKILL.md 파일을 만듭니다.

---
description: Review code for bugs, security, and performance
disable-model-invocation: true
---

Review the code I've selected or the recent changes for:
- Potential bugs or edge cases
- Security concerns
- Performance issues
- Readability improvements

Be concise and actionable.

Step 3: 플러그인 매니페스트 생성

플러그인을 설명하는 plugin.json 파일을 만듭니다. 매니페스트는 .claude-plugin/ 디렉토리에 위치합니다.

{
  "name": "review-plugin",
  "description": "Adds a /review skill for quick code reviews",
  "version": "1.0.0"
}

Step 4: Marketplace 파일 생성

플러그인을 나열하는 marketplace 카탈로그를 만듭니다.

{
  "name": "my-plugins",
  "owner": {
    "name": "Your Name"
  },
  "plugins": [
    {
      "name": "review-plugin",
      "source": "./plugins/review-plugin",
      "description": "Adds a /review skill for quick code reviews"
    }
  ]
}

Step 5: 추가 및 설치

marketplace를 추가하고 플러그인을 설치합니다.

/plugin marketplace add ./my-marketplace
/plugin install review-plugin@my-plugins

Step 6: 사용해 보기

에디터에서 코드를 선택하고 새 명령어를 실행합니다.

/review

hook, 에이전트, MCP 서버, LSP 서버를 포함하여 플러그인이 할 수 있는 것에 대해 더 알아보려면 Plugins를 참조하세요.

참고:

플러그인 설치 방식: 사용자가 플러그인을 설치하면 Claude Code는 플러그인 디렉토리를 캐시 위치에 복사합니다. 이는 플러그인이 ../shared-utils와 같은 경로를 사용하여 디렉토리 외부의 파일을 참조할 수 없다는 것을 의미합니다. 해당 파일은 복사되지 않기 때문입니다.

플러그인 간에 파일을 공유해야 하는 경우 심볼릭 링크를 사용하세요 (복사 시 따라갑니다). 자세한 내용은 플러그인 캐싱 및 파일 해석을 참조하세요.

Marketplace 파일 생성

저장소 루트에 .claude-plugin/marketplace.json을 만듭니다. 이 파일은 marketplace의 이름, 소유자 정보, 소스와 함께 플러그인 목록을 정의합니다.

각 플러그인 항목에는 최소한 name과 source(가져올 위치)가 필요합니다. 사용 가능한 모든 필드에 대해서는 아래 전체 스키마를 참조하세요.

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "[email protected]"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

Marketplace 스키마

필수 필드

필드	타입	설명	예시
`name`	string	Marketplace 식별자 (kebab-case, 공백 없음). 이것은 공개적으로 표시됩니다: 사용자가 플러그인 설치 시 확인합니다 (예: `/plugin install my-tool@your-marketplace`).	`"acme-tools"`
`owner`	object	Marketplace 관리자 정보 (아래 필드 참조)
`plugins`	array	사용 가능한 플러그인 목록	아래 참조

참고:

예약된 이름: 다음 marketplace 이름은 공식 Anthropic용으로 예약되어 있으며 서드파티 marketplace에서 사용할 수 없습니다: claude-code-marketplace, claude-code-plugins, claude-plugins-official, anthropic-marketplace, anthropic-plugins, agent-skills, life-sciences. 공식 marketplace를 사칭하는 이름(예: official-claude-plugins 또는 anthropic-tools-v2)도 차단됩니다.

Owner 필드

필드	타입	필수	설명
`name`	string	예	관리자 또는 팀 이름
`email`	string	아니오	관리자 연락 이메일

선택적 메타데이터

필드	타입	설명
`metadata.description`	string	간단한 marketplace 설명
`metadata.version`	string	Marketplace 버전
`metadata.pluginRoot`	string	상대 플러그인 소스 경로 앞에 추가되는 기본 디렉토리 (예: `"./plugins"`로 설정하면 `"source": "./plugins/formatter"` 대신 `"source": "formatter"`로 작성 가능)

플러그인 항목

필수 필드

필드	타입	설명
`name`	string	플러그인 식별자 (kebab-case, 공백 없음). 이것은 공개적으로 표시됩니다: 사용자가 설치 시 확인합니다 (예: `/plugin install my-plugin@marketplace`).
`source`	string\|object	플러그인을 가져올 위치 (아래 플러그인 소스 참조)

선택적 플러그인 필드

표준 메타데이터 필드:

필드	타입	설명
`description`	string	간단한 플러그인 설명
`version`	string	플러그인 버전
`author`	object	플러그인 작성자 정보 (`name` 필수, `email` 선택)
`homepage`	string	플러그인 홈페이지 또는 문서 URL
`repository`	string	소스 코드 저장소 URL
`license`	string	SPDX 라이선스 식별자 (예: MIT, Apache-2.0)
`keywords`	array	플러그인 검색 및 분류를 위한 태그
`category`	string	정리를 위한 플러그인 카테고리
`tags`	array	검색을 위한 태그
`strict`	boolean	`plugin.json`이 컴포넌트 정의의 권한을 가지는지 제어합니다 (기본값: true). 아래 Strict 모드 참조.

컴포넌트 구성 필드:

필드	타입	설명
`commands`	string\|array	명령어 파일 또는 디렉토리의 커스텀 경로
`agents`	string\|array	에이전트 파일의 커스텀 경로
`hooks`	string\|object	커스텀 hook 구성 또는 hook 파일 경로
`mcpServers`	string\|object	MCP 서버 구성 또는 MCP 설정 경로
`lspServers`	string\|object	LSP 서버 구성 또는 LSP 설정 경로

플러그인 소스

플러그인이 로컬 머신에 클론되거나 복사되면 ~/.claude/plugins/cache의 로컬 버전 관리 플러그인 캐시에 복사됩니다.

소스	타입	필드	참고
상대 경로	`string` (예: `"./my-plugin"`)	—	marketplace 저장소 내의 로컬 디렉토리. `./`로 시작해야 합니다
`github`	object	`repo`, `ref?`, `sha?`
`url`	object	`url` (.git으로 끝나야 함), `ref?`, `sha?`	Git URL 소스
`git-subdir`	object	`url`, `path`, `ref?`, `sha?`	git 저장소 내의 하위 디렉토리. 모노레포의 대역폭을 최소화하기 위해 sparse clone 사용
`npm`	object	`package`, `version?`, `registry?`	`npm install`로 설치
`pip`	object	`package`, `version?`, `registry?`	pip으로 설치

참고:

Marketplace 소스 vs 플러그인 소스: 이것은 서로 다른 것을 제어하는 서로 다른 개념입니다.

Marketplace 소스 — marketplace.json 카탈로그 자체를 가져올 위치. 사용자가 /plugin marketplace add를 실행하거나 extraKnownMarketplaces 설정에서 설정됩니다. ref(브랜치/태그)를 지원하지만 sha는 지원하지 않습니다.

플러그인 소스 — marketplace에 나열된 개별 플러그인을 가져올 위치. marketplace.json 내 각 플러그인 항목의 source 필드에 설정됩니다. ref(브랜치/태그)와 sha(정확한 커밋) 모두 지원합니다.

예를 들어, acme-corp/plugin-catalog(marketplace 소스)에 호스팅된 marketplace가 acme-corp/code-formatter(플러그인 소스)에서 가져오는 플러그인을 나열할 수 있습니다. marketplace 소스와 플러그인 소스는 서로 다른 저장소를 가리키며 독립적으로 고정됩니다.

상대 경로

같은 저장소의 플러그인:

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

참고:

상대 경로는 사용자가 Git(GitHub, GitLab 또는 git URL)을 통해 marketplace를 추가할 때만 작동합니다. 사용자가 marketplace.json 파일에 대한 직접 URL로 marketplace를 추가하면 상대 경로가 올바르게 해석되지 않습니다. 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"
  }
}

필드	타입	설명
`repo`	string	필수. `owner/repo` 형식의 GitHub 저장소
`ref`	string	선택. Git 브랜치 또는 태그 (기본값은 저장소의 기본 브랜치)
`sha`	string	선택. 정확한 버전에 고정하기 위한 40자 git commit 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"
  }
}

필드	타입	설명
`url`	string	필수. 전체 git 저장소 URL (`.git`으로 끝나야 함)
`ref`	string	선택. Git 브랜치 또는 태그 (기본값은 저장소의 기본 브랜치)
`sha`	string	선택. 정확한 버전에 고정하기 위한 40자 git commit SHA

Git 하위 디렉토리

{
  "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([email protected]:owner/repo.git)도 허용합니다.

필드	타입	설명
`url`	string	필수. Git 저장소 URL, GitHub `owner/repo` 단축 형식 또는 SSH URL
`path`	string	필수. 플러그인이 포함된 저장소 내 하위 디렉토리 경로 (예: `"tools/claude-plugin"`)
`ref`	string	선택. Git 브랜치 또는 태그 (기본값은 저장소의 기본 브랜치)
`sha`	string	선택. 정확한 버전에 고정하기 위한 40자 git commit SHA

npm 패키지

npm 패키지로 배포되는 플러그인은 npm install로 설치됩니다. 공개 npm registry 또는 팀이 호스팅하는 프라이빗 registry의 모든 패키지에서 작동합니다.

{
  "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에서 설치하려면 registry 필드를 추가합니다:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

필드	타입	설명
`package`	string	필수. 패키지 이름 또는 scoped 패키지 (예: `@org/plugin`)
`version`	string	선택. 버전 또는 버전 범위 (예: `2.1.0`, `^2.0.0`, `~1.5.0`)
`registry`	string	선택. 커스텀 npm registry URL. 기본값은 시스템 npm registry (일반적으로 npmjs.org)

고급 플러그인 항목

이 예시는 명령어, 에이전트, hook, MCP 서버의 커스텀 경로를 포함한 많은 선택적 필드를 사용하는 플러그인 항목을 보여줍니다:

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "[email protected]"
  },
  "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
}

주요 사항:

commands와 agents: 여러 디렉토리 또는 개별 파일을 지정할 수 있습니다. 경로는 플러그인 루트를 기준으로 합니다.
${CLAUDE_PLUGIN_ROOT}: hook과 MCP 서버 구성에서 플러그인 설치 디렉토리 내의 파일을 참조하기 위해 이 변수를 사용합니다. 플러그인은 설치 시 캐시 위치에 복사되므로 이것이 필요합니다.
strict: false: false로 설정되었으므로 플러그인에 자체 plugin.json이 필요하지 않습니다. marketplace 항목이 모든 것을 정의합니다. 아래 Strict 모드를 참조하세요.

Strict 모드

strict 필드는 plugin.json이 컴포넌트 정의(명령어, 에이전트, hook, skill, MCP 서버, 출력 스타일)에 대한 권한을 가지는지 제어합니다.

값	동작
`true` (기본값)	`plugin.json`이 권한입니다. marketplace 항목은 추가 컴포넌트로 보완할 수 있으며, 두 소스가 병합됩니다.
`false`	marketplace 항목이 전체 정의입니다. 플러그인에도 컴포넌트를 선언하는 `plugin.json`이 있으면 충돌이 발생하고 플러그인이 로드에 실패합니다.

각 모드를 사용할 때:

strict: true: 플러그인이 자체 plugin.json을 가지고 자체 컴포넌트를 관리합니다. marketplace 항목은 추가 명령어나 hook을 위에 추가할 수 있습니다. 이것이 기본값이며 대부분의 플러그인에 적합합니다.
strict: false: marketplace 운영자가 완전한 제어를 원합니다. 플러그인 저장소는 원시 파일을 제공하고 marketplace 항목이 해당 파일 중 어떤 것이 명령어, 에이전트, hook 등으로 노출되는지 정의합니다. marketplace가 플러그인 작성자의 의도와 다르게 플러그인의 컴포넌트를 재구성하거나 큐레이션할 때 유용합니다.

Marketplace 호스팅 및 배포

GitHub에서 호스팅 (권장)

GitHub은 가장 쉬운 배포 방법을 제공합니다:

저장소 생성: marketplace를 위한 새 저장소를 설정합니다
Marketplace 파일 추가: 플러그인 정의가 포함된 .claude-plugin/marketplace.json을 만듭니다
팀과 공유: 사용자가 /plugin marketplace add owner/repo로 marketplace를 추가합니다

장점: 내장된 버전 관리, 이슈 추적, 팀 협업 기능.

다른 git 서비스에서 호스팅

GitLab, Bitbucket, 자체 호스팅 서버 등 모든 git 호스팅 서비스에서 작동합니다. 사용자는 전체 저장소 URL로 추가합니다:

/plugin marketplace add https://gitlab.com/company/plugins.git

프라이빗 저장소

제공자	환경 변수	참고
GitHub	`GITHUB_TOKEN` 또는 `GH_TOKEN`	Personal access token 또는 GitHub App token
GitLab	`GITLAB_TOKEN` 또는 `GL_TOKEN`	Personal access token 또는 project token
Bitbucket	`BITBUCKET_TOKEN`	App password 또는 repository access token

셸 구성 파일(예: .bashrc, .zshrc)에서 토큰을 설정하거나 Claude Code 실행 시 전달합니다:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

참고:

CI/CD 환경에서는 토큰을 시크릿 환경 변수로 구성하세요. GitHub Actions는 같은 조직의 저장소에 대해 자동으로 GITHUB_TOKEN을 제공합니다.

배포 전 로컬 테스트

공유하기 전에 marketplace를 로컬로 테스트하세요:

/plugin marketplace add ./my-local-marketplace
/plugin install test-plugin@my-local-marketplace

추가 명령(GitHub, Git URL, 로컬 경로, 원격 URL)의 전체 범위에 대해서는 Marketplace 추가를 참조하세요.

팀에 marketplace 필수화

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

기본적으로 활성화할 플러그인도 지정할 수 있습니다:

{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

전체 구성 옵션에 대해서는 플러그인 설정을 참조하세요.

Managed marketplace 제한

managed settings에서 strictKnownMarketplaces가 구성되면 제한 동작은 값에 따라 달라집니다:

값	동작
미정의 (기본값)	제한 없음. 사용자가 모든 marketplace를 추가할 수 있음
빈 배열 `[]`	완전 잠금. 사용자가 새 marketplace를 추가할 수 없음
소스 목록	사용자가 허용 목록과 정확히 일치하는 marketplace만 추가 가능

일반적인 구성

모든 marketplace 추가 비활성화:

{
  "strictKnownMarketplaces": []
}

특정 marketplace만 허용:

{
  "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 서버의 모든 marketplace 허용:

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

경로에 대한 정규식 패턴 매칭을 사용하여 특정 디렉토리의 파일 시스템 기반 marketplace 허용:

{
  "strictKnownMarketplaces": [
    {
      "source": "pathPattern",
      "pathPattern": "^/opt/approved/"
    }
  ]
}

pathPattern으로 ".*"를 사용하면 네트워크 소스는 hostPattern으로 제어하면서 모든 파일 시스템 경로를 허용할 수 있습니다.

제한 작동 방식

허용 목록은 대부분의 소스 유형에 대해 정확한 매칭을 사용합니다. marketplace가 허용되려면 지정된 모든 필드가 정확히 일치해야 합니다:

GitHub 소스: repo가 필수이며, 허용 목록에 지정된 경우 ref 또는 path도 일치해야 합니다
URL 소스: 전체 URL이 정확히 일치해야 합니다
hostPattern 소스: marketplace 호스트가 정규식 패턴과 매칭됩니다
pathPattern 소스: marketplace의 파일 시스템 경로가 정규식 패턴과 매칭됩니다

strictKnownMarketplaces는 managed settings에서 설정되므로 개별 사용자 및 프로젝트 구성은 이러한 제한을 재정의할 수 없습니다.

지원되는 모든 소스 유형과 extraKnownMarketplaces와의 비교를 포함한 전체 구성 세부 사항은 strictKnownMarketplaces 레퍼런스를 참조하세요.

버전 해석 및 릴리스 채널

주의:

가능하면 두 곳 모두에서 버전을 설정하지 마세요. 플러그인 매니페스트가 항상 조용히 우선하므로 marketplace 버전이 무시될 수 있습니다. 상대 경로 플러그인의 경우 marketplace 항목에 버전을 설정하세요. 다른 모든 플러그인 소스의 경우 플러그인 매니페스트에 설정하세요.

릴리스 채널 설정

주의:

플러그인의 plugin.json은 각 고정된 ref 또는 커밋에서 다른 version을 선언해야 합니다. 두 ref 또는 커밋이 같은 매니페스트 버전을 가지면 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"
      }
    }
  ]
}

사용자 그룹에 채널 할당

managed settings를 통해 각 marketplace를 적절한 사용자 그룹에 할당합니다. 예를 들어, stable 그룹은 다음을 받습니다:

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/stable-tools"
      }
    }
  }
}

얼리 액세스 그룹은 대신 latest-tools를 받습니다:

{
  "extraKnownMarketplaces": {
    "latest-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/latest-tools"
      }
    }
  }
}

검증 및 테스트

공유하기 전에 marketplace를 테스트하세요.

marketplace JSON 구문 검증:

claude plugin validate .

또는 Claude Code 내에서:

/plugin validate .

테스트를 위해 marketplace 추가:

/plugin marketplace add ./path/to/marketplace

모든 것이 작동하는지 확인하기 위해 테스트 플러그인 설치:

/plugin install test-plugin@marketplace-name

전체 플러그인 테스트 워크플로우에 대해서는 플러그인 로컬 테스트를 참조하세요. 기술적 문제 해결에 대해서는 Plugins reference를 참조하세요.

문제 해결

Marketplace가 로드되지 않음

증상: marketplace를 추가하거나 플러그인을 볼 수 없음

해결 방법:

marketplace URL이 접근 가능한지 확인
지정된 경로에 .claude-plugin/marketplace.json이 존재하는지 확인
claude plugin validate 또는 /plugin validate를 사용하여 JSON 구문이 유효한지 확인
프라이빗 저장소의 경우 접근 권한이 있는지 확인

Marketplace 검증 오류

marketplace 디렉토리에서 claude plugin validate . 또는 /plugin validate .를 실행하여 문제를 확인합니다. 일반적인 오류:

오류	원인	해결 방법
`File not found: .claude-plugin/marketplace.json`	매니페스트 누락	필수 필드가 포함된 `.claude-plugin/marketplace.json` 생성
`Invalid JSON syntax: Unexpected token...`	JSON 구문 오류	누락된 쉼표, 추가 쉼표 또는 따옴표 없는 문자열 확인
`Duplicate plugin name "x" found in marketplace`	두 플러그인이 같은 이름을 공유	각 플러그인에 고유한 `name` 값 부여
`plugins[0].source: Path traversal not allowed`	소스 경로에 `..` 포함	`..` 없이 marketplace 루트 기준 상대 경로 사용

경고 (비차단):

Marketplace has no plugins defined: plugins 배열에 최소 하나의 플러그인을 추가
No marketplace description provided: 사용자가 marketplace를 이해할 수 있도록 metadata.description 추가

플러그인 설치 실패

증상: marketplace는 나타나지만 플러그인 설치가 실패

해결 방법:

플러그인 소스 URL이 접근 가능한지 확인
플러그인 디렉토리에 필요한 파일이 포함되어 있는지 확인
GitHub 소스의 경우 저장소가 공개되어 있거나 접근 권한이 있는지 확인
수동으로 클론/다운로드하여 플러그인 소스를 테스트

프라이빗 저장소 인증 실패

증상: 프라이빗 저장소에서 플러그인 설치 시 인증 오류

해결 방법:

수동 설치 및 업데이트:

git 제공자에 인증되어 있는지 확인 (예: GitHub의 경우 gh auth status 실행)
자격 증명 도우미가 올바르게 구성되어 있는지 확인: git config --global credential.helper
자격 증명이 작동하는지 확인하기 위해 저장소를 수동으로 클론 시도

백그라운드 자동 업데이트:

환경에 적절한 토큰이 설정되어 있는지 확인: echo $GITHUB_TOKEN
토큰에 필요한 권한(저장소 읽기 접근)이 있는지 확인
GitHub의 경우 프라이빗 저장소에 대해 토큰에 repo scope가 있는지 확인
GitLab의 경우 토큰에 최소 read_repository scope가 있는지 확인
토큰이 만료되지 않았는지 확인

Git 작업 시간 초과

증상: 플러그인 설치 또는 marketplace 업데이트가 "Git clone timed out after 120s" 또는 "Git pull timed out after 120s"와 같은 타임아웃 오류로 실패.

해결 방법: CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS 환경 변수를 사용하여 타임아웃을 늘립니다. 값은 밀리초 단위입니다:

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5분

URL 기반 marketplace에서 상대 경로 플러그인 실패

해결 방법:

외부 소스 사용: 플러그인 항목을 상대 경로 대신 GitHub, npm 또는 git URL 소스를 사용하도록 변경:
```
{ "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
```
Git 기반 marketplace 사용: Git 저장소에 marketplace를 호스팅하고 git URL로 추가합니다. Git 기반 marketplace는 전체 저장소를 클론하므로 상대 경로가 올바르게 작동합니다.

설치 후 파일을 찾을 수 없음

증상: 플러그인이 설치되었지만 파일에 대한 참조가 실패, 특히 플러그인 디렉토리 외부의 파일

해결 방법: 심볼릭 링크 및 디렉토리 재구성을 포함한 해결 방법은 플러그인 캐싱 및 파일 해석을 참조하세요.

추가 디버깅 도구와 일반적인 문제에 대해서는 디버깅 및 개발 도구를 참조하세요.

참고 자료

사전 빌드된 플러그인 검색 및 설치 - 기존 marketplace에서 플러그인 설치
Plugins - 자체 플러그인 만들기
Plugins reference - 전체 기술 사양 및 스키마
플러그인 설정 - 플러그인 구성 옵션
strictKnownMarketplaces 레퍼런스 - managed marketplace 제한

55. 플러그인 marketplace 생성 및 배포

플러그인 marketplace 생성 및 배포

개요

연습: 로컬 marketplace 만들기

Step 1: 디렉토리 구조 생성

Step 2: Skill 생성

Step 3: 플러그인 매니페스트 생성

Step 4: Marketplace 파일 생성

Step 5: 추가 및 설치

Step 6: 사용해 보기

Marketplace 파일 생성

Marketplace 스키마

필수 필드

Owner 필드

선택적 메타데이터

플러그인 항목

필수 필드

선택적 플러그인 필드

플러그인 소스

상대 경로

GitHub 저장소

Git 저장소

Git 하위 디렉토리

npm 패키지

고급 플러그인 항목

Strict 모드

Marketplace 호스팅 및 배포

GitHub에서 호스팅 (권장)

다른 git 서비스에서 호스팅

프라이빗 저장소

배포 전 로컬 테스트

팀에 marketplace 필수화

Managed marketplace 제한

일반적인 구성

제한 작동 방식

버전 해석 및 릴리스 채널

릴리스 채널 설정

예시

사용자 그룹에 채널 할당

검증 및 테스트

문제 해결

Marketplace가 로드되지 않음

Marketplace 검증 오류

플러그인 설치 실패

프라이빗 저장소 인증 실패

Git 작업 시간 초과

URL 기반 marketplace에서 상대 경로 플러그인 실패

설치 후 파일을 찾을 수 없음

참고 자료

55. 플러그인 marketplace 생성 및 배포

플러그인 marketplace 생성 및 배포

개요

연습: 로컬 marketplace 만들기

Step 1: 디렉토리 구조 생성

Step 2: Skill 생성

Step 3: 플러그인 매니페스트 생성

Step 4: Marketplace 파일 생성

Step 5: 추가 및 설치

Step 6: 사용해 보기

Marketplace 파일 생성

Marketplace 스키마

필수 필드

Owner 필드

선택적 메타데이터

플러그인 항목

필수 필드

선택적 플러그인 필드

플러그인 소스

상대 경로

GitHub 저장소

Git 저장소

Git 하위 디렉토리

npm 패키지

고급 플러그인 항목

Strict 모드

Marketplace 호스팅 및 배포

GitHub에서 호스팅 (권장)

다른 git 서비스에서 호스팅

프라이빗 저장소

배포 전 로컬 테스트