Agent Messaging Expert

Overview

A skill for implementing structured inter-agent communication in multi-agent systems. Enables Claude Code agents to send, receive, and process messages with proper protocols — supporting direct messaging, broadcast, request-reply patterns, and task coordination between agents working on shared codebases.

When to Use

• Coordinating multiple Claude agents working on the same project
• Building pipelines where one agent's output feeds another's input
• Implementing review workflows with handoffs between specialists
• Managing shared state across concurrent agent sessions
• Debugging communication issues in multi-agent setups

Quick Start

Copy
# Send a message between agents
claude "Send the security review findings to the implementation agent"

# Set up a messaging channel
claude "Create a message queue for the refactoring pipeline"

# Check agent inbox
claude "Check for pending messages from the review team"

Communication Patterns

1. Direct Messaging (Point-to-Point)

One agent sends a message to a specific agent:

Agent A ──message──→ Agent B

Use when: Assigning work, sending results, requesting review.

Copy
// Leader sends task to specific agent
write("security-reviewer", {
  type: "task_assignment",
  subject: "Review auth middleware",
  body: "Check src/middleware/auth.ts for OWASP Top 10 vulnerabilities",
  priority: "high",
  deadline: "before_merge"
});

2. Broadcast (One-to-Many)

Leader sends a message to all team members:

Leader ──broadcast──→ Agent A
                   ──→ Agent B
                   ──→ Agent C

Use when: Announcing changes, setting constraints, requesting status updates.

Copy
// Announce a constraint to all agents
broadcast("review-team", {
  type: "constraint",
  body: "All changes must maintain backward compatibility with API v2"
});

Warning: Broadcasts are expensive — each agent must process the message. Prefer direct messages when possible.

3. Request-Reply

Agent sends a request and waits for a response:

Agent A ──request──→ Agent B
Agent A ←──reply───┘

Use when: Seeking approval, asking for information, confirming before proceeding.

Copy
// Agent requests approval before destructive operation
const approval = await requestApproval("team-lead", {
  type: "plan_approval",
  subject: "Database schema migration",
  plan: "Drop deprecated columns: user.legacy_id, order.old_status",
  impact: "Irreversible after migration runs"
});

if (approval.approved) {
  // Proceed with migration
} else {
  // Revise plan based on feedback
}

4. Publish-Subscribe (Event-Based)

Agents subscribe to topics and receive relevant messages:

Event Bus ──"test.complete"──→ Agent A (subscribed)
          ──"test.complete"──→ Agent C (subscribed)
           (Agent B not subscribed — no message)

Use when: Loosely coupled agents that react to events.

Message Format

Standard Message Structure

Copy
{
  "id": "msg_abc123",
  "from": "security-reviewer",
  "to": "team-lead",
  "type": "task_complete",
  "subject": "Security review findings",
  "body": "Found 2 critical issues in auth.ts",
  "data": {
    "findings": [
      { "severity": "critical", "file": "src/auth.ts", "line": 45, "issue": "SQL injection" },
      { "severity": "high", "file": "src/auth.ts", "line": 89, "issue": "Missing rate limit" }
    ],
    "summary": { "critical": 2, "high": 1, "medium": 0 }
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "replyTo": null
}

Message Types

Type	Purpose	Example
task_assignment	Assign work to an agent	"Review auth middleware"
task_complete	Report completed work	"Security review done, 2 issues found"
plan_approval	Request sign-off	"Approve this migration plan?"
status_update	Progress report	"3/5 files reviewed"
constraint	Set rules for all agents	"Don't modify shared config"
shutdown_request	Ask agent to exit	"Work complete, please clean up"
error	Report failure	"Build failed, blocking deployment"
handoff	Transfer work to another agent	"Passing DB review to specialist"

Message Routing

Priority Levels

urgent    →  Interrupt current work, process immediately
high      →  Process next, before normal queue
normal    →  Process in order received
low       →  Process when idle

Message Queue Management

Copy
# Check inbox (unread messages)
amp-inbox

# Check all messages including read
amp-inbox --all

# Filter by sender
amp-inbox --from security-reviewer

# Filter by type
amp-inbox --type task_complete

# Read specific message
amp-read msg_abc123

# Reply to a message
amp-reply msg_abc123 "Acknowledged, will fix the SQL injection first"

Error Handling

Delivery Failures

Copy
// Retry with exponential backoff
async function sendWithRetry(to, message, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await send(to, message);
    } catch (err) {
      if (attempt === maxRetries - 1) throw err;
      await sleep(Math.pow(2, attempt) * 1000);
    }
  }
}

Dead Letter Queue

Messages that can't be delivered after retries go to a dead letter queue for manual inspection:

Copy
# Check dead letter queue
amp-dead-letters

# Retry a dead letter
amp-retry msg_failed_123

# Discard a dead letter
amp-discard msg_failed_123

Security

Message Validation

• Verify sender identity before processing
• Validate message schema against expected types
• Reject messages with unexpected fields or oversized payloads
• Log all messages for audit trail

Access Control

Copy
{
  "permissions": {
    "security-reviewer": { "can_send_to": ["team-lead"], "can_broadcast": false },
    "team-lead": { "can_send_to": ["*"], "can_broadcast": true },
    "worker": { "can_send_to": ["team-lead"], "can_broadcast": false }
  }
}

Best Practices

1. Prefer direct over broadcast — Targeted messages reduce noise and cost
2. Include context in messages — Don't assume the receiver knows the background
3. Use structured data — JSON payloads over free text for machine-processable messages
4. Set timeouts — Don't wait indefinitely for replies
5. Acknowledge important messages — Confirm receipt of critical assignments
6. Keep messages small — Send references (file paths, IDs) not full content
7. Log all communication — Enables debugging and audit trails
8. Handle message ordering — Messages may arrive out of order; use timestamps
9. Clean up channels — Remove completed conversations to reduce clutter
10. Graceful shutdown — Send shutdown acknowledgment before exiting