--plugin-dir（プラグインディレクトリ）

自分でプラグインを開発中で、マーケットプレイスを介さずローカルから動作確認したい人向け

Claude Code は通常、プラグインを「マーケットプレイス」という配布所からインストールして使います。ただ自分でプラグインを書いている最中だと、毎回インストールし直すのは現実的ではありません。--plugin-dir はその場面用に作られた起動時の指定です。フォルダのありか（例: ./my-first-plugin）を渡すと、そのフォルダの中身をプラグインとしてその回のセッションだけ読み込んでくれます。

言い換えると、開発中の作りかけプラグインを「インストールせずに、一時的にだけ動かしてみる」モードです。終了すれば次の起動では消えていて、設定にゴミが残りません。

噛み砕くと

これは、開発中のアプリを「ストアに登録せずに、自分のスマホに直接コピーして1回だけ動かしてみる」感覚に近いです。./my-first-plugin という自作プラグインのフォルダを、ストアを経由せず Claude Code に手渡しで読ませる、というイメージです。

本番に出す前の最後の動作確認、または公開予定がなくて自分専用にだけ使いたいプラグインを動かす場面で重宝します。「これ一発勝負で試したいだけなんだよ」と言いたい時の出口、と覚えておくとしっくりきます。

大事な前提：フォルダの中に「これはプラグインです」と名乗る1枚が要る

適当なフォルダを渡しても読み込んでくれません。指定先のフォルダの中に .claude-plugin/plugin.json という1枚の設定ファイルが必要です。これが「私はプラグインです、名前は○○です」という名札の役割をします。

名札がないと Claude Code は「これプラグインじゃないよ」と判断して、何も読み込まずに普通に起動します。エラーで止まるわけではないので、気づきにくい落とし穴です。

「自分が書いた ./my-first-plugin を読み込ませて動作確認する」で実際の手順を見る

挨拶を返してくれる小さな skill を1つだけ持った my-first-plugin を作って、それを起動時に読み込ませるところまで一気通貫でやります。

ステップ1: プラグイン用のフォルダと名札を用意する

適当な作業フォルダの中で、次の2つを作ります。

$ mkdir -p my-first-plugin/.claude-plugin
$ mkdir -p my-first-plugin/skills/hello

次に名札ファイル my-first-plugin/.claude-plugin/plugin.json を作って、こう書きます。

{
  "name": "my-first-plugin",
  "description": "挨拶を返す練習用プラグイン",
  "version": "1.0.0"
}

ステップ2: 中身の skill を1つだけ置く

my-first-plugin/skills/hello/SKILL.md を作って、こう書きます。

---
description: 利用者に挨拶を返す
---

ユーザーに温かい挨拶を返して、今日はどんな手伝いができるかを尋ねてください。

これで「/my-first-plugin:hello と呼ばれたら、挨拶を返す」という skill が1つできました。

ステップ3: --plugin-dir をつけて Claude Code を起動する

ターミナルでこう叩きます。

$ claude --plugin-dir ./my-first-plugin

これで起動した Claude Code セッションの中だけ、my-first-plugin が読み込まれた状態になります。マーケットプレイスにインストールしたわけではないので、終了したら次回起動では消えています。

ステップ4: 読み込まれているか確認する

起動した Claude Code の中で /help を打つと、利用可能な skill 一覧にプラグインの名前空間つきで /my-first-plugin:hello が出てくるはずです。試しに呼んでみます。

/my-first-plugin:hello

挨拶が返ってくれば成功です。

ステップ5: ファイルを書き換えたら /reload-plugins で反映する

ここで初心者がやりがちな勘違いがあります。SKILL.md を書き換えるたびに Claude Code を一度終了して再起動する人が多いのですが、その必要はありません。セッションを続けたまま、次の1行を打つだけで読み直してくれます。

/reload-plugins

これで skills、agents、hooks、プラグイン由来の MCP サーバー、LSP サーバー全部が読み直されます。試行錯誤のサイクルが一気に速くなります。

ステップ6: セッションを終了すると消える

Claude Code を終了して、次回 claude だけで起動すると、my-first-plugin はもう読み込まれていません。インストールではなく「その回限り」だからです。次もまた使いたければ、また --plugin-dir ./my-first-plugin をつけて起動する必要があります。

常用したくなった段階で初めて、マーケットプレイス経由のインストールを検討する流れです。

つまり --plugin-dir は何をしてくれるのか

• やってくれる: 渡したフォルダ（または .zip ファイル）を、その回の Claude Code セッションだけプラグインとして読み込む
• やってくれる: 同じ名前のプラグインがすでにマーケットプレイス経由で入っていても、ローカル側を優先してくれる（開発中の差分を試したい時に便利）
• やってくれない: プラグインの「インストール」はしない。次回起動のためには再度 --plugin-dir をつける必要がある
• やってくれない: 設定で強制的にオン/オフにされているプラグインを --plugin-dir で上書きすることはできない
• 意味が薄い場面: マーケットプレイス経由で常用したいプラグインを毎回 --plugin-dir で起動する運用。「セッション限定」の利点が活きないので、素直にインストールした方が楽

