Guides defining Claude Code SubAgents in agents/*.md files with YAML frontmatter, role-based tool selection, model choices, 3-Phase structure, and context passing best practices.
npx claudepluginhub sean-sunagaku/claude-code-plugin --plugin subagent-best-practicesThis skill uses the workspace's default tool permissions.
Claude Code の `agents/*.md` ファイルで SubAgent を正しく定義するための実践ガイド。
Guides creating, configuring, and orchestrating Claude Code subagents and Task tool. Covers prompts, tools, models, file structures, and multi-agent workflows.
Guides Claude Code subagent development: agent files, YAML frontmatter, tool/model config, lifecycle/resumption, CLI/SDK usage, priority, built-in agents, troubleshooting via docs delegation.
Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.
Share bugs, ideas, or general feedback.
Claude Code の agents/*.md ファイルで SubAgent を正しく定義するための実践ガイド。
チーム設計・通信プロトコル・タスク管理は agent-team-guide スキルを参照。
このスキルは「個別 SubAgent の定義品質」に特化している。
SubAgent は agents/*.md ファイルで定義された特化型エージェント。
my-skill/
└── agents/
├── researcher.md ← SubAgent 定義
├── writer.md
└── context-manager.md
Claude Code は agents/*.md を自動認識し、subagent_type: "my-skill:researcher" で起動できる。
SubAgent は親のコンテキストを持たない。起動時のプロンプトが唯一の情報源。
| 値 | 動作 |
|---|---|
"my-skill:researcher" | agents/researcher.md を読んで起動 |
"general-purpose" | agents/*.md を使わず、プロンプトでロールを定義 |
"Explore" | コードベース探索に特化した組み込みタイプ |
---
name: researcher # 必須: kebab-case の識別名
description: > # 必須: 役割の1〜3行説明
Market research specialist.
Part of the app-naming team.
tools: Read, Grep, Glob, WebSearch, # 推奨: 許可ツールのリスト
SendMessage, TaskList, TaskGet, TaskUpdate
model: sonnet # 推奨: haiku / sonnet / opus / inherit
---
subagent_type: "my-skill:{name}" の {name} 部分に対応context-manager, bias-reviewer）subagent_type 指定時のマッチングに使われる# 自動委譲を意図した description の例
description: >
Expert code review specialist. Use proactively after writing or modifying code.
Triggers: "review", "check", "レビュー"
| 役割タイプ | 推奨 tools |
|---|---|
| 調査系 | Read, Grep, Glob, WebSearch, SendMessage, TaskList, TaskGet, TaskUpdate |
| 執筆系 | Read, Grep, Glob, Write, Edit, SendMessage, TaskList, TaskGet, TaskUpdate |
| 実行系 | Read, Grep, Glob, Write, Edit, Bash, SendMessage, TaskList, TaskGet, TaskUpdate |
| 分析系（読み取り専用） | Read, Grep, Glob, SendMessage, TaskList, TaskGet, TaskUpdate |
| コンテキスト管理専任 | Read, Write, Edit, SendMessage, TaskList, TaskGet, TaskUpdate |
全エージェント必須: SendMessage, TaskList, TaskGet, TaskUpdate（チーム通信・タスク管理に必須）
重要制限: MCP ツール（mcp__pencil__* 等）は agents/*.md からアクセスできない。
MCP が必要な場合は subagent_type: "general-purpose" でプロンプト内に役割を定義する。
| 値 | モデル | 適した役割 |
|---|---|---|
haiku | claude-haiku-4-5 | 記録・転記・単純ファイル操作（context-manager 等） |
sonnet | claude-sonnet-4-6 | 通常の調査・執筆・分析（デフォルト推奨） |
opus | claude-opus-4-6 | 複雑な設計判断・最終品質レビュー |
inherit | 親セッションと同じ | チーム全体で統一モデルを使いたい場合 |
全エージェントに 初期化 → フィードバック対応 → 最終化 の3フェーズ構造を持たせる。
### Phase 1: 初期化
1. TaskList → TaskGet(blockedBy確認) → TaskUpdate(in_progress)
2. 初期作業を実行 → 関連エージェントに SendMessage
### Phase 2: フィードバック対応
- 実質的なフィードバックのみ返信（ACK 不要）
- ブロック中でも他エージェントの成果物にフィードバック可
### Phase 3: 最終化
1. TaskUpdate(status: "completed") ← 先にブロック解除
2. → team-lead: タスク #N 完了。{成果物パス}
## コミュニケーションルール
- ACK 返信不要
- 2人以上から反応があれば次のフェーズに進む（全員を待たない）
各 Phase の詳細実装パターンは references/phase-design.md を参照。
# 推奨: tools で許可リストを明示（意図が明確）
tools: Read, Grep, Glob, WebSearch, SendMessage, TaskList, TaskGet, TaskUpdate
# 用途: 一部のツールだけ禁止したい場合
disallowedTools:
- Bash
- Write
| 問題 | 原因 | 対策 |
|---|---|---|
| WebSearch が使えない | tools に未記載 | 調査系には明示的に追加 |
| ファイル書き込みができない | Write/Edit が未記載 | 執筆系には Write, Edit を追加 |
| タスクが見つからない | TaskList が未記載 | 全エージェントに必須 |
| 他エージェントに通信できない | SendMessage が未記載 | 全エージェントに必須 |
| コスト過多 | 全員 opus | 役割に合わせて haiku/sonnet を使う |
詳細は references/tool-selection.md を参照。
SubAgent は親のコンテキストを持たない。起動時のプロンプトが唯一の情報源。 以下を全て含めること（省略すると SubAgent が必要な情報を持てない）:
Task(
subagent_type: "my-skill:researcher",
name: "researcher",
team_name: "my-skill",
mode: "bypassPermissions",
run_in_background: true,
prompt: """
あなたは my-skill チームの researcher です。
## プロダクト情報 ← ユーザーからヒアリングした全情報（省略厳禁）
アプリ名: MyApp
カテゴリ: フィットネス
ターゲット: 30代男性
## コンテキスト
- ファイルパス: .claude/my-skill/20250222_myapp/
- チームメンバー:
- architect: セグメント設計担当
- writer: ペルソナ執筆担当
- context-manager: ファイル I/O 専任
## 既存コンテキスト（前回セッションがある場合）
{context.md の内容をここに展開}
agents/researcher.md の手順に従って作業を開始してください。
"""
)
| 症状 | 原因 | 対策 |
|---|---|---|
| エージェントがプロダクト情報を知らない | プロンプトに含め忘れ | 全情報を展開する |
| 前回の作業が引き継がれない | context.md を渡し忘れ | 既存コンテキストセクションを追加 |
| チームメンバーを知らない | 構成情報がない | 全メンバーの名前と役割を記載 |
| ファイルパスを間違える | パスを省略 | 絶対パスで明示 |
詳細パターンは references/context-patterns.md を参照。
| 問題 | 原因 | 対策 |
|---|---|---|
| エージェントがタスクを見つけられない | owner 未設定 | TaskUpdate で必ず owner を設定 |
| 後続タスクが永遠に待機 | completed にし忘れ | Phase 3 に「completed にする」を明記 |
| 全員が停滞する | 全員を待ってから次へ | 「2人以上から反応があれば次へ」を明記 |
| ACK だけの返信が大量発生 | 「無視禁止」ルールを厳格適用 | 「実質的な返信のみ」に変更 |
| MCP ツールが使えない | agents/*.md で定義 | general-purpose に変更 |
| コンテキストが渡らない | プロンプトに情報を含め忘れ | チェックリストで必須項目を確認 |
| コストが高い | 全員 opus | 役割別に haiku/sonnet を使い分ける |
| エラーがデバッグできない | ログがない | PostToolUse Hook でログを有効化 |
詳細は references/antipatterns.md を参照。
MCP ツール（mcp__pencil__*, mcp__devin__* 等）は agents/*.md では使えない。
Task(
subagent_type: "general-purpose", # ← agents/*.md を使わない
team_name: "ui-design",
name: "designer",
mode: "bypassPermissions",
run_in_background: true,
prompt: """
あなたは designer として ui-design チームのデザイン担当です。
## 役割
mcp__pencil__batch_design を使って UI デザインを実装する。
## 作業手順
1. TaskList で自分のタスク（owner: designer）を確認
2. TaskUpdate で in_progress に変更
...（通常のエージェント手順）
"""
)
general-purpose では全設定（role, tools, model）をプロンプト内で定義する必要がある。
トピック別に分離。必要なファイルだけ Read する:
フル実装テンプレート + 役割別実例: references/agent-template.md
ツール選択マトリクス（詳細版）: references/tool-selection.md
コンテキスト渡し・永続化パターン: references/context-patterns.md
3-Phase 詳細設計: references/phase-design.md
アンチパターン集: references/antipatterns.md