Document Swarm
Spin up a documentation team (Technical Writer + Architecture Describer + Examples Writer) to generate or update READMEs, runbooks, API docs, and architecture overviews.
How It Works
- Document a project: READMEs · runbooks · API docs · CLAUDE.md files · AGENTS.md
- Preflight + directory manifest: Audit stale docs · enumerate every dir that gets a CLAUDE.md
- Spawn 5 agents
- Integrate analysis: Fold invariants & security notes into CLAUDE.md + AGENTS.md
- Verify docs: README real · CLAUDE.md per dir ≥30 lines · examples & analysis present
- Docs PR: READMEs · runbook · ADRs · per-dir CLAUDE.md · AGENTS.md
Invocation Triggers
/document-swarmwrite docsgenerate READMEupdate runbookdocument projectUse Cases
- Generate complete documentation for a new project from code
- Update stale docs after a major refactor
- Create a runbook for a service that has none
The Problem
Documentation is always last and always stale. Engineers write it for the code they shipped last month. The architecture diagram describes a system that no longer exists. The runbook is missing the one step that matters at 2am. The README hasn't been updated since the initial commit. Document Swarm writes documentation when it matters — the day you ship the feature, while the code is still fresh.
What It Does
- 1Preflight audit
Checks what documentation already exists and how stale it is. Compares last modified timestamps of docs vs code — surfaces the gap before writing anything.
- 2Spawn 4 agents in parallel
Technical Writer, Architecture Describer, Examples Writer, and Runbook Author are dispatched simultaneously. Each owns a different documentation layer — no overlap.
- 3Technical Writer: README + API docs
Writes or updates README (get running in under 10 minutes), API documentation for every endpoint (method, path, request/response shapes), and CONTRIBUTING.md.
- 4Architecture Describer: architecture + runbook
Maps components, data flow, and external dependencies into architecture.md. Writes runbook.md for oncall — how to start/stop/restart, common failure modes, escalation path. Audience: someone who has never touched this code at 2am.
- 5Examples Writer: copy-paste-ready code
Identifies the top 5-10 use cases and writes self-contained, working examples for each. Every example includes error handling. All examples must run without modification.
What You Get / What It Doesn't Do
- Updated README that gets a new engineer running in under 10 minutes
- architecture.md with component diagram, data flow, and key decisions
- runbook.md for oncall with failure modes and escalation path
- Copy-paste-ready examples for top use cases that actually run
- CONTRIBUTING.md with local setup and PR process
- Keep docs in sync automatically — this is a one-pass write, not continuous sync
- Write code comments or inline documentation
- Validate that examples work in production — it tests them locally only
- Replace domain expertise — it documents what the code does, not what it should do
Tips
Write the runbook for someone who has never touched this code and is woken up by an alert. If they would need to ask a question to use it, add the answer.
Test every example by running it before the PR is created. A broken example is an active trap for the next developer.
Documentation debt compounds. A quarterly doc pass is cheaper than an emergency doc sprint before a major release.
Get the Skill
Unlock the full Document Swarm SKILL.md — drop it into ~/.claude/skills/ and trigger it by name.
- Updated README that gets a new engineer running in under 10 minutes
- architecture.md with component diagram, data flow, and key decisions
- runbook.md for oncall with failure modes and escalation path
- Copy-paste-ready examples for top use cases that actually run
29 more production skills ready to install.