プラグインマーケットプレイスの作成と配布

Claude Code 拡張機能を配布するためのプラグインマーケットプレイスを構築およびホストします。

プラグインマーケットプレイスは、他のユーザーにプラグインを配布できるカタログです。マーケットプレイスは、一元化された検出、バージョン追跡、自動更新、および複数のソースタイプ（Git リポジトリ、ローカルパスなど）のサポートを提供します。このガイドでは、チームやコミュニティとプラグインを共有するための独自のマーケットプレイスを作成する方法を説明します。

既存のマーケットプレイスからプラグインをインストールしたいですか？既成プラグインの検出とインストールを参照してください。

概要

マーケットプレイスの作成と配布には、以下が含まれます。

1. プラグインの作成：skills、agents、hooks、MCP サーバー、または LSP サーバーを使用して 1 つ以上のプラグインを構築します。このガイドでは、配布するプラグインが既にあることを前提としています。プラグインの作成方法の詳細については、プラグインの作成を参照してください。
2. マーケットプレイスファイルの作成：プラグインとその場所を一覧表示する marketplace.json を定義します。マーケットプレイスファイルの作成を参照してください。
3. マーケットプレイスのホスト：GitHub、GitLab、または別の Git ホストにプッシュします。マーケットプレイスのホストと配布を参照してください。
4. ユーザーと共有：ユーザーが /plugin marketplace add でマーケットプレイスを追加し、個別のプラグインをインストールします。プラグインの検出とインストールを参照してください。

マーケットプレイスがライブになったら、リポジトリに変更をプッシュして更新できます。ユーザーは /plugin marketplace update でローカルコピーを更新します。

チュートリアル：ローカルマーケットプレイスの作成

この例では、1 つのプラグイン（コードレビュー用の quality-review skill）を含むマーケットプレイスを作成します。ディレクトリ構造を作成し、skill を追加し、プラグインマニフェストとマーケットプレイスカタログを作成してから、インストールしてテストします。

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

---
description: Review code for bugs, security, and performance
---

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.

{
"name": "quality-review-plugin",
"description": "Adds a quality-review skill for quick code reviews",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}

{
"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

/quality-review-plugin:quality-review

プラグインが実行できることの詳細（hooks、agents、MCP サーバー、LSP サーバーを含む）については、プラグインを参照してください。

マーケットプレイスファイルの作成

リポジトリルートに .claude-plugin/marketplace.json を作成します。このファイルは、マーケットプレイスの名前、所有者情報、およびソースを含むプラグインのリストを定義します。

各プラグインエントリには、最低限 name と source（Claude Code がどこから取得するかを指定）が必要です。利用可能なすべてのフィールドについては、以下の完全なスキーマを参照してください。

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "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"
    }
  ]
}

マーケットプレイススキーマ

必須フィールド

所有者フィールド

オプションフィールド

description と version は後方互換性のため metadata の下でも受け入れられます。

プラグインエントリ

plugins 配列内の各プラグインエントリは、プラグインとその場所を説明します。プラグインマニフェストスキーマのフィールド（description、version、author、commands、hooks など）を含めることができます。さらに、これらのマーケットプレイス固有のフィールド：source、category、tags、strict、relevance、headers、および headersHelper があります。

必須フィールド

オプションプラグインフィールド

標準メタデータフィールド：

エントリとプラグイン自体の plugin.json の両方が、表示フィールド displayName、description、author、homepage、repository、license、および keywords を設定できます。プラグインリストと詳細では、インストール前後：

• エントリで設定したフィールドについては、plugin.json が異なる値を設定している場合でも、ユーザーはエントリの値を表示されます。
• エントリが設定していないフィールドについては、ユーザーは plugin.json の値を表示されます。

インストール前に、Claude Code は相対パスソースを持つエントリの plugin.json のみを読むことができます。そのプラグインファイルはマーケットプレイス内に存在します。他のソースタイプを持つエントリの場合、ユーザーはプラグインをインストールするまで、エントリ自体のフィールドのみを表示されます。

コンポーネント設定フィールド：

アーカイブ認証フィールド：

エントリが認証情報を必要とするサーバー上のarchive ソースを持つ場合、これらを設定します。

プラグインソース

プラグインソースは、Claude Code にマーケットプレイスにリストされた各プラグインをどこから取得するかを指示します。これらは marketplace.json の各プラグインエントリの source フィールドで設定されます。

Claude Code は、インストール済みの各プラグインをローカルバージョン管理されたプラグインキャッシュ（~/.claude/plugins/cache）にコピーします。ただし、プラグインがその場で読み込まれる場合は例外です。リンクモードの command ソースはその場で読み込まれ、ローカルディレクトリから追加されたマーケットプレイスの相対パスソースも同様です。Claude Code はまた、プラグインの対象となる Node.js パッケージ依存関係をキャッシュされたコピーにインストールします。ローカルディレクトリマーケットプレイスからその場で読み込まれたプラグインが編集内容を取得する方法については、プラグインキャッシングとファイル解決を参照してください。

以下の Git ベースのソースタイプは github、url、および git-subdir です。ref と sha の両方が設定されている場合、sha が有効なピンになります。Claude Code はピンされたコミットを直接フェッチしてチェックアウトします。

GitHub、GitLab、Bitbucket を含むほとんどの git ホストでは、ブランチまたはタグが ref で指定されていても、その後アップストリームで削除されていても、コミットがリポジトリから到達可能である限り、インストールは成功します。AWS CodeCommit などの一部のサーバーは、SHA でコミットをフェッチすることをサポートしていません。これらのサーバーでは、ref が存在し、ピンされたコミットがそこから到達可能である必要があります。

組織設定 > プラグイン を通じてプラグインを配布する場合、一部のソースタイプのみが許可されます。組織設定を通じた配布を参照してください。

相対パス

同じリポジトリ内のプラグインの場合、./ で始まるパスを使用します：

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

パスはマーケットプレイスルート（.claude-plugin/ を含むディレクトリ）を基準に解決されます。上記の例では、marketplace.json が <repo>/.claude-plugin/marketplace.json にあっても、./plugins/my-plugin は <repo>/plugins/my-plugin を指します。マーケットプレイスルートの外のパスを参照するために ../ を使用しないでください。macOS と Linux では、Claude Code は先頭の ./ より後のどこかにバックスラッシュがあるエントリパスを拒否するため、すべてのプラットフォームで区切り文字を / として記述してください。

裸の名前は、"formatter" のように / を含まない単一のディレクトリ名です。./ パスの代わりに裸の名前を記述するには、metadata.pluginRoot をそれらが解決されるディレクトリに設定します。"pluginRoot": "./plugins" の場合、Claude Code は "source": "formatter" を ./plugins/formatter に解決します。Claude Code v2.1.239 以降が必要です。

metadata.pluginRoot 自体はマーケットプレイス内の相対パスである必要があります。Claude Code は既に ./ で始まるソースに対しては無視します。team-a/formatter のように / を含むソースは裸の名前ではなく、metadata.pluginRoot が設定されていても ./ プレフィックスが必要です。

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"
  }
}

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"
  }
}

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）も受け入れます。

npm パッケージ

npm ソースは、公開 npm レジストリまたはチームがホストするプライベートレジストリ上の任意のパッケージに名前を付けることができます。Claude Code は npm クライアントでパッケージを解決し、tarball をダウンロードして、プラグインキャッシュに解凍します。

パッケージのインストールスクリプト（preinstall や postinstall など）は実行されず、フェッチ中に依存関係はインストールされません。

