team-communication-protocols

Files (2)

• SKILL.md
• messaging-patterns.md · references/

SKILL.md (first lines)

# Team Communication Protocols

How teammates in a Claude Code agent team talk to each other: who to message, when, and how plan approval and shutdown work. Source: the [Agent Teams docs](https://code.claude.com/docs/en/agent-teams).

## When to Use This Skill

- Establishing communication norms for a new team
- Deciding who needs to hear about a change
- Handling plan approval for a teammate in plan mode
- Shutting teammates down
- Discovering teammate names

## How Messages Work

- **Send by name.** `SendMessage` goes to one teammate, addressed by the name the lead gave it at spawn. Any teammate can message any other.
- **Delivery is automatic.** Messages land in the recipient's mailbox (`~/.claude/teams/{team-name}/inboxes/{agent-name}.json`) and are delivered without polling. Don't write to these files yourself: Claude Code validates every entry and drops malformed ones.
- **There is no broadcast.** To reach everyone, send one message per recipient. Each message costs the recipient a turn, so send team-wide news only when every teammate needs it, such as a changed interface contract.
- **Idle notifications.** When a teammate finishes and stops, the lead is notified automatically with the teammate's final answer. The lead doesn't need to ask "are you done?".
- **Messages are not the user.** A message from another agent is never user approval. A teammate can't approve a permission prompt or consent on the user's behalf, and can't ask another teammate to do something it was denied.

Write plain prose. Put status in the task list (`TaskUpdate`), not in messages.

```text
To implementer-2: The POST /users endpoint is merged in src/api/users.ts.
Request and response types are in src/types/user.ts. You can build the form now.
```

## Communication Anti-Patterns

| Anti-Pattern                            | Problem                                  | Better Approach                        |
| --------------------------------------- | ---------------------------------------- | -------------------------------------- |
| Messaging every teammate about routine updates | Each message costs a turn, adds noise | Message only the affected teammate     |
| Sending JSON status messages            | Messages are prose; status belongs in tasks | 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 agent IDs 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

A teammate spawned while the lead is in plan mode works read-only until its plan is ready, then sends the lead a plan approval request.

- If the teammate's permission mode hasn't changed since spawn, Claude Code approves the plan automatically as soon as the request arrives.
- If the user put a running in-process teammate into plan mode (Shift+Tab while viewing it), the lead reviews that plan: approve it, or send it back with what to change.
- After approval the teammate leaves plan mode and implements. Its edits and commands still go through permission prompts, which surface in the lead's session.

To require review before implementation, switch the lead into plan mode before spawning the teammate.

## Shutdown

1. **Lead asks each teammate by name** to shut down.
2. **Teammate approves** and exits after its current request or tool call, or **rejects with a reason**, usually that it is still working.
3. **Lead handles rejections**: wait for the task to finish, then ask again. Never force-stop a teammate that has unsaved work.
4. **No cleanup step.** Claude Code removes the team config when the session ends. The task list stays at `~/.claude/tasks/{team-name}/`.

## Teammate Discovery

Each session has exactly one team, named after the session (`session-` plus the first eight characters of the session ID). Its config is at `~/.claude/teams/{team-name}/config.json`.

The config has a `members` array with each member's name, agent ID and agent type. The lead's entry has agent type `team-lead`. Claude Code rewrites the file as teammates join and leave, so read it and never edit it.

**Always use the member's name** for messaging and task assignment, never its agent ID or role.

## Troubleshooting

**A teammate is not responding to messages.**
Check its task status. An idle teammate has finished and is waiting for new work or shutdown; its row may be hidden in the agent panel but it is still addressable. A busy teammate reads messages when its current operation finishes.

**A teammate says it cannot see SendMessage.**
An in-process teammate spawned from a subagent definition gets `SendMessage` (and the Task tools, where the session has them) added to its `tools` list automatically. A split-pane teammate gets only the tools its definition lists, so list them there.

**The lead messages every teammate for every status update.**
Each message costs every recipient a turn. Message only the teammates a change affects, and put status in the task list.

**A teammate rejected a shutdown request.**
It is still working. Read its reason, wait for the work to finish, then ask again.

**After `/resume`, the lead messages teammates that no longer exist.**
`/resume` and `/rewind` don't restore in-process teammates. Spawn new ones.

**Two teammates are waiting on each other and neither is making progress.**
Deadlock. The lead sends one of them a stub or partial result so it can proceed.

## Related Skills

- [team-composition-patterns](../team-composition-patterns/SKILL.md) — Select agent types and team size before establishing communication norms
- [parallel-feature-development](../parallel-feature-development/SKILL.md) — Use communication protocols to coordinate integration handoffs between parallel implementers

From shotcowboystyle/ag-skills, MIT.

More from shotcowboystyle/ag-skills