Most people reach for more agents when work gets hard.
Often the fix is the opposite: one agent, a skill library, and a green command - not a chatty committee.
This guide is for builders who watched multi-agent demos and want a setup that survives a real repo.
Kill the default approach
Default: spawn planner, coder, reviewer, and critic for every task. Hope debate produces quality.
What breaks first: token burn, conflicting edits, "done" with failing tests, and nobody owns the merge.
By the end you will have
- When multi-agent helps vs when it wastes money
- The Skill Library Compile magnet (turn roles into skills)
- Isolation rules if you still need parallel research
- Failure modes and a scorecard
- A clear next action for one repo
The useful question
Not "how many agents?" - where does the work fail?
| Failure | Better fix than more agents |
|---|---|
| Missing procedure | Skill with steps + verify |
| Context overflow | Smaller task + memory receipt |
| Parallel research | Isolated workers, then one merge owner |
| Bad judgment on irreversible work | Human gate, not more personas |
Research on multi-agent systems keeps finding the same pattern: coordination cost is real, and "teams" often fail to use the best expert in the room. Treat multi-agent as a special tool, not a default company structure.
When one agent + skills wins
Use a single agent when:
- One repo, one PR, one verification command
- The procedure is repeatable (skill-shaped)
- You need a consistent voice or coding style
- Cost and latency matter
Skill = muscle memory. The agent plans; the skill is the checked how-to.
Magnet: Skill Library Compile
Name: Skill Library Compile
Turn a multi-role fantasy into a single-agent skill shelf.
# From roles → skills
## Planner role becomes
skill: plan-diff
When: starting non-trivial work
Steps: state goal, list files, risks, done criteria
Verify: done criteria is testable
## Implementer role becomes
skill: implement-green
When: coding after plan
Steps: smallest diff, run check.sh, no drive-by refactors
Verify: check.sh exits 0
## Reviewer role becomes
skill: review-pr
When: before merge
Steps: security skim, test map, residual risks
Verify: risks listed; no secrets in diffLoad one skill at a time. Do not load the whole shelf into every prompt.
You should see: three skills used on real work twice each, with verify green, before you invent a fourth agent persona.
If you still need multi-agent
Only when all are true:
- Task is parallelizable (independent sub-questions)
- Workers get fresh context (no sibling chat)
- One owner merges and verifies
- Workers cannot publish, deploy, or spend
Parallel research is a good fit. Parallel "everyone edits main" is not.
Failure modes
| Anti-pattern | Cost |
|---|---|
| Debate without a green command | Expensive opinions |
| Averaging expert and non-expert takes | Diluted correctness |
| Multi-agent auto-publish | Error amplification |
| Skills without verify steps | Rituals that never ran |
| Ten agents, zero handoff doc | Hobby theater |
One-page scorecard
Score 0-2 each: green command · skill count ≤10 · skills used twice · human gate on irreversible · no multi-agent public write.
0-4: demo mode. 5-7: reliable solo. 8-10: ready for optional research workers.
When not to use single-agent-only
- You need simultaneous web crawls across many sources (then isolated workers)
- A regulated review requires independent second pass
- You are measuring multi-agent systems on purpose
Path options
| Path | When |
|---|---|
| Free checklist | Map the OS - Agent OS checklist |
| Skills primer | Contracts that do not rot - skills guide |
| Solo OS | Weekend layout - Agent OS for solo developers |
| Package | Install + handoff - Agent OS Setup |
Bottom line
Prefer one brain and many skills over many brains and no verify.
Your next action: run Skill Library Compile on one repo and replace one multi-role prompt with three skills that each have a verify step.