メインコンテンツへスキップ
プラグインは、plugin.json またはマーケットプレイスエントリにリストすることで、他のプラグインに依存できます。デフォルトでは、依存関係は最新の利用可能なバージョンを追跡するため、アップストリームリリースは警告なしにプラグインの依存関係を変更できます。バージョン制約を使用すると、移動を選択するまで、依存関係をテスト済みのバージョン範囲に保つことができます。 依存関係を宣言するプラグインをインストールすると、Claude Code は依存関係を自動的に解決してインストールし、インストール出力の最後に追加された依存関係をリストします。依存関係が後で見つからなくなった場合、/reload-plugins とバックグラウンドプラグイン自動更新により、設定済みマーケットプレイスにそのマーケットプレイスが既にある場合は、それを再インストールします。依存プラグインで claude plugin install を再実行するか、claude plugin marketplace add でマーケットプレイスを追加することでも、未解決の依存関係が解決されます。追加していないマーケットプレイスからの依存関係は未解決のままになります。 このガイドは、plugin.json で依存関係を宣言するプラグイン作成者と、リリースにタグを付けるマーケットプレイス保守者向けです。依存関係を持つプラグインをインストールするには、プラグインの検出とインストール を参照してください。完全なマニフェストスキーマについては、プラグインリファレンス を参照してください。

依存関係のバージョンを制約する理由

2 つのチームがプラグインを公開する内部マーケットプレイスを考えてみてください。プラットフォームチームは、シークレットバックエンドをラップする MCP サーバーである secrets-vault を保守しています。デプロイチームは、デプロイ中に認証情報を取得するために secrets-vault を呼び出す deploy-kit を保守しています。 deploy-kitsecrets-vault v2.1.0 に対してテストされています。バージョン制約がない場合、プラットフォームチームが MCP ツールの名前を変更するリリースにタグを付けると、次回の自動更新により、すべてのエンジニアの secrets-vault が新しいバージョンに移動し、deploy-kit が破損します。 バージョン制約を使用すると、deploy-kitsecrets-vault~2.1.0 範囲内にあることが必要であることを宣言します。deploy-kit がインストールされているエンジニアは、最高の一致する 2.1.x パッチに留まります。デプロイチームは、より広い制約を持つ新しい deploy-kit バージョンを公開することで、独自のスケジュールでアップグレードします。

バージョン制約を使用して依存関係を宣言する

プラグインの .claude-plugin/plugin.jsondependencies 配列に依存関係をリストします。各エントリは、プラグイン名またはバージョン制約を持つオブジェクトのいずれかです。 次のマニフェストは、1 つのバージョン指定なしの依存関係と 1 つの制約付き依存関係を宣言しています。
.claude-plugin/plugin.json
エントリは、上記の例の "audit-logger" のようにプラグイン名のみを含む単純な文字列にすることができます。これは、そのプラグインのマーケットプレイスが提供するバージョンに依存します。より詳細に制御するには、次のフィールドを持つオブジェクトを使用します。 version フィールドは、キャレット、チルダ、ハイフン、比較演算子範囲を含む、Node の semver パッケージでサポートされている任意の式を受け入れます。^2.0.0-0 のようなプレリリースサフィックスで範囲がオプトインしない限り、2.0.0-beta.1 などのプレリリースバージョンは除外されます。

チームのプラグインをバンドルする

必須の name の他に、プラグインマニフェストは dependencies 配列のみで構成することができます。これをインストールすると、すべての依存関係がプルされます。これにより、キュレーションされたプラグインセットを 1 つのインストールの背後にパッケージ化する方法になります。 例えば、プラットフォームチームは内部マーケットプレイスでロール固有のバンドルを公開できるため、エンジニアは各ツールを個別にインストールする代わりに、1 つの claude plugin install を実行できます。
.claude-plugin/plugin.json
backend-standard をインストールすると、4 つの依存関係すべてが解決され、インストールされます。 後で標準セットにツールを追加するには、追加の依存関係を含む新しい backend-standard バージョンを公開します。非 Anthropic マーケットプレイスではデフォルトで自動更新がオフになっているため、エンジニアは次の 2 つの方法のいずれかで新しいバージョンを取得します。
  • /plugin でマーケットプレイスの自動更新を有効にします。次の自動更新によってバンドルが新しいバージョンに移動し、追加される依存関係がインストールされます。
  • claude plugin update backend-standard を実行してから、/reload-plugins を実行して、新しく追加された依存関係をインストールします。