パッケージが package.json の隣にサポートされているロックファイルを配布する場合、Claude Code はそれらのNode.js パッケージ依存関係を別のステップでインストールし、スクリプトも無効にします。そうでない場合は、必要なすべてのものが既に構築されたプラグインを公開します。他のパッケージが必要な MCP サーバーは、npx を通じて起動でき、最初の実行時にそれらをインストールします。

{
  "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"
  }
}

Zip アーカイブ

archive を使用して、Claude Code が HTTPS でダウンロードする zip ファイルとしてプラグインを配布します。これにより、ユーザーのマシンに git や npm がなくてもインストールが機能します。S3 バケット、Artifactory 汎用リポジトリ、nginx などの静的ファイルサーバーまたはアーティファクトリポジトリでファイルをホストします。Claude Code v2.1.224 以降が必要です。v2.1.120 から v2.1.223 では、プラグインのインストールが This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again. で失敗します。より古いバージョンでは、archive エントリを含むマーケットプレイス全体がロードに失敗します。

このエントリはアーティファクトサーバー上の zip ファイルからプラグインをインストールします：

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip"
  }
}

zip を構築するときは、プラグインのコンテンツを直接 zip するか、プラグインフォルダ自体を zip できます。Claude Code はアーカイブの最上部で .claude-plugin/ を探し、次に単一の最上位フォルダ内を探すため、両方のレイアウトがインストールされます：

my-plugin.zip          my-plugin.zip
├── .claude-plugin/    └── my-plugin/
│   └── plugin.json        ├── .claude-plugin/
└── commands/              │   └── plugin.json
                           └── commands/

Claude Code は 1 フォルダより深く探さないため、さらに下にネストされたプラグインはインストールに失敗します。Claude Code は 256 MiB より大きいアーカイブを拒否します。

正確なファイルにピンするには、アーカイブのダイジェストを含む sha256 フィールドを追加します：

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip",
    "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
  }
}

ダウンロードされたファイルがピンと一致しない場合、Claude Code はインストールを拒否し、Plugin archive integrity check failed を報告します。

アーカイブソースはこれらのフィールドを受け入れます：

sha256 ダイジェストは、plugin.json またはマーケットプレイスエントリが宣言していない場合、プラグインのバージョンとしても機能します。バージョン管理を参照してください。version を宣言する場合、そのバージョン文字列が更新シグナルになるため、zip とそのダイジェストを変更した後、バージョンもバンプしてください。そうしないと、ユーザーはキャッシュされたコピーを保持し続けます。

アーカイブダウンロードの認証

プライベートレジストリからのダウンロードなど、アーカイブダウンロードを認証するには、Claude Code が送信する HTTP ヘッダーを設定します。マーケットプレイスを登録した url ソース（extraKnownMarketplaces エントリなど）で headers を設定します。Claude Code v2.1.238 以降では、プラグインのエントリで source の隣に設定できます。

headers に入れる値が短命の場合（レジストリがリクエストで生成するトークンなど）、代わりに同じ場所に headersHelper コマンドを設定します。Claude Code はコマンドを実行し、それが出力する JSON オブジェクトをその場所のヘッダーとして送信します。Claude Code v2.1.238 以降が必要です。

選択した場所は、どのダウンロードがヘッダーを取得し、Claude Code がコマンドをいつ実行するかを決定します：

両方の場所が同じ名前のヘッダーを設定する場合、Claude Code はエントリの値を送信します。1 つの場所内で、コマンドが出力するヘッダーは同じ名前のリストされたヘッダーをオーバーライドします。

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

このエントリは headersHelper を source の隣に設定します。また、"strict": false を設定します。これは Claude Code が headersHelper を設定する marketplace.json エントリに必要です。"strict": false では、マーケットプレイスエントリはプラグインの完全な定義なので、ユーザーはコマンドを受け入れる前にプラグインに含まれるものを確認できます：

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

エントリを確認するには、claude plugin install my-plugin@your-marketplace を実行します。Claude Code はコマンドとアーカイブ URL を表示し、受け入れた後に zip をダウンロードします。

v2.1.238 より前では、Claude Code はエントリのアーカイブを headers または headersHelper なしでダウンロードしたため、それらに依存するインストールは HTTP 401 while downloading plugin archive from で失敗し、その後に URL が続き、レジストリのステータスコードが 401 の代わりに表示されました。

headersHelper コマンドを記述

マーケットプレイスの url ソースまたはプラグインエントリで headersHelper を設定するかどうかに関わらず、コマンドがこれらの要件を満たすように記述します：

• コマンドテキスト: 最大 500 文字の印字可能 ASCII、4 文字以上の連続スペースなし。
• 出力: ヘッダー名と文字列値の 1 つの JSON オブジェクトを 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 は TOKEN、SECRET、KEY、AUTH などの単語を含む名前を持つすべての変数を削除します（ANTHROPIC_API_KEY を含む）。Claude Code はこの削除をユーザー設定、--settings ファイル、または管理設定で設定されたコマンドには適用しません。
• Claude Code が設定する変数: url ソースのコマンドの場合は CLAUDE_CODE_MARKETPLACE_URL と CLAUDE_CODE_MARKETPLACE_NAME、エントリのコマンドの場合は CLAUDE_CODE_PLUGIN_NAME と CLAUDE_CODE_PLUGIN_ARCHIVE_URL。CLAUDE_CODE_MARKETPLACE_NAME は、ユーザーが URL でマーケットプレイスを追加した後の最初のフェッチでは設定されません。そのフェッチが名前を提供するためです。

ベアラートークンを生成するコマンドは、次のようなオブジェクトを出力します：

