はじめに
Claude Code 2.1.323 の CHANGELOG には、plugin.json に engines["claude-code"] を書けるようになったと載っています。「指定した Claude Code のバージョン範囲の外では、プラグインのインストール・更新・読み込みを行わない」という説明です。古い Claude Code を使うメンバーに、新しい機能前提のプラグインが入ってしまう事故を防ぐ仕組みに見えます。
ところが手元で試すと、範囲を満たさないプラグインがそのまま入る経路がありました。自分で配布するプラグインに engines を書くとき、どの配布経路なら実際に弾かれるのでしょうか。
対象読者は、Claude Code のプラグインを自分やチームに配布している開発者です。
この記事で解決できること
-
engines["claude-code"]の書式と、claude plugin validateが返す指摘を確認できる - ローカルフォルダ配布と git 配布で、バージョン範囲外のときの挙動がどう違うかを把握できる
- 不正な範囲を書いたときに何が起きるかを知り、書き間違いを検証で拾える
前提条件と検証環境
- 実測条件は 2026-11-13 JST、
claude --versionが2.1.323 (Claude Code)、クラウドコンテナ(Linux)上です - 検証用のプラグインとマーケットプレイスは、すべて作業用ディレクトリに作った空の構成です。実際のプラグインは使っていません
- 同じ 2.1.323 で追加された Code Mode(Claude が JavaScript でツールを呼ぶ実験機能)は、公式ドキュメントのページを取得できなかったため試していません。この記事の対象外です
TL;DR
-
plugin.jsonのenginesは{"claude-code": ">=2.1.0"}の形で書きます。範囲を表さない文字列はclaude plugin validateが error にします -
claude plugin installは、git の URL で配布されるプラグインが範囲外ならFailed to install pluginで拒否します。ローカルフォルダ配布のマーケットプレイスでは、範囲外でも注意書き付きで入ります - 不正な範囲(
not-a-range)は、検証では error なのに、git 配布のインストールは成功しました。配布前にvalidateを通す運用が必要です
engines の書式と配布経路ごとの挙動
CHANGELOG の記述は次のとおりです。
Added
engines["claude-code"]toplugin.json: plugins outside their stated Claude Code version range are not installed, updated or loaded, and install and update pick the newest version that fits
今回は、このうち「インストール」を実機で確かめました。更新時に範囲へ収まる最新版を選ぶ挙動と、読み込み時の扱いは試していません。
| 配布経路 | 範囲 |
claude plugin install の結果 |
実測 |
|---|---|---|---|
| ローカルフォルダのマーケットプレイス | >=99.0.0 |
成功。範囲外だが、ローカルフォルダから読むので読み込むという注意書きが出る | 実機確認 |
| git URL で配布するプラグイン | >=99.0.0 |
失敗(exit 1)。needs Claude Code >=99.0.0, this is 2.1.323
|
実機確認 |
| git URL で配布するプラグイン | >=2.1.0 |
成功 | 実機確認 |
| git URL で配布するプラグイン | >=2.1.0 <3.0.0 |
成功 | 実機確認 |
| git URL で配布するプラグイン | not-a-range |
成功(範囲は無視される) | 実機確認 |
手順
1. engines を書いて validate にかける
検証用に最小の plugin.json を作ります。
{
"name": "engines-test",
"version": "0.1.0",
"description": "t",
"engines": { "claude-code": ">=99.0.0" }
}
claude plugin validate .
範囲が書式として正しければ、engines についての指摘は出ませんでした。実機の出力に出たのは、author が無い旨の warning と、プラグインディレクトリへの提出向けの README・LICENSE・アイコンの指摘です。これらは engines とは別の話です。
範囲を not-a-range に変えて同じコマンドを実行すると、次の error になりました。
× Found 1 error:
> engines.claude-code: Must be a version range such as ">=2.1.0"; got "not-a-range". It will be ignored at load time.
メッセージの末尾にある「読み込み時に無視される」は、後述の git 配布での実測と一致します。
2. ローカルフォルダのマーケットプレイスで試す
newer(>=99.0.0)と older(>=2.1.0)の 2 つのプラグインを入れたマーケットプレイスを作り、フォルダのパスで登録します。
claude plugin marketplace add /path/to/mk
claude plugin install newer@eng-mk
newer は範囲外ですが、インストールは成功しました。出力には次の注意書きが付きます。
Note: "newer" needs Claude Code >=99.0.0, this is 2.1.323, but loads anyway because it's read from a local folder
ローカルフォルダのマーケットプレイスは、開発中のプラグインを手元で動かす用途を想定しているようです。そのため engines による拒否は効かず、注意書きに留まります。ただし、この理由づけは出力の文言からの推測で、仕様として確認できたわけではありません。
3. git URL 配布で試す
次に、プラグインを git リポジトリとして用意し、マーケットプレイス側から URL で参照させます。今回は検証のため、ローカルの git リポジトリを file:// の URL で指しました。
{
"name": "git-mk",
"owner": { "name": "t" },
"plugins": [
{
"name": "gitnew",
"source": { "source": "url", "url": "file:///path/to/gp" },
"description": "git sourced"
}
]
}
範囲が >=99.0.0 のプラグインをインストールすると、今度は拒否されました。
× Failed to install plugin "gitnew@git-mk": "gitnew" was not installed: it needs Claude Code >=99.0.0, this is 2.1.323. Run `claude update`.
終了コードは 1 で、claude plugin list にも入っていませんでした。claude update を案内するので、利用者側は何を直せばよいかが分かります。
範囲を >=2.1.0 と >=2.1.0 <3.0.0 にした場合は、どちらもインストールに成功しました。
4. 不正な範囲の挙動を確かめる
最後に、validate が error にした not-a-range を git 配布のプラグインに書いてインストールしました。結果は成功で、拒否も注意書きも出ませんでした。
つまり、書式を間違えると engines はただ無視され、範囲外のバージョンにも入ってしまいます。配布する側が validate を通さないと、保護が効いていることに気づけません。
実際に使って気づいたこと
筆者が最も意外だったのは、ローカルフォルダ配布で拒否されない点です。プラグインを開発しているときは、手元のフォルダで engines を >=99.0.0 にしても何も起きません。「範囲外のバージョンで弾かれることを確かめたつもり」が、経路の違いで確認できていない状態になります。
拒否を確かめたいときは、file:// の URL で参照するローカルの git リポジトリを使うのが手軽でした。ネットワークに公開しなくても、git 配布と同じ経路を再現できます。
もうひとつは、不正な範囲が静かに通る点です。>=2.1.0 を >= 2.1.0 のようにスペース入りで書いたり、^2.1.0 のような別記法を使ったりした場合に、validate が受け付けるかどうかは今回の範囲では試していません。範囲の書式の幅は、実際に validate をかけて確かめるのが確実です。
運用への示唆
- プラグインを配布する前に
claude plugin validate .を通し、engines.claude-codeの error が無いことを確認します -
enginesの拒否が効くかを確かめるときは、ローカルフォルダではなく git URL 経由のマーケットプレイスで試します - 範囲の下限は、プラグインが使う機能が入った最初の版に合わせます。上限を付けるかは、先の版で壊れる根拠があるときに限ると、利用者を締め出しにくくなります
まとめ
engines["claude-code"] は、git URL で配布されるプラグインのインストール時に、Claude Code のバージョンが範囲外なら拒否する仕組みでした。ローカルフォルダ配布では拒否されず注意書きに留まり、書式が不正な範囲は無視されます。更新時に範囲へ収まる最新版を選ぶ挙動と、すでに入っているプラグインの読み込み時の扱いは、今回は確認していません。
自分のプラグインに engines を書くなら、まず validate を通し、次に git 配布の経路で拒否まで確認する。この 2 段階を踏めば、書いたつもりの保護が効いていない状態を避けられます。