組織全体にバンドルをロールアウトするには、バンドルプラグインを 管理設定enabledPlugins に追加します。

別のマーケットプレイスからプラグインに依存する

デフォルトでは、Claude Code は、それを宣言するプラグインとは異なるマーケットプレイスに存在する依存関係の自動インストールを拒否します。これにより、1 つのマーケットプレイスが、確認していないソースからプラグインを静かにプルインするのを防ぎます。 これを許可するには、ルートマーケットプレイスの保守者が、ターゲットマーケットプレイス名を marketplace.jsonallowCrossMarketplaceDependenciesOn に追加します。ルートマーケットプレイスは、ユーザーがインストールしているプラグインをホストするマーケットプレイスです。そのアローリストのみが参照されるため、信頼は中間マーケットプレイスを通じてチェーンされません。 次の marketplace.json は、deploy-kitacme-shared からプラグインに依存することを許可しています。
.claude-plugin/marketplace.json
フィールドが欠落しているか、ターゲットマーケットプレイスが含まれていない場合、インストールは cross-marketplace エラーで失敗し、設定するフィールドに名前を付けます。ユーザーは依然として依存関係を手動で最初にインストールできます。これにより、アローリストを変更することなく制約が満たされます。

バージョン解決のためのタグプラグインリリース

バージョン制約は、マーケットプレイスリポジトリの git タグに対して解決されます。Claude Code が依存関係の利用可能なバージョンを見つけるには、アップストリームプラグインのリリースが特定の命名規則を使用してタグ付けされている必要があります。 各リリースを {plugin-name}--v{version} としてタグ付けします。ここで、{version} はそのコミットの plugin.jsonversion フィールドと一致します。プラグインディレクトリから、以下を実行します。
claude plugin tag コマンドは、プラグインのマニフェストとそれを囲むマーケットプレイスエントリからタグ名を導出します。タグを作成する前に、プラグインの内容を検証し、plugin.json とマーケットプレイスエントリがバージョンについて一致していることを確認し、プラグインディレクトリの下でクリーンな作業ツリーを要求し、タグが既に存在する場合は拒否します。--dry-run を追加して、タグを作成せずにタグ付けされるものを確認します。plugin.json とマーケットプレイスエントリを自分で同期させておけば、git tag secrets-vault--v2.1.0 を直接実行することと同等です。 プラグイン名プレフィックスにより、1 つのマーケットプレイスリポジトリが独立したバージョン行を持つ複数のプラグインをホストできます。--v セパレータは、完全なプラグイン名のプレフィックスマッチとして解析されるため、ハイフンを含むプラグイン名は正しく処理されます。 { "name": "secrets-vault", "version": "~2.1.0" } を宣言するプラグインをインストールすると、Claude Code はマーケットプレイスのタグをリストし、secrets-vault--v で始まるタグにフィルタリングし、~2.1.0 を満たす最高バージョンを取得します。一致するタグが存在しない場合、依存プラグインは利用可能なバージョンをリストするエラーで無効になります。 ローカルフォルダパスとして追加されたマーケットプレイスは、フォルダが git リポジトリである場合、同じ方法でタグを解決します。これには Claude Code v2.1.196 以降が必要です。2 つのケースでは、Claude Code は依存関係をフォルダの現在の内容からインストールします。
  • 以前のバージョンはローカルフォルダマーケットプレイスからタグを読み取らないため、制約付き依存関係はそのコピーが範囲を満たす場合にのみロードされます。
  • git リポジトリではないローカルフォルダには、バージョンに関係なくタグがありません。
解決されたタグの semver は plugin.jsonversion とは別に記録されるため、制約チェックは plugin.json がそのコミットで古い値を持っていても、実際に取得されたタグを使用します。タグ解決インストールのキャッシュディレクトリ名には 12 文字のコミット SHA サフィックスが含まれるため、メンテナーがタグを別のコミットに強制移動した場合、次のインストールは古いコンテンツを再利用する代わりに新しいキャッシュディレクトリを取得します。
npm マーケットプレイスソースの場合、タグベースの解決は git バックアップソースにのみ適用されるため、制約はどのバージョンが取得されるかを制御しません。制約は依然としてロード時にチェックされ、インストールされたバージョンが満たさない場合、依存プラグインは dependency-version-unsatisfied で無効になります。

