Claude Codeの`claude plugin update`が「最新です」と言うのに中身が古いまま——バージョン判定の仕組みとGitHub Issue実例
Claude Codeで`claude plugin update`が「already at the latest version」と表示されるのに、プラグインの中身は古いまま——という報告を公式ドキュメントとGitHub Issue実例(#93108・#95788・#94547・#93825)から検証。バージョン判定の仕組み、本当に最新か確認する方法、現状の回避策まで整理した。
エンジニアのゆとです。
マーケットプレイス経由でClaude Codeのプラグインを入れている人なら、claude plugin marketplace updateのあとにclaude plugin update <plugin>を叩いて「もう最新のはず」と思ったことがあると思う。ところが実際にキャッシュの中身を覗いてみると、数週間、下手すると数ヶ月前のスキルやコマンドがそのまま残っている——という報告が、GitHub Issueにいくつも上がっている。
厄介なのは、コマンド自体はちゃんと成功しているように見える点だ。エラーは出ない。「already at the latest version (0.1.0)」ときっぱり言われる。だから普通は疑わない。疑わないまま、古いスキルの挙動に振り回されて時間を溶かす。
この記事では、この「更新されたと思ったら更新されていない」問題を、Claude Code公式ドキュメントの「Versions and updates」の記述と、anthropics/claude-codeに上がっている複数のGitHub Issue(いずれも2026年9月時点でOPEN)を突き合わせて整理する。原因を知ったうえで自分の環境が実際に最新かどうかを確認する方法と、現状取れる対処法もまとめた。
まず結論 — 何が起きているか
| 項目 | 内容 |
|---|---|
| 症状 | claude plugin updateが「already at the latest version」と表示するのに、プラグインの中身(スキル・コマンド等)が古いまま |
| 原因 | Claude Codeが更新判定に使うのは「バージョン文字列」だけで、実際のコミット内容やファイルの差分は見ない |
| バグか仕様か | 公式ドキュメントに明記された「意図した仕様」。ただし、その仕様のもとでも取りこぼしや別種のバグが複数報告されている |
| 影響範囲 | プラグイン作者がversionをバージョンアップし忘れているケースだけでなく、公式マーケットプレイスのsha固定プラグインや、プライベートマーケットプレイスの自動同期でも類似の報告あり |
| 現状の回避策 | アンインストール→再インストール、またはversionを固定しない運用に切り替える |
一言でいうと「バージョンを上げなければ、Claude Codeは中身が変わったことに気づけない」という、かなり素朴な判定ロジックがそのまま実装されている、という話だ。
症状: 「already at the latest version」なのに中身は古い
もっとも詳しく検証されているのがIssue #93108だ。報告者はlangsmith-skills@langsmith-skillsというプラグインを例に挙げている。このプラグインのplugin.jsonは"version": "0.1.0"のまま2026年3月のマニフェスト追加以降一度も変わっていないが、リポジトリ側のconfig/skills/には5件のコミットが積まれていて、直近の1件(8月17日)はlangsmith-evaluatorスキルを現行のLangSmith CLIに合わせて書き換えるという、内容的には決して小さくない変更だった。
それにもかかわらず、claude plugin update langsmith-skills@langsmith-skillsを実行すると返ってくるのは次の一行だ。
✔ langsmith-skills is already at the latest version (0.1.0).マーケットプレイス自体はすでに新しいコミットを取得済みで、known_marketplaces.jsonのautoUpdateもtrueになっている。それでもインストール済みのキャッシュだけが4ヶ月前の内容のまま置き去りにされる。報告者が確認した唯一の回避策は、claude plugin uninstallしてからclaude plugin installし直すことだった。
同じIssueには、公式マーケットプレイス側のプラグイン(superpowers、cloudflare@cloudflare)でも同様の構造の報告が追加コメントとして寄せられている。cloudflare@cloudflareはplugin.jsonの"version": "1.0.0"が一度も変わっておらず、marketplace.json側にもバージョン情報がないため、比較する材料がそもそもどちらの側にも存在しない状態だったという。
原因: 更新判定は「バージョン文字列」だけを見ている
なぜこんなことが起きるのか。実はこれ、隠れたバグというより公式ドキュメントに明記された仕様だ。「Plugin loading reference」の「Versions and updates」には、次のように書かれている。
If a plugin’s author pushed new commits and
claude plugin updateprints<name> is already at the latest version (<version>)., the version Claude Code computes for the plugin is unchanged, so nothing changes on disk.
Claude Codeはプラグインをインストールするたびに「バージョン」を計算し、installed_plugins.jsonに記録した値と比較して、一致していれば「更新不要」と判断する。このバージョンの計算順序は次のとおりだ。
- プラグインのマニフェスト(
plugin.json)のversionフィールド - マーケットプレイスエントリ側の
versionフィールド - どちらにも指定がなければ、ソース種別ごとのデフォルト(
github/url/git-subdirならコミットSHAの先頭12文字、ローカルディレクトリでgit管理下になければunknown、npmならunknown)
つまりversionをマニフェストに書いてしまった時点で、それが「固定ピン」として機能する。公式ドキュメントの言葉を借りれば、著者が何回コミットを積もうと「文字列を変えるまでユーザーはそのキャッシュに留まる」。逆に言えば、コミットを追いかけさせたいならversionをマニフェストにもマーケットプレイスエントリにも書かない、という選択が要る。
これ自体は仕組みとして筋が通っている。だが実際には、この「文字列が変わったかどうか」の判定ロジックの外側で、いくつもの取りこぼしが報告されている。
実例1: gitCommitShaだけが古いまま取り残される(Issue #95788)
Issue #95788は、version自体はきちんと上がっているのに、記録された内部情報の一部だけが更新されずに残ってしまうケースだ。報告者のマーケットプレイスエントリはref: "dist"(リリースごとに書き換わるブランチ)を指しており、plugin.jsonにはリリースバージョンが書かれている。
手動更新後の記録:
version: 0.1.0-rc9 installPath: .../envato-guardrails/0.1.0-rc9 gitCommitSha: 9d4c0c0d...その後バックグラウンドの自動更新が走った後の記録:
version: 0.1.0-rc10 installPath: .../envato-guardrails/0.1.0-rc10 gitCommitSha: 9d4c0c0d...versionもinstallPathも正しく0.1.0-rc10に進み、キャッシュディレクトリの中身も実際に新バージョンになっている。ところがgitCommitShaだけが前回インストール時のコミットのまま更新されていない。報告者は、同じ自動更新のバッチで6秒前に更新された別マーケットプレイスのプラグインではgitCommitShaが正しく動いていたことも確認しており、「相対パスでマーケットプレイス内から取得するプラグイン」と「ref付きgithubソースから取得するプラグイン」とで扱いが分かれている可能性を指摘している。
これは中身自体は最新なので実害は小さいが、「本当に最新のコミットから作られているか」をinstalled_plugins.jsonのメタデータだけで確認しようとすると、間違った答えを掴まされることになる。
実例2: スコープを跨いで入れると、キャッシュが歯抜けになる(Issue #94547)
もう一段実害が大きいのがIssue #94547だ。108個のスキルを含む大きめのプラグインを、ユーザースコープとプロジェクトスコープの両方にインストールしていた環境で、自動更新後にキャッシュディレクトリの中身が歯抜けになった。
具体的には108個中81個のスキルディレクトリと、他のトップレベルディレクトリ1つがまるごと消えていた一方、agents/・hooks/・scripts/・.mcp.json・plugin.json・README.mdはすべて揃っていたという。マーケットプレイス側のクローン自体は完全な状態で正しいコミットを指していたため、欠損が起きたのは「マーケットプレイスからキャッシュへのコピー」の過程だった。
さらに厄介なのは、これがまったく無警告で起きる点だ。セッションはエラーなくプラグインを読み込み、108個のはずのスキルを81個として扱う。/reload-pluginsは減った数をそのまま正しい数として報告し、スラッシュコマンドの補完にも欠けたスキルは単に出てこないだけ。installed_plugins.jsonを見ると、同じplugin@marketplace・同じバージョン・同じinstallPathのエントリが、lastUpdatedが2秒しか違わない状態でユーザースコープとプロジェクトスコープの両方に存在していた。2つのスコープからほぼ同時に書き込みが走ったことが、コピーの競合に繋がった可能性がある。
大きめのプラグインを複数スコープで併用している場合、更新後にclaude plugin details <name>やスキル数の見た目上のカウントを一度確認しておいたほうがいい理由がここにある。
実例3: 「自動同期」が謳い文句どおりに動かない(Issue #93825)
ここまではclaude plugin update側の話だったが、そもそも自動更新のトリガー自体が発火しないという報告もある。Issue #93825では、プライベートなアカウントマーケットプレイスに「Sync automatically — Re-syncs on GitHub changes」という設定があり、デフォルトで有効になっているにもかかわらず、実際には一度も自動発火しなかったと報告されている。
報告者が約9時間で8回pushしたところ、マーケットプレイスカードに表示される「Synced commit」もプラグインバージョンも一度も動かなかった。一方で「Check for updates」を手動で押すと、毎回20秒程度で新しいコミットを正しく取得できている。つまり同期のパイプライン自体は正常に機能しているのに、「変更があったら自動で」のトリガーだけが機能していない。
これはclaude plugin updateのロジックとは別の場所で起きている問題だが、結論は同じだ。「自動更新が有効になっている」という表示や設定を、実際に更新が反映されていることの証拠として信用しないほうがいい。
自分の環境で「本当に最新か」を確認する方法
これらの報告に共通しているのは、claude plugin updateや自動更新の「成功しました」というメッセージが、実際の中身の一致を保証していないという点だ。マーケットプレイス側のCLIから、実際に自分の目で突き合わせて確認する手段が用意されている。
# マーケットプレイスのクローンが今どのコミットにいるか
git -C ~/.claude/plugins/marketplaces/<marketplace名> rev-parse --short HEAD
# インストール済みキャッシュの中身とマーケットプレイスの中身を比較する
diff -rq \
~/.claude/plugins/cache/<marketplace名>/<plugin名>/<version>/ \
~/.claude/plugins/marketplaces/<marketplace名>/<プラグインのパス>/diffで差分が出るのにclaude plugin updateが「already at the latest version」と言い続ける場合は、Issue #93108のパターン(マニフェストのversionが固定されている)を疑うのが早い。plugin.jsonのversionフィールドを見て、コミット履歴に対して明らかに古いまま止まっていないかを確認する。
現状の対処法
根本的な修正(コミット単位での差分検知やclaude plugin update --forceのような強制再取得オプション)はIssue時点ではまだ実装されていない。現実的に取れる手は次の3つだ。
1. アンインストール→再インストールで強制的に取り直す
もっとも確実なのはこれだ。claude plugin uninstall <name>のあとにclaude plugin install <name>@<marketplace>をやり直せば、バージョン文字列の一致判定を経由せずにマーケットプレイスの現在の中身がそのままコピーされる。日常的に更新される私物プラグインなら、更新のたびにこれを挟む運用にしてしまったほうが早い。
2. 自分で作るプラグインなら「バージョンを固定しない」という選択肢を検討する
公式ドキュメントが明言しているとおり、マニフェストとマーケットプレイスエントリの両方からversionを外せば、コミットSHAがそのままバージョンとして使われ、pushするたびに「新バージョン」として扱われる。チーム内配布用のプラグインで「常に最新のmainを追わせたい」場合は、バージョンを律儀に上げる運用より、この方が事故が少ない。逆に、リリースを区切って安定版に固定したい場合はversionを明示するのが正しいので、どちらが自分の配布方針に合っているかを最初に決めておく必要がある。
3. autoUpdateの表示を過信せず、更新後に一度中身を見る
Issue #93825や#94547が示すとおり、「自動更新が有効」「更新しました」という表示は、実際の中身の一致を保証しない。特にスキル数が多いプラグインや、複数スコープで使っているプラグインは、更新のたびにclaude plugin details <name>やスキル一覧の見た目のカウントを軽く確認しておくと、歯抜けや取り残しに早く気づける。
プラグイン周りは同種の修正が繰り返されている領域でもある
余談だが、anthropics/claude-codeのCHANGELOGを遡ると、プラグインのバージョン管理・キャッシュまわりは過去にも何度か個別に直っている。「公式マーケットプレイスのスナップショットファイルがリンクだったり大きすぎたりするとclaude plugin updateが記録済みのコミットを消してunknownにしてしまうバグ」や、「公式マーケットプレイスのプラグインがコミット情報なしで記録され、コミット固定プラグインを更新したあとも古いコミットのまま残るバグ」など、似た系統の不具合が個別に修正されてきた形跡がある。
裏を返せば、「バージョン文字列だけで判定する」という設計自体がそう簡単には変わらない一方で、その周辺の記録ロジック(gitCommitShaやキャッシュのコピー処理)は今もまだ枯れきっていない、ということでもある。プラグインの更新が絡んで様子がおかしいと感じたら、「まだ直っていないバグを踏んでいる」可能性は十分にある。
FAQ
claude plugin update --forceのようなオプションはない?
2026年9月時点のIssueを見る限り、まだ実装されていない。Issue #93108でも要望として「最低限--forceが欲しい」という声が上がっているが、対応するリリースは確認できていない。現状は前述のアンインストール→再インストールが実質的な代替手段になる。
自分が配布しているプラグインで、ユーザーに確実に更新を届けたい場合は?
plugin.jsonのversionを必ずコミットごとに上げる運用を徹底するか、そもそもversionフィールドをマニフェストからもマーケットプレイスエントリからも外して、コミットSHAベースの判定に任せるかのどちらかになる。前者は「意図的にバージョンを固定したい」場合に有効だが、更新の度にバンプし忘れると今回のような取りこぼしが起きる。
公式マーケットプレイス(claude-plugins-official)のプラグインでも同じことは起きる?
Issue #93108のコメントでは、superpowersやcloudflare@cloudflareのような公式マーケットプレイスのプラグインでも同種の構造(バージョン文字列が固定されたまま、比較材料がない)が報告されている。公式だから安全というわけではなく、判定ロジック自体は同じものが使われている。
この記事の情報はいつの時点のもの?
Issue #93108は2026年9月9日作成、#95788は9月21日作成、#94547は9月15日作成、#93825は9月11日作成で、いずれも2026年9月24日時点でOPENのままになっている。プラグインまわりの挙動はマイナーアップデートのたびに変わりやすいので、実際に確認する際はclaude --versionで手元のバージョンを確認したうえで、各Issueの最新コメントも見ておくのが確実だ。
「更新した」と表示されたら安心してしまうのが普通の感覚だと思うが、プラグインについてはその表示自体があまり当てにならない、というのが今のところの実情に近い。特に自作プラグインをチームで配っている場合や、大きめのプラグインを複数スコープで使っている場合は、更新後に一度中身を見る癖をつけておいたほうがいい。