{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

Claude Code が headersHelper コマンドをスキップするか、その出力をドロップする場合

Claude Code は headersHelper コマンドを実行しないか、これらの状況で headers または コマンドの出力から来たヘッダーをドロップします：

• コマンド失敗: コマンドが 0 以外で終了する、10 秒を超えて実行される、または JSON 文字列値のオブジェクト以外を出力する場合、Claude Code はそれが実行されたフェッチまたはダウンロードを実行しません。
• マーケットプレイス URL が https:// で始まらない: Claude Code はその url ソースのコマンドを実行せず、headers フィールドにリストされたヘッダーのみを送信します。
• リダイレクトがオリジンを離れる: ダウンロードがアーカイブ URL のオリジンからリダイレクトされる場合、Claude Code はマーケットプレイス url ソースとプラグインエントリの両方の headers 値とコマンド出力をドロップします。
• エントリがルーティングまたはアイデンティティヘッダーを設定: Claude Code は Host、Cookie、X-Forwarded-* などのリクエストルーティングおよびクライアントアイデンティティ名をエントリの headers とコマンド出力からドロップし、Authorization などの認証名を保持します。Claude Code はすべての marketplace.json エントリをこの方法でフィルタリングし、インライン設定エントリはそれを宣言するファイルに応じて。
• --add-dir ディレクトリの設定で設定されたコマンド: Claude Code はそれを無視し、url ソースとインラインプラグインエントリの両方で、そのファイルの headers のみを送信します。
• 管理設定がコマンドをブロック: disableCommandPluginSources を true に設定すると headersHelper コマンドがブロックされ、allowManagedHooksOnly も disableCommandPluginSources が明示的に false でない限りそれらをブロックします。どちらのブロックでも、Claude Code は管理設定自体が宣言するマーケットプレイスのコマンドを実行します。

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

ユーザーはプラグインエントリのコマンドを、そのプラグインを単独でインストールまたは更新するたびに受け入れます。これは /plugin のプラグイン自体のビューから、または claude plugin install または claude plugin update で行われます。Claude Code はコマンドとアーカイブ URL を表示し、ユーザーが受け入れた後にのみコマンドを実行します。

非対話型シェルでは、--yes を claude plugin install または claude plugin update に渡してコマンドを受け入れます。前の --json 実行が表示したコマンドのみを受け入れるには、--accept-command に sha256 を渡します。

Claude Code は表示したコマンドのみを実行し、表示したアーカイブ URL に対してのみ実行します。その間にエントリのコマンドまたはアーカイブ URL が変更された場合、Claude Code はインストールまたは更新を拒否します。クエリ文字列のみの変更はカウントされません。

コマンドを要求する代わりに拒否するインストールと更新

単一プラグインのインストールまたは更新以外の操作では、Claude Code はエントリのコマンドを実行せず、そのアーカイブをダウンロードしないため、プラグインはインストール済みバージョンのままか、インストールされていないままです。ユーザーが見るものは操作によって異なります：

• 複数のプラグインを一度にインストール、プラグイン提案からインストール、または別のプラグインの依存関係としてインストール: Claude Code はコマンドを持つプラグインを拒否し、ユーザーをそのプラグインの /plugin 内の独自のビューに指します。一括インストール内の他のプラグインはまだインストールされます。拒否されたプラグインに依存するプラグインは、ユーザーが拒否されたプラグインを単独でインストールするまでインストールに失敗します。
• バックグラウンド自動更新、またはアーカイブがダウンロードされたことのないプラグインのセッション開始: Claude Code は /plugin エラータブにプラグインをリストして、ユーザーが手動でインストールまたは更新することを知らせます。インストール済みバージョンをまだ宣伝している自動更新は何もリストしません。

マーケットプレイス `url` ソースのコマンドが実行される時期

マーケットプレイス url ソースの headersHelper は、マーケットプレイスが公開するカタログではなく、extraKnownMarketplaces エントリなどの設定ファイルで宣言されるため、Claude Code は各インストールまたは更新でユーザーに受け入れを求めません。それを宣言する設定ファイルが Claude Code がいつそれを実行するかを決定します：

-p または SDK セッションでは、Claude Code はセキュリティ承認ダイアログを表示できません。他の配信された設定を適用しますが、マーケットプレイスフェッチと、コマンドが必要なアーカイブダウンロードは、ユーザーが対話型セッションで承認するまで失敗します。

これらのファイルのインラインプラグインエントリの場合、Claude Code はそのファイル内のマーケットプレイスレベルのコマンドと同じフォルダ信頼または設定承認を要求し、ユーザーは各インストールまたは更新でエントリのコマンドも受け入れます。

コマンドソース

ローカルにインストールされたツールがプラグインディレクトリを生成する場合（現在選択されているツールチェーンのプラグインをレンダリングする IDE など）に command を使用します。Claude Code はユーザーがプラグインをインストールするときにコマンドを実行し、セッションごとに 1 回バックグラウンドで再実行するため、ユーザーは再インストールなしでツールの変更された出力を取得します。Claude Code v2.1.229 以降が必要です。v2.1.120 から v2.1.228 では、プラグインのインストールが This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again. で失敗し、より古いバージョンではマーケットプレイス全体がロードに失敗します。

このエントリはツールが出力するディレクトリからプラグインをインストールします：

{
  "name": "my-plugin",
  "source": {
    "source": "command",
    "command": "my-tool claude-plugin-path"
  }
}

Claude Code はプラットフォームシェル（macOS と Linux では sh、Windows では cmd.exe）を通じてコマンドを実行し、ユーザーのホームディレクトリから実行します。コマンドは stdout に正確に 1 行を出力し、終了コード 0 で終了する必要があります。その行は、コマンドが終了するまでに完全なプラグインを含むディレクトリの絶対パスであり、パスは実行間で変更される可能性があります。

Claude Code は timeout 秒より長く実行されるコマンドを停止し、インストールまたは更新は失敗します。Claude Code はこれらの場合にも出力されたパスを拒否し、インストールまたは更新は同じ方法で失敗します：

• ディレクトリの最上部にプラグインコンテンツがない（.claude-plugin/ ディレクトリ、または skills/、commands/、agents/、hooks/ ディレクトリなど）
• ディレクトリは Claude Code が開始されたディレクトリ、またはその親の 1 つ
• Windows では、パスは UNC パス

コマンドソースはこれらのフィールドを受け入れます：

コピーモードとリンクモード

デフォルトの "mode": "copy" では、Claude Code は出力されたディレクトリをバージョン管理されたプラグインキャッシュにコピーし、ディレクトリのコンテンツのハッシュからプラグインバージョンを導出します。ツールはコマンドが終了した後にディレクトリを削除または上書きでき、同じコンテンツを生成する再実行は最新とカウントされます。Claude Code は 256 MiB より大きいディレクトリまたは 20,000 を超えるエントリを含むディレクトリのインストールを拒否します。

大規模なプラグインディレクトリ（レンダリングされた SDK エクスポートなど）をコピーしてはいけない場合は、"mode": "link" を設定します。Claude Code は出力されたディレクトリの各最上位エントリへのリンクでプラグインのキャッシュエントリを埋め、ファイルをその場で使用するため、何もコピーされず、ファイルコンテンツはハッシュされず、サイズ制限は適用されません。最上位エントリが出力されたディレクトリの外を指すシンボリックリンクの場合、インストールは失敗します。Claude Code はリンクモードプラグインのNode.js パッケージ依存関係インストールもスキップするため、プラグインが必要とする node_modules を既に含むディレクトリを出力します。

プラグインがインストール状態を保つ限り、出力されたディレクトリをその場に保ちます。Claude Code はすべての起動でそれらのリンクを通じてプラグインをロードするためです。Claude Code はプラグインバージョンを出力されたディレクトリの実パスとその最上位エントリから導出し、内部のファイルからではないため、新しいコンテンツを通知するために異なるパスを出力します。出力されたディレクトリまたはその下のどこかで開始されたセッションでは、Claude Code はプラグインをロードしません。

Claude Code は Windows でリンクモードをサポートしておらず、そこでリンクモードプラグインのインストールを拒否します。代わりに "mode": "copy" を宣言します。

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

Claude Code はユーザーのマシンでコマンドを実行するため、すべての実行をユーザーの明示的な受け入れにバインドします：

• ユーザーが /plugin のプラグインの詳細画面からプラグインをインストールするか、対話型ターミナルで claude plugin install または claude plugin update でインストールまたは更新する場合、Claude Code は最初に正確なコマンド文字列を表示し、そのインストールの受け入れられたコマンドを記録します。同じコマンドの受け入れで進行できる claude plugin update は何も表示しません。
• 非対話型シェルでは、claude plugin install または claude plugin update に --yes を渡してコマンドを受け入れます。前の --json 実行が表示したコマンドのみを受け入れるには、--accept-command に sha256 を渡します。
• 他のすべてのパスはユーザーが既に受け入れたコマンドのみを実行します。これには /plugin から開始された更新と、コマンドが再実行される場合のバックグラウンド実行が含まれます。何も受け入れられていない場合、Claude Code はコマンドの実行を拒否し、ユーザーにそれを確認する方法を指示します。Claude Code は別のプラグインの依存関係としてコマンドソースプラグインをインストールしないため、ユーザーは最初にそれを自分でインストールします。
• エントリの command を変更するか、その mode を切り替える場合、ユーザーは既に持っているバージョンを保持し、Claude Code はコマンドの再実行を停止します。対話型セッションでは、/plugin エラータブは新しいコマンドを表示し、ユーザーが claude plugin update <plugin>@<marketplace> を実行して確認して受け入れるまで表示されます。

管理者は管理設定 disableCommandPluginSources を使用して、組織全体でコマンドソースをブロックできます。組織が allowManagedHooksOnly を設定する場合、Claude Code はデフォルトでコマンドソースをブロックします。

Claude Code がコマンドを再実行する場合

出力されたディレクトリはコマンドが実行された時点でのツールの状態を反映するため、Claude Code はこれらの時間にコマンドを再実行します：

• ユーザーがプラグインをインストールまたは更新するたびに
• セッションごとに 1 回、有効な各コマンドソースプラグインに対して、セッション開始直後にバックグラウンドで。この実行はマーケットプレイス自動更新を通じて行われないため、マーケットプレイスの自動更新設定に依存しません
• 起動時または /reload-plugins で、有効なプラグインのインストール済みバージョンがプラグインキャッシュから欠落している場合

ユーザーが CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC を設定する場合、Claude Code は 2 つのバックグラウンド実行をスキップします。明示的なインストールと更新は、その変数が設定されていてもコマンドを実行します。

コマンドのハッシュされた出力が変更された場合、Claude Code は結果を新しいバージョンとしてインストールし、実行中の対話型セッションでそれをリロードし、/reload-plugins が切り替わるのと同じコンポーネントを切り替えます。ユーザーはプラグインがリロードされたという通知を見ます。その場でリロードするとセッションのプロンプトキャッシュが無効になる場合、Claude Code は代わりにユーザーに /reload-plugins を実行するよう促し、キャッシュコストについて警告し、--force で再実行すると適用されます。

高度なプラグインエントリ

この例は、コマンド、エージェント、フック、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": "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
}

