マルチエージェントAgent SDK でプラグインを読み込む方法
この記事の要点
- Agent SDK のプラグインは、手元のフォルダの場所を指定して読み込む。種類は local だけで、配布元から入れる時も先に手元に置く
- 読み込めたかは、始まりに届く init のメッセージの plugins の一覧で確かめる。場所が無くてもエラーにならず飛ばされる
- プラグインのスキルは「/プラグイン名:スキル名」で呼ぶ
活用例：部署ごとに決まった手順と道具をまとめて、社内の AI エージェントに配る
- 部署
- 情報システム・業務改善
- 使うもの
- Claude Agent SDK・プラグイン
- AIに任せる
- まとめられた手順に沿った作業と、決まった道具の呼び出し
- 人が決める
- プラグインに入れる手順と道具・どのエージェントに配るか
AI エージェントを社内で使い始めると、「同じスキルや設定を、いくつものエージェントで使い回したい」 という場面が出てきます。そのためのまとめ役が プラグイン です。スキル・サブエージェント・フック・MCP サーバーを1つのフォルダにまとめて、別のプロジェクトでも同じように使えます。
この記事では、公式ドキュメント「Plugins in the SDK」（2026年11月12日確認）にもとづいて、Claude Agent SDK でプラグインを読み込む方法を整理します。Claude Code でのプラグインそのものは Claude Codeのプラグインとは で解説しています。
結論：フォルダの場所を渡すだけで読み込める
Agent SDK では、プラグインのフォルダの場所を設定（plugins）に書くだけで読み込めます。 種類の指定は local の1つだけです。マーケットプレイスなど外にあるプラグインを使う時も、先に手元のフォルダに置いてから、その場所を渡します。
プラグインに入れられるものは次の4つです。
- スキル：場面に合わせて AI が自分から使う手順。直接呼ぶこともできる
- エージェント：決まった仕事を受け持つサブエージェント
- フック：道具を使う前後などに動く仕掛け
- MCP サーバー：外のサービスとつなぐ道具
場所の書き方で迷わないための3点
- プラグインの一番上のフォルダを指す：skills や agents、.claude-plugin といったフォルダが入っている、その1つ上を指定する
- 相対の書き方は作業フォルダ（cwd）から数える：「./plugins/my-plugin」のように書くと、作業フォルダからの場所になる
- ホームを表す「~」は使えない：SDK は「~/plugins」のような書き方を広げてくれない。フルの場所で書く
場所が間違っていても、SDK はエラーで止まりません。 そのプラグインを飛ばして作業を続けます。ここが一番つまずきやすい点です。
読み込めたかを確かめる
会話の始まりに届く init のメッセージに、読み込まれたプラグインの一覧（plugins）と、使えるスキルの一覧が入っています。 作業を始める前に、ここに自分のプラグインがあるかを見ておけば、読み込み漏れにすぐ気づけます。
一覧に無い時は、同じメッセージの plugin_errors に理由が入っていることがあります。init のメッセージの見方は Agent SDK の動く仕組み でも説明しています。
プラグインのスキルの呼び方
プラグインのスキルには、名前の前にプラグインの名前が付きます。 ほかのスキルと名前がぶつからないようにするためです。直接動かしたい時は、頼む文に次のように書きます。
- 書き方：「/プラグイン名:スキル名」
- 例：社内の報告書の型をまとめたプラグインなら「/report-kit:weekly」のような形
Claude Code の画面でマーケットプレイスから入れたプラグインも、入っているフォルダの場所を渡せば SDK から使えます。入った場所は、ホームの .claude の中の plugins フォルダです。スキルそのものの仕組みは Agent SDK でスキルを使う で解説しています。
動いている途中で直す・足す
| やりたいこと | TypeScript | Python |
|---|---|---|
| 直したプラグインを読み直す | reloadPlugins() を呼ぶ | 頼む文として /reload-plugins を送る |
| 別のプラグインを足す | reloadPlugins() に addPlugins を付けて呼ぶ（フルの場所） | 対応する方法は無い |
会話を始め直さずに、スキルや手順の変更を反映できます。 足したあとは、返ってくるプラグインの一覧に、その場所が入っているかを確かめます。
読み込まれない時の確かめ方
| 症状 | 確かめること |
|---|---|
| 一覧にプラグインが無い | 場所が一番上のフォルダか・フォルダが本当にあるか・読み取りの権限があるか |
| plugin.json があるのに読まれない | JSON の書き方が正しいか（カンマや括弧の抜け） |
| スキルが動かない | 「/プラグイン名:スキル名」で呼んでいるか |
| スキルが一覧に出ない | skills の中に、スキルごとのフォルダと SKILL.md があるか |
plugin.json（説明書きのファイル）は無くても動きます。無い時は、フォルダの並びからスキルなどを自動で見つけます。新しく作るなら、スキルは commands ではなく skills のフォルダに置くのが公式のすすめです。
仕事での使いどころ
- 部署ごとの道具箱：営業用・経理用など、部署で使う手順と道具を1つずつのプラグインにまとめる
- 試しと本番の切り替え：試しているプラグインだけを、試しのエージェントに読み込ませる
- 配る前の確認：Claude Code の画面で試したプラグインを、そのまま SDK のエージェントに渡す
よくある質問
マーケットプレイスの名前を書けば、SDK が取ってきてくれますか？
取ってきません。 SDK が受け付けるのは手元のフォルダの場所だけです。先にダウンロードして置いてから、その場所を書きます。プラグインの配り方は プラグインのマーケットプレイス で解説しています。
プラグインとスキルは、どう使い分けますか？
1つの手順ならスキル、いくつかの手順や道具をまとめて配るならプラグイン が目安です。プラグインの中身も、結局はスキルやフックなどの組み合わせです。
まとめ
- プラグインは 手元のフォルダの場所を渡して 読み込む。「~」は使えない
- 場所が間違っても止まらないので、init の plugins の一覧で確かめる
- スキルは 「/プラグイン名:スキル名」 で呼ぶ
出典
この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。
