# Compose

Use when a single agent demonstrably cannot handle the task and multi-agent...

- Repository: https://github.com/sharpdeveye/maestro (592 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-04-29
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add sharpdeveye/maestro --skill compose -g -a claude-code -y`
Codex: `npx skills add sharpdeveye/maestro --skill compose -g -a codex -y`
Cursor: `npx skills add sharpdeveye/maestro --skill compose -g -a cursor -y`
Gemini CLI: `npx skills add sharpdeveye/maestro --skill compose -g -a gemini-cli -y`

## Description

Use when a single agent demonstrably cannot handle the task and multi-agent coordination is justified.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

## MANDATORY PREPARATION

Invoke /agent-workflow, it contains workflow principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding, if no workflow context exists yet, you MUST run /teach-maestro first.
Consult the agent-architecture reference in the agent-workflow skill for topology patterns and when multi-agent is justified.

---

Design a multi-agent system. But first, are you sure you need one?

### Step 1: Pre-Composition Check

Answer these before proceeding:

1. **Has a single agent been tried and failed?** (If no, try single agent first)
2. **What specific limitation requires multiple agents?** (If you can't name it, you don't need multi-agent)
3. **Is the cost/latency increase justified?** (Multi-agent = 2-10x cost and latency)

If you can't articulate a specific limitation, use /amplify on the single agent instead.

### Step 2: Design the Topology

Choose the right architecture pattern (consult the agent-architecture reference in the agent-workflow skill):

For each agent in the system, define:

```markdown
## Agent: [Name]
Role: [One sentence]
Responsibilities: [What it does]
Boundaries: [What it does NOT do]
Tools: [List of tools this agent has access to]
Input: [What it receives]
Output: [What it produces]
```

### Step 3: Design Handoffs

For each agent-to-agent connection:

```markdown
## Handoff: [Agent A] → [Agent B]
Trigger: [When does A hand off to B?]
Payload: [What data is passed?]
Expected response: [What does A expect back?]
Timeout: [How long to wait?]
Failure handling: [What if B fails?]
```

### Step 4: Design the Supervisor

Every multi-agent system needs a supervisor:

- Monitors agent health and performance
- Routes tasks to appropriate agents
- Handles failures and escalation
- Enforces global constraints (budget, time, quality)

### Composition Checklist

The rest: https://github.com/sharpdeveye/maestro/blob/HEAD/source/skills/compose/SKILL.md