注意すべき重要な点：

• commands と agents: 複数のディレクトリまたは個別のファイルを指定できます。パスはプラグインルートを基準にしており、その内部に留まる必要があります。
  • Claude Code は、./../shared.md のようにプラグインディレクトリの外に解決されるパスを path escapes plugin directory エラーで拒否し、そのコンポーネントなしでプラグインをロードします
• ${CLAUDE_PLUGIN_ROOT}: フックコマンドと MCP サーバー設定でこの変数を使用して、プラグインのインストールディレクトリ内のファイルを参照します。
  • サーバータイプごとにどの設定フィールドがそれを置換するかについては、置換テーブルを参照してください
  • プラグイン更新を生き残るべき依存関係または状態の場合は、代わりに ${CLAUDE_PLUGIN_DATA} を使用します
• strict: false: これが false に設定されているため、プラグインは独自の plugin.json を必要としません。マーケットプレイスエントリがすべてを定義します。厳密モードを参照してください。

デフォルトでは、プラグインのスキルはそのソースの下の skills/ ディレクトリからロードされます。skills フィールドにリストされたパスはそのスキャンに追加されます：

"skills": ["./skills/", "./extra-skills/"]

複数のプラグインエントリがマーケットプレイスルート（source: "./") で 1 つの skills/ フォルダを共有する場合、各エントリが独自のスキルのみをロードするように特定のサブディレクトリをリストします：

"source": "./",
"skills": ["./skills/code-review", "./skills/docs"]

マーケットプレイスルート source では、リストされたパスはそのエントリの完全なセットであり、共有 skills/ フォルダ内の他のディレクトリはロードされません。./skills/ 自体またはプラグインルートをリストすると、完全なスキャンが保持されます。リストされたパスが存在しない場合、デフォルトスキャンが代わりに実行されます。

厳密モード

strict フィールドは、plugin.json がコンポーネント定義（スキル、エージェント、フック、MCP サーバー、出力スタイル）の権限であるかどうかを制御します。

各モードを使用する場合：

• strict: true: プラグインは独自の plugin.json を持ち、独自のコンポーネントを管理します。マーケットプレイスエントリは上に追加のスキルまたはフックを追加できます。これはデフォルトであり、ほとんどのプラグインで機能します。
• strict: false: マーケットプレイスオペレーターが完全な制御を望みます。プラグインリポジトリは生ファイルを提供し、マーケットプレイスエントリはプラグイン作成者の意図と異なる方法でプラグインのコンポーネントを再構成またはキュレートする場合に便利です。

マーケットプレイスのホストと配布

ユーザーが git リポジトリでホストされているマーケットプレイスを追加したり、そのマーケットプレイスがリストしている git ベースのプラグインをインストールしたりすると、Claude Code はそのマーケットプレイスまたはプラグインリポジトリをユーザーのマシンにクローンします。クローンは Git LFS コンテンツをダウンロードしないため、LFS で追跡されているファイルはポインタファイルとして到着します。プラグインが必要とするファイルを LFS の外に保つようにしてください。

GitHub でホストする（推奨）

GitHub はマーケットプレイスをホストして配布するための推奨される方法です。

1. リポジトリを作成する：マーケットプレイス用の新しいリポジトリを設定します
2. マーケットプレイスファイルを追加する：プラグイン定義を含む .claude-plugin/marketplace.json を作成します
3. チームと共有する：ユーザーは /plugin marketplace add owner/repo でマーケットプレイスを追加します

メリット：組み込みのバージョン管理、issue トラッキング、チームコラボレーション機能があります。

他の git サービスでホストする

GitLab、Bitbucket、自社ホストサーバーなど、任意の git ホスティングサービスが機能します。ユーザーは完全なリポジトリ URL で追加します。

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

プライベートリポジトリ

Claude Code はプライベートリポジトリからプラグインをインストールすることをサポートしています。代わりに Organization settings > Plugins を通じてマーケットプレイスを配布する場合、git 認証情報は関係ありません。organization sync は、claude.ai 上の organization の GitHub または GitLab 接続を通じてマーケットプレイスリポジトリを読み取ります。プライベートにできるプラグインソースについては、Distribute through organization settings を参照してください。

実行するコマンド

/plugin marketplace add、/plugin install、/plugin update、または /plugin marketplace update を実行すると、Claude Code は既存の git 認証情報ヘルパーを使用するため、gh auth login、macOS Keychain、または git-credential-store 経由の HTTPS アクセスはターミナルと同じように機能します。SSH アクセスは、ホストが既に known_hosts ファイルにあり、キーが ssh-agent に読み込まれている限り機能します。Claude Code はホストフィンガープリントとキーパスフレーズの対話的な SSH プロンプトを抑制するためです。GitHub の owner/repo 短縮形ソースはデフォルトで SSH 経由でクローンされます。代わりに HTTPS 経由でクローンするには、CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 を設定してください。

バックグラウンド自動更新

バックグラウンド更新チェックは、実行するコマンドと同じ方法で、設定された git 認証情報ヘルパーを使用してマーケットプレイスのリモートで新しいコミットをチェックします。SSH リモートの場合、ssh-agent に読み込まれたキーがチェックを認証します。Claude Code はチェックを非対話的に実行します。git のターミナルプロンプトと askpass プログラムをオフにし、認証情報ヘルパーにプロンプトを表示しないよう指示します。チェックが HTTPS 経由でプライベートリポジトリに認証できるかどうかは、ヘルパーに依存します。

• プロンプトなしで保存された認証情報を提供できるヘルパーはチェックを認証します。Git Credential Manager、macOS Keychain ヘルパー、および git-credential-store は、ホストの認証情報を保持すると、このように機能します。
• プロンプトが必要なヘルパーはバックグラウンドで応答できません。更新は静かに失敗し、既存のチェックアウトはそのままです。プラグインは最後に同期された状態から機能し続けます。/plugin marketplace update <name> を実行して、認証情報でマーケットプレイスを更新します。

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

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 を読み取ります。

organization settings を通じて配布する

Team または Enterprise プランで Organization settings > Plugins を通じてプラグインを配布する場合、これらのソースルールが適用されます。

