Claude Codeプラグインソースの使い分け — GitHub・Git・npm・zip・コマンド
marketplace.jsonのsourceフィールドが持つ7通り(相対パス・github・url・git-subdir・npm・archive・command)を仕様と制約から比較し、選び方の基準を示します。
marketplace.jsonのsourceフィールドが担う役割
Claude Codeのプラグインは、marketplace.jsonの各プラグインエントリが持つsourceフィールドで「どこから取得するか」を指定します。同じリポジトリ内の相対パスから、GitHub・任意のGitホスト・モノレポのサブディレクトリ・npmレジストリ・HTTPSでホストしたzip、さらにはローカルコマンドが動的に生成するディレクトリまで、7通りの取得方法があります。
どれを選ぶかは配布したい相手の環境で決まります。gitが入っている前提ならgithubやgit系が素直で、gitもnpmも入っていない端末に配りたいならarchiveが候補になります。逆にIDE連携ツールのようにローカルで生成物を都度作る場合はcommandが唯一の選択肢です。
プラグインの基本構造やインストール手順はClaude Codeプラグイン完全ガイドで扱っているので、marketplace.json自体を初めて書く場合はそちらを先に読むと流れがつかみやすくなります。
相対パスとgithubソース — 同じリポジトリと別リポジトリの基本形
最も単純なのは相対パスです。プラグインとマーケットプレイスが同じリポジトリにあるとき、./で始まる文字列だけで指定できます。
{ "name": "my-plugin", "source": "./plugins/my-plugin" }パスはmarketplace.jsonが置かれているディレクトリ(.claude-plugin/の親)を基準に解決されます。../で外に出ることはできません。多数のプラグインを1リポジトリにまとめる場合は、metadata.pluginRootに共通の親ディレクトリを設定すると、各エントリのsourceをスラッシュを含まない裸のディレクトリ名だけで書けます(Claude Code v2.1.239以降が必要)。ただしteam-a/formatterのようにスラッシュを含む名前は裸の名前扱いにならず、pluginRootを設定していても./始まりで書く必要があります。
相対パスには制約もあります。ユーザーがマーケットプレイスをgitソースやローカルディレクトリから追加した場合は問題なく解決できますが、marketplace.jsonへの直接URLで追加した場合、Claude Codeはそのファイルだけをダウンロードするため相対パスが解決できません。URLベースで配布したいマーケットプレイスには、相対パス以外のソース型を使う必要があります。
別リポジトリにあるプラグインを取得するときの基本形がgithubソースです。
{
"name": "github-plugin",
"source": { "source": "github", "repo": "owner/plugin-repo", "ref": "v2.0.0", "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0" }
}repoだけが必須で、ref(ブランチ・タグ)とsha(コミットSHA)は任意です。両方指定した場合はshaが優先されます。GitHub・GitLab・Bitbucketなど大半のgitホストでは、refが指す枝が後から削除されても、そのコミットにたどり着ける限りインストールは成功します。AWS CodeCommitのようにSHA指定のフェッチに対応しないサーバーでは、ref自体が存在し続けている必要があります。
urlとgit-subdirソース — GitHub以外のホストとモノレポ
GitHub以外のgitホスト(GitLab・Bitbucket・自前ホスト)を使う場合はurlソースを使います。フィールド構成はgithubソースとほぼ同じで、repoの代わりに完全なurlを指定します。
{
"name": "git-plugin",
"source": { "source": "url", "url": "https://gitlab.com/team/plugin.git", "ref": "main", "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0" }
}urlはhttps://とgit@のどちらの形式も受け付け、.git拡張子は省略できます。Azure DevOpsやAWS CodeCommitのように拡張子なしURLを使うホストにも対応しています。
モノレポの1ディレクトリだけをプラグインとして配りたい場合はgit-subdirソースが向きます。
{
"name": "my-plugin",
"source": { "source": "git-subdir", "url": "https://github.com/acme-corp/monorepo.git", "path": "tools/claude-plugin" }
}git-subdirはスパースクローンで該当ディレクトリだけを取得するため、大きなモノレポでも帯域を節約できます。urlにはGitHubのowner/repo形式やSSH URLも使えます。
npmソース — レジストリ経由でインストールする形
npmパッケージとして配布済みのプラグインはnpm installでそのまま取得できます。
{
"name": "my-npm-plugin",
"source": { "source": "npm", "package": "@acme/claude-plugin", "version": "^2.0.0", "registry": "https://npm.example.com" }
}packageが必須で、version(バージョン範囲指定も可)とregistry(社内レジストリの指定)は任意です。パブリックなnpmjs.orgだけでなく、自社ホストのレジストリにも対応します。npmソースはユーザーの端末にnpmコマンドが入っていることが前提になる点が、後述のarchiveソースとの分かれ目です。
archiveとcommandソース — gitもnpmも要らない配布と動的生成
gitもnpmも入っていない端末に配りたい場合はarchiveソースを使います。HTTPSでホストしたzipファイルをダウンロードしてインストールする形式で、S3・Artifactoryのgenericリポジトリ・nginxなど静的ファイルを配れる場所ならどこでもホストできます(Claude Code v2.1.224以降が必要)。sha256フィールドでダイジェストを固定でき、--plugin-dirや--plugin-urlでの一時ロードを含めた設定手順はClaude Codeプラグインをzip配布するにまとめています。
{ "name": "my-plugin", "source": { "source": "archive", "url": "https://artifacts.example.com/my-plugin.zip" } }ローカルにインストール済みのツールがプラグインディレクトリを都度生成する場合はcommandソースを使います。IDEが選択中のツールチェーンに合わせてプラグインを描画するような場面が典型例です。
{ "name": "my-plugin", "source": { "source": "command", "command": "my-tool claude-plugin-path" } }コマンドはインストール時に実行され、セッションごとに1回バックグラウンドで再実行されます。標準出力にプラグインディレクトリの絶対パスを1行だけ出力し、終了コード0で終える必要があります(Claude Code v2.1.229以降が必要)。取得したディレクトリを丸ごとキャッシュへコピーする既定のcopyモードと、大きなディレクトリをコピーせずそのまま使うlinkモードがあり、copy/linkの使い分けと再実行のタイミングはClaude Codeプラグインのコマンドソースでマーケットプレイスを動的生成するで扱っています。他のソース型と違い、Claude Codeはユーザーがそのプラグインを他プラグインの依存として自動インストールすることはなく、ユーザー自身が先にインストールを承諾する必要があります。
使い分け早見表
| ソース型 | 前提環境 | ピン留め | 向く場面 |
|---|---|---|---|
| 相対パス | 前提環境マーケットプレイスと同一リポジトリ | ピン留めリポジトリのコミット単位 | 向く場面マーケットプレイスとプラグインをまとめて管理したいとき |
| github | 前提環境git | ピン留めref / sha | 向く場面公開・社内のGitHubリポジトリで配るとき(最も一般的) |
| url(git) | 前提環境git | ピン留めref / sha | 向く場面GitLab・Bitbucket・自前gitホストで配るとき |
| git-subdir | 前提環境git(スパースクローン) | ピン留めref / sha | 向く場面モノレポの一部だけを配るとき |
| npm | 前提環境npm | ピン留めversion | 向く場面npmレジストリに公開済みのパッケージを配るとき |
| archive(zip) | 前提環境HTTPSのみ(git/npm不要) | ピン留めsha256 | 向く場面gitもnpmも無い端末、CI成果物をそのまま配るとき |
| command | 前提環境ローカルツール | ピン留めコンテンツハッシュ | 向く場面IDE等が都度生成するディレクトリを配るとき |
バージョンの決まり方もソース型ごとに異なります。plugin.jsonやmarketplace.jsonエントリにversionを明示しない場合、github / url / git-subdir / 相対パスはgitのコミットSHAが、archiveはアーカイブのSHA-256ダイジェストがそのままバージョンとして使われます。npmソースとgit管理外のローカルディレクトリだけはunknown扱いになり、更新の有無を自動追跡できません。npmソースを継続的に更新したいなら、versionを明示するかバージョン範囲(^2.0.0など)を指定して運用するのが実務上の対処になります。
組織配布(Organization settings)で選べるソースは限られる
TeamプランやEnterpriseプランのOrganization settings > Pluginsでプラグインを配布する場合、使えるソース型はgithub / url / git-subdir、そして./で始まる相対パスに限られます。npm・archive・commandはこの経路では使えません。組織同期はClaude GitHub App(または自社のGitHub Enterprise App)経由での読み取りを前提とした仕組みと読めます。
プライベートなプラグインを配りたい場合は、プラグイン本体をマーケットプレイスと同じリポジトリに置いて相対パスで参照する形が推奨されています。組織同期が配布時にプラグインをパッケージ化するため、利用者が別のソースリポジトリへのアクセス権を個別に持つ必要がなくなります。
コマンドソースは任意コード実行をユーザーの端末で行うため、リスクが他のソース型と質的に異なります。組織全体でコマンドソースを禁止したい場合は、managed settingsのdisableCommandPluginSourcesで一括ブロックできます。
どのソース型を選ぶべきか
実務上、選択の起点になるのは「配布先の端末に何が入っているか」です。社内の開発者向けでgitが必ず入っているならgithubかurlで十分で、わざわざarchiveを選ぶ理由はあまりありません。逆に、CIランナーやコンテナのようにgitもnpmも持たない実行環境へ配る用途では、archiveが唯一実用的な選択になります。
commandだけは他の6つと性格が異なります。他のソース型は「静的な取得先」を指すのに対し、commandは「ローカルの生成プロセス」を指す仕組みです。プラグインの中身がツールの状態に応じて変わる場合を除いて、選ぶ理由は基本的にありません。
まとめ
marketplace.jsonのsourceフィールドは、相対パス・github・url(git)・git-subdir・npm・archive・commandの7通りの書き方を持ちます。実質的な判断軸は「配布先の端末にgit・npmが入っているか」と「Organization settings経由で配るか」の2点です。git前提の社内配布ならgithub系、gitもnpmも無い端末にはarchive、組織同期経由ならさらに選択肢が絞られる、という順に絞り込むと迷いにくくなります。バージョン固定の粒度を細かく制御したい場合は、依存関係のバージョン制約とタグ運用を扱うClaude Codeプラグイン依存関係、headersHelperのようなソースエントリの厳格な検証はマーケットプレイスのstrict modeとvalidateの使い方もあわせて参照すると設計しやすくなります。