/reload-pluginsで再起動なしにプラグインを反映する

/reload-pluginsは有効化中のプラグインを再読み込みし、保留中の変更をセッションを再起動せずに反映するコマンドです。読み込んだコンポーネントごとの件数を1行で報告し、読み込みエラーがあれば警告します。MCPツールの構成が変わってプロンプトキャッシュが無効になる場合は、警告して処理をスキップし、--forceを付けたときだけ実行します。

再起動なしで何が入れ替わるか

プラグインを開発・調整しているとき、SKILL.mdやhooksの設定ファイルを編集するたびにClaude Codeを再起動するのは手間がかかります。/reload-pluginsはその再起動を省くコマンドで、対象はプラグイン本体だけではありません。プラグイン・スキル・エージェント・hooks・プラグインのMCPサーバー・プラグインのLSPサーバーがまとめて再読み込みされます。

/reload-plugins

実行すると、次の形式のサマリーが1行で出ます。

Reloaded: N plugins · N skills · N agents · N hooks · N plugin MCP servers · N plugin LSP servers

読み込みに失敗したプラグインがあれば、サマリーにN errors during load. Run /plugin for details.が付きます。詳細は/pluginのErrorsタブで確認します。対話用のターミナルがないセッションでは、プラグインMCPサーバーの件数は省かれます。

スキルの件数には、commands/のエントリとSKILL.md形式のスキルの両方が含まれます。エージェントの件数は、プラグイン由来でないものも含めたセッション全体の数です。未導入の依存プラグインがあれば、インストールして再読み込みしたうえで(+ N dependencies: <names>) resolvedがサマリーの末尾に付きます。

通常実行と--forceの違い

止まったときの警告は、cli-referenceページによると次のような文面です。

This reload changes MCP tools (<server>) — your next message will re-read the whole conversation instead of using the cache. Run /reload-plugins --force to apply.

/reload-plugins --force

警告が出る範囲は意外に狭く、キャッシュの扱いはコンポーネントの種類で分かれます。プロンプトキャッシュの公式ページによれば、スキル・コマンド・エージェント・hooks・monitors・themesは、既存の会話の後ろに追記されるだけです。キャッシュは無効になりません。次のリクエストで追記分の料金は発生しますが、それ以前の履歴はキャッシュから読まれます。

無効になりうるのは、プラグインのMCPサーバーの追加・削除と、定義ジャンプや参照検索、型エラーの報告を担うLSPツールの増減です。LSPツールの扱いは、v2.1.243で最後のLSPプラグインを無効化してもLSPツールが残る不具合が直り、あわせて再読み込み前に警告する動作が加わりました。

有効・無効を切り替えたときも、MCPサーバーの接続・切断は変更が適用された時点で起こります。適用は、このコマンドの実行のほか、メニューを閉じたときの自動実行でも走ります。設定が変わっていないプラグインサーバーの接続はそのまま維持されるため、関係のないサーバーまで再接続される心配はありません。

実機で見たコマンドと出力(v2.1.287)

手元のv2.1.287で、モデルを呼ばない範囲を確認しました。claude --versionは2.1.287 (Claude Code)を返し、claude plugin --helpのコマンド一覧にはconfigure・details・disable・enable・eval・init・installなどが並びます。/reload-plugins自体はセッション内のスラッシュコマンドなので、シェルから叩くサブコマンドではありません。

開発用に使えるのが、claude本体のフラグ--plugin-dirです。ヘルプには次の説明が出ます。

--plugin-dir <path>   Load a plugin from a directory or .zip for this session only;
                      a folder of plugins loads each child
                      (repeatable: --plugin-dir A --plugin-dir B.zip)

claude plugin init <name>は、~/.claude/skills/<name>/にひな形を作ります。--with skillsを付けるとskills/example/SKILL.mdまで生成されました。実行後の出力には、/reload-pluginsが登場します。

✔ Created plugin "demo-rp" at ~/.claude/skills/demo-rp
  It will auto-load next session as demo-rp@skills-dir. Run /reload-plugins to load it now.

次のセッションで自動的に読み込まれるまでの間、いまのセッションに反映させるのがこのコマンドの役目です。claude plugin validate <path>はマニフェストと各スキル・エージェントのfrontmatterを検査するので、再読み込みの前にシェル側で通しておけます。ただし、プラグインのルートに置いたSKILL.mdは検査の対象外です。initが作るのはこのルートのSKILL.mdなので、ひな形の中身まではvalidateで確かめられません。

どの変更でこのコマンドが要るか

Claude Codeは、変更の経路によっては自分で再読み込みを走らせます。経路ごとに整理すると、手動で打つ必要が残るのは次の場面です。

「自動で実行される」場合でも、反映でキャッシュが無効になるなら変更は保留されます。メニューの閉じ方でも、フォルダの追加・削除でも、通知が出るので/reload-pluginsか--forceで明示的に進めます。この自動化が、v2.1.221・v2.1.268と段階的に広がってきた経緯は、後半のバージョン履歴で見ます。

開発ループでの回し方

プラグインを作るときは、次の流れで反復します。

動作確認の具体的な方法は、コンポーネントごとに違います。