• github.com と gitlab.com では、マーケットプレイスリポジトリはプライベートまたは内部である必要があります。Organization sync はホストに一致する接続を通じてリポジトリを読み取ります。
  • github.com：Claude GitHub App
  • Your GitHub Enterprise Server host：organization の GitHub Enterprise App
  • gitlab.com または自社管理の GitLab インスタンス：organization の GitLab configuration のそのホストのアクセストークン
• 各プラグインソースは github、url、または git-subdir タイプ、または ./ で始まる 相対パス である必要があります。metadata.pluginRoot の下で裸の名前でプラグインをリストする場合、organization sync はそれをサポートされていないソースとして拒否するため、./plugins/deploy-tools などのパスを書き出してください。
• プラグインソースは 3 つの場合にプライベートにできます。
  • マーケットプレイスリポジトリの所有者を共有する github.com ソース
  • GHE App がリポジトリにインストールされている organization の GitHub Enterprise ホスト上のソース
  • マーケットプレイスリポジトリと同じ GitLab ホスト上の url または git-subdir ソース。gitlab.com では、ソースはマーケットプレイスリポジトリと同じトップレベルグループまたはユーザー名前空間の下にある必要があります。
• その他のプラグインソースは、github.com、gitlab.com、または bitbucket.org 上のパブリックリポジトリである必要があり、organization sync は認証情報なしでフェッチします。Organization sync はこれらのルールがカバーしていないホスト上のプラグインソースを拒否します。

admin ワークフローについては、Manage plugins for your organization を参照してください。

プライベートプラグインを含めるには、プラグインフォルダをマーケットプレイスリポジトリ内に配置し、相対パス で参照します。Organization sync は配布中に各プラグインをパッケージ化するため、ユーザーは別のソースリポジトリへのアクセスが必要ありません。

例えば、この marketplace.json プラグインエントリは、マーケットプレイスリポジトリの plugins/deploy-tools にコミットしたプラグインを参照します。

{
  "name": "deploy-tools",
  "source": "./plugins/deploy-tools"
}

GitLab でホストされているマーケットプレイスを同期する

gitlab.com または自社管理の GitLab インスタンスからマーケットプレイスを同期するには、Owner が最初に Organization settings > Claude Code でそのホストの GitLab configuration を追加します。GitLab configuration はパブリックベータ版であり、プラグインマーケットプレイス同期にのみ適用されます。1 つを追加しても、GitLab リポジトリが cloud sessions で利用可能になることはありません。セットアップ手順については、Manage plugins for your organization を参照してください。

マーケットプレイスを追加するときは、https://gitlab.example.com/platform/claude-plugins などのプロジェクトの HTTPS URL を入力します。ネストされたサブグループ内のプロジェクトが機能します。Organization sync はプロジェクトのデフォルトブランチを読み取ります。Sync automatically をオンにすると、デフォルトブランチへのプッシュのみが同期を開始します。

トップレベルの bin ディレクトリから実行可能ファイルを除外する

organization settings を通じて配布するプラグインにトップレベルの bin/ ディレクトリを含めないでください。マーケットプレイス同期または直接アップロードのいずれかでプラグインが到着するかどうかに関わらず、claude.ai はそのようなプラグインを拒否します。

• マーケットプレイス同期：organization sync はそのプラグインを拒否し、マーケットプレイスの残りを同期します。エラーメッセージは Plugin contains a top-level bin/ directory で始まります。
• 直接アップロード：代わりに Organization settings > Plugins でプラグインをアップロードする場合、claude.ai は同じメッセージで拒否します。

実行可能ファイルを scripts/ などの別のディレクトリに保持し、skills、hooks、または MCP サーバー configs から ${CLAUDE_PLUGIN_ROOT}/scripts/<name> として参照してください。

チームのマーケットプレイスを必須にする

リポジトリを設定して、Claude Code がチームメンバーが プロジェクトフォルダを信頼 した後、マーケットプレイスを追加するようにできます。別のプロンプトはありません。マーケットプレイスを .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
  }
}

完全な設定オプションについては、Plugin settings を参照してください。

コンテナ用にプラグインを事前入力する

コンテナイメージと 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 を 1 回実行し、必要なプラグインをインストールしてから、結果の ~/.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 フラグを使用した非対話モードの両方で機能します。

動作の詳細。

• 読み取り専用：Claude Code はシードディレクトリに書き込みません。
• 自動更新が無効：シードマーケットプレイスは自動更新されません。
• シードエントリが優先：シードで宣言されたマーケットプレイスは、スタートアップのたびにユーザーの設定内の一致するエントリを上書きします。シードプラグインをオプトアウトするには、マーケットプレイスを削除する代わりに /plugin disable を使用します。
• パス解決：Claude Code はシードの JSON 内に保存されたパスを信頼するのではなく、実行時に $CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/ をプローブしてマーケットプレイスコンテンツを見つけます。これは、シードが構築された場所とは異なるパスにマウントされている場合でも、シードが正しく機能することを意味します。
• ミューテーションがブロック：シード管理マーケットプレイスに対して /plugin marketplace remove または /plugin marketplace update を実行すると、管理者にシードイメージを更新するよう求めるガイダンスで失敗します。
• 設定と構成：extraKnownMarketplaces または enabledPlugins がシードに既に存在するマーケットプレイスを宣言する場合、Claude Code はクローンする代わりにシードコピーを使用します。

マネージドマーケットプレイスの制限

プラグインソースの厳密な制御を必要とする organization の場合、管理者はマネージド設定の strictKnownMarketplaces 設定を使用して、ユーザーが追加できるプラグインマーケットプレイスを制限できます。単一実行のためにプラグイン、エージェント、MCP サーバーをサイドロードする CLI フラグも拒否するには、disableSideloadFlags とペアにします。マーケットプレイスのプラグインがコンテキスト内インストール提案として表示されるかをホワイトリストするには、pluginSuggestionMarketplaces を設定します。

strictKnownMarketplaces はプラグインが来るマーケットプレイスと一致し、その中のエントリではないため、ユーザーは許可されたマーケットプレイスから command source を持つプラグインをインストールできます。コマンドソースもブロックするには、disableCommandPluginSources を設定します。

strictKnownMarketplaces がマネージド設定で設定されている場合、制限動作は値に依存します。

一般的な設定

公式 Anthropic マーケットプレイスを含むすべてのマーケットプレイス追加を無効にします。

{
  "strictKnownMarketplaces": []
}

Claude Code は claude.ai から同期されたプラグイン をマーケットプレイスではなくアカウントからダウンロードするため、このロックダウンはそれらをカバーしません。それらも停止するには、マネージド設定で syncClaudeAiPlugins を false に設定するか、claude.ai で organization の Skills をオフにします。

公式 Anthropic マーケットプレイスのみを許可します。単一リポジトリエントリのマッチングは正確であるため、このエントリは同じリポジトリの ref または path バリアントをカバーしません。

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "anthropics/claude-plugins-official"
    }
  ]
}

このエントリを使用すると、Claude Code は既に登録されている公式マーケットプレイスを利用可能に保ち、新しいマシンでは、Claude Code を対話的に初めて開始するときにマーケットプレイスを自動的に登録します。

自動登録はすべてのマシンをカバーしていません。最も一般的に見落とされるのは。

• マシンの最初の対話的な起動の前に実行される非対話環境。
• Claude Code が既に公式マーケットプレイスをブロックするポリシーの下で対話的に実行されたマシン（空の配列ロックダウンなど）。Claude Code はブロックされた試みを記録し、ポリシーが変更された後は再試行しません。

これらのマシンでは、マーケットプレイスを同じ managed-settings.json の extraKnownMarketplaces に追加して Claude Code が自動的に登録するようにするか、claude plugin marketplace add anthropics/claude-plugins-official を実行します。

