home / skills / desplega-ai / ai-toolbox / swarm-expert

swarm-expert skill

safe

This skill helps you manage agent swarms, delegate tasks, and monitor multi-agent workflows using MCP tools for efficient coordination.

npx playbooks add skill desplega-ai/ai-toolbox --skill swarm-expert

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

3.1 KB

---
name: swarm-expert
description: Multi-agent coordination expert for agent-swarm MCP. Use when the user asks about swarm coordination, delegating tasks to agents, checking swarm status, agent messaging, or managing multi-agent workflows.
---

# Swarm Expert

You are an expert on the agent-swarm MCP server for multi-agent coordination. Help users manage agent swarms, delegate tasks, communicate between agents, and coordinate work.

> **Note**: This skill requires the `agent-swarm` MCP server to be configured. The MCP provides tools for swarm coordination.

## Quick Reference

| Goal | MCP Tool | Example |
|------|----------|---------|
| Join swarm | `join-swarm` | Join as leader or worker |
| Check swarm status | `get-swarm` | See all agents and status |
| List tasks | `get-tasks` | View tasks with filters |
| Delegate task | `send-task` | Assign task to agent/pool |
| Claim task | `task-action` | Claim from pool |
| Update progress | `store-progress` | Mark complete/failed |
| Send message | `post-message` | Chat with @mentions |
| Read messages | `read-messages` | Check unread/mentions |

## Common Workflows

### Starting as Leader

```
1. Use `join-swarm` with name and isLead=true
2. Use `get-swarm` to see available workers
3. Use `send-task` to delegate work to specific agents or pool
4. Monitor with `get-tasks` and `get-task-details`
```

### Starting as Worker

```
1. Use `join-swarm` with name (isLead=false)
2. Use `poll-task` to check for assignments
3. Use `task-action` to claim unassigned tasks
4. Use `store-progress` to report completion
```

### Delegating a Task

```
1. Use `send-task` with:
   - title: Clear task description
   - description: Detailed requirements
   - toAgentId: Specific agent OR leave empty for pool
   - tags: For categorization
   - dependsOnTaskIds: If blocked by other tasks
```

### Checking Status

```
1. Use `get-swarm` - Shows all agents (name, status, current task)
2. Use `get-tasks` - Filter by status, tags, or search text
3. Use `get-task-details` - Full task info, output, and logs
```

### Agent Communication

```
1. Use `list-channels` - See available chat channels
2. Use `post-message` with:
   - channelId: Target channel
   - content: Message text (supports @mentions)
   - replyToMessageId: For threading
3. Use `read-messages` with:
   - unreadOnly: true for new messages
   - mentionsOnly: true for @mentions to you
```

## Task States

| State | Description |
|-------|-------------|
| `pending` | Created but not started |
| `in_progress` | Being worked on |
| `completed` | Successfully finished |
| `failed` | Failed with reason |
| `blocked` | Waiting on dependencies |

## Troubleshooting

### "Agent not found"
You need to join the swarm first. Use `join-swarm` with a name.

### "Task not assigned to you"
Use `task-action` to claim the task before working on it.

### "No tasks available"
Check `get-tasks` with different filters. Tasks may be assigned or blocked.

### Can't see other agents
Use `get-swarm` to refresh the agent list. Agents may have disconnected.

## Detailed Reference

For complete MCP tool documentation, see [MCP-REFERENCE.md](MCP-REFERENCE.md).

Overview

This skill is a multi-agent coordination expert for the agent-swarm MCP server. It helps you join and manage swarms, delegate and claim tasks, monitor swarm status, and handle agent-to-agent messaging. Use it to design and operate reliable multi-agent workflows and communication patterns.

How this skill works

The skill maps common coordination intents to MCP server tools such as join-swarm, get-swarm, get-tasks, send-task, task-action, store-progress, post-message, and read-messages. It inspects swarm membership, task lists and states, task dependencies, channel lists, and unread/mentioned messages, then issues the appropriate MCP calls to perform joins, delegation, claims, progress updates, or messaging. Responses include concise actions to follow and checks to verify success.

When to use it

When you need to join a swarm as leader or worker and establish presence.
When delegating work to specific agents or a shared pool of workers.
When checking overall swarm health, agent status, or current assignments.
When claiming, updating, or reporting progress on tasks.
When sending or reading inter-agent messages, replies, or mentions.

Best practices

Join the swarm with a clear name and isLead flag to establish role and visibility.
Tag tasks and set dependsOnTaskIds to express dependencies and avoid blockers.
Prefer assigning to a pool for flexible load balancing; assign to specific agents for specialized work.
Poll get-tasks and get-task-details regularly to detect blocked or failed tasks early.
Use post-message with channelId and @mentions for targeted agent coordination and threading.

Example use cases

Start a leader session: join-swarm (isLead=true), list workers with get-swarm, send-task to assign subtasks, monitor progress with get-tasks.
Worker workflow: join-swarm (isLead=false), poll-task for new assignments, claim via task-action, report via store-progress.
Task delegation: create a detailed send-task with title, description, tags, and dependsOnTaskIds to coordinate multi-step work.
Troubleshoot state: run get-tasks filtered by status or tags, then use get-task-details to inspect logs and outputs.
Agent chat: list-channels, post-message with mentions for alerts, and read-messages (unreadOnly/mentionsOnly) to process responses.

FAQ

What if I see 'Agent not found'?

You must join the swarm first using join-swarm with a name; then retry the operation.

How do I claim a task assigned to the pool?

Use task-action to claim an unassigned task from the pool before starting work, then update progress with store-progress.