majiayu000 Subagent Best Practices
Auto-inject when: User mentions "subagent", "Task tool", "spawn agent", "parallel"
⛔ HARD STOP: No Claude Subagents
NEVER use Claude models (Haiku, Sonnet, Opus) as subagents.
| ❌ FORBIDDEN | ✅ ALLOWED |
|---|---|
model="haiku" |
model omitted (default) |
model="sonnet" |
general-purpose agent |
model="opus" |
MiniMax, GLM, Kimi K2.5 |
Preferred subagents: Kimi K2.5 (complex), GLM (creative), MiniMax (fast)
Enforced: .claude/settings.local.json deny rules
Two-Tier Model
| Tier | Role | Does | Doesn't |
|---|---|---|---|
| Claude | Orchestrator | Reason, decide, write code | Explore, bulk read |
| Subagent | Worker | Explore, research, batch ops | Make final decisions |
See .claude/roles/ROLES.md for full details.
Provider Selection
| Task | Provider |
|---|---|
| Complex reasoning | Kimi K2.5 |
| Vision (batch) | Kimi K2.5 |
| Creative | GLM-4.7 |
| Fast/simple | MiniMax |
See /skill delegation for full matrix.
Subagent Prompt Template
You are tasked with:
{Specific subtask description}
Search scope: {directories/files}
Output format: {table/list/JSON}
Return ONLY the requested output, nothing else.
Parallel Execution
Launch independent tasks in single message:
Task(prompt="Research X") ←─┐
Task(prompt="Research Y") ←─┼─ Same message = parallel
Task(prompt="Research Z") ←─┘
Don't chain sequentially when parallel is possible.
Background Execution (Token Suspension)
For tasks >30 seconds: Use run_in_background=true + end turn.
| Execution Mode | Token Cost | UX |
|---|---|---|
| Blocking | High (Claude waits) | Seamless |
| Background + continue | Medium | Seamless |
| Background + end turn | Low | Requires re-prompt |
Fire-and-Retrieve Pattern
1. Task(prompt="...", run_in_background=true) → gets task_id
2. Claude ends turn: "Dispatched. Say 'continue' for results."
3. User prompts → TaskOutput(task_id="...", block=true)
4. Claude synthesizes
Why it saves tokens: Ending Claude's turn stops the token meter. Subagent tokens are 50x cheaper than Claude tokens.
Quick Checklist
Before spawning:
- Can I decompose into independent chunks?
- Clear deliverables defined?
- Right provider for task type?
When spawning:
- Specific prompt with scope
- Single message for parallel tasks
- No Claude models
After results:
- Aggregate without re-running
- Claude makes final decision
[Opus 4.5 - 2026-01-29]