マーケットプレイスをホストして維持する

​

マーケットプレイスをホストする

​

リポジトリ内のすべてのユーザーのためにマーケットプレイスを登録する

​

URL ホストマーケットプレイスで相対パスエントリを避ける

​

ホストされたファイルのダウンロード制限内に留まる

• エントリ：100,000 ファイルおよびディレクトリ
• ファイルサイズ：圧縮されていない場合、任意の 1 つのファイルに対して 512 MiB
• 合計サイズ：圧縮されていない場合 1 GiB
• 圧縮率：圧縮されていないコンテンツが zip のサイズの 50 倍

​

共有ディレクトリでプラグインをその場で編集する

​

プラグインファイルを Git LFS から除外する

​

シンボリックリンクでマーケットプレイス内のファイルを共有する

• プラグイン自体のディレクトリ内：シンボリックリンクはキャッシュ内で相対シンボリックリンクとして保持されるため、実行時にコピーされたターゲットへの解決を続けます。
• 同じマーケットプレイス内の他の場所：シンボリックリンクは逆参照されます。ターゲットのコンテンツはキャッシュにコピーされます。これにより、メタプラグインの skills/ ディレクトリがマーケットプレイス内の他のプラグインで定義されたスキルにリンクできます。
• マーケットプレイス外：セキュリティ上の理由からシンボリックリンクはスキップされます。

ln -s ../../shared-plugin/skills/foo ./skills/foo

​

組織設定を通じて配布する

• マーケットプレイスリポジトリ：github.com と gitlab.com では、プライベートまたは内部である必要があります
• プラグインソース：organization sync は一部のソースタイプのみを受け入れます
• トップレベルの bin/ ディレクトリ：claude.ai はこれを持つプラグインを拒否し、マーケットプレイスの残りを同期します。エラーメッセージは Plugin contains a top-level bin/ directory で始まります。実行可能ファイルを scripts/ などの別のディレクトリに保持し、フック または MCP サーバー設定から ${CLAUDE_PLUGIN_ROOT}/scripts/<name> として参照してください

​

プライベートマーケットプレイスへのアクセスを許可する

• GitHub owner/repo：Claude Code は ssh -T git@github.com をプローブし、プローブが成功する場合は SSH でクローンします。プローブが失敗するか、SSH クローン自体が失敗する場合は、HTTPS でクローンします。GitHub SSH キーを持たないマシンのユーザーは、CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 を設定してプローブをスキップし、HTTPS でクローンできます。
• git@host:path.git：SSH。
• https://example.com/repo.git：HTTPS。

• SSH：キーはパスフレーズプロンプトなしで機能する必要があります。例えば ssh-agent に読み込まれているため。ホストは既に known_hosts にある必要があります。
• HTTPS：Claude Code はユーザーの git 認証情報ヘルパーを有効にしたままにしますが、プロンプトを禁止し、GIT_ASKPASS で設定されたものなどの askpass プログラムも実行しません。ヘルパーが既に保存している認証情報は機能します。要求する必要があるものは失敗します。GitHub では、gh auth login の後に gh auth setup-git を実行すると、認証情報が保存されます。

​

git ホストアカウントを持たないユーザーにサービスを提供する

• archive：HTTPS でダウンロードされた zip。ユーザーは git またはアカウントを必要とせず、URL へのネットワークアクセスのみが必要です。Claude Code v2.1.224 以降が必要です。各アーカイブを sha256 でピンして、Claude Code が変更されたダウンロードを拒否するようにしてください。ダウンロードで認証情報を送信するには、アーカイブダウンロードを認証するを参照してください。
• パブリック git リポジトリ：Claude Code は、エントリが https:// URL を指定する場合、認証情報なしで HTTPS 経由でパブリック url または git-subdir ソースをクローンします。github ソース、または owner/repo として記述された git-subdir ソースの場合、GitHub SSH キーを持たないユーザーは CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 を設定します。

​

バックグラウンド自動更新が認証情報で行うこと

• SSH リモート：ssh-agent に読み込まれたキーがチェックを認証します。
• 保存された認証情報を持つ HTTPS リモート：プロンプトなしで保存された認証情報を提供できるヘルパーがチェックを認証します。Git Credential Manager、macOS Keychain ヘルパー、および git-credential-store は、ホストの認証情報を保持すると、このように機能します。
• プロンプトが必要なヘルパーを持つ HTTPS リモート：ヘルパーはバックグラウンドで応答できません。更新は静かに失敗し、既存のチェックアウトが所定の位置に留まるため、ユーザーのプラグインは最後に同期された状態から機能し続けます。