• スキルは/plugin-name:skill-nameの形で直接呼び出し、応答を見ます。/pluginのInstalledタブでプラグインを探す手もあります
• エージェントは@の候補にプラグイン名:エージェント名で出るか、@agent-<plugin>:<name>で呼べるかを確かめます
• hooksはそのhookが反応するイベントを実際に起こします。たとえばファイル編集をClaudeに頼みます。マッチしたhookと終了コード・出力はデバッグログに残ります

マニフェストのパスが間違っていると、/pluginのErrorsタブにcommands path not foundのように出ます。パスを直して/reload-pluginsをやり直せば、再起動なしで復旧できます。

スキルだけ入れ替えたいときの別の選択肢

スキルやコマンドのディレクトリだけを読み直したいなら、/reload-skillsがあります。コマンド一覧では、ディスク上で追加・変更されたスキルを再スキャンして、利用可能な数と増減を報告するコマンドとして載っています。プラグイン全体を読み直す/reload-pluginsとの違いは、対象がスキルとコマンドのディレクトリに限られる点です。

件数の読み方で迷う点

旧い版では、skills/*/SKILL.mdで定義したスキルがサマリーの件数に入らず、「0 skills」と出る不具合がありました。v2.1.246で修正され、現在はcommands/とSKILL.mdの両方が数えられます。古いバージョンのClaude Codeを使う環境では、変更が反映されていても0件と表示されることがあります。

ターミナルがない環境での挙動

v2.1.260で、-pの非対話モード・Agent SDK・デスクトップアプリでも/reload-pluginsが使えるようになりました。条件は、セッションに自分で入力することです。Remote ControlやSlack経由で届いたコマンドは対象外です。次のメッセージが返り、何も再読み込みされません。

/reload-plugins isn't available over a remote connection in this session.

この種のセッションの再読み込みでは、プラグインMCPサーバーの接続・切断は行われません。MCPの変更は次のセッションで有効になるので、途中でキャッシュを失う心配もありません。

コマンド一覧の説明でも、-p・Agent SDK・デスクトップアプリでは直接入力にだけ働き、プラグインMCPサーバーの変更は反映しないとあります。Remote Controlからの実行を拒否するのは、この種のセッションだけです。対話ターミナルのセッションでは、v2.1.110以降Remote Control(モバイル/Web)からも実行できます。

想定外に感じやすい場面

• アンインストールしたのにスキルが残って見える: 無効化したプラグインのスキルは、/pluginメニューで操作したならメニューを閉じた時点で消えます。別ターミナルのclaude pluginで操作したなら、/reload-pluginsの実行か再起動を経て一覧から消えます。
• 自作版でなくインストール版を触っていた: --plugin-dirのプラグインとインストール済みプラグインが同名だと、そのセッションではローカル版が使われます。claude --plugin-dir ./my-plugin plugin listで、<name>@inlineとして読み込まれているかを確認できます。claude plugin disable <name>@inlineで無効化した場合や、管理設定がそのプラグイン名をロックしている場合は、インストール済みの方が読み込まれます。管理者が承認した提供元からしか読み込めない環境では、--plugin-dirで起動したときにその旨のエラーが出ます。
• 依存プラグインが足りない: /reload-pluginsは、追加済みのマーケットプレイスにある未導入の依存プラグインを自動インストールします。足りないものが追加済みのマーケットプレイスにも見つからないとき、手動対応が要ります。

このコマンドの役割はどう変わってきたか

/plugin installで入れた直後はすぐ使えることが多いのに、/reload-pluginsが独立したコマンドのまま残っているのはなぜか。バージョン履歴をたどると、「自動化できる経路を増やしつつ、キャッシュに響く変更だけは明示させる」方向に整理されてきたと分かります。

プラグイン配布の初期は再起動が唯一の手段でしたが、いまは自動反映・明示コマンド・再起動の3つがあり、影響範囲で選べます。コマンドの性格は「変更を検知して反映する」ことから、「反映を明示して、コストに響くときは止める」ことに寄ってきました。

よくある質問

プラグインを1つだけ再読み込みできますか

/reload-pluginsは有効化中のプラグインをまとめて再読み込みするコマンドです。コマンド一覧の書式は/reload-plugins [--force]だけで、対象を絞る引数は載っていません。個別に切り分けたい場合は、一時的に他のプラグインを無効化してから実行する方法があります。

/mcpとの違いは何ですか

/mcpは個々のサーバーの接続状態を確認・再接続するコマンドです。サーバー追加やスコープの扱いはClaude Code MCP設定ガイドにあります。/reload-pluginsはプラグイン側の変更をまとめて反映する起点で、結果としてプラグインMCPサーバーの接続・切断が起こります。

コマンドで生成するタイプのプラグインにも効きますか

プラグインの内容をコマンドの実行結果から生成するcommandソースにも効きます。有効なプラグインのインストール済みバージョンがキャッシュに無ければ、そのコマンドが再実行されます。起動時と同じ扱いです。

まとめ

プラグインを自作するなら、--plugin-dirで起動しておき、手で打つのは編集のあとと、警告が出て--forceを付けるときだけと決めておくと迷いません。詳しい配布・自作の手順はClaude Codeプラグイン完全ガイドにあります。コマンド全体の見取り図はClaude Codeスラッシュコマンド一覧を参照してください。追加当時の背景はClaude Code v2.1.69にあります。