プラグインマーケットプレイスは、他のユーザーにプラグインを配布できるカタログです。マーケットプレイスは、一元化された検出、バージョン追跡、自動更新、および複数のソースタイプ(Git リポジトリ、ローカルパス、その他)のサポートを提供します。このガイドでは、チームやコミュニティとプラグインを共有するための独自のマーケットプレイスを作成する方法を説明します。
既存のマーケットプレイスからプラグインをインストールしたいですか?既成プラグインの検出とインストールを参照してください。
マーケットプレイスの作成と配布には、以下が含まれます。
- プラグインの作成:コマンド、エージェント、hooks、MCP サーバー、または LSP サーバーを使用して 1 つ以上のプラグインを構築します。このガイドでは、配布するプラグインが既にあることを前提としています。プラグインの作成方法の詳細については、プラグインの作成を参照してください。
- マーケットプレイスファイルの作成:プラグインとその場所を一覧表示する
marketplace.json を定義します(マーケットプレイスファイルの作成を参照)。
- マーケットプレイスのホスト:GitHub、GitLab、または別の Git ホストにプッシュします(マーケットプレイスのホストと配布を参照)。
- ユーザーと共有:ユーザーが
/plugin marketplace add でマーケットプレイスを追加し、個別のプラグインをインストールします(プラグインの検出とインストールを参照)。
マーケットプレイスがライブになったら、リポジトリに変更をプッシュして更新できます。ユーザーは /plugin marketplace update でローカルコピーを更新します。
チュートリアル:ローカルマーケットプレイスの作成
この例では、1 つのプラグイン(コードレビュー用の /quality-review スキル)を含むマーケットプレイスを作成します。ディレクトリ構造を作成し、スキルを追加し、プラグインマニフェストとマーケットプレイスカタログを作成してから、インストールしてテストします。
ディレクトリ構造の作成
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
スキルの作成
/quality-review スキルが何をするかを定義する SKILL.md ファイルを作成します。my-marketplace/plugins/quality-review-plugin/skills/quality-review/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.
プラグインマニフェストの作成
プラグインを説明する plugin.json ファイルを作成します。マニフェストは .claude-plugin/ ディレクトリに配置されます。my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json
{
"name": "quality-review-plugin",
"description": "Adds a /quality-review skill for quick code reviews",
"version": "1.0.0"
}
マーケットプレイスファイルの作成
プラグインを一覧表示するマーケットプレイスカタログを作成します。my-marketplace/.claude-plugin/marketplace.json
{
"name": "my-plugins",
"owner": {
"name": "Your Name"
},
"plugins": [
{
"name": "quality-review-plugin",
"source": "./plugins/quality-review-plugin",
"description": "Adds a /quality-review skill for quick code reviews"
}
]
}
追加とインストール
マーケットプレイスを追加し、プラグインをインストールします。/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins
試してみる
エディタでコードを選択し、新しいコマンドを実行します。
プラグインが実行できることの詳細(hooks、エージェント、MCP サーバー、LSP サーバーを含む)については、プラグインを参照してください。
プラグインのインストール方法:ユーザーがプラグインをインストールすると、Claude Code はプラグインディレクトリをキャッシュロケーションにコピーします。これは、../shared-utils のようなパスを使用してプラグインディレクトリの外部のファイルを参照できないことを意味します。これらのファイルはコピーされないためです。プラグイン間でファイルを共有する必要がある場合は、シンボリックリンクを使用します(コピー中にフォローされます)。詳細については、プラグインキャッシングとファイル解決を参照してください。
マーケットプレイスファイルの作成
リポジトリルートに .claude-plugin/marketplace.json を作成します。このファイルは、マーケットプレイスの名前、所有者情報、およびソースを含むプラグインのリストを定義します。
各プラグインエントリには、最低限 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"
}
]
}
マーケットプレイススキーマ
必須フィールド
| フィールド | タイプ | 説明 | 例 |
|---|
name | string | マーケットプレイス識別子(ケバブケース、スペースなし)。これは公開向けです。ユーザーはプラグインをインストールするときに表示されます(例:/plugin install my-tool@your-marketplace)。 | "acme-tools" |
owner | object | マーケットプレイスメンテナー情報(以下のフィールドを参照) | |
plugins | array | 利用可能なプラグインのリスト | 以下を参照 |
予約名:以下のマーケットプレイス名は Anthropic の公式使用のために予約されており、サードパーティのマーケットプレイスでは使用できません。claude-code-marketplace、claude-code-plugins、claude-plugins-official、anthropic-marketplace、anthropic-plugins、agent-skills、life-sciences。公式マーケットプレイスになりすましている名前(official-claude-plugins や anthropic-tools-v2 など)もブロックされています。
所有者フィールド
| フィールド | タイプ | 必須 | 説明 |
|---|
name | string | はい | メンテナーまたはチームの名前 |
email | string | いいえ | メンテナーの連絡先メール |
オプションメタデータ
| フィールド | タイプ | 説明 |
|---|
metadata.description | string | マーケットプレイスの簡潔な説明 |
metadata.version | string | マーケットプレイスバージョン |
metadata.pluginRoot | string | 相対プラグインソースパスの前に付加される基本ディレクトリ(例:"./plugins" を使用すると、"source": "./plugins/formatter" の代わりに "source": "formatter" と記述できます) |
プラグインエントリ
plugins 配列内の各プラグインエントリは、プラグインとその場所を説明します。プラグインマニフェストスキーマのフィールド(description、version、author、commands、hooks など)を含めることができます。さらに、これらのマーケットプレイス固有のフィールド:source、category、tags、strict があります。
必須フィールド
| フィールド | タイプ | 説明 |
|---|
name | string | プラグイン識別子(ケバブケース、スペースなし)。これは公開向けです。ユーザーはインストール時に表示されます(例:/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)。以下の厳密モードを参照してください。 |
コンポーネント設定フィールド:
| フィールド | タイプ | 説明 |
|---|
commands | string|array | コマンドファイルまたはディレクトリへのカスタムパス |
agents | string|array | エージェントファイルへのカスタムパス |
hooks | string|object | カスタム hooks 設定または hooks ファイルへのパス |
mcpServers | string|object | MCP サーバー設定または MCP 設定ファイルへのパス |
lspServers | string|object | LSP サーバー設定または LSP 設定ファイルへのパス |
プラグインソース
プラグインソースは、マーケットプレイスに一覧表示されている各個別プラグインを取得する場所を Claude Code に指示します。これらは marketplace.json 内の各プラグインエントリの source フィールドで設定されます。
プラグインがローカルマシンにクローンまたはコピーされると、~/.claude/plugins/cache のローカルバージョン管理プラグインキャッシュにコピーされます。
| ソース | タイプ | フィールド | 注記 |
|---|
| 相対パス | string(例:"./my-plugin") | — | マーケットプレイスリポジトリ内のローカルディレクトリ。./ で始まる必要があります |
github | object | repo、ref?、sha? | |
url | object | url(.git で終わる必要があります)、ref?、sha? | Git URL ソース |
git-subdir | object | url、path、ref?、sha? | Git リポジトリ内のサブディレクトリ。帯域幅を最小化するためにスパースクローンします |
npm | object | package、version?、registry? | npm install でインストール |
pip | object | package、version?、registry? | pip でインストール |
マーケットプレイスソースとプラグインソース:これらは異なる概念で、異なるものを制御します。
- マーケットプレイスソース —
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"
}
相対パスは、ユーザーが 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"
}
}
| フィールド | タイプ | 説明 |
|---|
repo | string | 必須。owner/repo 形式の GitHub リポジトリ |
ref | string | オプション。Git ブランチまたはタグ(デフォルトはリポジトリのデフォルトブランチ) |
sha | string | オプション。完全な 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"
}
}
| フィールド | タイプ | 説明 |
|---|
url | string | 必須。完全な Git リポジトリ URL(.git で終わる必要があります) |
ref | string | オプション。Git ブランチまたはタグ(デフォルトはリポジトリのデフォルトブランチ) |
sha | string | オプション。完全な 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([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 コミット 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"
}
}
| フィールド | タイプ | 説明 |
|---|
package | string | 必須。パッケージ名またはスコープ付きパッケージ(例:@org/plugin) |
version | string | オプション。バージョンまたはバージョン範囲(例:2.1.0、^2.0.0、~1.5.0) |
registry | string | オプション。カスタム npm レジストリ URL。デフォルトはシステム npm レジストリ(通常は npmjs.org) |
高度なプラグインエントリ
この例は、コマンド、エージェント、hooks、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}:hooks と MCP サーバー設定でこの変数を使用して、プラグインのインストールディレクトリ内のファイルを参照します。プラグインはインストール時にキャッシュロケーションにコピーされるため、これは必要です。
strict: false:これが false に設定されているため、プラグインは独自の plugin.json を必要としません。マーケットプレイスエントリがすべてを定義します。以下の厳密モードを参照してください。
厳密モード
strict フィールドは、plugin.json がコンポーネント定義(コマンド、エージェント、hooks、スキル、MCP サーバー、出力スタイル)の権限であるかどうかを制御します。
| 値 | 動作 |
|---|
true(デフォルト) | plugin.json が権限です。マーケットプレイスエントリは追加のコンポーネントで補足でき、両方のソースがマージされます。 |
false | マーケットプレイスエントリが完全な定義です。プラグインに plugin.json があってコンポーネントを宣言している場合、それは競合であり、プラグインは読み込みに失敗します。 |
各モードを使用する場合:
strict: true:プラグインは独自の plugin.json を持ち、独自のコンポーネントを管理します。マーケットプレイスエントリは上に追加のコマンドまたは hooks を追加できます。これはデフォルトで、ほとんどのプラグインで機能します。
strict: false:マーケットプレイスオペレーターが完全に制御したい場合。プラグインリポジトリは生ファイルを提供し、マーケットプレイスエントリはそれらのファイルのどれがコマンド、エージェント、hooks などとして公開されるかを定義します。マーケットプレイスがプラグイン作成者の意図と異なる方法でプラグインのコンポーネントを再構成またはキュレートする場合に便利です。
マーケットプレイスのホストと配布
GitHub でホスト(推奨)
GitHub は最も簡単な配布方法を提供します。
- リポジトリを作成:マーケットプレイス用の新しいリポジトリを設定します
- マーケットプレイスファイルを追加:プラグイン定義を含む
.claude-plugin/marketplace.json を作成します
- チームと共有:ユーザーが
/plugin marketplace add owner/repo でマーケットプレイスを追加します
メリット:組み込みバージョン管理、問題追跡、チームコラボレーション機能。
他の 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 キーチェーン、git-credential-store が含まれます。
バックグラウンド自動更新は、認証情報ヘルパーなしで起動時に実行されます。これは、対話的なプロンプトが Claude Code の起動をブロックするためです。プライベートマーケットプレイスの自動更新を有効にするには、環境に適切な認証トークンを設定します。
| プロバイダー | 環境変数 | 注記 |
|---|
| GitHub | GITHUB_TOKEN または GH_TOKEN | 個人用アクセストークンまたは GitHub App トークン |
| GitLab | GITLAB_TOKEN または GL_TOKEN | 個人用アクセストークンまたはプロジェクトトークン |
| Bitbucket | BITBUCKET_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
add コマンドの完全な範囲(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
}
}
完全な設定オプションについては、プラグイン設定を参照してください。
管理マーケットプレイスの制限
プラグインソースを厳密に制御する必要がある組織の場合、管理者は管理設定の 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 サーバーからのすべてのマーケットプレイスを許可する:
{
"strictKnownMarketplaces": [
{
"source": "hostPattern",
"hostPattern": "^github\\.example\\.com$"
}
]
}
パスの正規表現パターンマッチングを使用して、特定のディレクトリからのファイルシステムベースのマーケットプレイスを許可する:
{
"strictKnownMarketplaces": [
{
"source": "pathPattern",
"pathPattern": "^/opt/approved/"
}
]
}
pathPattern として ".*" を使用して、ネットワークソースを hostPattern で制御しながら、任意のファイルシステムパスを許可します。
制限の仕組み
制限はプラグインインストールプロセスの早い段階で検証され、ネットワークリクエストやファイルシステム操作が発生する前に検証されます。これにより、不正なマーケットプレイスアクセスの試みを防ぎます。
ホワイトリストはほとんどのソースタイプに対して正確なマッチングを使用します。マーケットプレイスが許可されるには、指定されたすべてのフィールドが正確に一致する必要があります。
- GitHub ソースの場合:
repo は必須で、ホワイトリストで指定されている場合は ref または path も一致する必要があります
- URL ソースの場合:完全な URL が正確に一致する必要があります
hostPattern ソースの場合:マーケットプレイスホストが正規表現パターンと照合されます
pathPattern ソースの場合:マーケットプレイスのファイルシステムパスが正規表現パターンと照合されます
strictKnownMarketplaces は管理設定で設定されるため、個別のユーザーとプロジェクト設定はこれらの制限をオーバーライドできません。
完全な設定詳細(サポートされているすべてのソースタイプと extraKnownMarketplaces との比較を含む)については、strictKnownMarketplaces リファレンスを参照してください。
バージョン解決とリリースチャネル
プラグインバージョンはキャッシュパスと更新検出を決定します。プラグインマニフェスト(plugin.json)またはマーケットプレイスエントリ(marketplace.json)でバージョンを指定できます。
可能な限り、両方の場所でバージョンを設定することを避けてください。プラグインマニフェストは常に無言で優先されるため、マーケットプレイスバージョンが無視される可能性があります。相対パスプラグインの場合、マーケットプレイスエントリでバージョンを設定します。他のすべてのプラグインソースの場合、プラグインマニフェストで設定します。
リリースチャネルの設定
プラグインの「安定」と「最新」リリースチャネルをサポートするには、同じリポジトリの異なる ref または SHA を指す 2 つのマーケットプレイスを設定できます。その後、管理設定を通じて 2 つのマーケットプレイスを異なるユーザーグループに割り当てることができます。
プラグインの plugin.json は、各固定 ref またはコミットで異なる version を宣言する必要があります。2 つの 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"
}
}
]
}
チャネルをユーザーグループに割り当てる
管理設定を通じて各マーケットプレイスを適切なユーザーグループに割り当てます。例えば、安定グループは以下を受け取ります。
{
"extraKnownMarketplaces": {
"stable-tools": {
"source": {
"source": "github",
"repo": "acme-corp/stable-tools"
}
}
}
}
早期アクセスグループは代わりに latest-tools を受け取ります。
{
"extraKnownMarketplaces": {
"latest-tools": {
"source": {
"source": "github",
"repo": "acme-corp/latest-tools"
}
}
}
}
検証とテスト
共有する前にマーケットプレイスをテストします。
マーケットプレイス JSON 構文を検証します。
または Claude Code 内から:
テスト用にマーケットプレイスを追加します。
/plugin marketplace add ./path/to/marketplace
すべてが機能することを確認するためにテストプラグインをインストールします。
/plugin install test-plugin@marketplace-name
完全なプラグインテストワークフローについては、プラグインをローカルでテストを参照してください。技術的なトラブルシューティングについては、プラグインリファレンスを参照してください。
トラブルシューティング
マーケットプレイスが読み込まれない
症状:マーケットプレイスを追加できない、またはそこからプラグインが表示されない
解決策:
- マーケットプレイス URL がアクセス可能であることを確認します
.claude-plugin/marketplace.json が指定されたパスに存在することを確認します
claude plugin validate または /plugin validate を使用して JSON 構文が有効であることを確認します
- プライベートリポジトリの場合、アクセス権限があることを確認します
マーケットプレイス検証エラー
マーケットプレイスディレクトリから 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 | 2 つのプラグインが同じ名前を共有しています | 各プラグインに一意の name 値を指定します |
plugins[0].source: Path traversal not allowed | ソースパスに .. が含まれています | マーケットプレイスルートに相対的なパスを使用し、.. なしで使用します |
警告(ブロッキングなし):
Marketplace has no plugins defined:plugins 配列に少なくとも 1 つのプラグインを追加します
No marketplace description provided:ユーザーがマーケットプレイスを理解するのに役立つように metadata.description を追加します
プラグインインストール失敗
症状:マーケットプレイスは表示されますが、プラグインインストールが失敗します
解決策:
- プラグインソース URL がアクセス可能であることを確認します
- プラグインディレクトリに必須ファイルが含まれていることを確認します
- GitHub ソースの場合、リポジトリが公開されているか、アクセス権限があることを確認します
- プラグインソースを手動でクローン/ダウンロードしてテストします
プライベートリポジトリ認証が失敗する
症状:プライベートリポジトリからプラグインをインストールするときに認証エラーが発生します
解決策:
手動インストールと更新の場合:
- Git プロバイダーで認証されていることを確認します(例:GitHub の場合は
gh auth status を実行)
- 認証情報ヘルパーが正しく設定されていることを確認します:
git config --global credential.helper
- リポジトリを手動でクローンして、認証情報が機能することを確認します
バックグラウンド自動更新の場合:
- 環境でトークンが設定されていることを確認します:
echo $GITHUB_TOKEN
- トークンに必要な権限があることを確認します(リポジトリへの読み取りアクセス)
- GitHub の場合、トークンがプライベートリポジトリの
repo スコープを持つことを確認します
- GitLab の場合、トークンが少なくとも
read_repository スコープを持つことを確認します
- トークンが期限切れになっていないことを確認します
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 minutes
相対パスを持つプラグインが 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 など)は、それらのファイルがコピーされないため機能しません。
解決策:シンボリックリンクとディレクトリ再構成を含む回避策については、プラグインキャッシングとファイル解決を参照してください。
追加のデバッグツールと一般的な問題については、デバッグと開発ツールを参照してください。
関連項目