claude plugin marketplace addの3フラグ — 部分取得・宣言先・claude.ai連携

claude plugin marketplace addは、<source>に加えて3つのフラグを取ります。モノレポの一部だけを取得する--sparse、宣言先の設定ファイルを選ぶ--scope、claude.aiがホストするマーケットプレイスを名前で足す--claudeaiです。役割はそれぞれ別で、組み合わせに制限もあります。

この記事は、3フラグの効き方と、<source>の書式ごとの取得方法を1か所にまとめます。addが失敗したときの切り分けはClaude Codeでmarketplace addが失敗する原因と対処法が扱います。

3つのフラグの役割と、併用できない組み合わせ

書式はclaude plugin marketplace add <source> [options]です。フラグの一覧は次のとおりです。

--claudeaiを付けたコマンドは--scopeと--sparseを拒否します。claude.ai側のマーケットプレイスはアカウントにホストされ、設定ファイルには宣言されないためです。

sourceの書式で取得方法が決まる

<source>に何を渡すかで、sourceの型と取得方法が変わります。手で型を指定する必要はなく、入力の形から自動で判定されます。

つまずきやすいのは、.gitを付けない自前のGitホストです。https://git.example.com/team/pluginsのようなURLはurl型になり、marketplace.jsonそのものを取りに行きます。リポジトリをクローンさせたいなら.gitを付けます。ホスト名から始まるgitlab.example.com/team/pluginsのような形は、owner/repoの略記として不正扱いになります。https://を付けるか、ローカルパスにします。

AWS CodeCommitのようにクローンURLに.gitが付かないホストは、addではなくextraKnownMarketplacesにgit型で書く方法が案内されています。この型ならURLが.gitで終わらなくてもクローンされます。

--scopeで宣言先を選ぶ

--scopeが決めるのは、マーケットプレイスを宣言する設定ファイルです。プラグインのインストール先スコープとは別の話です。省略するとuserになります。

チームで同じマーケットプレイスを使うなら、projectで宣言します。

claude plugin marketplace add your-org/your-marketplace --scope project

成功するとSuccessfully added marketplace: your-marketplace (declared in project settings)と出ます。名前はマーケットプレイス自身のマニフェストのnameです。

同じマーケットプレイスをすでに追加済みなら、Marketplace 'your-marketplace' already on disk — declared in project settingsと出て、終了コードは0です。エラー扱いにならないので、スクリプトからの再実行に向いています。形式を認識できないsourceは終了コード1で、Invalid marketplace source format. Try: owner/repo, https://..., or ./pathが返ります。

projectで宣言すると、リポジトリの.claude/settings.jsonのextraKnownMarketplacesに載る形になります。同じ内容を手で書くなら、次のような形です(公式の例に沿った形)。

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    }
  }
}

ここで注意が2つあります。

• リポジトリの.claude/settings.jsonや.claude/settings.local.jsonのエントリは、そのフォルダのワークスペース信頼ダイアログを承認した後にだけ効きます。未承認のフォルダ(-p実行を含む)では、何も表示されないまま無視されます
• プラグインの有効化は別です。マーケットプレイスを宣言しても、各プラグインはenabledPluginsかインストール操作で有効にします。共同作業者側ではclaude plugin install <name>@<marketplace> --scope projectを1回ずつ実行する必要があります

チーム全体への必須化や自動更新はClaude Codeプラグインマーケットプレイスの必須化と自動更新設定、管理者による許可リスト運用はGHESプラグインマーケットプレイスを許可リストで運用するにあります。

--sparseでモノレポの一部だけをチェックアウトする

--sparse <paths...>は、gitのチェックアウトを指定ディレクトリに絞ります。マーケットプレイスがモノレポの中にあり、リポジトリ全体は要らない場面で使います。対象はgithub型とgit型のsourceだけです。

claude plugin marketplace add your-org/monorepo \
  --sparse .claude-plugin plugins

--sparseに渡した値は、マーケットプレイスのsourceのsparsePathsフィールドとして保存されます。公式のフィールド表には、[".claude-plugin", "plugins"]のような配列が例に挙がっています。マーケットプレイス定義は.claude-plugin/marketplace.jsonが既定の置き場なので、少なくとも.claude-pluginは含める形になります。

コマンドを使わず設定ファイルに直接書くなら、github型のsourceにsparsePathsを足します。公式のフィールド表(repo・ref・path・sparsePaths)に沿った形の例です。

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/monorepo",
        "sparsePaths": [".claude-plugin", "plugins"]
      }
    }
  }
}

refでブランチやタグに固定する場合も、同じsourceオブジェクトに並べて書きます。CLIならyour-org/monorepo#v1.2.0のように末尾へ付けます。

絞り込みで押さえる点は3つです。

1. プラグインの実体の場所: マーケットプレイス内の相対パスで参照するプラグインは、その置き場所も--sparseに含める形になります。追加後は/pluginの一覧で、目的のプラグインが見えるかを確かめておくと確実です
2. url型・directory型・file型には使えない: クローンを伴わないsourceに絞り込みの意味がないためです
3. 別物のworktree.sparsePaths: 設定キーのworktree.sparsePathsは、ワークツリーのチェックアウトを絞る設定です。マーケットプレイスの取得とは関係しません