• チェックアウトは最新です：Claude Code はそのままにします。
• チェックが新しいコミットを見つけるか、リモートに到達または認証できないため失敗する：Claude Code はマーケットプレイスを再度クローンし、既存のチェックアウトを新しいクローンに置き換えます。そのクローンが失敗する場合、既存のチェックアウトが所定の位置に留まります。再クローンは大規模なリポジトリでタイムアウトする可能性があります。

• 認証情報を保存する：最初に認証情報ヘルパーにサインインして、ホストの認証情報を保持するようにします。GitHub の場合、gh auth login を実行してから gh auth setup-git を実行します。
• 失敗時にチェックアウトを保持する：ユーザーが CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 を設定する場合、バックグラウンドチェックがリモートに到達または認証できない場合、Claude Code は再クローンを試みずに既存のチェックアウトを保持します。プラグインは最後に同期された状態から機能し続けます。

​

会社全体にロールアウトする

• git アカウントを必要としないエントリソース：git ホストアカウントを持たないユーザーにサービスを提供する
• 事前入力されたプラグインディレクトリ：コンテナと CI をシードする。これは git ホストアカウントを持たないユーザーにもサービスを提供します
• claude.ai 組織設定：組織設定を通じて配布する。ユーザーの git 認証情報は関係ありません

​

ユーザーを最新の状態に保つ

​

自動更新をオンにする

• ユーザーにオンにするよう指示する：各ユーザーは /plugin のMarketplacesに移動し、マーケットプレイスを選択して、Enable auto-updateを選択します。
• 管理者に設定するよう依頼する：管理者が管理設定でマーケットプレイスの extraKnownMarketplaces エントリで "autoUpdate": true を設定する場合、それらの設定を受け取るすべてのユーザーに対してオンです。更新ポリシーを設定するを参照してください。

​

新しいバージョンをリリースする

• 各リリースで version をバンプする：ユーザーはキャッシュされたコピーに留まります。文字列が変更されるまで。"version": "1.0.0" を設定してコミットをプッシュしても変更しない場合、ユーザーはそれらを受け取りません。
• version を省略する：ユーザーはコミットを追跡します。plugin.json とマーケットプレイスエントリの両方から version を除外してください。

​

ユーザーを 1 つのバージョンに保持する

• プラグインエントリの ref と sha：ref はブランチまたはタグに名前を付け、sha は github、url、または git-subdir ソースのコミットに名前を付けます。プラグインソースを参照してください。
• 追加コマンドの #<ref>：your-org/your-marketplace#stable を追加するユーザーはカタログのそのブランチまたはタグを取得します。一度に 2 つのリリースラインの場合は、リリースチャネルを実行するを参照してください。
• <plugin>--v<version> タグ：依存関係のバージョン範囲はこれらのタグに対して解決されます。他のプラグインが依存するプラグインをリリースするを参照してください。

​

コマンドソースのコマンドを変更する

• バックグラウンド実行なし：コマンドのセッションごとの実行はそのユーザーに対して停止するため、ツールの新しい出力はそれらに到達しません。
• /plugin エラータブのエントリ：エントリは新しいコマンドと実行する claude plugin update コマンドを表示します。

​

リリースチャネルを実行する

{
  "name": "stable-tools",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": { "source": "github", "repo": "your-org/code-formatter", "ref": "stable" } }
  ]
}

{
  "name": "latest-tools",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": { "source": "github", "repo": "your-org/code-formatter", "ref": "latest" } }
  ]
}

​

プラグインの名前変更または削除

​

名前変更マップでユーザーを移行する