制約がどのように相互作用するか

複数のインストール済みプラグインが同じ依存関係を制約する場合、Claude Code はそれらの範囲を交差させ、依存関係をすべての範囲を満たす最高バージョンに解決します。下の表は、一般的な組み合わせがどのように解決されるかを示しています。 自動更新は、制約付き依存関係を、マーケットプレイスの最新バージョンではなく、インストール済みプラグインのすべての範囲を満たす最高 git タグで取得するため、依存関係は許可された範囲内で更新を受け続けます。すべての範囲を満たすタグがない場合、自動更新はその依存関係をスキップし、スキップを /plugin エラータブに表示し、制約するプラグインに名前を付けます。 依存関係を制約する最後のプラグインをアンインストールすると、依存関係は保持されなくなり、次の更新でマーケットプレイスエントリの追跡を再開します。

依存関係を持つプラグインを有効または無効にする

プラグインを有効にすると、それが依存するプラグインも有効になり、別の有効なプラグインがまだそれを必要としている場合、プラグインを無効にすることはブロックされます。両方の動作には Claude Code v2.1.143 以降が必要です。以前のバージョンは、名前付きプラグインのみを有効または無効にし、次のロード時に dependency-unsatisfied エラーを表示します。 プラグインを有効にすると、Claude Code は同じスコープでその依存関係も有効にします。依存関係が独自の依存関係を持つ場合、Claude Code はそれらも有効にします。成功メッセージは、名前を付けたプラグインと一緒に有効になったものをリストします。依存関係を有効にできない場合、コマンドは拒否され、何がブロックしているか、およびそれを修正する方法が表示されます。 これは、依存関係がマニフェストで defaultEnabled: false を設定している場合でも当てはまります。Claude Code はそれに対して明示的な true を書き込むためです。同じことがインストール時にも適用されます。アクティブなプラグインを満たすために取得された依存関係は、独自のデフォルトに関係なく true でインストールされます。 プラグインを無効にすると、別の有効なプラグインがまだそれに依存している場合、Claude Code は拒否します。エラーはそれに依存するプラグインに名前を付け、正しい順序でそれらを無効にする連鎖コマンドを提供します。 たとえば、deploy-kitsecrets-vault に依存している場合、secrets-vault だけを無効にすると、次のような出力で失敗します。
エラーから連鎖コマンドをコピーして、1 つのステップで完全なセットを無効にします。

孤立した自動インストール依存関係を削除する

自動インストール依存関係は、それらをインストールしたプラグインがアンインストールされた後もディスク上に留まります。これは、依存プラグインを再インストールしたい場合や、依存関係を直接使用し続けたい場合に備えてです。それらをクリーンアップするには、claude plugin prune を実行して、インストール済みプラグインがもう必要としない自動インストール依存関係をリストし、確認プロンプトの後に削除します。これには Claude Code v2.1.121 以降が必要です。
デフォルトでは、prune はユーザースコープで動作します。別のスコープをターゲットにするには、--scope project または --scope local を使用します。--dry-run を渡して、何が削除されるかをリストし、何も変更しません。-y を渡して確認プロンプトをスキップします。stdin または stdout がターミナルでない場合、prune は孤立したものをリストして終了し、-y が渡されない限り削除しません。 アンインストールの一部として prune するには、claude plugin uninstall--prune を渡します。名前付きプラグインを削除した後、Claude Code は自動インストール依存関係をスキャンして、現在孤立しているものを削除します。自分でインストールしたプラグインは決して prune されません。別のプラグインの dependencies 配列を通じて自動的にインストールされたものだけです。 たとえば、deploy-kit をアンインストールし、それが残す依存関係をクリーンアップするには、以下を実行します。

依存関係エラーを解決する

依存関係の問題は、claude plugin list/plugin インターフェイスに表示されます。Claude Code は、エラーを解決するまで影響を受けたプラグインを無効にします。以下の表は、最も一般的なエラーとその解決方法を示しています。 これらのエラーをプログラムで確認するには、claude plugin list --json を実行し、各プラグインの errors フィールドを読みます。

関連項目