claude plugin installの導入経路を選ぶ — --marketplaceと@形式の使い分け

claude plugin install でプラグインを入れる経路は、配布元がどこにあるかで変わります。公式マーケットプレイス、未登録の配布元、claude.aiに並ぶ配布元、非公開リポジトリ、CIでの非対話実行。この記事は、この5つのうちどれを選ぶかと、各経路で詰まりやすい点を扱います。オプションを1つずつ引きたいときはClaude Code plugin init/installコマンドの全オプションが向いています。

軸になるのは --marketplace <source> です。まだ登録していないマーケットプレイスの追加と導入が1コマンドで済みます。shellの claude plugin install ではv2.1.292以降、セッション内の /plugin install ではv2.1.275以降で使えます。

配布元の場所で導入経路が決まる

claude.com/marketplaceで見つけたプラグインは、「Claude Code」ボタンが claude plugin install <name>@claude-plugins-official の形をコピーします。貼り付けるだけで、公式の行の経路で入ります。

基本の書き方は「プラグイン名」と「配布元」を分けること

--marketplace を使うときは、プラグイン名を @marketplace なしのベア名で渡し、配布元をフラグ側に書きます。

claude plugin install deploy-helper --marketplace your-org/plugins

従来は marketplace add で配布元を登録し、そのあと install <plugin>@<marketplace> で入れる2段階でした。同僚から「このリポジトリのプラグインを入れて」と頼まれたとき、手順書が1行で済みます。

<source> に書ける形は marketplace add と同じです。GitHubの owner/repo、#ref 付きの指定、gitのclone URL、ローカルのパス、https:// の marketplace.json が使えます。ローカルの相対パスは ./ か ../ で始めます。name/name のままだとGitHubリポジトリとして読まれるためです。各書式の違いはclaude plugin marketplace addの3フラグにまとめています。

セッション内とshellで確認の有無が変わる

同じ --marketplace でも、動く場所によって挙動が違います。

セッション内は対話前提なので、追加前に「このソースを足してよいか」を挟みます。shellは確認なしで追加する代わりに、組織のポリシー検査(strictKnownMarketplaces の許可リストと blockedMarketplaces のブロックリスト)は claude plugin marketplace add と同じように通ります。許可リストに無いソースは、ここで止まります。

--scope projectでも配布元の宣言はuser設定に入る

見落としやすいのがスコープです。shellで新しい配布元を足すと、--scope project を付けても、マーケットプレイスの宣言はuser設定に書かれます。

claude plugin install formatter --marketplace your-org/plugins --scope project

プラグインが有効になる記録は .claude/settings.json に入ります。いっぽう「your-org/pluginsという配布元がある」という宣言は、自分のマシンのuser設定にしか残りません。これをコミットしても、チームの他メンバーの環境には配布元が登録されていません。

チーム全員に同じ配布元を配りたいときは、リポジトリの設定側で配布元を宣言する別の手当てが要ります。extraKnownMarketplacesでチームにマーケットプレイスを自動配布するの方法が向いています。また、プロジェクトスコープで有効にしただけでは各メンバーの手元にダウンロードされないため、メンバーごとに claude plugin install <name>@<marketplace> --scope project を1回ずつ実行します。

公式マーケットプレイスは新しいマシンだと登録されていない

公式の claude-plugins-official は、対話のClaude Codeセッションを初めて開いたときに自動で登録されます。つまり、誰も対話セッションを開いていないマシンでは未登録です。セットアップスクリプトが公式のプラグインを入れる場合は、先に次を実行します。

claude plugin marketplace add anthropics/claude-plugins-official
claude plugin install commit-commands@claude-plugins-official

手元の端末なら登録済みなので、2行目だけで足ります。コンテナや新しいCIランナーでは1行目が要る、というのが違いです。

claude.aiに並ぶ配布元は名前で追加する

claude.aiアカウントからプラグインが同期される端末(v2.1.273以降)では、組織のプラグインライブラリや自分のアップロードがclaude.ai側の配布元として並びます。これは <source> ではなく名前で追加します。

claude plugin marketplace list
claude plugin marketplace add --claudeai claudeai-organization-library
claude plugin install <plugin>@claudeai-organization-library

登録名は claudeai- で始まり、claude.ai上の表示名から作られます。「Organization library」なら claudeai-organization-library です。サインアウトしたり別の組織でサインインし直したりしても、配布元の登録は残ります。ただしプラグインの一覧は空になり、導入済みのプラグインは読み込まれたままです。

marketplace list の From claude.ai: には、gitベースの配布元が混ざることもあります。ソースが表示されているものは --claudeai ではなく、通常のソース指定で追加します。

非公開リポジトリを --marketplaceに渡すとき

非公開の配布元も、書き方は公開のものと同じです。ただしClaude Codeは、手元にあるgitの認証情報でcloneし、パスワードなどを尋ねません。

CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 を設定すると、owner/repo 形式のSSH判定を省いて常にHTTPSにできます。同じ認証情報は /plugin install や claude plugin update にも使われます。CIで非公開の配布元を指定するなら、事前にランナーへ認証情報を渡しておきます。

組織が管理設定で配布元を登録している場合は、自分で追加する必要がありません。

setupスクリプトとCIで使うときの要点

プラグイン導入をスクリプトに入れる場合は、前提が3つあります。

• 非対話の承認: プラグインによっては、配布元が指定した command ソースのコマンドで導入されます。表示されたコマンドへの確認に答える人がいない場面では、-y を付けて承認します。標準入力か標準出力がTTYでなく、-y も --accept-command も無ければ、インストールは拒否され終了コードは1です
• 結果の取得: --json を付けると、結果が最終行に1つのJSONオブジェクトとして出ます(v2.1.268以降)
• Claude自身が実行する場合: Bashツール経由では -y が無視されます。承認が要る導入は、自分の端末から実行します

-y で何でも通すのが不安なときは、--accept-command <sha256>(v2.1.271以降)が使えます。--json で一度実行すると、承認されなかったコマンドの内容と sha256 が shownCommand に入って返ります。人がそのコマンドを確認したうえで、同じ sha256 を渡して再実行する流れです。コマンド、プラグイン、配布元のカタログのどれかが変わっていれば sha256 は受け付けられず、コマンドが改めて表示されます。-y とは同時に指定できず、Claude Codeのセッション内では効きません。

反映のタイミングも決まっています。導入したプラグインは次回の起動か、開いているセッションでの /reload-plugins で読み込まれます。

プラグインが依存関係を持つとき

プラグインが別のプラグインへの依存を宣言している場合、導入時に依存先も同じスコープで入って有効になります。成功メッセージにその一覧が出ます。

逆向きにも挙動があります。無効化は、ほかの有効なプラグインがまだ必要としていると拒否され、両方を正しい順で無効化するコマンドが示されます。アンインストールしても、自動で入った依存先は残ります。claude plugin prune を実行して初めて消えます。CIで入れて後片付けまでするなら、uninstall のあとに prune を足す形になります。

「already added from a different source」が出たとき

配布元の名前は、取得したカタログの名前で決まります。同じ名前の配布元を別のソースから登録済みだと、Claude Codeは既存の登録を残し、プラグインは入りません。メッセージは次の形です。

Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.

次のどちらかで抜けられます。

• 登録済みの配布元でよければ、名前を指定して入れる: /plugin install <plugin>@<name>
• 新しいソースに切り替えるなら、/plugin marketplace remove <name> で消してから再実行する

marketplace remove は、その配布元から入れたプラグインのアンインストールまで含みます。切り替えの前に、何が入っているかを claude plugin list で見ておくと安全です。このコマンドは Version、Scope、Status の行つきで一覧を出します。

入れたあとの確認と片付け

導入が通ったかは、Successfully installed plugin: formatter@your-org (scope: project) の出力で分かります。すでに同じスコープに入っている場合は already installed と出て、終了コードは0です。承認プロンプトを断ったときは Aborted. で終了コードは1になります。スクリプトでは、この0と1の差で分岐できます。

入れたプラグインが毎回のセッションに何トークン足すかは、claude plugin details <name> の Always-on 行で見られます。使っていないものは /plugin のInstalledタブの「Not used recently」に並ぶので、無効化かアンインストールの判断材料になります。

/plugin パネルで変更したときは、パネルを閉じる時点で /reload-plugins が自動で走ります。ただし再読み込みでプロンプトキャッシュが無効になる場合は、警告を出して変更を保留にします。それでも反映するなら /reload-plugins --force を実行します。

shellからの操作は次の形です。install と uninstall の既定はuserスコープ、enable と disable はそのプラグインが書かれている最も狭いスコープに作用します。

claude plugin disable formatter@your-org
claude plugin enable formatter@your-org
claude plugin uninstall formatter@your-org --scope project

自動更新は配布元の種類で既定が違う

公式マーケットプレイス(knowledge-work-plugins と first-party-plugins を除く)とclaude.aiから追加した配布元は、自動更新が既定でオンです。それ以外はオフです。--marketplace で足した第三者の配布元も、既定では自動更新されません。更新は自分で回すか、配布元ごとに自動更新をオンにします。

まとめ

--marketplace が省くのは「登録」の1手順だけで、登録先のスコープや自動更新の既定は変わりません。1回限りの導入には便利ですが、チームで使い続ける配布元は、設定側で宣言して配るほうが再現性が保てます。新しいマシンの公式マーケットプレイスと、--scope project の宣言先は、スクリプトを書く前に押さえておく2点です。