charles
162ff7a559
Move the protocol documentation to references/ and expand it with read receipts and thread IDs. Update SKILL.md to reference the new location and add a YAML frontmatter block. Remove the outdated MAILBOX.md file.
95 lines
5.6 KiB
Markdown
95 lines
5.6 KiB
Markdown
---
|
|
name: monkey-swarm
|
|
description: >
|
|
Delegates work to specialized sub-agents (monkeys) using behavioral archetypes
|
|
(specialist, surveyor, researcher, planner, interfacer). Use when the user
|
|
mentions monkeys, swarm, delegation, or requests that benefit from parallel
|
|
or specialized agent work. Don't use for simple single-step tasks.
|
|
---
|
|
|
|
# Monkey Swarm
|
|
|
|
When the user mentions needing help from the team, monkeys, or swarm — or asks you to delegate work — invoke the monkey swarm. The swarm keeps your context clean by offloading work to specialized sub-agents.
|
|
|
|
## Trigger
|
|
|
|
Activate this skill whenever the user mentions any of:
|
|
|
|
- "monkey", "monkeys", "monkey swarm", "the swarm"
|
|
- "ask the monkeys", "have the monkeys", "send a monkey"
|
|
- "spawn", "delegate" (when referring to offloading a subtask)
|
|
- Requests that imply parallel or specialized work that would benefit from a dedicated agent
|
|
|
|
## How It Works
|
|
|
|
The swarm does **not** spawn agents with fixed roles. Instead, it spawns agents with **archetypes** — broad behavioral profiles. An "HR monkey" then translates the archetype into a concrete persona tailored to the immediate need.
|
|
|
|
### Archetypes
|
|
|
|
| Archetype | Purpose |
|
|
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| **specialist** | Dives deep into a very specific task. Use when the work is narrow, technical, and requires focused expertise. |
|
|
| **surveyor** | Explores a large space superficially. Use when you need breadth over depth — scanning a codebase, exploring a directory tree, or surveying a set of options. |
|
|
| **researcher** | Distills information from the work done by others. Use when multiple sources of information need to be synthesized into a coherent summary or recommendation. |
|
|
| **planner** | Looks at the current state of the project and proposes next steps. Use when you need a high-level plan, decomposition of work, or prioritization. |
|
|
| **interfacer** | Comes up with a set of questions for the user. Use when the problem is underspecified and you need more input before proceeding. |
|
|
|
|
## Spawning a Monkey
|
|
|
|
When spawning a monkey agent:
|
|
|
|
1. **Identify the archetype** based on what's needed.
|
|
2. **Generate a persona** — briefly describe the exact role this agent should play, including its scope, goals, and deliverables. Be specific about what "done" looks like.
|
|
3. **Generate an agent ID** — a short random hex string like `monkey-a3f7`. Pass it to the agent in its prompt.
|
|
4. **Set up the mailbox** — read `references/mailbox.md` for the full mailbox protocol. At minimum:
|
|
- Ensure `mail/<agent-id>/inbox/`, `mail/<agent-id>/inbox/.read/`, and `mail/<agent-id>/drafts/` exist before the agent starts.
|
|
- Pass the orchestrator's ID (e.g. `orchestrator`) so the agent can send status updates or questions back.
|
|
- Pass a **thread ID** for this agent's conversation with the orchestrator (e.g. `task-refactor-auth`). All messages between the orchestrator and this agent should use the same thread ID.
|
|
- Tell the agent to register in `mail/dir/<agent-id>.txt` with `status: active` and to update its status as it works.
|
|
5. **Include all context** — the agent does not see your conversation history. Provide file paths, requirements, constraints, any relevant background, and its agent ID.
|
|
6. **Use `spawn_agent`** to launch the sub-agent with the persona as its label and the full prompt as its message.
|
|
|
|
### Persona Template
|
|
|
|
When generating a persona, fill in:
|
|
|
|
```text
|
|
You are a [ROLE NAME], a [ARCHETYPE] monkey in the swarm.
|
|
|
|
## Your Role
|
|
[2-3 sentences describing what you do and why you exist for this task.]
|
|
|
|
## Scope
|
|
- [What you're responsible for]
|
|
- [What you're NOT responsible for]
|
|
|
|
## Deliverables
|
|
- [Concrete output expected — file, summary, plan, questions, etc.]
|
|
|
|
## Context
|
|
[All background the agent needs: project structure, relevant files, constraints, etc.]
|
|
|
|
## Instructions
|
|
[Step-by-step or high-level guidance on how to approach the work.]
|
|
```
|
|
|
|
### Mailbox Protocol
|
|
|
|
The mailbox is the communication channel between swarm agents and the orchestrator. It lives in `mail/` at the repo root. Agents read their inbox at the start of a run and check for new mail between work units.
|
|
|
|
**Key features:**
|
|
|
|
- **Read receipts** (`inbox/.read/`) — agents only poll unread messages, preventing context bloat.
|
|
- **Thread IDs** — group related messages into conversations; the orchestrator and each agent share a thread ID.
|
|
- **Agent status** (`status:` in `mail/dir/`) — the orchestrator polls status to know who's working, done, or blocked.
|
|
|
|
**Load `references/mailbox.md`** for the full protocol: directory structure, registration, sending/receiving rules, mail format, thread protocol, message status, and cleanup.
|
|
|
|
### Practical Rules
|
|
|
|
- **Keep your context clean.** Offload work whenever a task can be completed by a sub-agent. The orchestrator's job is coordination, not doing everything.
|
|
- **Parallel when possible.** If multiple independent monkeys can work at once, spawn them in parallel.
|
|
- **Match archetype to need.** Don't send a specialist to explore — send a surveyor. Don't send a planner to implement — send a specialist.
|
|
- **Chain when needed.** A surveyor's findings can feed into a researcher's synthesis, which can feed into a planner's proposal.
|
|
- **The HR monkey is implicit.** You don't need to spawn a separate HR agent — you generate the persona yourself before spawning.
|