特定のマーケットプレイスのみを許可します。

{
  "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"
    }
  ]
}

owner-wildcard エントリを使用して GitHub organization の下のすべてのマーケットプレイスリポジトリを許可します。Owner wildcards には Claude Code v2.1.223 以降が必要です。

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/*"
    }
  ]
}

ホストの正規表現パターンマッチングを使用して、内部 git サーバーからすべてのマーケットプレイスを許可します。これは GitHub Enterprise Server または自社ホスト GitLab インスタンスの推奨アプローチです。

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

パスの正規表現パターンマッチングを使用して、特定のディレクトリからファイルシステムベースのマーケットプレイスを許可します。

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

pathPattern として ".*" を使用して、ネットワークソースを hostPattern で制御しながら、任意のファイルシステムパスを許可します。

制限がどのように機能するか

制限はネットワークまたはファイルシステム操作の前にチェックされます。チェックはマーケットプレイス追加時およびプラグインのインストール、更新、更新、自動更新時に実行されます。マーケットプレイスがポリシーが設定される前に追加され、そのソースがホワイトリストと一致しなくなった場合、Claude Code はそれからプラグインをインストールまたは更新することを拒否します。同じ強制が blockedMarketplaces に適用されます。

GitHub 所有者の下のすべてのマーケットプレイスリポジトリをブロックするには、blockedMarketplaces エントリで owner-wildcard 形式を使用します。{ "source": "github", "repo": "untrusted-org/*" }。Claude Code v2.1.223 以降が必要です。マッチングルールについては、ブロックリストとホワイトリストの間で異なり、Owner wildcards を参照してください。

ユーザーが Claude Code が フェッチするのではなくクローンする https:// リポジトリ URL（裸の github.com または gitlab.com リポジトリ URL など）を追加する場合、Claude Code は blockedMarketplaces の url エントリに対してもチェックします。Claude Code はエントリが同じ URL を名前付けする場合、追加をブロックします。その比較では、Claude Code は .git サフィックスと、ユーザーが # の後に追加する任意の ref を無視します。Claude Code v2.1.232 以降が必要です。v2.1.232 より前では、Claude Code は url エントリをホストされた marketplace.json ファイルとしてフェッチした URL に対してのみマッチしました。

ホワイトリストは owner-wildcard github エントリを除き、ほとんどのソースタイプに対して正確なマッチングを使用します。マーケットプレイスが許可されるには、すべての指定されたフィールドが一致する必要があります。

• GitHub ソースの場合：repo は必須であり、1 つのリポジトリを名前付けするか、owner-wildcard 形式 owner/* を使用してそのオーナーの下のすべてのリポジトリをカバーします。ワイルドカードエントリがどのようにマッチするか（大文字小文字ルールを含む）については、Owner wildcards を参照してください。単一リポジトリエントリの場合、ref は正確に一致する必要があるか、マーケットプレイスソースとホワイトリストエントリの両方に存在しない必要があり、同じルールが path に適用されます。
• URL ソースの場合：完全な URL は正確に一致する必要があります。
• hostPattern ソースの場合：マーケットプレイスホストは正規表現パターンに対してマッチされます。
• pathPattern ソースの場合：マーケットプレイスのファイルシステムパスは正規表現パターンに対してマッチされます。

ホワイトリストの正確なマッチングは、末尾のスラッシュ、.git サフィックス、または ssh:// と https:// スキームのみが異なる URL を異なる値として扱います。organization のマーケットプレイスが複数の URL 形式でクローンできる場合、リテラル URL よりも hostPattern エントリを優先して、https://、ssh://、および user@host:path 形式がすべてマッチするようにします。

claude.ai でホストされているマーケットプレイス はホストでマッチされます。hostPattern エントリが claude.ai にマッチする場合、strictKnownMarketplaces と blockedMarketplaces の両方でそれを管理します。ホワイトリストでは、そのようなエントリはメンバーの個人的な claude.ai アップロードを許可しません。Claude Code v2.1.273 以降が必要です。

strictKnownMarketplaces は マネージド設定 で設定されるため、個々のユーザーとプロジェクト設定はこれらの制限をオーバーライドできません。

サポートされているすべてのソースタイプと extraKnownMarketplaces との比較を含む完全な設定詳細については、strictKnownMarketplaces reference を参照してください。

バージョン解決とリリースチャネル

プラグインバージョンはキャッシュパスと更新検出を決定します。解決されたバージョンがユーザーが既に持っているものと一致する場合、/plugin update と自動更新はプラグインをスキップします。git ベースのソースの場合、version を省略すると、Claude Code はソースの解決されたコミット SHA を使用するため、ユーザーはそのコミットが変更されるたびに更新を取得します。これは内部または積極的に開発されているプラグインの最も簡単なセットアップです。完全な解決順序（archive ソースを含む）については、Version management を参照してください。

リリースチャネルを設定する

プラグインの「stable」と「latest」リリースチャネルをサポートするには、同じリポジトリの異なる ref または SHA を指す 2 つのマーケットプレイスを設定できます。その後、マネージド設定を通じて各ユーザーグループに独自のマーケットプレイスを提供できます。2 つの方法のいずれかで。

• 各グループのデバイスに個別の endpoint-managed settings（マネージド設定ファイルまたは MDM プロファイルなど）をデプロイします。Claude Code がマネージドソースを組み合わせる方法 は、organization 全体のソースも持つデバイスでグループごとのファイルまたはプロファイルが適用されるかどうかを示します。
• グループごとに 1 つの Claude apps gateway policy を定義します。ゲートウェイは一致ルールが適合する最初のポリシーを適用するため、各ユーザーがグループのポリシーに到達するようにポリシーを順序付けます。グループポリシーの extraKnownMarketplaces はキャッチオールポリシーのマップを置き換えるため、グループが必要とするすべてのマーケットプレイスをグループのポリシーにリストします。チャネルマーケットプレイスのみではなく。

admin コンソールからのサーバー管理設定は organization 内のすべてのユーザーに適用 されるため、グループごとの割り当てを実行できません。

例

{
  "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"
      }
    }
  ]
}

チャネルをユーザーグループに割り当てる

リリースチャネルを設定する の下で説明されているグループごとの endpoint-managed settings またはゲートウェイポリシーを通じて、各マーケットプレイスをそのユーザーグループに割り当てます。例えば、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"
      }
    }
  }
}

依存関係バージョンをピン留めする

プラグインは依存関係を semver 範囲に制限して、依存関係への更新が依存プラグインを破壊しないようにできます。{plugin-name}--v{version} git-tag 規約、範囲構文、および同じ依存関係に対する複数の制約がどのように組み合わされるかについては、Constrain plugin dependency versions を参照してください。

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

プラグインの 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 が削除されたことを記録します。

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

ユーザーが古い名前がまだ設定に含まれた状態で Claude Code を開始すると、Claude Code は 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 の以前のバージョンは renames フィールドを無視し、古い名前に対して plugin-not-found を報告します。

検証とテスト

マーケットプレイスを共有する前にテストしてください。検証はファイル構造をチェックします。プラグインが現実的なプロンプトで Claude の動作を変更するかどうかをテストするには、新しいバージョンを公開する前に claude plugin eval を使用してその eval スイートを実行してください。

マーケットプレイスディレクトリから 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 を追加します

URL はスキームを含める必要があります。Claude Code v2.1.196 以降、gitlab.example.com/team/plugins のようにスキームなしで入力されたホストは、無効な owner/repo ショートハンドとして拒否され、エラーメッセージは https:// を追加するか、ローカルパスに ./ を使用するよう指示します。以前のバージョンでは、これを GitHub リポジトリパスとして誤読し、GitHub の見つからないエラーでクローン時に失敗します。

オプション：

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 の From claude.ai: セクションに表示されている名前で、claude.ai でホストされているマーケットプレイスを追加します。

claude plugin marketplace add --claudeai claudeai-organization-library

--claudeai を使用すると、コマンドは --scope と --sparse を拒否します。マーケットプレイスはアカウント用にホストされており、設定ファイルで宣言されていないため、プロジェクトの .claude/settings.json 経由で共有することはできません。

プラグインマーケットプレイスリスト

設定されたすべてのマーケットプレイスをリストします。

claude plugin marketplace list [options]

オプション：

--json を使用すると、各エントリには name、source、マーケットプレイスが保存されているローカルキャッシュパスを含む installLocation フィールド、およびソース固有のフィールドが含まれます：GitHub ソースの場合は repo、Git および URL ソースの場合は url、ローカルソースの場合は path。GitHub および Git ソースには、マーケットプレイスが固定されたブランチまたはタグで追加された場合、ref フィールドも含まれます。

追加された claude.ai マーケットプレイスにはローカルクローンがないため、そのエントリは installLocation の代わりに claude.ai 識別子である marketplaceId と organizationUuid を含みます。

プラグインが claude.ai アカウントから同期されるターミナルセッションでは、テキストリストの末尾に From claude.ai: セクションがあり、追加したマーケットプレイスを超えて claude.ai がアカウント用にリストしているものを名前で示します。それらの 1 つを追加するには、claude.ai から追加を参照してください。--json 出力は設定されたマーケットプレイスのみをカバーし、そのセクションは除外されます。Claude Code v2.1.273 以降が必要です。

プラグインマーケットプレイス削除

設定されたマーケットプレイスを削除します。エイリアス rm も受け入れられます。

claude plugin marketplace remove <name> [options]

引数：

• <name>：削除するマーケットプレイス名。claude plugin marketplace list で表示されます。これは渡したソースではなく、marketplace.json の name です

オプション：

プラグインマーケットプレイス更新

マーケットプレイスをソースから更新して、新しいプラグインとバージョン変更を取得します。ブランチまたはタグ ref で追加されたマーケットプレイスは、リポジトリのデフォルトブランチではなく、その ref の最新コミットに更新されます。

claude plugin marketplace update [name]

引数：

• [name]：更新するマーケットプレイス名。claude plugin marketplace list で表示されます。省略した場合はすべてのマーケットプレイスを更新します

remove と update の両方は、読み取り専用のシード管理マーケットプレイスに対して実行すると失敗します。すべてのマーケットプレイスを更新する場合、シード管理エントリはスキップされ、他のマーケットプレイスは引き続き更新されます。シード提供プラグインを変更するには、管理者にシードイメージを更新するよう依頼してください。コンテナ用にプラグインを事前入力するを参照してください。

トラブルシューティング

マーケットプレイスが読み込まれない

症状: マーケットプレイスを追加できない、またはそこからプラグインが見えない

解決策:

• マーケットプレイス URL がアクセス可能であることを確認してください
• .claude-plugin/marketplace.json が指定されたパスに存在することを確認してください
• claude plugin validate . または /plugin validate . をマーケットプレイスディレクトリから実行して JSON 構文が有効であることを確認してください。スキル、エージェント、コマンドのフロントマターを確認するには、マニフェストなしでプラグインまたはディレクトリを検証するを参照してください
• プライベートリポジトリの場合は、アクセス権限があることを確認してください

マーケットプレイス検証エラー

マーケットプレイスディレクトリから 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 からのみ下降します。

マーケットプレイスディレクトリから、Claude Code はプラグインのスキル、エージェント、コマンド、またはフックファイルを開きません。これらのファイルのエラーを見つけるには、マニフェストなしでプラグインまたはディレクトリを検証するを参照してください。以下の表は、マーケットプレイスディレクトリからの最も一般的なエラーと、それぞれの原因と修正方法を示しています:

警告 （ブロッキングなし）:

• 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 マーケットプレイス同期はそれらを拒否します。
• Marketplace name "x" is reserved in Claude Desktop: マーケットプレイスが org、org-provisioned、または unknown という名前である（大文字小文字は問わない）。Claude Code はこれらの名前を受け入れますが、Claude Desktop の管理マーケットプレイス同期はマーケットプレイス全体を拒否します。マーケットプレイスの名前を変更してください。v2.1.221 より前では、claude plugin validate はこのチェックを実行していませんでした。
• Marketplace name "x" is not accepted by Claude Desktop または Plugin name "x" is not accepted by Claude Desktop: Claude Desktop は、文字、数字、.、_、- で構成され、文字または数字で始まる最大 128 文字の名前を受け入れます。Claude Code は他の形式を受け入れますが、Claude Desktop の管理マーケットプレイス同期は名前チェックに失敗したマーケットプレイスを拒否し、名前チェックに失敗したプラグインエントリを静かにドロップします。マーケットプレイスまたはプラグインの名前を変更してください。v2.1.221 より前では、claude plugin validate はこれらのチェックを実行していませんでした。

マニフェストなしでプラグインまたはディレクトリを検証する

フロントマターが解析されないスキル、エージェント、コマンドファイルを見つけるには、claude plugin validate を実行し、それらを保持するディレクトリを指定してください。Claude Code は指定したディレクトリの外を見ません。plugin.json を持つプラグインに対する 1 つを除くすべての実行には、Claude Code v2.1.233 以降が必要です。

指定するディレクトリを選択する

Claude Code は、指定したディレクトリに応じて異なるファイルをチェックします。最初の列で確認したいものを見つけ、その行のコマンドを実行してください:

スキルがルート `SKILL.md` であるプラグインをチェックする

プラグインディレクトリに対して claude plugin validate を実行すると、Claude Code はプラグインルートの SKILL.md をチェックしません。プラグインが skills という名前のディレクトリにある場合は、コマンドを 2 回実行してください:

• その skills ディレクトリを指定して、プラグインのルート SKILL.md をチェックしてください。
• プラグインディレクトリを指定して、残りをチェックしてください。

プラグインが plugins/ などの別の名前の下にある場合、skills ディレクトリの実行は利用できず、ルート SKILL.md をチェックする実行がありません。

シンボリックリンクの背後にあるファイルをチェックする

claude plugin validate を実行すると、Claude Code は指定したディレクトリ内のシンボリックリンクをフォローしません。リンクがどこにあるかによって、実行内容が異なります:

• プラグインまたは .claude ルートの下にリンクされた skills、agents、または commands ディレクトリ: Claude Code は、その中のものが何も読まれなかったことを警告します。
• skills、agents、または commands ディレクトリ内のリンクされたエントリ: Claude Code はそれをスキップし、ディレクトリごとにスキップしたエントリの数をセッションが読み込むことを警告します。
• 指定した skills、agents、または commands ディレクトリ自体がシンボリックリンク、またはその親 .claude ディレクトリがシンボリックリンク: Claude Code はエラーを報告し、その中のものをチェックしません。代わりに実際のディレクトリを指定してください。

2 つのスキルケースでは、実行は警告付きで成功します。リンクされたファイルをチェックするには、再度実行し、それらを直接保持するディレクトリを指定してください:

• skills ディレクトリが兄弟プラグインのスキルにリンクしているプラグイン: 兄弟プラグインのディレクトリを指定してください。
• ~/.claude/skills または .claude/skills のシンボリックリンクされたスキルエントリ: Claude Code はセッションでエントリをフォローします。チェックするには、実際のフォルダを保持する skills という名前のディレクトリを指定してください。

検証結果を読む

クリーンな実行は Validation passed で終了します。

No manifest found in directory は、Claude Code がそこに plugin.json または marketplace.json を見つけず、その下で調査するディレクトリにスキル、エージェント、またはコマンドファイルがないことを意味します。代わりに、ファイルを保持する skills、agents、または commands ディレクトリを指定してください。

Claude Code がこれらの実行から報告する 2 つのエラーと、それぞれの修正方法:

• YAML frontmatter failed to parse: ...: スキル、エージェント、またはコマンドファイルのフロントマターブロック内の YAML を修正してください。修正するまで、セッションはそのファイルからフロントマターフィールドを読み込みません
• Invalid JSON syntax: ... on hooks/hooks.json: JSON 構文を修正してください。修正するまで、セッションはそのファイルのフックなしでプラグインを読み込みます。Claude Code はこのエラーをプラグイン実行でのみ報告します

プラグイン実行では、Claude Code はプラグインルートの CLAUDE.md についても警告します。plugin.json のコンポーネントパスフィールドを通じて設定したパスについては、Claude Code は各パスが存在することをチェックしますが、そこのファイルは読み込みません。

プラグインインストール失敗

症状: マーケットプレイスは表示されるがプラグインのインストールが失敗する

解決策:

• プラグインソース URL がアクセス可能であることを確認してください
• プラグインディレクトリに必須ファイルが含まれていることを確認してください
• GitHub ソースの場合は、リポジトリがパブリックであるか、アクセス権限があることを確認してください
• プラグインソースを手動でテストしてクローン/ダウンロードしてください
• ソースが ref と sha の両方をピンしている場合、削除されたアップストリームブランチまたはタグは、GitHub、GitLab、Bitbucket を含むほとんどの git ホストでのインストールをブロックしません。AWS CodeCommit などの SHA でのコミット取得をサポートしないサーバーでは、ref は依然として存在する必要があり、ピンされたコミットはそこから到達可能である必要があります。インストールが依然として失敗する場合は、ピンされたコミットがリポジトリに依然として存在することを確認してください

プライベートリポジトリ認証失敗

症状: プライベートリポジトリからプラグインをインストールするときに認証エラーが発生する

解決策:

手動インストールと更新の場合:

• git プロバイダーで認証されていることを確認してください（例: GitHub の場合は gh auth status を実行）
• 認証情報ヘルパーが設定されていることを確認してください: git config --global credential.helper
• git ls-remote <marketplace-url> を実行して、git が単独で認証できるかテストしてください。git がユーザー名またはパスワードを要求する場合は、最初に認証情報を保存してください: GitHub over HTTPS の場合は gh auth setup-git を実行し、SSH リモートの場合はキーを ssh-agent に読み込んでください

バックグラウンド自動更新の場合:

• バックグラウンドチェックは設定された git 認証情報ヘルパーを使用しますが、プロンプトを表示しません。そのため、ヘルパーは保存された認証情報で応答できる必要があります。ssh-agent に読み込まれたキーを持つ SSH リモートも認証します
• ヘルパーがプロンプトを表示する必要がある場合、バックグラウンド更新は静かに失敗し、既存のチェックアウトが所定の位置に留まります。ヘルパーに最初にサインインして、ホストの認証情報を保持するようにしてください。GitHub の場合は、gh auth login を実行してから gh auth setup-git を実行してください
• チェックが新しいコミットを見つけた場合、またはリモートに到達または認証できない場合、Claude Code は同じ認証情報でマーケットプレイスを再クローンします。再クローンは大規模なリポジトリでタイムアウトする可能性があります
• CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 を設定して、バックグラウンドチェックがリモートに到達または認証できない場合に既存のチェックアウトを保持してください
• 大規模なリポジトリで再クローンがタイムアウトする場合は、CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MSで制限を増やしてください
• または、認証情報を使用する /plugin marketplace update <name> でプライベートマーケットプレイスを手動で更新してください

v2.1.280 より前では、バックグラウンドチェックは認証情報ヘルパーなしで実行され、HTTPS 経由でプライベートリポジトリに認証できませんでした。

オフライン環境でマーケットプレイス更新が失敗する

症状: オフラインまたはエアギャップ環境では、バックグラウンドマーケットプレイス更新がリモートに到達できず、Claude Code が成功できない再クローンを繰り返し試みます。

原因: バックグラウンド更新はマーケットプレイスのリモートで新しいコミットをチェックし、チェックがリモートに到達できない場合、Claude Code はマーケットプレイスを再度クローンしようとします。オフラインでは、クローンは同じ方法で失敗し、既存のチェックアウトが所定の位置に留まります。v2.1.274 より前では、更新は既存のチェックアウトで git pull を実行し、プルが失敗したときにチェックアウトを脇に移動して再クローンし、その後ベストエフォートベースで復元していました。

更新はスタートアップ後にバックグラウンドで実行されるため、スタートアップは遅延しません。各セッションは依然として失敗した試みを繰り返し、各 git 操作は120 秒のタイムアウトを待つことができます。

解決策: CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 を設定して、チェックがリモートに到達できない場合に再クローン試行をスキップし、既存のチェックアウトを使用し続けてください:

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

リポジトリが到達不可能になる完全オフラインデプロイメントの場合は、代わりにCLAUDE_CODE_PLUGIN_SEED_DIRを使用してビルド時にプラグインディレクトリを事前入力してください。

Git 操作がタイムアウトする

症状: プラグインのインストールまたはマーケットプレイスの更新が「Git clone 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 ベースのマーケットプレイスで相対パスを持つプラグインが失敗する

症状: https://example.com/marketplace.json などの URL を通じてマーケットプレイスを追加しましたが、"./plugins/my-plugin" などの相対パスソースを持つプラグインが its marketplace entry path does not stay inside the marketplace directory でインストールに失敗します。既にインストールされているプラグインは Plugin source path refused で読み込みに失敗します。両方のメッセージにエラーリファレンスエントリがあります。

原因: URL ベースのマーケットプレイスを追加すると、marketplace.json ファイル自体のみがダウンロードされ、Claude Code はそのサーバーから相対パスでプラグインファイルをフェッチしません。マーケットプレイスエントリの相対パスは、ダウンロードされなかったリモートサーバー上のファイルを参照します。

解決策:

• 外部ソースを使用: プラグインエントリを相対パス以外の任意のプラグインソースに変更してください:

  { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
  

• Git ベースのマーケットプレイスを使用: マーケットプレイスを Git リポジトリでホストし、git URL で追加してください。Git ベースのマーケットプレイスはリポジトリ全体をクローンするため、相対パスが正しく機能します。

インストール後にファイルが見つからない

症状: プラグインはインストールされますが、ファイルへの参照が失敗します。特にプラグインディレクトリの外のファイル

原因: プラグインは、リンクモードの command ソースを除き、その場で使用されるのではなく、キャッシュディレクトリにコピーされます。コピーされたプラグインのディレクトリの外のファイルを参照するパス（../shared-utils など）は、それらのファイルがコピーされないため機能しません。

解決策: プラグインキャッシングとファイル解決を参照して、シンボリックリンクとディレクトリ再構成を含む回避策を確認してください。

追加のデバッグツールと一般的な問題については、デバッグと開発ツールを参照してください。

関連項目

• 既成プラグインの検出とインストール - 既存のマーケットプレイスからプラグインをインストール
• プラグイン - 独自のプラグインの作成
• プラグインリファレンス - 完全な技術仕様とスキーマ
• プラグイン設定 - プラグイン設定オプション
• strictKnownMarketplaces リファレンス - 管理マーケットプレイス制限