使いどころ3シナリオ（具体題材で再現）

シナリオ1: 自分専用の「日報整形プラグイン」を開発中

毎日の日報を Markdown でまとめる skill を自作中の人を想定します。~/dev/daily-report-plugin/.claude-plugin/plugin.json と skills/format-daily/SKILL.md を書きながら、3〜4時間に1回の頻度でプロンプトを練り直している状況です。

この場合、マーケットプレイスに置く必要はゼロです。仕事を始めるたびに claude --plugin-dir ~/dev/daily-report-plugin で起動して、/daily-report-plugin:format-daily を呼ぶ。プロンプトを直したら /reload-plugins。これだけで1日が回ります。

シナリオ2: チーム配布前の最終動作確認

「コードレビュー観点をチェックする skill」をチームに配布する直前のシーンです。マーケットプレイスにアップロードする前に、自分の環境で claude --plugin-dir ./team-review-plugin で起動して、想定したパターンで本当に動くかを確かめます。

このとき、すでに前バージョンが入っているなら --plugin-dir 側が優先されるので、「前バージョンを一旦アンインストール」みたいな手間が要りません。アップ予定の最新フォルダだけ動作確認できます。

シナリオ3: GitHub で見つけた他人のプラグインを試食する

GitHub で「これ便利そう」というプラグインを見つけた時、いきなりマーケットプレイス経由でインストールするのは少し怖い、という場面です。

その場合は git clone で手元に落としてきて、claude --plugin-dir ./cloned-plugin で1回だけ動かして中身を確認できます。気に入らなければセッションを終了するだけで、システムには何も残りません。試食のあとちゃんと使いたくなったら、その時マーケットプレイス経由でインストールに移行します。

初心者が踏みやすい落とし穴

• 複数プラグインを --plugin-dir A B と並べて書いてしまう。これは無効です。1回ぶんの --plugin-dir につき1つのフォルダのありかしか取れません。複数読ませたい時は --plugin-dir ./plugin-one --plugin-dir ./plugin-two と、その都度書き直します。よく似た --plugin-url はクオートで囲んだ一括渡しにも対応しているので、混同しがちです
• .zip を渡したらエラーが出る。--plugin-dir ./my-plugin.zip の .zip 対応は Claude Code v2.1.128 以降です。それより古いと「これは未対応の形式」と弾かれます。バージョン確認は claude --version で
• マーケットプレイス版がすでに入っていることに気づかず開発版で動かしている。同名プラグインが入っているとローカル版が優先されるので、想定通りに動いているように見えても実は別のコピーを叩いている、という事故が起きます。/help で出てくる skill 一覧の出どころを意識しましょう
• 会社や組織の設定で強制的にオン/オフされているプラグインを --plugin-dir で上書きしようとする。これは効きません。managed settings で固定されているものは、--plugin-dir 側より優先されます
• ファイルを直すたびに Claude Code を再起動している。/reload-plugins で十分です。再起動より3桁くらい速いので、これを覚えるだけで開発体験が劇的に変わります
• プラグインのフォルダ内から外を指す symlink を貼って参照させようとする。--plugin-dir でロードした場合、プラグインのフォルダ内に解決される symlink だけ生き残り、外を指すものは無視されます。共通部品を symlink で引っ張る設計は通用しません
• 毎回 --plugin-dir をつけて常用している。これは本来の使い方ではありません。常用する段階に来たら、マーケットプレイス経由でインストールに移行した方がコマンドラインがスッキリします。--plugin-dir は「開発中」または「お試し」専用、と割り切ると迷いません
• claude agents や /bg でも --plugin-dir が効くのは新しめのバージョンだけ。claude agents --plugin-dir は v2.1.126 以降、/bg 経由での継承は v2.1.143 以降です。それより古い環境だと「指定したはずなのに反映されない」現象が起きます

書き方

claude --plugin-dir <フォルダのありか または .zipファイル>
# 複数読ませたい時は --plugin-dir を繰り返す
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

やってみるとこうなる

入力

claude --plugin-dir ./my-first-plugin

出力例

（Claude Code が起動し、my-first-plugin が読み込まれた状態のセッションが始まる。/help で /my-first-plugin:hello が一覧に表示される。セッションを終了すると次回起動時には消えている）

関連項目

• claude plugin（クロード・プラグイン）
• --mcp-config（エムシーピー・コンフィグ）
• --strict-mcp-config（ストリクト・エムシーピー・コンフィグ）
• --add-dir（アドディレクトリ）
• --bare（ベア）

公式ドキュメント

https://code.claude.com/docs/en/cli-reference