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

公開 更新 著者 永上裕之導入とルール
虫眼鏡を持った小さなロボットが、並んだ3つの箱を順番にのぞいて、どこで止まっているかを調べているイメージ

この記事の要点

  • プラグインは「設定に書く」「ディスクに取り込む」「実行中に読み込む」の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-dirskills フォルダの中に plugin.json 付きで置いたマニフェストの defaultEnabled。設定で上書き可
@syncedclaude.ai のアカウントでオンにした既定でオン。設定に false で止める

この4つの名前は予約されているので、同じ名前の置き場は作れません。

無効にしたのに読み込まれる時

同じ ID の設定は、優先順位の高い方が勝ちます。低い方から並べると次の順です。

  1. --add-dir で追加したフォルダの設定(true だけ有効)
  2. user(ホームフォルダの設定。自分のすべてのプロジェクト)
  3. project(プロジェクトの .claude/settings.json。クローンした全員)
  4. local(プロジェクトの .claude/settings.local.json。自分だけ)
  5. flag(起動時の --settings)
  6. managed(管理設定。どれにも上書きされない)

自分の user 設定で false にしても、project 側が true なら読み込まれます。自分のパソコンだけ止めたい時は、local に false を書きます。 管理設定で true にされているものは、個人では止められません。

更新しても変わらない時

「is already at the latest version」と出る時は、Claude Code が計算したバージョンが同じです。作者が新しい変更を出しても、バージョンの値が変わらなければ、手元のファイルは入れ替わりません。更新を届けたい作者は、バージョンを上げるのが基本です。

古いバージョンのフォルダは、更新や削除から14日後に自動で片付けられます。実行中のセッションが古い版を使い続けられるようにするためです。

ディスク上の置き場所

置き場の既定は、ホームフォルダの .claude/plugins/ です。主なものを挙げます。

プラグインの外のファイルを指す設定(親フォルダへの参照や、外に向いたシンボリックリンク)は、読み込まれません。macOS と Linux では、パスにバックスラッシュが入っているだけで拒否されます。 パスは斜め線(/)で書きます。

見落としやすい5つの原因

調べる順番の例

  1. /plugin の Installed と Errors を開き、どの段階で止まったかを見る
  2. ID の末尾で出どころを確かめる
  3. 設定の優先順位の表で、どの設定が最後に勝っているかを探す
  4. ディスク上の installed_plugins.json に記録があるかを見る
  5. 直したら /reload-plugins を打ち、変わったかを確かめる

読み方に迷う時は、Claude にこのドキュメントを読ませて、自分の設定を診断させる方法もあります。

まとめ

  1. 宣言・取り込み・読み込みの3段階で、止まっている所を探す
  2. ID の @ より後ろで、出どころが分かる
  3. 同じ ID は優先順位の高い設定が勝つ。個人の無効化は local に書く
  4. 変更は /reload-plugins か再起動で初めて届く

出典:Plugin loading reference(公式ドキュメント)

永上裕之

ユニコスクール株式会社 代表取締役。AIエージェント専門のスクール&コミュニティを運営しています。

この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。

関連する記事