| name | agent-team-guide |
| description | Agent Teams スキルを設計・構築するためのベストプラクティスガイド。 サブエージェント定義、SendMessage 通信プロトコル、タスク依存管理、 PostToolUse Hook によるログ、MCP ツール統合、コンテキストファイル設計を網羅。 7つの実績あるチームスキル（app-naming, ui-review, logo-design, persona-creation, skill-creator-team, ui-variations, aso-optimize）から抽出したパターン集。 Use when: Agent Teams を使ったスキルを新規作成したい、 既存のチームスキルの品質を改善したい、エージェント間通信のデバッグ、 チームスキルの設計パターンを知りたい。 Triggers: "agent team", "チームスキル", "エージェントチーム", "サブエージェント定義", "SendMessage パターン", "チーム設計", "エージェント間通信", "team skill", "swarm pattern"
|
Agent Team Guide
7つの実績あるチームスキルから抽出した Agent Teams 設計パターン集。
新規チームスキルの作成と、既存スキルの品質監査の両方に使える。
このスキルの使い方
新規作成: SKILL.md テンプレート → エージェント定義 → タスク設計 → テスト の順で構築
品質監査: references/quality-checklist.md を既存スキルに適用し、改善点を特定
チームスキルのディレクトリ構成
my-team-skill/
├── SKILL.md <- リーダーの手順書（ワークフロー全体）
├── agents/ <- サブエージェント定義
│ ├── role-a.md
│ ├── role-b.md
│ └── context-manager.md <- ファイル I/O 専任を推奨
├── references/ <- テンプレート・ドメイン知識
│ └── report-template.md
└── scripts/ <- 初期化・ユーティリティ
└── init.sh
設計の5原則
- エージェント数は 3〜6 体: 少なすぎると並列の意味なし、多すぎると通信爆発
- MECE な役割分担: 各エージェントの責務が重複しない
- 3-Phase ワークフロー: 全エージェントが init → active → finalize の構造
- 実質的通信のみ: ACK だけの返信は不要。相手の次アクションに繋がる内容がある時のみ返信
- 待ちすぎない: 全員のフィードバックを待たない。2人以上から反応があれば次へ進む
- コンテキストファイルで永続化: セッション跨ぎの知識蓄積
SKILL.md テンプレート
## Step 1: ヒアリング
以下を確認する（不明ならユーザーに質問）:
- **項目A**: {具体的に何を聞くか}
- **項目B**: ...
## Step 2: チーム作成とエージェント起動
TeamCreate で `{skill-name}` チームを作成。
以下 N エージェントを **1つのメッセージで並列に** Task ツールで起動する。
| name | 役割 | 主な手段 |
|------|------|---------|
| `role-a` | ... | 分析 |
| `role-b` | ... | WebSearch |
### タスク作成
TaskCreate で N+1 個のタスクを作成:
1. context-manager: 初期化（依存なし）
2. role-a: ...（`addBlockedBy: ["1"]`）
3. role-b: ...（依存なし or `addBlockedBy: ["1"]`）
4. ...（`addBlockedBy: ["2","3"]`）
5. 統合レポート（`addBlockedBy: ["1","2","3","4"]`）
### 起動設定（全エージェント共通）
subagent_type: "{skill-name}:{role-name}"
team_name: "{skill-name}"
mode: "bypassPermissions"
run_in_background: true
プロンプトに含める情報:
- ユーザーからヒアリングした全情報
- コンテキストファイルパス
- 既存の context.md 内容（あれば）
## Step 3: フィードバックループ
### フィードバックプロトコル
1. 自分の作業完了後、即座に関連エージェントへ共有
2. **実質的な内容のある返信のみ送る** - 「了解しました」「ありがとうございます」だけのACK返信は不要。フィードバック・質問・修正報告など、相手の次アクションに繋がる内容がある場合のみ返信する
3. 重大問題は即座に全員へ緊急通知
4. フィードバックを受けたら修正し、変更内容を共有
5. **待ちすぎない** - フィードバックを全員から集める必要はない。2人以上から反応があれば次のフェーズに進む
### Round 1: {概要}
{エージェント間の通信フロー}
### Round 2: {概要}
...
### Round 3: {概要}
...
### 緊急通知パターン
- **role-a**: {どんな問題を検知したら} → {誰にどうアクションを求めるか}
- **role-b**: ...
## Step 4: 最終レポート出力
テンプレート: [references/report-template.md](references/report-template.md)
## Step 5: クリーンアップ
1. 全エージェントに shutdown_request を送信
2. 全員シャットダウン後に TeamDelete でチーム削除
リーダーの行動指針（SKILL.md 実行時）
エージェント起動後のリーダー（メインの Claude）の動き方:
- 見守りが基本: エージェントが自律的に議論する間は介入しない
- 介入タイミング: エージェントが詰まった時、矛盾が解消されない時、同じメッセージが繰り返される時
- TaskList で進捗確認: 全タスクが completed になるまで待機
- 最終統合: 全報告を統合してレポートを作成（最終タスクはリーダー担当）
- シャットダウン: 全員に
shutdown_request → 承認確認後 TeamDelete
MCP ツールを使うエージェント
MCP ツール（mcp__pencil__* 等）は agents/*.md からアクセスできない。
MCP が必要なエージェントは subagent_type: "general-purpose" で起動し、プロンプト内で役割を定義する:
Task(
subagent_type: "general-purpose",
team_name: "my-team",
prompt: "あなたは ui-designer として... mcp__pencil__batch_design を使って..."
)
よくある落とし穴
| 問題 | 原因 | 対策 |
|---|
| エージェントがタスクを見つけられない | owner 未設定 | TaskUpdate で必ず owner を設定 |
| ACK だけの返信が大量に発生 | 「無視禁止」を厳格に適用しすぎ | 「実質的な内容のある返信のみ」に変更 |
| エージェントが全員の返信を待ちすぎる | 「待ちすぎない」ルールがない | 2人以上から反応があれば次フェーズへ進む |
| エージェントが暇すぎる | 過剰な依存関係 | 並列可能なタスクの依存を外す + 早期フィードバック設計 |
| 最終タスクだけ残る | 完了通知なし | エージェントに「完了時リーダーに報告」を指示 |
| デバッグが困難 | ログがない | PostToolUse Hook (agent-teams-log プラグイン) を有効化 |
| MCP ツールが使えない | agents/*.md で定義 | subagent_type: "general-purpose" に変更 |
詳細リファレンス
トピック別に分離。必要なファイルだけ Read する:
関連スキル
- SubAgent 定義の品質向上:
subagent-best-practices スキル（~/.claude/skills/subagent-best-practices/）
- 個別の agents/*.md の書き方に特化したベストプラクティス
- Frontmatter 全フィールド解説、ツール選択マトリクス、3-Phase 詳細設計、アンチパターン集
- 本スキル（agent-team-guide）がチーム全体の設計を扱うのに対し、subagent-best-practices は個別エージェント定義の品質に特化
