概要
マーケットプレイスの作成と配布には、以下が含まれます。- プラグインの作成:skills、agents、hooks、MCP サーバー、または LSP サーバーを使用して 1 つ以上のプラグインを構築します。このガイドでは、配布するプラグインが既にあることを前提としています。プラグインの作成方法の詳細については、プラグインの作成を参照してください。
- マーケットプレイスファイルの作成:プラグインとその場所を一覧表示する
marketplace.jsonを定義します。マーケットプレイスファイルの作成を参照してください。 - マーケットプレイスのホスト:GitHub、GitLab、または別の Git ホストにプッシュします。マーケットプレイスのホストと配布を参照してください。
- ユーザーと共有:ユーザーが
/plugin marketplace addでマーケットプレイスを追加し、個別のプラグインをインストールします。プラグインの検出とインストールを参照してください。
/plugin marketplace update でローカルコピーを更新します。
チュートリアル:ローカルマーケットプレイスの作成
この例では、1 つのプラグイン(コードレビュー用のquality-review skill)を含むマーケットプレイスを作成します。ディレクトリ構造を作成し、skill を追加し、プラグインマニフェストとマーケットプレイスカタログを作成してから、インストールしてテストします。
1
ディレクトリ構造の作成
2
skill の作成
quality-review skill が何をするかを定義する SKILL.md ファイルを作成します。my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md
3
プラグインマニフェストの作成
プラグインを説明する
plugin.json ファイルを作成します。マニフェストは .claude-plugin/ ディレクトリに配置されます。my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json
version を設定すると、ユーザーはこのフィールドを変更した場合にのみ更新を受け取ります。そのため、リリースのたびにバージョンを上げてください。version を省略し、このマーケットプレイスを git でホストする場合、すべてのコミットが自動的に新しいバージョンとしてカウントされます。バージョン解決を参照して、適切なアプローチを選択してください。4
マーケットプレイスファイルの作成
プラグインを一覧表示するマーケットプレイスカタログを作成します。
my-marketplace/.claude-plugin/marketplace.json
5
追加とインストール
マーケットプレイスを追加し、プラグインをインストールします。
6
試してみる
エディタでコードを選択し、新しい skill を実行します。プラグイン skill はプラグイン名でネームスペース化されます。
プラグインのインストール方法:ユーザーがプラグインをインストールすると、Claude Code はプラグインディレクトリをキャッシュロケーションにコピーします。これは、
../shared-utils のようなパスを使用してプラグインディレクトリの外部のファイルを参照できないことを意味します。これらのファイルはコピーされないためです。プラグイン間でファイルを共有する必要がある場合は、symlinks を使用します。詳細については、プラグインキャッシングとファイル解決を参照してください。マーケットプレイスファイルの作成
リポジトリルートに.claude-plugin/marketplace.json を作成します。このファイルは、マーケットプレイスの名前、所有者情報、およびソースを含むプラグインのリストを定義します。
各プラグインエントリには、最低限 name と source(Claude Code がどこから取得するかを指定)が必要です。利用可能なすべてのフィールドについては、以下の完全なスキーマを参照してください。
マーケットプレイススキーマ
必須フィールド
予約名:以下のマーケットプレイス名は Anthropic の公式使用のために予約されており、サードパーティのマーケットプレイスでは使用できません:
claude-code-marketplace、claude-code-plugins、claude-plugins-official、claude-plugins-community、claude-community、anthropic-marketplace、anthropic-plugins、agent-skills、anthropic-agent-skills、knowledge-work-plugins、life-sciences、claude-for-legal、claude-for-financial-services、financial-services-plugins、first-party-plugins、healthcare。公式マーケットプレイスになりすましている名前(official-claude-plugins や anthropic-plugins-v2 など)もブロックされています。これらの名前を予約することで、サードパーティのマーケットプレイスが Anthropic 公開ソースとして自らを提示することを防ぎます。Claude Code は、マーケットプレイスを追加するときだけでなく、マーケットプレイスをロードするたびに予約名を再チェックします。これらの名前の 1 つの下に登録されていたマーケットプレイスが、その名前が予約されるようになると、ロードが停止し、信頼できないソースから登録されていることを報告します。そのマーケットプレイスを削除し、公式 Anthropic ソースから再度追加してください。新しく予約された名前の影響を受けるサードパーティのマーケットプレイスは、別の名前の下で再度追加するとすぐにロードされます。v2.1.205 より前では、first-party-plugins と healthcare は予約されておらず、予約名の下に既に登録されているマーケットプレイスはロードされ続けていました。所有者フィールド
オプションフィールド
description と version は後方互換性のため metadata の下でも受け入れられます。
プラグインエントリ
plugins 配列内の各プラグインエントリは、プラグインとその場所を説明します。プラグインマニフェストスキーマのフィールド(description、version、author、commands、hooks など)を含めることができます。さらに、これらのマーケットプレイス固有のフィールド:source、category、tags、strict、および relevance があります。
必須フィールド
オプションプラグインフィールド
標準メタデータフィールド:
コンポーネント設定フィールド:
プラグインソース
プラグインソースは、マーケットプレイスに一覧表示されている各個別プラグインを取得する場所を Claude Code に指示します。これらはmarketplace.json 内の各プラグインエントリの source フィールドで設定されます。
Claude Code がプラグインをローカルマシンにクローンまたはダウンロードした後、プラグインは ~/.claude/plugins/cache のローカルバージョン管理プラグインキャッシュにコピーされます。
マーケットプレイスソースとプラグインソース:これらは異なる概念で、異なるものを制御します。
- マーケットプレイスソース:
marketplace.jsonカタログ自体を取得する場所。ユーザーが/plugin marketplace addを実行するか、extraKnownMarketplaces設定で設定されます。ref(ブランチ/タグ)をサポートしますが、shaはサポートしません。 - プラグインソース:マーケットプレイスに一覧表示されている個別プラグインを取得する場所。
marketplace.json内の各プラグインエントリのsourceフィールドで設定されます。ref(ブランチ/タグ)とsha(正確なコミット)の両方をサポートします。
acme-corp/plugin-catalog(マーケットプレイスソース)でホストされているマーケットプレイスは、acme-corp/code-formatter(プラグインソース)から取得されたプラグインを一覧表示できます。マーケットプレイスソースとプラグインソースは異なるリポジトリを指し、独立して固定されます。github、url、および git-subdir です。ref と sha の両方がそれらのいずれかに設定されている場合、sha が有効なピンです。Claude Code はピンされたコミットを直接取得してチェックアウトします。
GitHub、GitLab、Bitbucket を含むほとんどの Git ホストでは、ブランチまたは ref で指定されたタグが上流で削除されていても、コミットがリポジトリから到達可能である限り、インストールは成功します。AWS CodeCommit などの一部のサーバーは、SHA によるコミットの取得をサポートしていません。これらのサーバーでは、ref が存在し、ピンされたコミットがそこから到達可能である必要があります。
相対パス
同じリポジトリ内のプラグインの場合、./ で始まるパスを使用します。
.claude-plugin/ を含むディレクトリ)に相対的に解決されます。上記の例では、./plugins/my-plugin は <repo>/plugins/my-plugin を指します。marketplace.json は <repo>/.claude-plugin/marketplace.json に存在していても同じです。../ を使用してマーケットプレイスルートの外を参照しないでください。
相対パスはマーケットプレイスのローカルコピーに対して解決されるため、ユーザーが Git ソースまたはローカルディレクトリからマーケットプレイスを追加する場合に機能します。ユーザーが
marketplace.json ファイルへの直接 URL でマーケットプレイスを追加する場合、相対パスは解決されません。そのファイルのみがダウンロードされるためです。URL ベースの配布の場合は、GitHub、npm、または Git URL ソースを使用してください。詳細については、トラブルシューティングを参照してください。GitHub リポジトリ
Git リポジトリ
Git サブディレクトリ
git-subdir を使用して、Git リポジトリのサブディレクトリ内に存在するプラグインを指します。Claude Code はスパースな部分クローンを使用してサブディレクトリのみを取得し、大規模なモノレポの帯域幅を最小化します。
url フィールドは、GitHub ショートハンド(owner/repo)または SSH URL(git@github.com:owner/repo.git)も受け入れます。
npm パッケージ
npm パッケージとして配布されるプラグインは、npm install を使用してインストールされます。これは、公開 npm レジストリまたはチームがホストするプライベートレジストリ上の任意のパッケージで機能します。
version フィールドを追加します。
registry フィールドを追加します。
高度なプラグインエントリ
この例は、commands、agents、hooks、MCP サーバーのカスタムパスを含む、多くのオプションフィールドを使用するプラグインエントリを示しています。commandsとagents:複数のディレクトリまたは個別のファイルを指定できます。パスはプラグインルートに相対的です。${CLAUDE_PLUGIN_ROOT}:hooks と MCP サーバー設定でこの変数を使用して、プラグインのインストールディレクトリ内のファイルを参照します。プラグインはインストール時にキャッシュロケーションにコピーされるため、これは必要です。- サーバータイプごとにどの設定フィールドがそれを置換するかについては、置換テーブルを参照してください
- 依存関係またはプラグイン更新後も保持する必要がある状態については、代わりに
${CLAUDE_PLUGIN_DATA}を使用します
strict: false:これが false に設定されているため、プラグインは独自のplugin.jsonを必要としません。マーケットプレイスエントリがすべてを定義します。以下の厳密モードを参照してください。
source の下の skills/ ディレクトリから読み込まれます。skills フィールドに一覧表示されているパスはそのスキャンに追加されます。
source: "./" )で 1 つの skills/ フォルダを共有する場合、各エントリが独自の skills のみを読み込むように、特定のサブディレクトリを代わりに一覧表示します。
source を使用する場合、一覧表示されたパスはそのエントリの完全なセットであり、共有 skills/ フォルダ内の他のディレクトリは読み込まれません。./skills/ 自体またはプラグインルートを一覧表示すると、完全なスキャンが保持されます。一覧表示されたパスが存在しない場合、デフォルトスキャンが代わりに実行されます。
厳密モード
strict フィールドは、plugin.json がコンポーネント定義(skills、agents、hooks、MCP サーバー、出力スタイル)の権限であるかどうかを制御します。
各モードを使用する場合:
strict: true:プラグインは独自のplugin.jsonを持ち、独自のコンポーネントを管理します。マーケットプレイスエントリは上に追加の skills または hooks を追加できます。これはデフォルトで、ほとんどのプラグインで機能します。strict: false:マーケットプレイスオペレーターが完全に制御したい場合。プラグインリポジトリは生ファイルを提供し、マーケットプレイスエントリはそれらのファイルのどれが skills、agents、hooks などとして公開されるかを定義します。マーケットプレイスがプラグイン作成者の意図と異なる方法でプラグインのコンポーネントを再構成またはキュレートする場合に便利です。
マーケットプレイスのホストと配布
GitHub でホスト(推奨)
GitHub はマーケットプレイスをホストして配布するための推奨される方法です。- リポジトリを作成:マーケットプレイス用の新しいリポジトリを設定します
- マーケットプレイスファイルを追加:プラグイン定義を含む
.claude-plugin/marketplace.jsonを作成します - チームと共有:ユーザーが
/plugin marketplace add owner/repoでマーケットプレイスを追加します
他の Git サービスでホスト
GitLab、Bitbucket、自己ホスト型サーバーなど、任意の Git ホスティングサービスが機能します。ユーザーは完全なリポジトリ URL で追加します。プライベートリポジトリ
Claude Code はプライベートリポジトリからプラグインをインストールすることをサポートしています。手動インストールと更新の場合、Claude Code は既存の Git 認証情報ヘルパーを使用するため、HTTPS アクセスはgh auth login、macOS キーチェーン、または git-credential-store 経由で機能し、ターミナルと同じように動作します。SSH アクセスは、ホストが既に known_hosts ファイルにあり、キーが ssh-agent に読み込まれている限り機能します。Claude Code はホストフィンガープリントとキーパスフレーズの対話的な SSH プロンプトを抑制するためです。GitHub の owner/repo ショートハンドソースはデフォルトで SSH 経由でクローンされます。代わりに HTTPS 経由でクローンするには、CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 を設定します。
バックグラウンド自動更新は異なる方法で機能します。デフォルトでは、バックグラウンドリフレッシュは git pull の Git 認証情報ヘルパーを無効にするため、ヘルパーが設定されている場合でも、プルは HTTPS 経由でプライベートリポジトリに認証できません。SSH リモートは影響を受けません。ssh-agent に読み込まれたキーは、手動操作と同じ方法でバックグラウンドプルを認証します。バックグラウンドプルが失敗すると、Claude Code はマーケットプレイスをゼロから再クローンすることにフォールバックします。再クローンは保存された Git 認証情報を使用しますが、大規模なリポジトリではタイムアウトする可能性がありますため、プライベートマーケットプレイスの自動更新は断続的に失敗する可能性があります。
2 つの設定により、プライベートマーケットプレイスは予測可能に動作します。
CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1を設定して、バックグラウンドプルが失敗したときに削除して再クローンする代わりに、既存のクローンを保持します。プラグインは最後に同期された状態から機能し続け、/plugin marketplace updateでの手動更新は引き続き認証情報でプルします。- Git 認証情報ヘルパーを設定します。例えば GitHub の場合は
gh auth setup-gitを使用して、再クローンフォールバックがプロンプトなしで認証できるようにします。
GITHUB_TOKEN などのプロバイダートークンを設定しても、それ自体ではバックグラウンド認証は有効になりません。トークンは設定された認証情報ヘルパー(例えば gh CLI のヘルパー)を通じてのみ有効になります。これは GH_TOKEN と GITHUB_TOKEN を読み込みます。
バックグラウンドプル自体が HTTPS 経由で認証するようにするには、グローバル Git URL リライトを設定します。リライトはトークンをリモート URL に埋め込むため、バックグラウンドプルが認証情報ヘルパーを無効にしても有効になり、成功したプルは再クローンフォールバックをスキップします。次の例は、マーケットプレイスリポジトリの URL をアクセストークンを含むようにリライトします。
リライトはトークンを gitconfig にプレーンテキストで保存するため、マーケットプレイスリポジトリへの読み取り専用アクセス権を持つトークンを使用します。
CI/CD 環境では、プライベートリポジトリからプラグインをインストールする前に Git 認証情報ヘルパーを設定します。GitHub Actions では、マーケットプレイスリポジトリへの読み取りアクセス権を持つトークンを
GH_TOKEN としてエクスポートしてから、gh auth setup-git を実行します。デフォルトワークフロートークンはワークフロー自身のリポジトリにのみアクセスできるため、別のリポジトリ内のプライベートマーケットプレイスには個人用アクセストークンまたはアプリトークンが必要です。パイプラインで設定されたグローバル URL リライトもバックグラウンドプルを直接認証します。配布前にローカルでテスト
共有する前にマーケットプレイスをローカルでテストします。チーム向けマーケットプレイスの要求
リポジトリを設定して、チームメンバーがプロジェクトフォルダを信頼するときにマーケットプレイスをインストールするよう自動的に促されるようにできます。マーケットプレイスを.claude/settings.json に追加します。
ローカル
directory または file ソースを相対パスで使用する場合、パスはリポジトリのメインチェックアウトに対して解決されます。Git worktrees から Claude Code を実行する場合、パスはメインチェックアウトを指し続けるため、すべての worktrees は同じマーケットプレイスロケーションを共有します。マーケットプレイス状態は、プロジェクトごとではなく、ユーザーごとに 1 回 ~/.claude/plugins/known_marketplaces.json に保存されます。コンテナ用にプラグインを事前入力する
コンテナイメージと CI 環境の場合、ビルド時にプラグインディレクトリを事前入力して、Claude Code が実行時にクローンすることなく、マーケットプレイスとプラグインが既に利用可能な状態で起動するようにできます。CLAUDE_CODE_PLUGIN_SEED_DIR 環境変数をこのディレクトリを指すように設定します。
複数のシードディレクトリをレイヤーするには、Unix では : で、Windows では ; でパスを区切ります。Claude Code は各ディレクトリを順番に検索し、特定のマーケットプレイスまたはプラグインキャッシュを含む最初のシードが優先されます。
シードディレクトリは ~/.claude/plugins の構造をミラーリングします。
~/.claude/plugins ディレクトリをイメージにコピーして、CLAUDE_CODE_PLUGIN_SEED_DIR をそれを指すように設定します。
コピーステップをスキップするには、ビルド中に CLAUDE_CODE_PLUGIN_CACHE_DIR をターゲットシードパスに設定して、プラグインが直接そこにインストールされるようにします。
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 設定を使用して、ユーザーが追加できるプラグインマーケットプレイスを制限できます。また、単一実行のために CLI フラグをサイドロードするプラグイン、エージェント、MCP サーバーを拒否するには、disableSideloadFlags と組み合わせます。コンテキストインストール提案として表示できるマーケットプレイスのプラグインをホワイトリストに登録するには、pluginSuggestionMarketplaces を設定します。
strictKnownMarketplaces が管理設定で設定されている場合、制限動作は値によって異なります。
一般的な設定
すべてのマーケットプレイス追加を無効にする:pathPattern として ".*" を使用して、ネットワークソースを hostPattern で制御しながら、任意のファイルシステムパスを許可します。
strictKnownMarketplaces はユーザーが追加できるものを制限しますが、マーケットプレイスを自動的に登録しません。許可されたマーケットプレイスをユーザーが /plugin marketplace add を実行せずに自動的に利用可能にするには、同じ managed-settings.json で extraKnownMarketplaces と組み合わせます。両方を一緒に使用するを参照してください。制限の仕組み
制限はネットワークまたはファイルシステム操作の前にチェックされます。チェックはマーケットプレイス追加時およびプラグインのインストール、更新、リフレッシュ、自動更新時に実行されます。マーケットプレイスがポリシー設定前に追加され、そのソースがホワイトリストと一致しなくなった場合、Claude Code はそこからプラグインをインストールまたは更新することを拒否します。同じ強制がblockedMarketplaces に適用されます。
ホワイトリストはほとんどのソースタイプに対して正確なマッチングを使用します。マーケットプレイスが許可されるには、指定されたすべてのフィールドが正確に一致する必要があります。
- GitHub ソースの場合:
repoは必須で、ホワイトリストで指定されている場合はrefまたはpathも一致する必要があります - URL ソースの場合:完全な URL が正確に一致する必要があります
hostPatternソースの場合:マーケットプレイスホストが正規表現パターンと照合されますpathPatternソースの場合:マーケットプレイスのファイルシステムパスが正規表現パターンと照合されます
.git サフィックス、または ssh:// と https:// の形式は異なる値として扱われます。組織のマーケットプレイスが複数の URL 形式でクローンできる場合、リテラル URL よりも hostPattern エントリを優先して、すべての形式が一致するようにします。
strictKnownMarketplaces は管理設定で設定されるため、個別のユーザーとプロジェクト設定はこれらの制限をオーバーライドできません。
完全な設定詳細(サポートされているすべてのソースタイプと extraKnownMarketplaces との比較を含む)については、strictKnownMarketplaces リファレンスを参照してください。
バージョン解決とリリースチャネル
プラグインバージョンはキャッシュパスと更新検出を決定します。解決されたバージョンがユーザーが既に持っているものと一致する場合、/plugin update と自動更新はプラグインをスキップします。
Claude Code はプラグインのバージョンを以下の最初のものから解決します。
- プラグインの
plugin.jsonのversion - プラグインのマーケットプレイスエントリの
version - プラグインのソースの Git コミット SHA
github、url、git-subdir、および Git ホスト型マーケットプレイス内の相対パスの場合、version を完全に省略でき、すべての新しいコミットが新しいバージョンとして扱われます。これは内部または積極的に開発されているプラグインの最も簡単なセットアップです。
リリースチャネルの設定
プラグインの「安定」と「最新」リリースチャネルをサポートするには、同じリポジトリの異なる ref または SHA を指す 2 つのマーケットプレイスを設定できます。その後、管理設定を通じて 2 つのマーケットプレイスを異なるユーザーグループに割り当てることができます。latest-tools を受け取ります。
プラグイン依存関係バージョンをピンする
プラグインは依存関係を semver 範囲に制限して、依存関係の更新が依存プラグインを破壊しないようにできます。{plugin-name}--v{version} Git タグ規約、範囲構文、および同じ依存関係に対する複数の制約がどのように組み合わされるかについては、プラグイン依存関係バージョンを制限するを参照してください。
プラグインの名前変更または削除
プラグインのname はその安定識別子です。ユーザーは enabledPlugins、pluginConfigs、および /plugin install コマンドでそれを参照するため、それを変更するとすべての既存インストールが破壊されます。UI に表示されるラベルを既存インストールを破壊することなく変更するには、displayName を設定して name を変更しないままにします。
プラグインの name を変更する必要がある場合、または plugins 配列からプラグインを削除する場合は、既存ユーザーが plugin-not-found エラーを見る代わりに移行するように、トップレベルの renames エントリを追加します。自動移行には Claude Code v2.1.193 以降が必要です。各前の名前を現在の名前にマップするか、プラグインが存在しなくなった場合は null にマップします。次の例は formatter を code-formatter に名前変更し、legacy-linter が削除されたことを記録します。
renames マップに従います。
- エントリが新しい名前を指している場合、Claude Code はプラグインを新しい名前で読み込み、
Renamed to "code-formatter" in the "acme-tools" marketplaceなどの 1 行の通知を表示します。その後、ユーザー、プロジェクト、ローカル設定スコープのenabledPluginsとpluginConfigsの両方で古いキーを新しいキーに書き直すため、通知は 1 回表示されます。 nullエントリの場合、Claude Code は古いキーを削除し、通知はプラグインがマーケットプレイスから削除されたことを報告します。- 名前変更されたプラグインが
githubまたはnpmなどのリモートソースを使用する場合、Claude Code は名前変更後にplugin-cache-missを報告し、ユーザーは新しい名前で取得するために 1 回/plugin installを実行する必要があります。
renames を追加のみの履歴として扱う:すべてのユーザーが移行することを期待した後でも、古いエントリを所定の位置に保持します。Claude Code はチェーンに従うため、後で code-formatter を formatter-pro に名前変更する場合は、最初のエントリを編集するのではなく、2 番目のエントリを追加します。元の formatter がまだ有効になっているユーザーは、両方のエントリを通じて formatter-pro に解決されます。
マップを編集した後、claude plugin validate . を実行します。チェーンがサイクルを形成したり、null または plugins にリストされている名前で終了しないエントリを拒否します。
管理設定とポリシー設定は Claude Code に対して読み取り専用であるため、そこで有効になっているプラグインは自動的に書き直すことができません。名前変更されたプラグインは各セッションで読み込まれ続けますが、管理者が管理設定ファイルの
enabledPlugins を新しい名前を使用するように更新するまで、名前変更通知は繰り返されます。同じことが --add-dir などの他の読み取り専用ソースを通じて有効になっているプラグインに適用されます。renames フィールドを無視し、古い名前に対して plugin-not-found を報告します。
検証とテスト
共有する前にマーケットプレイスをテストします。 マーケットプレイス JSON 構文を検証します:CLI からマーケットプレイスを管理する
Claude Code は、スクリプトと自動化のための非対話的なclaude plugin marketplace サブコマンドを提供します。これらは、対話的なセッション内で利用可能な /plugin marketplace コマンドと同等です。
プラグインマーケットプレイス追加
GitHub リポジトリ、Git URL、リモート URL、またはローカルパスからマーケットプレイスを追加します。<source>:GitHubowner/repoショートハンド、Git URL、marketplace.jsonファイルへのリモート URL、またはローカルディレクトリパス。ブランチまたはタグに固定するには、GitHub ショートハンドに@refを追加するか、Git URL に#refを追加します
gitlab.example.com/team/plugins のようにスキームなしで入力されたホストは、無効な owner/repo ショートハンドとして拒否され、エラーメッセージは https:// を追加するか、ローカルパスに ./ を使用するよう指示します。以前のバージョンでは、これを GitHub リポジトリパスとして誤読し、GitHub の見つからないエラーでクローン時に失敗します。
オプション:
GitHub から
owner/repo ショートハンドを使用してマーケットプレイスを追加します。
@ref を使用して特定のブランチまたはタグに固定します。
marketplace.json ファイルを直接提供するリモート URL から追加します。
.claude/settings.json 経由でチームと共有します。
プラグインマーケットプレイスリスト
設定されたすべてのマーケットプレイスをリストします。--json を使用すると、各エントリには name、source、およびソース固有のフィールドが含まれます:GitHub ソースの場合は repo、Git および URL ソースの場合は url、ローカルソースの場合は path。GitHub および Git ソースには、マーケットプレイスが固定されたブランチまたはタグで追加された場合、ref フィールドも含まれます。
プラグインマーケットプレイス削除
設定されたマーケットプレイスを削除します。エイリアスrm も受け入れられます。
<name>:削除するマーケットプレイス名。claude plugin marketplace listで表示されます。これは渡したソースではなく、marketplace.jsonのnameです
プラグインマーケットプレイス更新
マーケットプレイスをソースから更新して、新しいプラグインとバージョン変更を取得します。ブランチまたはタグref で追加されたマーケットプレイスは、リポジトリのデフォルトブランチではなく、その ref の最新コミットに更新されます。
[name]:更新するマーケットプレイス名。claude plugin marketplace listで表示されます。省略した場合はすべてのマーケットプレイスを更新します
remove と update の両方は、読み取り専用のシード管理マーケットプレイスに対して実行すると失敗します。すべてのマーケットプレイスを更新する場合、シード管理エントリはスキップされ、他のマーケットプレイスは引き続き更新されます。シード提供プラグインを変更するには、管理者にシードイメージを更新するよう依頼してください。コンテナ用にプラグインを事前入力するを参照してください。
トラブルシューティング
マーケットプレイスが読み込まれない
症状:マーケットプレイスを追加できない、またはそこからプラグインが表示されない 解決策:- マーケットプレイス URL がアクセス可能であることを確認します
.claude-plugin/marketplace.jsonが指定されたパスに存在することを確認しますclaude plugin validateまたは/plugin validateを使用して JSON 構文が有効であることを確認します。skill、agent、command frontmatter をチェックするには、各プラグインディレクトリに対してコマンドを実行します- プライベートリポジトリの場合、アクセス権限があることを確認します
マーケットプレイス検証エラー
マーケットプレイスディレクトリからclaude plugin validate . または /plugin validate . を実行して、問題をチェックします。マーケットプレイスディレクトリを指定した場合、バリデーターは marketplace.json のスキーマエラー、重複するプラグイン名、ソースパストラバーサルをチェックします。source がローカルパスである各エントリについて、そのプラグイン自体の plugin.json も検証し、エントリの version が plugin.json のものと一致しない場合に警告します。プラグインの plugin.json で見つかった問題には、エントリインデックスが接頭辞として付けられ、plugins[2] plugin.json → の形式になります。
Claude Code v2.1.196 以降、エントリごとのパスは以下も含みます:
sourceが.であるプラグインmarketplace.jsonが.claude-pluginディレクトリの外にある場合に実行され、ソースをファイル自体のディレクトリに対して解決します- ファイルの別の部分にスキーマエラーがある場合でも、各エントリの問題を報告します
.claude-plugin/marketplace.json からのみ下降します。
個別のプラグインの plugin.json およびその skill、agent、command、hook ファイルを検証するには、プラグインディレクトリ自体に対してコマンドを実行します。例えば claude plugin validate ./plugins/my-plugin。一般的なエラー:
警告(ブロッキングなし):
Marketplace has no plugins defined:plugins配列に少なくとも 1 つのプラグインを追加しますNo marketplace description provided:ユーザーがマーケットプレイスを理解するのに役立つように、トップレベルのdescriptionを追加しますPlugin name "x" is not kebab-case:プラグイン名に大文字、スペース、または特殊文字が含まれています。小文字、数字、ハイフンのみに名前を変更します(例:my-plugin)。Claude Code は他の形式を受け入れますが、claude.ai マーケットプレイス同期はそれらを拒否します。
プラグインインストール失敗
症状:マーケットプレイスは表示されますが、プラグインインストールが失敗します 解決策:- プラグインソース URL がアクセス可能であることを確認します
- プラグインディレクトリに必須ファイルが含まれていることを確認します
- GitHub ソースの場合、リポジトリが公開されているか、アクセス権限があることを確認します
- プラグインソースを手動でクローン/ダウンロードしてテストします
- ソースが
refとshaの両方をピンしている場合、削除されたアップストリームブランチまたはタグはほとんどの Git ホスト(GitHub、GitLab、Bitbucket を含む)でインストールをブロックしません。AWS CodeCommit などの SHA でコミットをフェッチすることをサポートしないサーバーでは、refが存在する必要があり、ピンされたコミットがそこから到達可能である必要があります。インストールが失敗し続ける場合は、ピンされたコミットがリポジトリに存在することを確認します
プライベートリポジトリ認証が失敗する
症状:プライベートリポジトリからプラグインをインストールするときに認証エラーが発生します 解決策: 手動インストールと更新の場合:- Git プロバイダーで認証されていることを確認します(例:GitHub の場合は
gh auth statusを実行) - 認証情報ヘルパーが正しく設定されていることを確認します:
git config --global credential.helper - リポジトリを手動でクローンして、認証情報が機能することを確認します
- デフォルトでは、バックグラウンド更新は pull の git 認証情報ヘルパーを無効にするため、pull は HTTPS 経由で認証できません。
ssh-agentに読み込まれたキーを持つ SSH リモートは引き続き認証します。失敗した pull は、保存された認証情報を使用するが大規模なリポジトリでタイムアウトする可能性がある、スクラッチからの再クローンをトリガーします CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1を設定して、バックグラウンド pull が失敗したときに既存のクローンを保持します- git 認証情報ヘルパー(例:
gh auth setup-git)を設定して、再クローンフォールバックが認証できるようにします - 大規模なリポジトリで再クローンがタイムアウトする場合は、
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MSで制限を増やします - バックグラウンド pull が直接認証するように、マーケットプレイスリポジトリにスコープされた git URL 書き換えを設定します
- または、認証情報を使用する
/plugin marketplace update <name>でプライベートマーケットプレイスを手動で更新します
オフライン環境でマーケットプレイス更新が失敗する
症状:マーケットプレイスgit pull がバックグラウンドで失敗し、Claude Code が成功できない再クローンを繰り返し試みます。
原因:デフォルトでは、git pull が失敗すると、Claude Code はスクラッチから再クローンを試みます。オフラインまたはエアギャップ環境では、再クローンが同じ方法で失敗し、その後の前のキャッシュの復元はベストエフォートです。更新はスタートアップ後にバックグラウンドで実行されるため、スタートアップを遅延させませんが、各セッションは失敗した試みを繰り返し、各 git 操作は 120 秒のタイムアウトを待つことができます。
解決策:CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 を設定して、pull が失敗したときに再クローン試行をスキップし、既存のキャッシュを使用し続けます:
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 環境変数を使用してタイムアウトを増やします。値はミリ秒単位です:
相対パスを持つプラグインが URL ベースのマーケットプレイスで失敗する
症状:URL(https://example.com/marketplace.json など)経由でマーケットプレイスを追加しましたが、"./plugins/my-plugin" のような相対パスソースを持つプラグインが「path not found」エラーでインストールに失敗します。
原因:URL ベースのマーケットプレイスは marketplace.json ファイル自体のみをダウンロードします。サーバーからプラグインファイルをダウンロードしません。マーケットプレイスエントリの相対パスは、ダウンロードされなかったリモートサーバー上のファイルを参照します。
解決策:
- 外部ソースを使用:プラグインエントリを相対パスの代わりに GitHub、npm、または Git URL ソースを使用するように変更します:
- Git ベースのマーケットプレイスを使用:マーケットプレイスを Git リポジトリでホストし、Git URL で追加します。Git ベースのマーケットプレイスはリポジトリ全体をクローンするため、相対パスが正しく機能します。
インストール後にファイルが見つからない
症状:プラグインはインストールされますが、ファイルへの参照が失敗します。特に、プラグインディレクトリの外部のファイル 原因:プラグインはインプレイスで使用されるのではなく、キャッシュディレクトリにコピーされます。プラグインディレクトリの外部のファイルを参照するパス(../shared-utils など)は、それらのファイルがコピーされないため機能しません。
解決策:symlinks とディレクトリ再構成を含む回避策については、プラグインキャッシングとファイル解決を参照してください。
追加のデバッグツールと一般的な問題については、デバッグと開発ツールを参照してください。
関連項目
- 既成プラグインの検出とインストール - 既存のマーケットプレイスからプラグインをインストール
- プラグイン - 独自のプラグインの作成
- プラグインリファレンス - 完全な技術仕様とスキーマ
- プラグイン設定 - プラグイン設定オプション
- strictKnownMarketplaces リファレンス - 管理マーケットプレイス制限