Index of every page on this site: llms.txt
All skills
wshobson avatar

/team-communication-protocols

@4220308
by Seth Hobsonwshobson/agents43k stars
4,518
Run it yourself

Structured messaging protocols for agent team communication including message type selection, plan approval, shutdown procedures, and anti-patterns to avoid. Use this skill when establishing communication norms for a newly spawned team, when deciding whether to send a direct message or a broadcast, when a team-lead needs to review and approve an implementer's plan before work begins, when orchestrating a graceful team shutdown after all tasks are complete, or when debugging why teammates are not coordinating correctly at integration points.

Use this Skill: https://skilld.dev/gh/wshobson/agents/team-communication-protocols

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈144 tokens for metadata: the name and description. ≈1.7k when used: this file. ≈538 more on demand in 1 file.

Description uses 7.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈577 characters, or 7.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Team Communication Protocols

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.",
  "summary": "API endpoint ready for frontend"
}

Use for: Task updates, coordination, questions, integration notifications.

broadcast — Use Sparingly

Send to ALL teammates simultaneously:

{
  "type": "broadcast",
  "content": "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:

  1. Teammate creates a plan using read-only exploration tools
  2. Teammate calls ExitPlanMode which sends a plan_approval_request to the lead
  3. Lead reviews the plan
  4. 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

  1. Lead sends shutdown_request to each teammate
  2. Teammate receives request as a JSON message with type: "shutdown_request"
  3. Teammate responds with shutdown_response:
    • approve: true — Teammate saves state and exits
    • approve: false + reason — Teammate continues working
  4. Lead handles rejections — Wait for teammate to finish, then retry
  5. After all teammates shut down — Call TeamDelete to remove team resources

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, role names, or unsuffixed aliases directly. If a teammate was spawned as team-lead-2, send to team-lead-2, not team-lead.

Troubleshooting

A teammate is not responding to messages. Check the teammate's task status. If it is idle, it may have completed its task and is waiting to be assigned new work or shut down. If it is still active, it may be mid-execution and will process messages once the current operation finishes.

A teammate says it cannot see SendMessage. Check the teammate agent's tools: frontmatter. Agent Teams communication tools such as SendMessage, TaskList, TaskGet, and TaskUpdate must be listed explicitly when an agent uses a restricted tool allowlist.

The lead is sending broadcasts for every status update. This is a common anti-pattern. Broadcasts are expensive — each one sends N messages. Use direct messages (type: "message") for point-to-point updates. Reserve broadcasts for critical shared-resource changes like an updated interface contract.

A teammate rejected a shutdown request unexpectedly. The teammate is still working. Check the rejection reason in the shutdown_response content field, wait for the work to finish, then retry. Never force-terminate a teammate that has unsaved work.

A plan_approval_request arrived but the request_id is missing. The teammate called ExitPlanMode without the required request context. Have the teammate re-enter plan mode, complete exploration, and call ExitPlanMode again. The request_id is generated automatically by the plan mode system.

Two teammates are waiting on each other and neither is making progress. This is a deadlock: both are blocked waiting for the other to finish first. The lead should send a direct message to one teammate with a stub or partial result so it can unblock and proceed.

Related Skills

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo5 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill defines communication protocols and messaging templates for AI agent teams. It is safe and contains no malicious code, unauthorized network activity, or credential theft. It establishes standard patterns for agent-to-agent interaction using platform-native tools.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer8mo

    2 files scanned · No issues

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 4220308. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 6 months ago
version
1.0.2
  • agent-teams
  • messaging
  • protocols
  • coordination
  • multi-agent
  • shutdown
  • plan-approval
  • communication

README badge

README badge for wshobson/agents/team-communication-protocols

Defines message types, approval workflows, and shutdown procedures for coordinating work between agent teammates. Use this skill when establishing communication norms for a new team, choosing between direct messages and broadcasts, handling plan reviews, or debugging coordination failures at integration points.

Generated from the current SKILL.md.

When should I use broadcast vs. direct message?
Use direct message by default for task updates and coordination with a single teammate. Reserve broadcast only for critical blockers affecting everyone, like updates to shared resources, because each broadcast sends N separate messages and wastes resources.
How do I approve or reject a teammate's plan?
The teammate calls ExitPlanMode which sends a plan_approval_request to the lead. The lead responds with plan_approval_response, setting approve to true or false. If false, include feedback content with revision instructions.
What happens if a teammate rejects a shutdown request?
Check the rejection reason in the shutdown_response content field — usually the teammate is still working on a task. Wait for the task to complete, then retry the shutdown request.
Should I use agent UUIDs or names when sending messages?
Always use teammate names for messaging and task assignment. Never use agentId, role names, or unsuffixed aliases directly.
How do I find out which teammates are on my team?
Read the config file at ~/.claude/teams/{team-name}/config.json, which lists each member's name, agentId, and agentType. Use the name field for all communication.

Generated from the current SKILL.md. These answers refresh after source changes.