Agent Collaboration

Use this skill when a human or coordinator tells you to collaborate with other agents through the Agent Collaboration MCP server.

Roles

There are two role categories:

• coordinator: the main agent that creates the topic, assigns work, receives progress, and decides next steps.
• secondary: an agent that performs assigned work and reports back to the coordinator.

Use a clear friendly agent_name, such as coordinator, builder, reviewer, tester, or security-reviewer.

Joining

Join the topic before sending or reading messages.

Use:

• create_topic if you are the coordinator and the topic might not exist.
• join_topic with your friendly name and role.
• Store the returned join_token and use it for all later calls.

After joining, send a presence message to coordinator or to all.

Example body:

{
  "type": "presence",
  "status": "ready",
  "role": "reviewer"
}

Reading Messages

read_messages is destructive and long-polling. check_in uses the same read semantics and can also send one message first.

• If messages are pending, it returns immediately.
• If no messages are pending and timeout_ms > 0, it waits until a relevant message arrives or the requested timeout elapses.
• If timeout_ms is 0, it returns immediately.
• Returned messages are consumed.
• send_message, read_messages, and check_in return compact output by default.
• Use verbosity: "full" only when metadata is needed for debugging.
• In check_in, body: null means read-only. Use timeout_ms: 0 when sending progress and returning immediately.

When idle, call read_messages with the largest practical timeout available. When it returns because of timeout, call it again unless your session is ending.

When actively working, do not run for a long uninterrupted period. After each meaningful unit of work, use check_in to send progress to the coordinator and check messages with timeout_ms: 0 or a short timeout.

Mandatory Polling Rule

Always poll after work. Do not finish a work chunk, review, task, or outbound message and then continue silently or end the turn without checking messages.

• After each meaningful work chunk: call check_in with progress and timeout_ms: 0 or a short timeout.
• After sending review_result: immediately poll with read_messages or check_in.
• After sending task_complete: send request_more_work using check_in, then long-poll while idle.
• After sending a task assignment, clarification, cancellation, or follow-up as coordinator: poll for replies before assuming no response.
• If the poll returns messages, handle them before continuing or ending.

Cooperative Interrupts

The collaboration MCP cannot forcibly interrupt an active agent. Messages wake agents that are blocked in read_messages; working agents see messages at their next check-in.

Treat messages with these body types as high priority when seen:

• interrupt
• cancel_task
• task_assignment
• review_result

Do not ignore coordinator changes just because work is already in progress.

Secondary Agent Contract

As a secondary agent:

1. Join the topic.
2. Send presence.
3. Wait for a task_assignment if no task is already known.
4. Work in bounded chunks.
5. Use check_in to send progress to the coordinator and check messages between chunks.
6. Handle cancellation, scope changes, and reviewer feedback before continuing.
7. Send task_complete when done.
8. Send request_more_work with check_in, then handle any returned messages.
9. Return to idle long-polling. Do not stop after completion without polling.

Progress body:

{
  "type": "progress",
  "task_id": "task-001",
  "status": "in_progress",
  "done": "Implemented topic join and direct delivery.",
  "next": "Testing broadcast cleanup.",
  "blockers": []
}

Completion body:

{
  "type": "task_complete",
  "task_id": "task-001",
  "summary": "Task completed.",
  "result": "Tests pass."
}

More-work body:

{
  "type": "request_more_work",
  "last_task_id": "task-001"
}

Coordinator Contract

As the coordinator:

1. Start the MCP server if needed.
2. Create the topic.
3. Join as coordinator.
4. Assign work with task_assignment messages.
5. Watch progress, blockers, completions, and requests for more work.
6. Send clarifications, cancellations, or follow-up tasks as needed.
7. Poll after each outbound assignment or instruction so pending replies are consumed.

Task assignment body:

{
  "type": "task_assignment",
  "task_id": "task-001",
  "summary": "Review the message deletion rules.",
  "details": "Check direct delete, broadcast all-read delete, and leave cleanup.",
  "acceptance": ["Findings cite exact files or behavior", "No unrelated edits"]
}