| name | subagent-orchestrator |
| description | Delegate large work to subagents safely. Use for codebase mapping, bug tracing, security review, test gap analysis, performance review, and research. Trigger on /subagent-orchestrator, or when a task is too large for a single agent pass. |
| user-invocable | true |
| allowed-tools | Read, Grep, Glob, Bash, Edit |
Subagent Orchestrator
Delegate large or parallel work to subagents while keeping the main agent in control.
When to Use Subagents
- Codebase map — exploring unfamiliar areas of a large codebase.
- Bug trace — tracing a code path across many files.
- Security review — scanning for vulnerabilities, credential leaks, injection risks.
- Test gap review — identifying untested code paths.
- Performance review — profiling, identifying bottlenecks.
- Documentation and research — gathering context from docs or external sources.
When NOT to Use Subagents
- Tiny single-file edits.
- Tasks that require consistent state across multiple file edits (risk of conflicts).
- Trivial lookups that can be done with Grep/Glob directly.
Subagent Prompt Template
Every subagent prompt must include:
Goal: <what to accomplish>
Context: <relevant background, file paths, domain knowledge>
Scope: <exact boundaries — what files, what aspects>
Forbidden: <what NOT to do — e.g. "do not edit files", "do not run destructive commands">
Tools: <allowed tools — default: Read, Grep, Glob, Bash>
Output: <expected deliverable format>
Validation: <how the main agent will verify the output>
Budget: <estimated complexity, time guidance>
Coordination Rules
- Subagents should not edit files unless explicitly scoped to do so.
- The main agent integrates all findings. Do not merge subagent output blindly.
- Do not spawn multiple subagents that edit overlapping files.
- If a subagent result conflicts with another, the main agent resolves the conflict.
- Track subagent tasks in a shared ledger to avoid redundant work.
Experience Log
This skill learns from experience. Mechanism:
-
Read .claude/experience/subagent-orchestrator.md at skill start to benefit from past lessons.
-
Write to .claude/experience/subagent-orchestrator.md after use if you learned something new.
-
Format: YYYY-MM-DD: <lesson> — one line per entry.
-
Evolve: If the same issue repeats 3+ times, update this SKILL.md itself.
This skill improves over time. After each use, append lessons learned.
Record format: YYYY-MM-DD: <lesson>
Read this at skill start to apply past lessons.
