Claude Codeプラグインをzip配布する — --plugin-urlとsha256ピン留め

zip配布が向く場面

Claude Codeのプラグインは、gitリポジトリやnpmパッケージだけでなくzipアーカイブでも配れます。gitもnpmも入っていない端末や、CIが吐き出したビルド成果物をそのまま配りたいときに使う経路です。使う場面によってコマンドが3段階に分かれます。開発中に手元のzipを一時的に試す--plugin-dir、CIの成果物URLをその場で読み込む--plugin-url、そしてチームや社外へ本番配布するmarketplace.jsonのarchiveソースです。

この3つは対象読者が違います。--plugin-dirと--plugin-urlはプラグインを作る側がその場限りで動作確認するためのフラグで、インストールにはなりません。本番でユーザーに配るのはarchiveソースだけです。この違いを取り違えると、「動作確認できたのに配布したプラグインが見えない」というつまずきにつながります。

プラグインの構造そのもの(.claude-plugin/plugin.jsonやスキル・フックの配置)はClaude Codeプラグイン完全ガイドにまとまっているので、初めてプラグインを作る場合は先にそちらで全体像をつかむと読みやすくなります。

ローカルのzipを一時ロードして試す

--plugin-dirはディレクトリだけでなく、プラグインディレクトリをそのまま固めたzipアーカイブも受け付けます。配布用のzipを作った直後に、展開せずそのまま起動確認できるのが利点です。

claude --plugin-dir ./my-plugin
claude --plugin-dir ./my-plugin.zip

フラグは繰り返し指定でき、複数のプラグインを同時に一時ロードできます。

claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two.zip

同名のマーケットプレイスプラグインが既にインストールされている場合、そのセッションでは--plugin-dir側が優先されます。既存プラグインをアンインストールせずに変更を試せるので、開発中の反復に向いています。ただしmanaged settingsで強制有効化・無効化されているプラグインはこの上書きの対象外です。

編集を加えるたびにセッションを再起動する必要はありません。/reload-pluginsで再起動なしにプラグインを反映するの手順でスキル・フック・MCPサーバーの変更をまとめて読み込み直せます。

CI成果物のURLをその場で読み込む

--plugin-dirはローカルパス前提です。CIがビルドしたzipをアーティファクトサーバーへ置いている場合は、--plugin-urlでURLから直接フェッチできます。

claude --plugin-url https://example.com/my-plugin.zip

Claude Codeはセッション開始時にアーカイブを取得し、そのセッション限りで読み込みます。取得に失敗した場合や、アーカイブの中身が不正な場合は、プラグインを読み込まずに起動し、/pluginマネージャーのErrorsタブにロードエラーを記録します。プラグインが動かないまま起動が止まることはありません。

複数プラグインを読み込みたいときは、フラグを繰り返すか、1つの引数にスペース区切りで並べます。

claude --plugin-url https://example.com/my-plugin.zip --plugin-url https://example.com/other.zip
claude --plugin-url "https://example.com/my-plugin.zip https://example.com/other.zip"

--plugin-urlは他のプラグインソースと同じ信頼性の判断が要ります。自分が管理している、あるいは信頼できるアーカイブだけを指定してください。CI成果物のようにURLが頻繁に変わる運用では、固定URLの先を最新ビルドに差し替える形が扱いやすくなります。

marketplace.jsonでzip配布を本番化する

開発中の確認が終わったら、実際にユーザーへ配るにはmarketplace.jsonのプラグインエントリでarchiveソースを使います。gitもnpmも入っていない端末でもインストールできる点が、この方式の中心的な価値です。S3・Artifactoryのgenericリポジトリ・nginxなど、静的ファイルを配れるサーバーであればホスト先は問いません。

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip"
  }
}

zipを作るとき、プラグインの中身を直接zipにしても、プラグインのフォルダごとzipにしてもどちらでも動きます。Claude Codeはアーカイブの最上位に.claude-plugin/を探し、無ければ単一のトップレベルフォルダの中を探すためです。ただし2段階より深い階層にネストしたプラグインはインストールに失敗します。アーカイブのサイズにも上限があり、256MiBを超えるものは拒否されます。

zipにNode.jsパッケージの依存を含める場合、プラグインのルート直下にpackage.jsonと対応するロックファイル(npm-shrinkwrap.json / package-lock.json / bun.lock / bun.lockb)を同梱しておくと、Claude Codeがキャッシュへコピーするタイミングで自動的にインストールしてくれます。npmソースで配る場合はpackage-lock.jsonがnpm publish時に除外されるためnpm-shrinkwrap.jsonを使う必要がありますが、archiveソースはzipをそのまま送るのでこの制約を受けません。

