Guide · Agent skill
How to use the Team Communication Protocols agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The team-communication-protocols skill is a set of messaging conventions for AI agents that work together as a team, such as a lead agent coordinating several implementer and reviewer agents. It tells the agent when to send a direct message instead of a broadcast, how a lead reviews a teammate's plan before work starts, how to shut a team down cleanly, and which coordination mistakes to avoid. This guide explains what the skill does, how to install it, how to trigger it, and what it needs, so you can use it in your own Claude Code Agent Teams setup.
Team Communication Protocolswshobson/agents · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into .claude/skills/ inside a project.
- 2Confirm your team setup. Make sure Claude Code with the Agent Teams feature is available and that the agent can read ~/.claude/teams/{team-name}/config.json.
- 3Ask for the task in plain language. Describe what you need, such as deciding between a direct message and a broadcast, or shutting the team down after all tasks are complete.
- 4Use direct messages by default. Send updates to the specific teammate who needs them and reserve broadcasts for critical blockers or shared-resource changes.
- 5Run plan approval and shutdown in order. Approve plans before implementation starts, then send shutdown requests to each teammate, retry any rejected ones, and call TeamDelete at the end.
What this skill makes the agent do
The skill gives an agent a playbook for talking to its teammates. It covers three message types (message, broadcast and shutdown_request), a plan approval workflow in which a lead approves or rejects a teammate's plan, a graceful shutdown sequence, a table of communication anti-patterns, and guidance on finding teammate names in a team config file.
It only defines conventions for agents talking to each other inside a team. It is not a general chat or messaging tool, and it does nothing for a single agent working alone.
- Choose between a direct message and a broadcast
- Run plan approval before an implementer starts work
- Orchestrate a graceful team shutdown after tasks are complete
- Find teammate names in the team config file
- Debug teammates that are not coordinating at integration points
How to install the skill
Download the ZIP file for the skill from this page. Then install it using one of these options.
Option 1 is a personal install: unzip the file into ~/.claude/skills/ so the skill is available across your projects. Option 2 is a project install: unzip the file into the .claude/skills/ folder inside a specific project. Option 3 is to upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
- Personal: unzip into ~/.claude/skills/
- Project: unzip into .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
How to trigger the skill with natural requests
You do not need to name the skill to use it. The skill's description lists the situations where it applies, so ask for the task in plain language. The skill is designed to be picked up when you are setting up a new team, choosing a message type, reviewing a plan, shutting a team down, or debugging coordination problems.
Requests that should match the skill include the following examples.
- Set up communication norms for this newly spawned team.
- Should I send this update as a direct message or a broadcast?
- Review implementer-1's plan before it starts coding.
- All tasks are done, so shut the team down gracefully.
- The frontend and API agents are not coordinating at the integration point. Help me debug it.
Message types: direct messages, broadcasts and shutdown requests
A direct message (type message) is the default. Send it to one specific teammate for task updates, coordination, questions and integration notifications. The skill says to use broadcasts sparingly, only for critical blockers that affect everyone or major changes to shared resources. Each broadcast sends one message per teammate, so cost grows with team size.
A shutdown_request asks a teammate to stop. The teammate replies with shutdown_response, either approving (it saves state and exits) or rejecting with a reason.
- Use message for task updates, coordination, questions and integration notices
- Use broadcast only for critical blockers or changes to shared resources such as an updated interface contract
- Use shutdown_request to end a teammate's work
- Do not use JSON status messages; use TaskUpdate to change task status instead
{"type": "message", "recipient": "implementer-1", "content": "Your API endpoint is ready. You can now build the frontend form.", "summary": "API endpoint ready for frontend"}How plan approval works
Plan approval applies when a teammate is spawned with plan_mode_required. The teammate explores the code using read-only tools and builds a plan. It then calls ExitPlanMode, which sends a plan_approval_request to the lead. The lead reviews the plan and replies with a plan_approval_response that either approves it or rejects it with feedback.
The example below shows an approval. To reject, set approve to false and add feedback in the content field.
- Teammate creates a plan with read-only exploration tools
- Teammate calls ExitPlanMode, which sends plan_approval_request to the lead
- Lead replies with plan_approval_response
- Use approve true to accept, or approve false with content to request changes
{"type": "plan_approval_response", "request_id": "abc-123", "recipient": "implementer-1", "approve": true}How to shut a team down gracefully and find teammates
Send a shutdown_request to each teammate. A teammate that approves saves its state and exits. A teammate that rejects is usually still working. Wait for its current task to finish, then send the request again. Once every teammate has shut down, call TeamDelete to remove the team's resources. If a shutdown is urgent, the source says the user can force it, but it warns never to force-terminate a teammate that has unsaved work.
To find teammates, read the team config file at ~/.claude/teams/{team-name}/config.json. It lists each member's name, agentId and agentType. Always message and assign tasks by name, never by agentId, role name or an unsuffixed alias. If a teammate was spawned as team-lead-2, send to team-lead-2.
- Send shutdown_request to each teammate
- If a teammate rejects, wait for the work to finish and retry
- Call TeamDelete after all teammates have shut down
- Read ~/.claude/teams/{team-name}/config.json to discover names
{"members": [{"name": "security-reviewer", "agentId": "uuid-here", "agentType": "team-reviewer"}]}Anti-patterns and troubleshooting
The skill lists six common mistakes: broadcasting routine updates, sending JSON status messages, not communicating at integration points, micromanaging through messages, using UUIDs instead of names, and ignoring idle teammates. Each has a better approach, such as messaging the affected teammate directly or checking in at milestones.
If a teammate is not responding, check its task status. An idle teammate may be waiting for new work or a shutdown. An active one will process messages after its current operation. If two teammates are waiting on each other, the lead should send one of them a stub or partial result so work can continue.
- Teammate not responding: check whether it is idle or still active
- Teammate cannot see SendMessage: add the Agent Teams tools (SendMessage, TaskList, TaskGet, TaskUpdate) to its tools: frontmatter if it uses a restricted allowlist
- Plan approval request missing request_id: have the teammate re-enter plan mode and call ExitPlanMode again
- Deadlock: send one teammate a stub or partial result
What people use it for
- A lead agent sets communication norms when it spawns a new team of implementers and reviewers.
- An implementer finishes an API endpoint and sends a direct message so the frontend teammate can start building against it.
- A lead reviews an implementer's plan through plan_approval_request and sends back approval or feedback before any code is written.
- A lead closes out a finished project by sending shutdown requests, retrying any teammate still working, and then calling TeamDelete.
Frequently asked questions
How do I install the team-communication-protocols skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
What do I need to use this skill?
You need Claude Code with the Agent Teams feature, because the skill refers to tools such as SendMessage, TaskList, TaskGet, TaskUpdate, ExitPlanMode and TeamDelete. The agent also needs read access to ~/.claude/teams/{team-name}/config.json to find teammates.
Is the team-communication-protocols skill free to use?
The skill is published under the MIT licence, as listed on this page. The source does not mention prices, so check the repository for any terms beyond the licence.
Does this skill run scripts or use the network?
According to this page, the skill does not run scripts and does not use the network. It consists of instructions and message templates that the agent follows inside a team.
Can I use this skill without a multi-agent team?
No. The protocols only apply when there are teammates to coordinate with. For a single agent with no teammates, none of the message types or shutdown steps are relevant.
Why is my teammate not responding or not seeing SendMessage?
If a teammate is idle, it may be waiting for new work or a shutdown. If it cannot see SendMessage, add SendMessage, TaskList, TaskGet and TaskUpdate to its tools: frontmatter when it uses a restricted tool allowlist.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you run Claude Code Agent Teams with a lead and several implementer or reviewer agents and want consistent messaging, plan approval and shutdown behavior. Skip it if you work with a single agent or need a general-purpose chat or messaging tool, since it only defines conventions for agents talking to each other inside a team.
Download the skill