Protocols for effective communication between agent teammates, including message type selection, plan approval workflows, shutdown procedures, and common anti-patterns to avoid.
When to Use This Skill
Establishing communication norms for a new team
Choosing between message types (message, broadcast, shutdown_request)
Handling plan approval workflows
Managing graceful team shutdown
Discovering teammate identities and capabilities
Message Type Selection
message
(Direct Message) — Default Choice
Send to a single specific teammate:
{
"type"
:
"message"
,
"recipient"
:
"implementer-1"
,
"content"
:
"Your API endpoint is ready. You can now build the frontend form."
"Critical: shared types file has been updated. Pull latest before continuing."
,
"summary"
:
"Shared types updated"
}
Use ONLY for
Critical blockers affecting everyone, major changes to shared resources.
Why sparingly?
Each broadcast sends N separate messages (one per teammate), consuming API resources proportional to team size.
shutdown_request
— Graceful Termination
Request a teammate to shut down:
{
"type"
:
"shutdown_request"
,
"recipient"
:
"reviewer-1"
,
"content"
:
"Review complete, shutting down team."
}
The teammate responds with
shutdown_response
(approve or reject with reason).
Communication Anti-Patterns
Anti-Pattern
Problem
Better Approach
Broadcasting routine updates
Wastes resources, noise
Direct message to affected teammate
Sending JSON status messages
Not designed for structured data
Use TaskUpdate to update task status
Not communicating at integration points
Teammates build against stale interfaces
Message when your interface is ready
Micromanaging via messages
Overwhelms teammates, slows work
Check in at milestones, not every step
Using UUIDs instead of names
Hard to read, error-prone
Always use teammate names
Ignoring idle teammates
Wasted capacity
Assign new work or shut down
Plan Approval Workflow
When a teammate is spawned with
plan_mode_required
:
Teammate creates a plan using read-only exploration tools
Teammate calls
ExitPlanMode
which sends a
plan_approval_request
to the lead
Lead reviews the plan
Lead responds with
plan_approval_response
:
Approve
:
{
"type"
:
"plan_approval_response"
,
"request_id"
:
"abc-123"
,
"recipient"
:
"implementer-1"
,
"approve"
:
true
}
Reject with feedback
:
{
"type"
:
"plan_approval_response"
,
"request_id"
:
"abc-123"
,
"recipient"
:
"implementer-1"
,
"approve"
:
false
,
"content"
:
"Please add error handling for the API calls"
}
Shutdown Protocol
Graceful Shutdown Sequence
Lead sends shutdown_request
to each teammate
Teammate receives request
as a JSON message with
type: "shutdown_request"
Teammate responds
with
shutdown_response
:
approve: true
— Teammate saves state and exits
approve: false
+ reason — Teammate continues working
Lead handles rejections
— Wait for teammate to finish, then retry
After all teammates shut down
— Call
Teammate
cleanup
Handling Rejections
If a teammate rejects shutdown:
Check their reason (usually "still working on task")
Wait for their current task to complete
Retry shutdown request
If urgent, user can force shutdown
Teammate Discovery
Find team members by reading the config file:
Location
:
~/.claude/teams/{team-name}/config.json
Structure
:
{
"members"
:
[
{
"name"
:
"security-reviewer"
,
"agentId"
:
"uuid-here"
,
"agentType"
:
"team-reviewer"
}
,
{
"name"
:
"perf-reviewer"
,
"agentId"
:
"uuid-here"
,
"agentType"
:
"team-reviewer"
}
]
}
Always use
name
for messaging and task assignment. Never use
agentId
directly.