Claude Codeプラグインをチーム向けにバンドル配布する

プラグインのマニフェストは、必須のnameのほかにdependencies配列だけで成立します。この最小構成を使うと、複数のプラグインをまとめて1つのインストールコマンドの背後に隠せます。バックエンド担当・フロントエンド担当のようにロールごとにひとまとまりのツールセットを配りたいとき、社内マーケットプレイスで役立つ手法です。

バンドルとは何か

backend-standardのようなバンドル用プラグインを社内マーケットプレイスに公開すると、エンジニアは個別のプラグインを1つずつ入れる代わりにclaude plugin installを1回打つだけで済みます。

{
  "name": "backend-standard",
  "version": "1.0.0",
  "description": "Standard plugin set for backend engineers",
  "dependencies": [
    "secrets-vault",
    "deploy-kit",
    { "name": "db-migrate", "version": "^3.0" },
    "oncall-runbook"
  ]
}

backend-standardをインストールすると、この4つの依存が解決されて一緒にインストールされます。依存側にバージョン制約を付けられる点は通常の依存宣言と同じで、db-migrateだけ^3.0に固定するといった調整も可能です。バンドル自体はコードを持たず、依存を並べたカタログのような役割に徹します。

配布後に新しいツールを追加する2つの経路

標準セットに新しいツールを足したくなったら、backend-standardの新バージョンを公開して依存を追加します。ここで注意したいのは、非Anthropic製マーケットプレイスは既定で自動更新が無効という点です。エンジニアの手元に新バージョンを届けるには、次のどちらかが必要になります。

自動更新が有効な場合、次回の自動更新でバンドルが新バージョンへ移り、追加された依存も一緒にインストールされます。手動経路では、updateだけでは新しい依存の読み込みまでは終わらず、/reload-pluginsを挟んで初めて反映される点を運用手順に明記しておくと迷いが減ります。

組織全体に一律配布する

チームの合意を待たず組織全体へ一律で配りたい場合は、managed settingsのenabledPluginsにバンドルプラグインを追加します。この設定は読み取り専用でユーザー側からは書き換えられないため、全端末で同じツールセットを強制する手段として機能します。バンドルを配布できるマーケットプレイス自体を絞りたいときは、strictKnownMarketplacesと組み合わせて許可リスト化すると、社内で承認していないマーケットプレイスからバンドルが入り込む経路自体を塞げます。

プロジェクトスコープでリポジトリにコミットする配り方と比べると、性格の違いがはっきりします。プロジェクトスコープはリポジトリをcloneした人にだけ届き、.claude/settings.jsonの変更はレビューを経て取り込まれます。managed settingsのenabledPluginsはリポジトリの有無に関係なく、組織が管理するすべての端末に強制されます。チーム単位の緩い共有ならプロジェクトスコープ、部門横断で例外なく揃えたいならmanaged settingsという使い分けになります。

有効化・無効化は依存関係ごと連動する

バンドルに限らず、依存を持つプラグインの有効化・無効化には連動のルールがあります。プラグインを有効化すると、そのプラグインが依存する側も同じスコープで自動的に有効化されます。依存にさらに依存がある場合は、そこも連鎖して有効になります。依存先が未インストール・組織ポリシーでブロック済み・より優先度の高いスコープで無効化済みのいずれかに当てはまると、有効化コマンドはその場で失敗し、何が妨げているかと直し方を表示します。

逆に無効化しようとしたとき、他の有効なプラグインがまだその依存を必要としていると拒否されます。たとえば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

エラーメッセージに出てくるコマンドをそのままコピーすれば、依存関係を壊さずに一括で無効化できます。

使われなくなった依存を掃除する

バンドルからプラグインを外したり、バンドル自体をアンインストールしたりすると、自動的にインストールされた依存はディスク上に残り続けます。再インストールに備えた挙動ですが、増え続けると散らかります。掃除にはclaude plugin pruneを使います。

claude plugin prune

このコマンドは、もうどのプラグインからも必要とされていない自動インストール済みの依存だけを一覧表示し、確認プロンプトの後に削除します。該当が無ければNothing to pruneと表示されて終わります。既定ではuserスコープが対象で、--scope projectや--scope localで対象スコープを切り替えられ、--dry-runで削除内容だけを確認でき、-yで確認プロンプトを省略できます。標準入出力が端末でない環境では、-yを付けない限り一覧表示だけで実際の削除は行われません。

アンインストールと同時に掃除したい場合は、--pruneを付けます。

claude plugin uninstall backend-standard --prune

