Claude Codeの仕組み講座（講師のためのエンジニア水準）

区分3 拡張の仕組み★★

No.12 サブエージェントとプラグイン

サブエージェントは「別の机で仕事をして、要約だけ持ち帰る助っ人」で、プラグインは「ここまでの仕組みを1つの箱にまとめて配る入れ物」です。2つとも、これまでの単元の部品の組み合わせなので、まず全体像を押さえてください。
目次
  1. 第0章 前提知識
  2. 第1章 サブエージェントの動き
  3. 第2章 定義ファイルの書き方
  4. 第3章 プラグイン
  5. 確認問題

第0章 前提知識

① サブエージェント　：別の机で動く助っ人

AIが仕事をする「机」は、コンテキスト（AIが一度に見渡せる範囲）のことです。長い調べ物をすると、検索結果やログで机が埋まります。サブエージェントは、そのための助っ人です。

専用の別の机（別のコンテキスト）で仕事をして、終わったら要約だけをメインの会話へ返します。

事務所でいえば、自分の机で作業している時に、「資料の下調べは隣の席の担当者に頼む」ようなものです。担当者は自分の机で何十冊も資料を広げますが、あなたの机に届くのは、A4一枚の報告書だけです。

② プラグイン　：機能をまとめて配る箱

スキル・フック・サブエージェント・MCPは、どれも単独で使えます。プラグインは、それらを1つの箱にまとめて、そのまま配る仕組みです。

事務所でいえば、「新入社員セット」です。マニュアル（スキル）と、入退室のチャイム（フック）と、助っ人の連絡先（サブエージェント）と、取引先の窓口の設定（MCP）を、1つの箱に詰めて渡します。

第1章 サブエージェントの動き

サブエージェントについて、渡る物・返る物・任せ方の順に見ます。

① 何が渡り、何が渡らないか 必ず覚える

サブエージェントは、メインの会話とは別の、まっさらな机から始まります。公式に書かれている内容は次の通りです。

机に置かれる 置かれない
サブエージェント自身の指示（定義ファイル） メインの会話の履歴
メインのAIが書いた依頼文 すでに読んだファイル
作業場の CLAUDE.md（No.08） メインで呼んだスキルの本文
指定されたスキルの本文 メインの記憶（auto memory）

つまり、メインの会話で説明したことは、依頼文に書かない限り、サブエージェントには伝わりません。 依頼文が、助っ人にとっての「引き継ぎ書の全部」になります。

なお、Claude Code が標準で持つ「Explore」（探索用）と「Plan」（計画用）は、CLAUDE.md を読まず、読み取り専用で動きます。

② 結果は要約だけが返る 必ず覚える

サブエージェントが終わると、メインの会話へ返るのは要約だけです。中でやった検索の山は、メインの机に残りません。作業の記録は別のファイルに保存され、メインの会話が要約されても残ります。

これが、サブエージェントの最大の利点です。ほかに、使える道具を絞れること、安いモデルに任せて費用を抑えられることがあります。

③ いつ任せるかは、説明文で決まる 必ず覚える

メインのAIは、あなたの依頼と、各サブエージェントの description（説明文）を見比べて、任せるかを決めます。スキル（No.09）と同じ考え方です。名指しで任せる方法は、次の3つがあります。

並べて動かすこともできます。公式には、初期値で同時に20件までと書かれていて、超えると新しい呼び出しは失敗します。サブエージェントがさらにサブエージェントを呼ぶことも可能で、初期値ではメインから数えて3層までです。どちらの数字も環境変数（パソコンに持たせる設定値）で変えられ、過去の版では初期値が違っていたので、古い解説の数字は当てになりません。

○ 受講生によく聞かれる質問：「サブエージェントに頼んだのに、前に話したことを知らないです」
→ 答え方：別の机で始まるので、メインの会話は見えません。依頼文に、必要な背景と範囲を全部書きます
○ 受講生によく聞かれる質問：「スキルとサブエージェントの違いは何ですか」
→ 答え方：スキル（No.09）は「メインの机に手順書を出す」仕組みで、サブエージェントは「別の机に仕事ごと任せる」仕組みです。机を汚したくない長い調べ物はサブエージェントに向きます
○ 講義で使える図のたとえ：スキル＝自分の机に出す業務マニュアル、サブエージェント＝別の部屋の担当者に頼む下調べです。
○ 関係する単元：No.09 スキル、No.05 コンテキストウィンドウの中身

第2章 定義ファイルの書き方

① 1ファイル1人 必ず覚える

サブエージェントは、Markdown ファイル1つで1人です。先頭の設定欄（frontmatter）に名前や説明を書き、その下の本文が、そのサブエージェントへの指示になります。

---
name: code-reviewer
description: コードをレビューする。変更の後に使う
tools: Read, Glob, Grep
model: sonnet
---

あなたはコードレビューの担当です。…（以下、指示）

サブエージェントには、Claude Code 本体の長い指示は渡らず、この本文と環境の情報、それに作業場の CLAUDE.md が渡ります。

② 設定欄の項目 必ず覚える

公式の主な項目です。必須は name と description だけです。

項目 役割
name 名前。: は使えない（プラグインの区切りに使うため）
description いつ任せるかの説明。AIが任せる判断に使う
tools 使える道具の許可リスト。省略すると、使える道具を全部引き継ぐ
disallowedTools 使わせない道具の一覧
model sonnet・opus・haiku・inherit（メインと同じ）など
permissionMode 許可モード（No.13）
skills 起動時に本文を丸ごと読み込ませるスキル
mcpServers そのサブエージェントだけで使うMCPのサーバー
hooks そのサブエージェントが動く間だけ有効なフック
memory そのサブエージェント専用の記憶を持たせる（範囲は user・project・local から選ぶ）
isolation worktree にすると、git の worktree（同じ git 管理フォルダの一時的な作業コピー）の中で動く。元の作業場を汚さない

