Claude Codeのplugin-dirを安全に更新する

結論：plugin-dirは子フォルダをまとめて読み込み、実行中の追加・削除も検出する

一次情報はClaude Code公式changelogの2.1.265、および公式Pluginsガイド、Plugins referenceです。changelogはフォルダの子要素とmanifest、実行中の追加・削除を説明し、Plugins文書は構成要素と配布単位を説明します。バージョンを確認せずに古いインストール方法を一律適用しないことが出発点です。

plugin-dirと他の配布方法を比較する

方法	向く場面	確認すべき境界
--plugin-dir	ローカル検証や複数プラグインの一括読み込み	子フォルダ、manifest、追加・削除の反映
市場・リポジトリ経由	配布元とバージョンを台帳で管理する	取得元、更新承認、依存関係
project-scoped plugins	リポジトリ単位で同じ開発環境を再現する	worktree、branch、レビュー範囲
個別の手動指定	一件だけ隔離して調査する	端末差分と指定漏れ

この機能の価値は「全部を自動で許可すること」ではなく、読み込み対象を一つのフォルダへ集約し、差分を検査できることです。子フォルダが増えると、plugin、agent、skill、hookなどの影響も増えます。読み込みに成功したプラグインを、そのまま本番相当の作業へ使う運用は避けます。

また、実行中の追加・削除は便利ですが、同じフォルダを複数の担当者が書き換えると、sessionの再現性が崩れます。作業中に変更する共有ディレクトリではなく、変更申請済みのimmutableなリリースディレクトリ、または検証用の個人コピーを使い分けます。

導入手順：小さなプラグインから7ステップで検証する

1. claude --versionを実行し、2.1.265以降か、確認時刻と端末を記録します。
2. 配布対象を一つの用途へ絞り、プラグイン名、所有者、想定する入力と出力を台帳へ書きます。
3. 指定フォルダ直下に、manifest付きの子フォルダだけを置き、秘密情報、個人設定、未審査の実行ファイルを除外します。
4. manifestの名前、説明、version、提供するcommand・agent・skill・hookを読み、権限と外部通信の有無を確認します。
5. 検証用sessionを起動し、--plugin-dirでフォルダを指定した後、実際に読み込まれた一覧とエラーを記録します。
6. 子フォルダを一つ追加・削除し、実行中に反映されたか、意図しないpluginが残っていないかを確認します。
7. テスト、rollback、承認者、配布対象の3点を記録してから、限定したチームへリリースします。

確認は「読み込めたか」だけで終わらせません。pluginが呼び出すshell、HTTP、MCP、ファイルアクセスが業務の許可範囲に収まるかを見ます。manifestの説明が短くても、実際のhookや依存先まで確認してください。更新前後で、同じ入力に対する出力、ログ、所要時間を比較すると、動いたが挙動が変わったケースを見つけやすくなります。

チーム運用の判断：動的検出と承認を分ける

チーム共有では、動的検出を便利さのために使い、承認を別工程に残します。例えば、開発者は個人のstagingフォルダで追加・削除を試し、管理者はmanifestと差分をレビューし、承認済みのリリースフォルダだけをチームへ配ります。session開始後に変更されたpluginは、いつ、誰が、なぜ追加したかをログへ残します。

既存のSkillsの同期・出所確認はskillの正本と優先順位、権限設定ガイドは実行可否、managedMcpServers運用は組織MCPの配布を扱います。plugin-dirの記事では、それらを一つの配布フォルダへ置く前の検査と更新境界に意図を限定します。

rollbackはフォルダを消すだけにしません。読み込み前のmanifest一覧、plugin version、設定scope、sessionの作業対象を保存し、問題が出たら最後に承認されたフォルダへ戻します。未追跡の追加・削除をsession中に行う場合も、担当者以外が同じパスへ書き込まないルールを設けます。更新を急ぐ時ほど、変更を一件ずつ切り出し、どのpluginが原因かを追跡できる状態を保ちます。

配布後は、利用者が見つけた違和感を個別の端末修正で終わらせず、正本の変更要求へ戻します。そうすると、便利な動的検出を保ちながら、どのversionを誰が承認したかを追跡できます。

チェックリスト：plugin-dirを配布する前に

Claude Codeのversionを確認したか／plugin-dirの所有者を決めたか／子フォルダごとにmanifestがあるか／command・agent・skill・hookを列挙したか／秘密情報が含まれていないか／外部通信とファイル範囲を確認したか／追加・削除を検証したか／stagingと本番相当を分けたか／versionと承認者を台帳へ残したか／前のリリースへ戻せるか、を確認します。

読み込まれない時は、version、指定パス、子フォルダの深さ、manifestの形式、権限の順に切り分けます。読み込まれたのにcommandが使えない場合は、manifestの対象とsessionの再読み込み条件を確認し、共有フォルダをその場で編集して解決しないでください。まず検証用コピーへ戻します。エラー文、実行したcommand、フォルダのhashを一緒に残すと、担当者が変わっても同じ切り分けを再開できます。

よくある質問

子フォルダなら何でもpluginになりますか？

公式changelogは、指定フォルダの子フォルダにmanifestがある場合に読み込む仕様を示しています。名前だけでなくmanifestと構成要素を確認し、不要なファイルを同居させないでください。

実行中の追加・削除はリリースにも使えますか？

検出できることと、無承認で配布してよいことは別です。stagingで便利に使い、チーム配布では変更履歴、テスト、承認、rollbackを残します。

plugin-dirを使えば権限確認は不要ですか？

不要にはなりません。pluginのcommand、hook、MCP、ファイルアクセスは別途確認し、Claude Codeの権限や組織ポリシーと組み合わせて判断します。

公式情報と無料診断

plugin-dirの仕様はClaude Code公式changelog、pluginの構成は公式PluginsガイドとPlugins referenceで公開直前に確認します。Miraigentの無料診断では、プラグインの正本、承認、権限、更新、rollbackを業務フローへ整理できます。