なお、プラグイン側のsourceにもgit-subdirという型があり、他のリポジトリのサブディレクトリを1つだけ、sparseな部分クローンで取得します。マーケットプレイスのリポジトリ全体を絞るのが--sparse、個々のプラグインのサブディレクトリを取るのがgit-subdirという分担です。

--claudeaiでclaude.ai側のマーケットプレイスを名前で足す

--claudeaiは、claude.aiがホストするマーケットプレイスを追加するためのフラグです。組織のプラグインライブラリや、自分でclaude.aiにアップロードしたものが対象になります。v2.1.273以降が必要です。

手順は2段階です。まず一覧で名前を確かめます。

claude plugin marketplace list
claude plugin marketplace add --claudeai claudeai-organization-library

一覧の末尾にFrom claude.ai:の節が出ます。ここに載っている名前を--claudeaiに渡します。この節は、claude.aiのアカウントからプラグインが同期される端末セッションで出るもので、同期の対象外の環境では出ません。

追加したマーケットプレイスは、ローカルではclaudeai-で始まる名前で登録されます。たとえば「Organization library」はclaudeai-organization-libraryになります。プラグインのインストールもこの名前で指定します。

claude plugin install <plugin>@claudeai-organization-library

次の挙動も押さえておくと混乱しません。

• サインアウトするか、別のclaude.ai組織にサインインし直すと、マーケットプレイスの設定は残りますがプラグインは表示されなくなります。すでにインストールしたプラグインは読み込まれ続けます
• From claude.ai:の節には、claude.ai経由で共有されたgit系のマーケットプレイスも載ることがあります。こちらは--claudeaiではなく、表示されたsourceを通常の形式でaddします
• claude.ai側のマーケットプレイスは自動更新が既定でオンです。公式の一覧上、それ以外のサードパーティは既定でオフです
• 宣言先の設定ファイルがないので、プロジェクトの.claude/settings.jsonでは共有できません

セッション内の/plugin marketplace addとの違い

セッション内では/plugin marketplace add [source]が使えます。sourceを渡すとその場で追加して結果を報告し、渡さなければAdd marketplaceの入力欄が開きます。/plugin market addという短縮形もあります。ただし公式のセッション内コマンド表には--scope・--sparse・--claudeaiが載っていません。3つのフラグが必要な追加は、シェルからclaude plugin marketplace addで行う前提で組むのが確実です。

未追加のマーケットプレイスのプラグインを入れたいだけなら、/plugin install <plugin> --marketplace <source>(v2.1.275以降)という道もあります。sourceにはaddと同じ書式を使えますが、空白は含められません。まだ追加されていなければ、解決したsourceを見せて確認を求めてから追加し、そのままプラグインの詳細画面を開きます。

プライベートなリポジトリを追加するときの前提

クローンに認証が要るリポジトリも、公開のものと同じコマンドで追加します。ただしClaude Codeは、手元にあるgitの認証情報でクローンし、対話的なプロンプトは出しません。接続方法ごとの前提は次のとおりです。

• HTTPS: gitのcredential helperが効きます。gh auth loginやmacOSのキーチェーンで設定済みなら通ります。一度も認証していないホストは、パスワードを聞かれずに失敗します
• SSH: ホストがknown_hostsに登録済みで、鍵がパスフレーズなしで使える必要があります。指紋確認とパスフレーズ入力のプロンプトも抑制されるためです
• GitHubのowner/repo略記: SSH鍵がgithub.comで認証できればSSH、できなければHTTPSでクローンします。環境変数CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1を設定すると、この判定を飛ばして常にHTTPSにします

この認証は/plugin installやmarketplace updateでも同じです。

追加後の確認と削除の注意

claude plugin marketplace list --jsonを使うと、追加結果を機械的に確認できます。各要素はname・source(github・git・url・directory・file・claudeaiのいずれか)・installLocationなどを持ちます。claudeaiの要素にはクローンがないため、installLocationの代わりにmarketplaceIdとorganizationUuidが付きます。

claude plugin marketplace list --json | jq '.[] | {name, source}'

追加後にsourceが意図した型になっているかを見れば、前半の書式判定の落とし穴(.gitなしのURLがurl型になるなど)をその場で拾えます。

削除は追加より慎重に扱います。claude plugin marketplace remove <name>は、最後に宣言していたスコープから外すとき、キャッシュを消して、そのマーケットプレイスから入れたプラグインもすべてアンインストールします。--scopeを付けなければ、すべてのスコープから宣言が外れます。取得し直したいだけならclaude plugin marketplace updateを使います。ref付きで追加したものは、リポジトリの既定ブランチではなく、そのrefの最新コミットに更新されます。

全体像から確認したいときは、Claude Codeプラグイン(Plugins)完全ガイドにまとめてあります。

フラグの選び方の早見表