Claude Codeのプラグインが読み込まれない時の調べ方

この記事の要点
- プラグインは「設定に書く」「ディスクに取り込む」「実行中に読み込む」の3段階を通る。止まっている段階を探す
- ID の @ より後ろ(marketplace・inline・skills-dir・synced)で、どこから来たプラグインかが分かる
- 同じ ID は設定の優先順位の高い方が勝つ。個人で無効にしても、プロジェクト側や管理設定が有効なら読み込まれる
活用例:社内で配ったAIの道具(プラグイン)が動かない時の原因を切り分ける
- 部署
- 情報システム・開発
- 使うもの
- Claude Code の /plugin と設定ファイル
- AIに任せる
- 設定と置き場所の読み取り・原因の診断
- 人が決める
- どの設定を直すか・誰の設定を優先するか
プラグインを入れたのに動かない、無効にしたのに動いてしまう、更新しても何も変わらない。こうした時は、エラーメッセージを探す前に「どの設定が決めているか」を見ると早く片付きます。
この記事は、公式ドキュメント「Plugin loading reference」(2026年11月18日確認)にもとづいて、調べる順番をまとめます。エラー文が出ている場合は プラグインのトラブル対処 を、入れ方・置き場の作り方は プラグインのマーケットプレイス をご覧ください。
結論:まず「どの段階で止まったか」を見る
プラグインは3つの段階を通って使えるようになります。
| 段階 | 場所 | 見るもの |
|---|---|---|
| 宣言 | 設定ファイル | enabledPlugins(オンにするプラグイン)と extraKnownMarketplaces(置き場の登録) |
| 取り込み | ホームフォルダの .claude/plugins/ | installed_plugins.json と known_marketplaces.json、cache フォルダ |
| 読み込み | 実行中のセッション | 起動時、または最後に /reload-plugins を打った時点の状態 |
設定やファイルを変えても、実行中のセッションには届きません。 /reload-plugins を打つか、新しく起動し直します。更新のあとに「Restart to apply changes.」と出るのは、このためです。
ID の末尾で、どこから来たか分かる
プラグインの ID は「名前@出どころ」の形です。@ より後ろを見ます。
| 末尾 | 出どころ | オン・オフの方法 |
|---|---|---|
| @置き場の名前 | 登録した置き場(マーケットプレイス)から入れた | enabledPlugins に true か false |
| @inline | 起動時に --plugin-dir などで渡した(そのセッションだけ) | 既定でオン。設定に false で止める |
| @skills-dir | skills フォルダの中に plugin.json 付きで置いた | マニフェストの defaultEnabled。設定で上書き可 |
| @synced | claude.ai のアカウントでオンにした | 既定でオン。設定に false で止める |
この4つの名前は予約されているので、同じ名前の置き場は作れません。
無効にしたのに読み込まれる時
同じ ID の設定は、優先順位の高い方が勝ちます。低い方から並べると次の順です。
- --add-dir で追加したフォルダの設定(true だけ有効)
- user(ホームフォルダの設定。自分のすべてのプロジェクト)
- project(プロジェクトの .claude/settings.json。クローンした全員)
- local(プロジェクトの .claude/settings.local.json。自分だけ)
- flag(起動時の --settings)
- managed(管理設定。どれにも上書きされない)
自分の user 設定で false にしても、project 側が true なら読み込まれます。自分のパソコンだけ止めたい時は、local に false を書きます。 管理設定で true にされているものは、個人では止められません。
更新しても変わらない時
「is already at the latest version」と出る時は、Claude Code が計算したバージョンが同じです。作者が新しい変更を出しても、バージョンの値が変わらなければ、手元のファイルは入れ替わりません。更新を届けたい作者は、バージョンを上げるのが基本です。
古いバージョンのフォルダは、更新や削除から14日後に自動で片付けられます。実行中のセッションが古い版を使い続けられるようにするためです。
ディスク上の置き場所
置き場の既定は、ホームフォルダの .claude/plugins/ です。主なものを挙げます。
- cache:入れたバージョンごとのファイル。プラグインの根のパスは、バージョンが変わるたびに変わる
- data:プラグインの永続データ。更新しても残る。消えては困るファイルは、cache ではなくこちらに置く
- marketplaces:登録した置き場の複製
- synced:claude.ai から取り込んだもの
- installed_plugins.json / known_marketplaces.json:何を入れたか、どの置き場を取得したかの記録
プラグインの外のファイルを指す設定(親フォルダへの参照や、外に向いたシンボリックリンク)は、読み込まれません。macOS と Linux では、パスにバックスラッシュが入っているだけで拒否されます。 パスは斜め線(/)で書きます。
見落としやすい5つの原因
- プロジェクトの中のサブフォルダから起動している:skills フォルダ型のプラグインは、親のフォルダまでは探しません。プロジェクトの根から起動する
- 信頼していないフォルダ:作業フォルダの信頼の確認を通るまで、プロジェクトのプラグインは読み込まれない
- 管理設定でふさがれている:skills フォルダのプラグインは、カスタマイズをプラグインだけに限る設定(strictPluginOnlyCustomization)などで、エラーなしで飛ばされる。/status で Setting sources に管理設定が出るかを見る
- サインインの方式:claude.ai の同期は、claude.ai のアカウントで入った時だけ動く。トークンや認証の補助スクリプトで入っているセッションでは、同期されない
- 依存パッケージが入っていない:ロックファイル(package-lock.json か bun.lock)が無い、または yarn.lock と pnpm-lock.yaml だけだと、自動の取り込みは行われない。詳しくは プラグイン同士の依存 の記事へ
調べる順番の例
- /plugin の Installed と Errors を開き、どの段階で止まったかを見る
- ID の末尾で出どころを確かめる
- 設定の優先順位の表で、どの設定が最後に勝っているかを探す
- ディスク上の installed_plugins.json に記録があるかを見る
- 直したら /reload-plugins を打ち、変わったかを確かめる
読み方に迷う時は、Claude にこのドキュメントを読ませて、自分の設定を診断させる方法もあります。
まとめ
- 宣言・取り込み・読み込みの3段階で、止まっている所を探す
- ID の @ より後ろで、出どころが分かる
- 同じ ID は優先順位の高い設定が勝つ。個人の無効化は local に書く
- 変更は /reload-plugins か再起動で初めて届く
出典:Plugin loading reference(公式ドキュメント)
この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。


