結論：archive sourceはHTTPS ZIPをSHA-256とversionで固定する

Claude Code v2.1.224以降では、marketplaceのplugin sourceにarchiveを指定し、HTTPS上のZIPをgitやnpmなしでinstallできます。

本番ではZIPへsha256を付け、pluginのversionもreleaseごとに更新し、別端末でinstallと改ざん拒否を確認してから配布します。

読者の具体的な困りごとは、制限端末へgit credentialやnpm registryを増やしたくない一方、artifact server上のZIPが差し替わっても同じreleaseとしてcacheされ、誰が何を入れたか説明できないことです。この記事を読むと、archive、git、npm、relative pathを比較し、配布方式と改ざん検知、更新条件を判断できます。

次の行動：対象端末について「git利用可否」「npm利用可否」「HTTPS artifact server到達可否」を三列で書き、archiveが解く制約を一つに固定してください。

archive plugin sourceの提供条件とZIP構造

archive sourceはClaude Code v2.1.224で追加されました。marketplaceのmarketplace.json内でpluginごとにsource: archiveとurlを指定します。URLはHTTPS必須で、HTTP、loopback、link-local、cloud metadata hostは拒否されます。redirectする場合もすべてのhopが同じsecurity条件を満たす必要があります。

ZIPの上限は256MiBです。Claude Codeはarchive直下の.claude-plugin/、または単一top-level folderの直下にある.claude-plugin/を探します。二階層より深くpluginを入れるとinstallできません。build outputをそのままzipするのではなく、展開後のrootをCIで検査します。

sha256は64桁のhex digestで、upper/lower caseを受け付けます。downloadしたfileがpinと一致しなければPlugin archive integrity check failedで拒否されます。digestは配布経路の改ざんや誤差し替えを検知しますが、作成者が悪意あるZIPとdigestを同時に更新することは防げません。source review、signing、release承認は別に必要です。

archive・git・npm・relative pathを6軸で比較する

  1. 端末要件：archiveはgitもnpmも不要です。git sourceはclone、npm sourceはregistryとnpm installが必要です。
  2. 再現性：archiveはsha256、gitはcommit SHA、npmはpackage versionでpinします。branch、latest、同じURLの上書きだけに依存しません。
  3. private配布：artifact server認証をmarketplaceと同一originのheaderで渡せる場合があります。redirectでoriginが変わるとcredentialは送られません。
  4. 更新検知：plugin.jsonまたはmarketplace entryにversionがある場合、その文字列がcache更新のsignalです。ZIPとdigestを変えたらversionも上げます。
  5. 組織sync：claude.ai Organization settingsのplugin syncはgithub、url、git-subdirを対象にし、archiveとnpmは非対応です。管理面を先に選びます。
  6. 開発速度：同じmarketplace repository内のrelative pathは開発が簡単です。URLでmarketplace.jsonだけを配る方式ではrelative fileがdownloadされないため使えません。

archiveは「一番安全な方式」ではなく、install端末のdependencyを減らす方式です。sourceの変更履歴や差分reviewはgitが得意で、package dependencyとversion解決はnpmが得意です。artifactを既存のrelease管理へ載せたい時にarchiveを選びます。

ZIP pluginを配布する8手順

  1. plugin directoryでmanifest、Skills、agents、hooks、MCP設定をreviewし、claude plugin validateを通します。外部path参照はcacheへcopyされないため削除します。
  2. release versionを決め、plugin.jsonかmarketplace entryのどちらか一方へ置きます。両方に置くとplugin.jsonが優先され、stale versionを見逃します。
  3. .claude-plugin/がarchive直下または一つのfolder直下に来るようZIPを作り、展開testで階層と256MiB未満を確認します。
  4. CIの信頼できるrunnerでZIPのSHA-256を計算し、artifact、digest、source commit、build logを同じrelease recordへ保存します。
  5. immutableなHTTPS URLへuploadします。同じfilenameの上書きを禁止し、release versionをpathかfilenameへ含めます。
  6. marketplace entryへarchive URLとsha256を登録し、ZIPを変えた場合はversionも同時に更新します。digestだけ変えてversionを据え置くと既存userがcached copyを使う可能性があります。
  7. gitもnpmもないclean端末、または同等containerでmarketplace追加、plugin install、skill起動、hook/MCP loadを確認します。
  8. marketplace更新後に旧versionからupgradeし、故意に一文字違うdigestでinstallが拒否されるnegative testも行ってから配布します。

marketplaceがURL sourceでcustom headerを持つ場合、archive URLが同じscheme、host、portならheaderがdownloadにも使われます。別originやredirect先には送られません。これはcredential漏えいを防ぐ仕様です。private artifactを別hostへ置くなら、短時間signed URLなど別の認証設計を選びます。

release前のチェックリスト

  • Claude Code v2.1.224以降を対象にしている
  • marketplaceの利用面がorganization syncではない
  • URLがHTTPSでprivate・metadata hostへ解決しない
  • redirect hopもsecurity条件を満たす
  • ZIPが256MiB未満である
  • .claude-pluginが直下または一階層にある
  • sha256をCIで計算し64桁で固定した
  • versionをZIP変更と同時に更新した
  • clean端末でinstallと起動を確認した
  • digest不一致が拒否されることを確認した
  • 旧artifactとmarketplaceをrollback可能にした

配布後はplugin cacheのversion、marketplace URL、実際のdigestを台帳へ残します。問い合わせで「新しいZIPを置いたのに反映されない」と言われた時は、最初にversion resolutionを確認します。優先順位はplugin.jsonのversion、marketplace entryのversion、source由来のversionです。archiveではsha256 pin、pinがなければdownload digestがfallbackになります。

sha256を省略してもinstallはできますが、同一URLの内容が変わった時に事前承認したartifactとの一致を証明しにくくなります。本番配布はpinあり、検証用の一時marketplaceだけpinなしと分け、pinなしをmanaged設定へ入れない運用が明快です。

よくある質問と次の行動

ZIPへplugin folderごと入れてもよいですか？

はい。単一top-level folderの直下に.claude-plugin/があれば認識されます。さらに深い階層は不可です。

digestを変えればversionを上げなくても更新されますか？

versionをmanifestかentryに明示している場合、そのversionが先に使われます。ZIPとdigestの変更時はversionも上げてください。

archiveでprivate repositoryの代わりになりますか？

artifact配布はできますが、source reviewや履歴管理を置き換えません。build元repositoryとartifactの対応をrelease recordへ残します。

archive schema、ZIP階層、256MiB、sha256、version解決はAnthropic公式Plugin marketplaces、追加versionと日付はClaude Code公式Changelog、plugin manifestとcacheは公式Plugins referenceで公開直前にも確認してください。

利用端末の導入はClaude Code install、組織への展開条件は企業導入checklist、pluginが使える操作の境界は権限設定へつなげます。Miraigentの無料診断では、artifact、digest、version、配布端末、rollbackを一枚のrelease gateへ整理します。