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つの依存が同じスコープで解決され、一緒にインストールされて有効になります。バンドル自体はコードを持たず、依存を並べたカタログのような役割に徹します。

このマニフェストを作業用の空ディレクトリに置いて、Claude Code v2.1.289のclaude plugin validateにかけると、次の出力でした。依存先がまだ存在しなくても検証は通ります。

claude plugin validate ./bundle

⚠ Found 1 warning:
 
  ❯ author: No author information provided. Consider adding author details for plugin attribution
 
✔ Validation passed with warnings

警告はauthorが無いことだけです。nameとdependenciesだけのマニフェストでも、version・descriptionを付ければauthor以外の警告は出ません。

依存のバージョン制約と、組み合わさったときの解決

依存には、プラグイン名だけの文字列と、versionを持つオブジェクトの2通りの書き方があります。文字列だけなら、依存先のマーケットプレイスが出す最新版に追従します。db-migrateに付けた^3.0のような制約は、semverの範囲指定です。

制約が効く場面はgit系のソースに限られます。依存先をgithub・url・git-subdirで配っている場合、<プラグイン名>--v<バージョン>の形式のgitタグのうち、範囲を満たす最も高いものが入ります。依存先の作者はリリースのたびにタグを打つ必要があり、そのためのclaude plugin tag --pushが用意されています。

相対パスで置いたプラグインは、マーケットプレイスのリポジトリ側にタグを打ちます。タグが範囲を満たさないとき、独自リポジトリのプラグインはインストールが失敗します。相対パスのプラグインはマーケットプレイスの現行コピーが入り、範囲外ならバンドル側が無効のまま残ってRequires "secrets-vault@acme-tools" ~2.1.0, installed 3.0.0のように表示されます。

npm・archive・commandのソースでは、制約はどのバージョンを取得するかを決めません。ロード時にplugin.jsonのversionと照合され、満たさなければバンドルが無効になります。versionを書いていないplugin.jsonはどの制約も満たさないため、制約を付ける前に依存先へversionを持たせておく必要があります。

複数のプラグインが同じ依存に制約を付けたときは、すべての範囲を満たす最高バージョンに解決されます。

claude plugin validateは、依存のversionにlatestのようなsemverでない文字列を書いても警告を出しません。v2.1.289で{ "name": "db-migrate", "version": "latest" }を含むマニフェストを検証すると、version・description・authorが無いという3件の警告だけで通りました。範囲の不正は公開後のインストール時にhas an invalid version requirementとして表に出るため、制約の書式はマーケットプレイスに載せる前に目で見直す項目です。

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

標準セットに新しいツールを足したくなったら、backend-standardの新バージョンを公開して依存を追加します。ここで効いてくるのが、マーケットプレイスごとの自動更新の既定値です。claude-plugins-official などAnthropicの公式マーケットプレイス(一部を除く)と、claude.aiから追加したものは自動更新が有効で、それ以外は無効です。社内マーケットプレイスは、設定で有効にしない限り手動更新になります。

自動更新は、対話セッションで最初のメッセージを送ってから最大10分のランダムな待ちを置いて走ります。「更新を出した直後に全員へ届く」わけではないので、急ぎの追加は手動の手順も併せて案内しておくと確実です。

組織全体と1つのリポジトリ、配り方の違い

配布範囲の選び方は2通りあります。チームの合意を待たず組織全体へ配るならmanaged settings、特定のリポジトリの参加者だけなら.claude/settings.jsonです。

managed settingsでの指定は、extraKnownMarketplacesでマーケットプレイスを登録し、enabledPluginsにバンドル名@マーケットプレイス名を書く2点セットです。配布手段はサーバー管理設定・MDM・ファイル配置の3通りで、Claude for TeamsまたはEnterpriseの組織なら管理画面から設定できます。許可するマーケットプレイスの出どころはstrictKnownMarketplacesで絞れます。ただしこのキーはマーケットプレイスを登録するものではなく、許可したマーケットプレイスの中のエントリを制限するものでもありません。

リポジトリ側には見落としやすい条件があります。バンドルが相対パスで置かれていればマーケットプレイスのコピーから読み込まれますが、プラグインの置き場所が外部のGitHubリポジトリなどだと、設定だけでは入りません。参加者の画面にはPlugin "<name>" is enabled in project settings but isn't installedと出て、各自がclaude plugin install <name>@<marketplace> --scope projectを打つまで動きません。参加者全員に自動で届けたいなら、バンドルを相対パスでマーケットプレイスに置くか、managed settingsを選ぶ形になります。

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

バンドルに限らず、依存を持つプラグインの有効化・無効化には連動のルールがあります。プラグインを有効化すると、インストール済みで無効になっている依存も有効になります。

依存が未インストールのときは、有効化コマンドが失敗して先にインストールするよう促します。ロード時に問題があると、プラグインは無効のまま残り、claude plugin listと/pluginのErrorsタブにメッセージが出ます。バンドルで遭遇しやすいのは次の3つです。

claude plugin list --jsonを使うと、問題のあるプラグインにerrorsとerrorDetailsが付いて返ります。端末の表示を目で追う代わりに、配布後の状態を点検するスクリプトへ組み込めます。