これでbackend-standard本体を消したあと、それが引き込んだ依存のうち他に必要とするプラグインが無いものだけがまとめて削除されます。自分で個別にインストールしたプラグインは、たとえ他のバンドルの依存と同じ名前でも掃除対象にはなりません。

既定で無効なプラグインを束ねたとき

外部サービスへ接続する、追加コストが発生するといった理由で、プラグインの中にはplugin.jsonにdefaultEnabled: falseを設定し、単体でインストールすると無効な状態で入るものがあります。バンドル経由で引き込んだ場合はこの既定値が上書きされ、Claude Codeは有効化するプラグインとその依存すべてに対象スコープで明示的なtrueを書き込みます。バンドルに課金対象のツールを含めるときは、この挙動によって「知らないうちに有効化されていた」という驚きが起きやすい点を、配布前にメンバーへ周知しておくと親切です。

一度書き込まれたenabledPluginsの値は、プラグインが更新されてdefaultEnabledが変わっても引き継がれます。バンドル側で有効・無効の方針を変えたいときは、plugin.jsonの値を書き換えるだけでは既存ユーザーには効かず、ユーザー自身か管理者が明示的に設定し直す必要があります。

たとえばbackend-standardの依存に、外部の脆弱性スキャンAPIを呼ぶ従量課金のツールを新しく足したとします。そのツール単体ならdefaultEnabled: falseで配布し、使いたい人だけ有効化してもらう設計にできますが、backend-standardの依存として引き込まれた瞬間に自動で有効化されるため、課金が発生することを知らせないまま全員に行き渡ってしまいます。コストのかかる依存をバンドルに加えるときは、事前の告知をセットにしておく必要があります。

複数マーケットプレイスをまたぐバンドルを組む

社内で複数のマーケットプレイスを運用しているなら、バンドルの依存が別マーケットプレイスのプラグインを指すこともあります。既定では、宣言元と異なるマーケットプレイスへの依存は自動導入がブロックされます。許可するには、依存元をホストする側のmarketplace.jsonでallowCrossMarketplaceDependenciesOnに相手のマーケットプレイス名を追加します。

{
  "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エラーになりますが、ユーザーが依存先を手動で先にインストールしておけば、許可リストを変えずに制約自体は満たせます。

よくある質問

バンドル自体にコードを書く必要はありますか

ありません。必須なのはnameだけで、dependencies配列に依存を並べるだけでバンドルとして機能します。バンドル自身がスキルやフックを持つことも技術的には可能ですが、役割を混ぜると更新の見通しが悪くなるため、依存の集約に専念させるのが基本です。

バンドルの依存をユーザーが個別に無効化したらどうなりますか

ユーザーが依存の1つだけを無効化しようとしても、バンドル本体がまだ有効な限り、その依存を必要とするプラグインが残っているとして拒否されます。バンドルごと外すか、依存だけを外すコマンドをエラーメッセージから確認してから実行します。

個別にインストールしていたプラグインをバンドルに含めたら重複しますか

重複しません。バンドルをインストールしても、既に入っている依存はそのまま使われます。ただしその依存は「自分でインストールしたプラグイン」として扱われ続けるため、claude plugin pruneの掃除対象にはなりません。

バンドルの更新頻度はどう考えればよいですか

自動更新を有効にする運用と、claude plugin updateを手動で回す運用のどちらでも動きますが、追加したツールがすぐに全員へ行き渡ってほしいか、チーム側でタイミングを管理したいかで選び分けます。緊急度の高い変更が多いなら自動更新、変更内容を事前レビューしたいなら手動更新が向きます。

バンドルの依存に制約付きバージョンを混ぜても大丈夫ですか

問題ありません。バンドルの依存配列には、バージョン指定なしの依存と^3.0のような制約付き依存を混在させられます。ただし制約付きの依存だけは、他のバンドル利用者や他のプラグインが持つ制約と衝突すると解決に失敗することがあるため、緩めのレンジで運用したい依存には安易に制約を付けないほうが、バンドル全体のインストール成功率は安定します。

まとめ

dependenciesだけを持つプラグインは、複数ツールを1つのインストール操作の裏に隠す配布手段になります。新しいツールを足したときの展開経路、有効化・無効化が依存を連鎖させる挙動、そして不要になった依存をclaude plugin pruneで片付ける手順を押さえておけば、社内マーケットプレイスの運用は大きく楽になります。バンドルの中身を作り込むスキル・フックの書き方はClaude Code Skills完全ガイド、組織全体への一律配布はClaude Code組織管理ガイド、プラグイン全体の仕組みはClaude Codeプラグイン完全ガイドを参照してください。