メインコンテンツへスキップ

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

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

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

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

プラグインの .claude-plugin/plugin.json の dependencies 配列に依存関係をリストします。各エントリは、プラグイン名またはバージョン制約を持つオブジェクトのいずれかです。 次のマニフェストは、1 つのバージョン指定なしの依存関係と 1 つの制約付き依存関係を宣言しています。
.claude-plugin/plugin.json
{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}
エントリは、上記の例の "audit-logger" のようにプラグイン名のみを含む単純な文字列にすることができます。これは、そのプラグインのマーケットプレイスが提供するバージョンに依存します。より詳細に制御するには、次のフィールドを持つオブジェクトを使用します。
フィールド型説明
namestringプラグイン名。宣言するプラグインと同じマーケットプレイス内で解決されます。必須。
versionstring~2.1.0、^2.0、>=1.4、または =2.1.0 などの semver 範囲。依存関係は、この範囲を満たす最高のタグ付きバージョンで取得されます。
marketplacestringname を解決する別のマーケットプレイス。クロスマーケットプレイス依存関係は、ターゲットマーケットプレイスがルートマーケットプレイスの marketplace.json の allowCrossMarketplaceDependenciesOn にリストされていない限り、ブロックされます。
version フィールドは、キャレット、チルダ、ハイフン、比較演算子範囲を含む、Node の semver パッケージでサポートされている任意の式を受け入れます。^2.0.0-0 のようなプレリリースサフィックスで範囲がオプトインしない限り、2.0.0-beta.1 などのプレリリースバージョンは除外されます。

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

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

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

バージョン制約は、マーケットプレイスリポジトリの git タグに対して解決されます。Claude Code が依存関係の利用可能なバージョンを見つけるには、アップストリームプラグインのリリースが特定の命名規則を使用してタグ付けされている必要があります。 各リリースを {plugin-name}--v{version} としてタグ付けします。ここで、{version} はそのコミットの plugin.json の version フィールドと一致します。プラグインディレクトリから、以下を実行します。 
claude plugin tag --push
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 を満たす最高バージョンを取得します。一致するタグが存在しない場合、依存プラグインは利用可能なバージョンをリストするエラーで無効になります。 解決されたタグの semver は plugin.json の version とは別に記録されるため、制約チェックは plugin.json がそのコミットで古い値を持っていても、実際に取得されたタグを使用します。タグ解決インストールのキャッシュディレクトリ名には 12 文字のコミット SHA サフィックスが含まれるため、メンテナーがタグを別のコミットに強制移動した場合、次のインストールは古いコンテンツを再利用する代わりに新しいキャッシュディレクトリを取得します。
npm マーケットプレイスソースの場合、タグベースの解決は git バックアップソースにのみ適用されるため、制約はどのバージョンが取得されるかを制御しません。制約は依然としてロード時にチェックされ、インストールされたバージョンが満たさない場合、依存プラグインは dependency-version-unsatisfied で無効になります。

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

複数のインストール済みプラグインが同じ依存関係を制約する場合、Claude Code はそれらの範囲を交差させ、依存関係をすべての範囲を満たす最高バージョンに解決します。下の表は、一般的な組み合わせがどのように解決されるかを示しています。
プラグイン A が必要プラグイン B が必要結果
^2.0>=2.12.1.0 以上の最高 2.x タグで 1 つのインストール。両方のプラグインが読み込まれます。
~2.1~3.0プラグイン B のインストールが range-conflict で失敗します。プラグイン A と依存関係は以前のままです。
=2.1.0なし依存関係は 2.1.0 に留まります。プラグイン A がインストールされている間、自動更新は新しいバージョンをスキップします。
自動更新は、制約付き依存関係を、マーケットプレイスの最新バージョンではなく、インストール済みプラグインのすべての範囲を満たす最高 git タグで取得するため、依存関係は許可された範囲内で更新を受け続けます。すべての範囲を満たすタグがない場合、更新はスキップされ、スキップは /doctor と /plugin エラータブに表示され、制約するプラグインに名前を付けます。 依存関係を制約する最後のプラグインをアンインストールすると、依存関係は保持されなくなり、次の更新でマーケットプレイスエントリの追跡を再開します。

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