archiveソースの利用にはClaude Code v2.1.224以降が必要です。v2.1.120〜v2.1.223では該当プラグインのインストール時に「このプラグインが使うソースタイプは、お使いのClaude Codeのバージョンに対応していません」という趣旨のエラーになり、それより古いバージョンではarchiveエントリを含むマーケットプレイス自体が読み込みに失敗します。社内配布で古いバージョンのユーザーが残っている場合は、事前にバージョンの周知が必要です。

urlフィールドはhttps://のみを受け付けます。http://のURL、ループバックアドレス、リンクローカルアドレス、クラウドのメタデータエンドポイントへのURLは拒否され、リダイレクト先の各ホップも同じ条件を満たさない限りダウンロードそのものが拒否されます。

sha256ピン留めとバージョン管理の関係

archiveソースはsha256フィールドを省略できますが、省略するとホスト側のzipファイルのバイト列が変わるたびにユーザー側が更新扱いになります。特定のビルドを固定して配りたいときは、アーカイブのダイジェストをsha256に追加します。

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip",
    "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
  }
}

ダウンロードしたファイルがこのダイジェストと一致しない場合、Claude Codeはインストールを拒否し、「archive integrity check」の対処のエラーを報告します。改ざんされたファイルはもちろん、単純にzipを更新してダイジェストを書き換え忘れたときも同じエラーになる点は覚えておく必要があります。

plugin.jsonにもマーケットプレイスエントリにもversionを書かない場合、sha256のピンがそのままプラグインのバージョンとして扱われます(先頭12文字に短縮して表示)。明示的なversionを設定している場合は、そちらが更新シグナルになるため、zipとダイジェストを差し替えたらversionも必ずbumpしてください。bumpを忘れると、ユーザー側はキャッシュ済みの古いコピーを使い続けます。

社内の静的サーバーやアーティファクトリポジトリへ継続的に配布するプラグインには、ダイジェストバージョンが向いています。安定したリリースサイクルで配る公開プラグインには、明示バージョンのほうが更新タイミングを制御しやすくなります。

プライベートなzipを認証付きで配る

社内レジストリのようにアーカイブへのアクセスに認証が要る場合、ダウンロード時に送るHTTPヘッダーを設定できます。headersは、マーケットプレイスを追加したURLソース(extraKnownMarketplacesのエントリなど)に設定するのが基本です。Claude Code v2.1.238以降では、sourceと並べてプラグインのエントリ側にも設定できます。

トークンが短命で毎回発行し直す必要がある場合は、headersの代わりにheadersHelperにコマンドを設定します。Claude Codeがそのコマンドを実行し、出力したJSONオブジェクトをヘッダーとして送信します。

{
  "name": "my-plugin",
  "description": "Formatting commands for internal services",
  "strict": false,
  "commands": "./commands",
  "source": {
    "source": "archive",
    "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"
  },
  "headersHelper": "/opt/bin/mint-registry-token.sh"
}

headersHelperを設定するエントリは"strict": falseが必須です。マーケットプレイスエントリだけでプラグインの内容が確定するようにし、ユーザーがコマンドを受け入れる前にプラグインの中身を確認できるようにするためです。ヘッダーを設定する場所によって、どのダウンロードに反映されるか、いつコマンドが実行されるかが変わります。マーケットプレイスのurlソースに設定すると同じオリジンへのすべてのアーカイブダウンロードに適用され、プラグインエントリ側に設定するとそのプラグイン単体のダウンロードだけに適用されます。

よくあるつまずきと回避策

プラグインのキャッシュがどこに展開され、どう更新差分を検知しているかを詳しく知りたい場合はClaude Codeプラグインのキャッシュとファイル解決の仕組みで扱っています。バージョン解決の全体像(git commit SHA・npm・archiveダイジェストの優先順位)はClaude Codeプラグインのリリースチャネルとバージョン解決にまとまっています。

まとめ

zip配布は、開発中の一時確認(--plugin-dir)、CI成果物の即時確認(--plugin-url)、本番配布(archiveソース)の3段階で使い分けます。本番配布では、gitもnpmも不要という利点と引き換えに、sha256ピンとバージョン管理を自分で設計する必要があります。ピンを設定するかどうか、明示バージョンとダイジェストバージョンのどちらを使うかは、更新をどれだけ細かく制御したいかで決めてください。プライベートなアーカイブを配る場合は、headersかheadersHelperで認証を組み込めば、静的サーバーだけで完結する配布経路になります。