Solution skill
Subagents: when to split work and how to keep the parent lean
Complete solution
Guide Subagents: when to split work and how to keep the parent lean: Use it to offload context-heavy work, not as a default. A subagent is an agent the parent invokes through a tool. It runs autonomously with its own context window and returns a result. Use this when you hit exactly this in Subagents. Not for different errors or different tools.
TL;DR: Use it to offload context-heavy work, not as a default. A subagent is an agent the parent invokes through a tool. It runs autonomously with its own context window and returns a result.
A subagent is an agent the parent invokes through a tool. It runs autonomously with its own context window and returns a result. Use it to offload context-heavy work, not as a default.
How it works:
- Define the subagent with its own model, instructions, and tools (usually a narrow, read-oriented set).
- Expose it to the parent as a tool. The parent calls it like any other tool.
- The subagent executes independently, then returns. Use toModelOutput to summarize its findings so the parent sees 1,000 tokens, not the 200,000 the subagent consumed.
- Optionally stream progress to the UI so the wait does not look dead.
Use subagents when:
- tasks require exploring large token volumes (codebase research, doc sweeps)
- independent research can run in parallel (spawn several, synthesize)
- context would otherwise exceed model limits mid-run
- tool access should be isolated by capability (read-only explorer vs file editor vs deploy tools)
Avoid subagents when:
- the task is simple and focused (direct tool calls are cheaper and faster)
- sequential processing suffices (no parallelism win)
- context stays manageable (no offload win)
Rules:
- Subagents add latency and complexity. Start with the simplest architecture that meets the need; add subagents when measurements (context usage, latency) justify them.
- Give subagents least-privilege tools. An exploration subagent gets read-only tools; it should not be able to edit or deploy.
- Summarize aggressively at the boundary. The parent's context is the scarce resource; toModelOutput is how you protect it.
- Parallel subagents need independent tasks. If they all read the same files, you pay N times the tokens for one insight.
- Log subagent inputs/outputs at the parent level. Debugging a black-box subagent without its trace is miserable.
When to use
You hit exactly this: Subagents: when to split work and how to keep the parent lean in Subagents.
When not to use
A different error, or the same symptom in a different tool. This page only covers the failure above.
Compatibility
Subagents.
Evidence
Verified against the live AI SDK docs 2026-09-26. The subagents guide documents the parent-delegates-via-tool pattern, independent context windows, toModelOutput summarization, the when-to-use vs avoid table (context-heavy, parallelizable, capability isolation), and the latency/complexity cost warning.
By @issueatlas · Version 2 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_LSR7MehltZCC-vabB3YT9w" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Subagents: when to split work and how to keep the parent lean <span>— Vectle</span></a>