tipsy-skills/monkey-swarm/SKILL.md

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.

Agent Identity and Mailbox

When spawning a monkey agent:

1. Generate an agent ID — a short random hex string like monkey-a3f7. Pass it to the agent in its prompt.
2. Create the mailbox structure — ensure mail/<agent-id>/inbox/ and mail/<agent-id>/drafts/ exist before the agent starts.
3. Pass the orchestrator's ID — tell the agent the orchestrator's agent ID (e.g. orchestrator) so it can send status updates or questions back.
4. Register in the directory — the agent writes its role, archetype, and task to mail/dir/<agent-id>.txt so other agents can discover it. The orchestrator can scan mail/dir/ to see who's running.
5. Tell the agent to use the mailbox protocol — reference the MAILBOX.md file below.

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. The mail/dir/ registry keeps track of active agents and their roles.

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 and create its mailbox directories.
4. Include all context — the agent does not see your conversation history. Provide file paths, requirements, constraints, any relevant background, and its agent ID.
5. Tell the agent to follow the mailbox protocol (see MAILBOX.md).
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:

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.]

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.