{
  "name": "your-marketplace",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

• 名前変更されたエントリ：プラグインは新しい名前で読み込まれます。claude plugin list とプラグインの詳細は /plugin の下に Renamed to "code-formatter" in the "your-marketplace" marketplace を 1 回表示し、Claude Code はユーザー、プロジェクト、ローカル設定スコープの enabledPlugins と pluginConfigs の古いキーを新しいキーに書き直します。
• null エントリ：古いキーはそれらのスコープから削除され、ユーザーは Removed from the "your-marketplace" marketplace を見ます。
• 管理設定で有効：プラグインは新しい名前で読み込まれ続けますが、Claude Code は管理設定を書き直すことができないため、管理者がそこで enabledPlugins を更新するまで通知が繰り返されます。

​

削除されたプラグインをユーザーのマシンからアンインストールする

1. ユーザーがマーケットプレイスからインストールしたものをエントリと renames マップと比較し、リストされていないか名前変更されていないプラグインを削除されたものとして扱います。
2. ユーザー、プロジェクト、ローカルスコープから各削除されたプラグインをアンインストールします。管理設定のみがインストールしたプラグインは所定の位置に留まります。
3. /plugin のFlagged見出しの下に各削除されたプラグインをリストします。ステータスは Removed from marketplace です。

​

アーカイブダウンロードを認証する

• マーケットプレイスの url ソース：マーケットプレイスの登録元である url ソースです。extraKnownMarketplaces のエントリなどが該当します。
• プラグインのエントリ：Claude Code v2.1.238 以降では、代わりにプラグインの marketplace.json エントリ内で、source と並べて設定できます。

​

プラグインのエントリに headersHelper を追加する

{
  "name": "my-plugin",
  "description": "Formatting commands for internal services",
  "strict": false,
  "source": {
    "source": "archive",
    "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"
  },
  "headersHelper": "/opt/bin/mint-registry-token.sh"
}

​

headersHelper コマンドを作成する

• コマンドのテキスト：印字可能な ASCII で 500 文字以内とし、4 つ以上連続するスペースを含めないでください。
• 出力：ヘッダー名と文字列値からなる JSON オブジェクトを 1 つ stdout に出力し、10 秒以内に終了コード 0 で終了してください。
• シェルと作業ディレクトリ：Claude Code はコマンドを sh で実行します（Windows では cmd.exe）。作業ディレクトリは設定ディレクトリで、~/.claude または CLAUDE_CONFIG_DIR です。相対パスはユーザーのプロジェクトではなくこのディレクトリを基準に解決されるため、絶対パスか PATH 上のコマンドを指定してください。
• Claude Code が削除する変数：コマンドが marketplace.json エントリ、またはプロジェクトの .claude/settings.json や .claude/settings.local.json で設定されている場合、Claude Code は、MCP の headersHelper に適用するのと同じルールに従い、名前が認証情報らしく見えるすべての変数を環境から削除します。ANTHROPIC_API_KEY と MY_REGISTRY_TOKEN はどちらも削除されるため、コマンドは認証情報をファイルや認証情報ストアから読み取るようにしてください。この削除は、ユーザー設定、--settings ファイル、または管理設定で設定されたコマンドには適用されません。
• Claude Code が設定する変数：url ソースのコマンドには CLAUDE_CODE_MARKETPLACE_URL と CLAUDE_CODE_MARKETPLACE_NAME、エントリのコマンドには CLAUDE_CODE_PLUGIN_NAME と CLAUDE_CODE_PLUGIN_ARCHIVE_URL が設定されます。ユーザーが URL でマーケットプレイスを追加した後の最初の取得では、その取得によって名前が得られるため、CLAUDE_CODE_MARKETPLACE_NAME は設定されません。

{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

​

Claude Code が headersHelper コマンドをスキップする場合や出力を破棄する場合

• コマンドが失敗した：コマンドが 0 以外の終了コードで終了した場合、10 秒を超えて実行された場合、または文字列値からなる JSON オブジェクト以外のものを出力した場合、そのコマンドを実行する目的だった取得やダウンロードは行われません。
• マーケットプレイスの URL が https:// で始まらない：その url ソースのコマンドは実行されず、リクエストには headers フィールドに記載されたヘッダーのみが付与されます。
• リダイレクトでオリジンを離れた：ダウンロードがアーカイブ URL のオリジン外にリダイレクトされた場合、リダイレクト後のリクエストには、マーケットプレイスの url ソースとプラグインのエントリのどちらの headers の値もコマンドの出力も付与されません。
• エントリがルーティング用または識別用のヘッダーを設定している：Claude Code は、Host、Cookie、X-Forwarded-* などのリクエストルーティング用やクライアント識別用の名前をエントリの headers とコマンドの出力から破棄し、Authorization などの認証用の名前は保持します。すべての marketplace.json エントリがこの方法でフィルタリングされます。設定内のインラインプラグインエントリについては、extraKnownMarketplaces を参照してください。
• コマンドが --add-dir ディレクトリの設定で設定されている：url ソースでもインラインプラグインエントリでも、コマンドは無視され、そのファイルの headers のみが送信されます。
• 管理設定がコマンドをブロックしている：disableCommandPluginSources を true に設定すると headersHelper コマンドがブロックされます。また、allowManagedHooksOnly も、disableCommandPluginSources が明示的に false でない限りこれらをブロックします。どちらのブロック下でも、管理設定自体が宣言しているマーケットプレイスについては、Claude Code は引き続きコマンドを実行します。

​

ユーザーが headersHelper コマンドを受け入れる方法

• ターミナルのセッション：/plugin 内のそのプラグイン自身のビューから行います。
• シェル：claude plugin install または claude plugin update で行います。
• VS Code 拡張機能：拡張機能のバージョン 2.1.290 以降で、Manage plugins ダイアログから行います。

​

確認せずにコマンドを拒否するインストールと更新

• 複数のプラグインを一度にインストールする場合、プラグインの提案からインストールする場合、または別のプラグインの依存関係としてインストールする場合：Claude Code はコマンドを持つプラグインを拒否し、ユーザーを /plugin 内のそのプラグイン自身のビューに誘導します。一括インストールの他のプラグインは引き続きインストールされます。拒否されたプラグインに依存するプラグインは、ユーザーが拒否されたプラグインを単独でインストールするまでインストールに失敗します。
• バックグラウンドでの自動更新、またはアーカイブが一度もダウンロードされていないプラグインのセッション開始時：Claude Code はそのプラグインを /plugin の Errors タブに表示し、ユーザーが自分でインストールまたは更新する必要があることを知らせます。

​

マーケットプレイスの url ソースのコマンドが実行されるタイミング

​

他のプラグインに依存し、推奨する

• バージョン範囲: 依存関係は semver 範囲を含むことができます。
• クロスマーケットプレイス依存関係: 別のマーケットプレイスからの依存関係は、お客様のマーケットプレイスが allowCrossMarketplaceDependenciesOn にそのマーケットプレイスをリストしている場合にのみインストールされます。

​

マーケットプレイスができないことへの対応

• ユーザーがインストールできるその他のプラグインを制限する: マーケットプレイスの許可リストは管理設定 strictKnownMarketplaces です。ユーザーがインストールできるものを制限する を参照してください。
• ユーザーが要求せずにプラグインをインストールまたは有効にする: エントリフィールドはプラグインをインストールしません。管理設定の enabledPlugins はフリート全体に対してそれを実行します。プラグインを事前インストールして必須にする を参照してください。
• 異なるユーザーに異なるエントリを表示する: エントリには対象ユーザーフィールドがなく、マーケットプレイスを追加するすべてのユーザーがカタログ全体を表示します。異なる対象ユーザー向けに別々のマーケットプレイスをホストしてください。
• プラグインを非推奨としてマークする: 非推奨状態はありません。オプションはエントリを削除し、その名前を renames で null にマップし、オプションで forceRemoveDeletedPlugins を設定することです。
• ユーザーの自動更新をオンにする: 各ユーザーは /plugin の Marketplaces でオンにするか、管理者が管理設定で autoUpdate を設定します。自動更新をオンにする を参照してください。
• Git 認証情報を保持する: マーケットプレイスフィールドは Git トークンを保持しません。Git でホストされるマーケットプレイスまたはプラグインへのアクセスは、プライベートマーケットプレイスへのアクセスを許可する に従い、ユーザーの Git セットアップに従います。archive ソースの場合、エントリは代わりに headers または headersHelper を設定できます。

​

次のステップ

• マーケットプレイスリファレンス：marketplace.json フィールド、ソースタイプ、および検証メッセージ
• 組織のプラグインを管理する：組織のマシン全体でマーケットプレイスを要求、制限、またはシードする
• プラグイン依存関係：プラグインが依存するプラグインがバージョンを解決できるようにリリースをタグ付けする
• プラグインのトラブルシューティング：ユーザーがマーケットプレイスから追加または更新するときに見るエラー