プラグインを有効にすると、それが依存するプラグインも有効になり、別の有効なプラグインがまだそれを必要としている場合、プラグインを無効にすることはブロックされます。両方の動作には Claude Code v2.1.143 以降が必要です。以前のバージョンは、名前付きプラグインのみを有効または無効にし、次のロード時に dependency-unsatisfied エラーを表示します。 プラグインを有効にすると、Claude Code は同じスコープでその依存関係も有効にします。依存関係が独自の依存関係を持つ場合、Claude Code はそれらも有効にします。成功メッセージは、名前を付けたプラグインと一緒に有効になったものをリストします。依存関係を有効にできない場合、コマンドは拒否され、何がブロックしているか、およびそれを修正する方法が表示されます。
条件結果
依存関係がインストールされていない有効化が失敗し、各欠落している依存関係の claude plugin install コマンドを出力します。
依存関係が組織のプラグインポリシーによってブロックされている有効化が失敗し、ブロックされた依存関係に名前を付けます。
依存関係が、ターゲットスコープより優先度の高いスコープで false に設定されている有効化が失敗します。そのスコープで依存関係を有効にするか、--scope を渡してそこに書き込みます。
すべての依存関係がインストールされ、許可されている有効化が成功し、プラグインと、ターゲットスコープでまだ有効になっていない各依存関係に対して true を書き込みます。
プラグインを無効にすると、別の有効なプラグインがまだそれに依存している場合、Claude Code は拒否します。エラーはそれに依存するプラグインに名前を付け、正しい順序でそれらを無効にする連鎖コマンドを提供します。 たとえば、deploy-kit が secrets-vault に依存している場合、secrets-vault だけを無効にすると、次のような出力で失敗します。 
secrets-vault is still required by deploy-kit. Disable that plugin first, or
disable everything together: claude plugin disable deploy-kit@acme-tools && claude plugin disable secrets-vault@acme-tools
エラーから連鎖コマンドをコピーして、1 つのステップで完全なセットを無効にします。

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

自動インストール依存関係は、それらをインストールしたプラグインがアンインストールされた後もディスク上に留まります。これは、依存プラグインを再インストールしたい場合や、依存関係を直接使用し続けたい場合に備えてです。それらをクリーンアップするには、claude plugin prune を実行して、インストール済みプラグインがもう必要としない自動インストール依存関係をリストし、確認プロンプトの後に削除します。これには Claude Code v2.1.121 以降が必要です。 
claude plugin prune
デフォルトでは、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 uninstall deploy-kit --prune

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

依存関係の問題は、claude plugin list、/plugin インターフェイス、および /doctor に表示されます。影響を受けるプラグインは、エラーを解決するまで無効になります。最も一般的なエラーとその修正は以下にリストされています。
エラー意味解決方法
dependency-unsatisfied宣言された依存関係がインストールされていないか、インストールされていますが無効になっています。エラーメッセージに表示されている claude plugin install コマンドを実行してください。依存関係のマーケットプレイスがまだ設定されていない場合は、claude plugin marketplace add で追加すると、Claude Code が依存関係を自動的に解決します。依存関係が無効になっている場合は、有効にしてください。
range-conflict依存関係のバージョン要件を組み合わせることができません。エラーメッセージは原因に名前を付けます。バージョンがすべての範囲を満たさない、範囲が有効な semver 構文ではない、または結合された範囲が複雑すぎて交差できません。競合するプラグインの 1 つをアンインストールまたは更新し、無効な version 文字列を修正し、長い || チェーンを簡略化するか、アップストリーム作成者に制約を広げるよう依頼してください。
dependency-version-unsatisfiedインストール済み依存関係のバージョンがこのプラグインの宣言された範囲外です。claude plugin install <dependency>@<marketplace> を実行して、すべての現在の制約に対して依存関係を再解決します。
no-matching-tag依存関係のリポジトリに、範囲を満たす {name}--v* タグがありません。アップストリームが上記の規則を使用してリリースにタグを付けていることを確認するか、範囲を緩和してください。
これらのエラーをプログラムで確認するには、claude plugin list --json を実行し、各プラグインの errors フィールドを読みます。

​
関連項目