無効化は逆向きです。他の有効なプラグインがまだその依存を必要としていると、コマンドは拒否され、両方を正しい順序で無効化する連結コマンドを表示します。たとえばdeploy-kitが使っているsecrets-vaultだけを無効化しようとしたときです。表示されたコマンドをそのまま実行すれば、依存関係を壊さずに外せます。

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

バンドルからプラグインを外したり、バンドル自体をアンインストールしたりすると、自動的にインストールされた依存はディスク上に残り続けます。掃除にはclaude plugin pruneを使います。autoremoveというエイリアスもあります。

claude plugin prune --dry-run

--dry-runは、削除候補を一覧表示して(dry run — nothing removed)で終わります。該当が無ければNothing to pruneで始まる行が出ます。実際に消すかどうかは、端末の有無と-yで変わります。

CIのスクリプトにclaude plugin pruneだけを書いても、何も消えないまま終了します。終了コードは確認プロンプトにどう答えても0です。このため、掃除が走ったかどうかを終了コードで判定するのは向きません。

オプションはclaude plugin prune --helpの出力どおり、-s, --scope <scope>(user・project・local、既定はuser)、--dry-run、-y, --yesの3つです。アンインストールと同時に掃除したいときは--pruneを付けます。

claude plugin uninstall backend-standard --prune

--pruneは、backend-standardを消したあと、他のどのプラグインからも必要とされなくなった自動インストールの依存をまとめて削除します。非対話の環境では、こちらにも-yが必要です。自分で個別にインストールしたプラグインは、pruneの対象になりません。

プラグインのデータディレクトリを残したいときは、uninstallの--keep-dataが使えます。

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

プラグインの作者が既定で無効にしたい場合は、plugin.jsonにdefaultEnabled: falseを設定します。そのプラグインは、単体でインストールすると無効な状態で入ります。単体なら、claude plugin enable <name>か/pluginのInstalledタブで有効にするまで動きません。

バンドルの依存にした場合は事情が変わります。defaultEnabledの説明には、有効なプラグインが依存しているプラグインは、この値にかかわらず有効な状態で始まると書かれています。課金対象のツールをバンドルに入れると、メンバーは何もしなくてもそれが有効になります。配布前に周知しておくと安全です。

たとえばbackend-standardの依存に、外部の脆弱性スキャンAPIを呼ぶ従量課金のツールを足したとします。そのツール単体ならdefaultEnabled: falseで配り、使いたい人だけが有効化する設計にできます。バンドルの依存として引き込まれた時点で、この設計は効かなくなります。

もう1つの注意点が、更新後の挙動です。ユーザーのenabledPluginsにいったん値が書き込まれると、プラグインが更新されてdefaultEnabledが変わっても、その値は引き継がれます。バンドル側で有効・無効の方針を変えたくなったら、plugin.jsonを書き換えるだけでは既存ユーザーには効きません。マーケットプレイスのエントリに同じdefaultEnabledを書くと、プラグイン側のマニフェストの値より優先される点も、運用側の調整手段として覚えておけます。

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

社内で複数のマーケットプレイスを運用しているなら、バンドルの依存が別マーケットプレイスのプラグインを指すこともあります。既定では、宣言元と異なるマーケットプレイスへの依存は自動導入されません。許可するには、バンドルをホストする側(ルート)の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" }
      ]
    }
  ]
}

適用されるのは、インストールするプラグインをホストするルートのマーケットプレイスの許可リストだけです。

許可リストに無いときの失敗の仕方は、依存をどこに宣言したかで分かれます。マーケットプレイスのエントリ側に書いていれば、インストール自体がis in marketplace "acme-shared", which is not in the allowlistで始まるメッセージとともに拒否されます。plugin.json側に書いていた場合は、依存抜きでインストールが完了し、そのあとバンドルがロードに失敗します。インストールが成功したのにツールが動かない、という見え方になるため、claude plugin listでエラーを確かめる手がかりになります。

許可リストを変えずに通す方法もあります。依存先のプラグインを、ユーザーが同じスコープで先にインストールし、有効にしておく方法です。この場合、チェックは適用されません。

公開前に手元で試す手順

マーケットプレイスへ出す前に、バンドルと依存をローカルで一緒に動かして確かめられます。

親フォルダに複数のプラグインが並んでいるなら、v2.1.265以降はその親フォルダを--plugin-dirに1度指定するだけで、.claude-plugin/plugin.jsonを持つ子フォルダが読み込まれます。

まとめ

dependenciesだけを持つプラグインは、複数ツールを1つのインストール操作の裏に隠す配布手段になります。注意が要るのは、依存に課金対象を入れたときの自動有効化と、自動更新が無効な社内マーケットプレイスの更新漏れ、掃除が非対話環境では-yなしだと働かない点の3つです。Claude Codeの組織向け運用はClaude Code組織管理ガイドにあります。バンドルの中身になるスキルはClaude Code Skills完全ガイド、プラグイン全体の仕組みはClaude Codeプラグイン完全ガイドが参考になります。