書き間違えた項目は、エラーにならず無視されます。maxTurns のように複数語の項目は camelCase（語の頭を大文字にする書き方）で、一字違っても効きません。

③ 置き場所と優先順位 さらっと

同じ名前が複数あるとき、強い順は次の通りです。機能ごとの強さの比較は No.15 にまとめます。

  1. 組織の管理設定
  2. 起動時の --agents 指定（その会話だけ）
  3. 作業場の .claude/agents/
  4. 自分の ~/.claude/agents/
  5. プラグインの agents/

「作業場」は、いま開いているフォルダ（公式では「プロジェクト」）です。

④ 手元の実物 さらっと

あなたの環境では、作業場の .claude/agents/hands.md が、まさに1人のサブエージェントです。先頭の設定欄は、name: hands・description（「仕様が決まった作業や修正を任せる」など）・model: sonnet の3つで、tools は書かれていないので使える道具を全部引き継ぎます。この講座を書く作業も、この「手」に任せています。メインの会話（頭）が決めた範囲だけを、別の机で実行して、結果を返す形です。

第3章 プラグイン

プラグインについて、箱の中身・名前の付き方・入れる前の注意の順に見ます。

① 箱の中身 必ず覚える

プラグインは、決まった形のフォルダです。フォルダの中身が、そのまま機能になります。

my-plugin/
├ .claude-plugin/
│  └ plugin.json     名前など（箱の名札）
├ skills/
│  └ review/SKILL.md スキル
├ agents/
│  └ reviewer.md     サブエージェント
├ hooks/
│  └ hooks.json      フック
├ .mcp.json          MCPのサーバー
└ bin/               プラグインが配る実行ファイル

名札の plugin.json で必須なのは name だけです。plugin.json 以外は、.claude-plugin/ の中ではなく、箱の一番上に置きます。ほかにも、monitors（会話の裏で動き続けるコマンドで、出力を通知として受け取る部品。公式では試験的な扱い）などを入れられます。

② 名前の付き方 必ず覚える

プラグインの機能は、名前の前にプラグイン名が付きます。

名前が長くなる代わりに、別のプラグインと同じ名前でもぶつかりません。

プラグインのサブエージェントには、制限もあります。hooks・mcpServers・permissionMode は無視されます。 公式では、安全のためとされています。フックやMCPを足したいときは、プラグイン自体の hooks/hooks.json と .mcp.json に書きます。

③ 入れる前に知っておくこと 必ず覚える

プラグインは、入れた時点で、毎回の会話に影響します。

最後が特に大事です。入れたプラグインは、あなたのパソコンで、あなたの権限で命令を動かせます。公式も、入れる前に中身を確認することを勧めています。

配布元は、Anthropic が出している「公式」の一覧（パートナーや外部の作者の物も含む）、外部の作者が Anthropic に提出した物を並べた「コミュニティ」の一覧、それ以外の作者が自分で運営する一覧（第三者）に分かれます。公式には、第三者の一覧は Anthropic が審査しないと書かれています。

入れる場所（範囲）は3つから選べます。

あなたの環境では、freee-mcp などの4つのプラグインが有効です。freee の道具が mcp__plugin_freee-mcp_freee__… という名前で見えているのは、②の名前の付き方そのままです。

○ 受講生によく聞かれる質問：「プラグインとスキル、何が違うんですか」
→ 答え方：スキルは機能の1つで、プラグインはスキル・フック・サブエージェント・MCPを1つにまとめて配る箱です。自分だけで使うなら、プラグインにしなくても、スキルのフォルダを置けば使えます
○ 受講生によく聞かれる質問：「プラグインを入れたら、会話が重くなりました」
→ 答え方：スキルやサブエージェントの説明文が、毎回の机に置かれているからです。使わないプラグインは、アンインストールしなくても無効にできます
○ 講義で使える図のたとえ：プラグインは、新入社員に渡す「入社セット」です。マニュアル・チャイムの設定・助っ人の連絡先・取引先の窓口が、1箱に入っています。
○ 関係する単元：No.09 スキル、No.10 フック、No.11 MCP

サブエージェント＝別の机で動き、要約だけ返す。伝えたい事は依頼文に全部書く。プラグイン＝スキル・フック・サブエージェント・MCPを配る箱。名前にプラグイン名が付き、あなたの権限で動くので中身を確認して入れる。機能ごとの強さの比較は No.15。

確認問題

問1　サブエージェントに調べ物を頼みました。メインの会話に戻ってくるものは？

問2　メインの会話で長く説明した背景を、サブエージェントが知らずに作業してしまいました。仕組みから見た原因は？

問3　自分の作業場だけで使うサブエージェントの定義ファイルは、どこに置く？

問4　プラグインの中のサブエージェント定義に `permissionMode` を書きました。どうなりますか？

出典：Claude Code 公式ドキュメント「Create custom subagents」（https://code.claude.com/docs/en/sub-agents）／「Plugins overview」（https://code.claude.com/docs/en/plugins/overview）／「Add components to a plugin」（https://code.claude.com/docs/en/plugins/components）／「Extend Claude Code」（https://code.claude.com/docs/en/features-overview）／「Plugins reference」（https://code.claude.com/docs/en/plugins-reference）／「Install and manage plugins」（https://code.claude.com/docs/en/plugins/install）／「Anthropic's marketplaces」（https://code.claude.com/docs/en/plugins/anthropic-marketplaces）／手元で動かして確かめた .claude/agents/hands.md と ~/.claude/settings.json の実物。数字は2026年10月時点の公式による

← 前へ次へ →