orchestrating-task-agents

Orchestrating Task Agents

Best practices for the main agent when delegating work to Task agents (sub-agents).

When to Use Subagents vs Main Conversation

Keep in main conversation when:

• Task needs frequent back-and-forth or iteration
• Multiple phases share significant context
• Making quick, targeted changes
• Latency matters (subagents start fresh, need time to gather context)

Delegate to subagent when:

• Task produces verbose output (test runs, log analysis, doc fetches)
• Work is self-contained and can return a summary
• Want to preserve main conversation context for other work
• Running parallel independent investigations

Consult this skill when:

• About to launch 3+ Task agents
• Batch processing files (transform, validate, migrate)
• Sub-agents need to invoke skills (requires explicit Skill tool syntax — they won't invoke automatically)
• Coordinating research → plan → implement phases
• Uncertain about agent type selection

Core Principles

1. Explicit over implicit — Task agents need exact instructions, not hints
2. Context is critical — Include file paths, constraints, and expectations
3. Parallel when possible — Launch independent tasks in a single message
4. Right agent for the job — Choose the appropriate agent type

Quick Reference

Prompt structure:

• <context> — Background, file paths, constraints
• <task> — What to accomplish
• <output_format> — How to structure results

Agent types:

• Explore — Research, file searches (default for read-only)
• Plan — Design implementation before coding
• Bash — Terminal commands only
• general-purpose — Implementation requiring write access

Models:

• haiku — Fastest (Explore default)
• sonnet — Balanced
• opus — Most capable
• inherit — Match main conversation

Parallel: Single message with multiple Task tool calls Sequential: Wait for results before dependent tasks

Skill Invocation Syntax (CRITICAL)

Task agents don't automatically invoke skills. You must provide explicit Skill tool syntax.

What DOESN'T Work

"Use the auditing-citations skill to verify these claims"

The task agent receives this instruction but doesn't know to call the Skill tool.

What WORKS

Verify these citations.

To access the citation verification workflow, invoke the Skill tool:
  Skill(skill: 'auditing-citations')

The skill provides structured verification templates and red flag criteria.

Template for Skill Invocation

When delegating a task that should use a skill, include this pattern:

<task>
[Description of what the agent should accomplish]
</task>

<skill_invocation>
Invoke the [skill-name] skill using the Skill tool:
  skill: "[skill-name]"
  args: "[optional arguments if needed]"

This skill provides: [brief description of what the skill offers]
</skill_invocation>

<output_format>
[What the agent should return]
</output_format>

Task Prompt Structure

Use XML tags for clear structure:

<context>
[Background information, file paths, constraints]
</context>

<task>
[Explicit instructions - what exactly to do]
</task>

<output_format>
[How to structure the response]
</output_format>

Be Explicit, Not Vague

Vague (Less Effective)	Explicit (More Effective)
"Look at the code"	"Read src/auth/login.ts and identify the validation logic"
"Fix the bug"	"The login fails when email contains '+'. Fix the regex in validateEmail()"
"Use the skill"	"Invoke the Skill tool: Skill(skill: 'skill-name')"
"Improve this"	"Add error handling for network timeouts in fetchUser()"

Add Context/Motivation

Explain WHY the task matters:

<context>
We're auditing citations before product launch. Accuracy is critical because
incorrect claims could violate FTC guidelines.
</context>

<task>
Verify the research citations in articles/chronic-pain.md
</task>

Agent Type Selection

Agent Type	Use When	Tools Available
Explore	Quick codebase searches, finding files, understanding patterns	Read-only tools
Plan	Designing implementation, architectural decisions	Read-only tools
Bash	Git operations, running commands, terminal tasks	Bash only
general-purpose	Complex multi-step work requiring all capabilities	All tools

Custom Agents (agents/ directory)

User-defined agents have their own tool configurations. If an agent lacks Write/Edit, it may use bash workarounds that trigger permission prompts.

See ./references/custom-agent-coordination.md for:

• Tool access verification patterns
• Coordination pattern (agent returns content → main agent writes)
• Post-task feedback loops for improving agent configs

Selection Guidelines

• Default to Explore for research and file searches
• Use Plan when you need implementation design before coding
• Use Bash for isolated command execution
• Use general-purpose only when the task requires writing/editing files

Model Selection

When launching Task agents, you can specify model:

Model	Characteristics
haiku	Fastest, good for simple searches
sonnet	Balanced capability and speed
opus	Most capable, best for complex reasoning
inherit	Match main conversation model

If cost matters: Use haiku for simple searches, sonnet for implementation, opus for complex analysis.

If cost doesn't matter (e.g., Claude Max): Default to opus for best results across all tasks. Speed is the only tradeoff.

Note: Explore agents default to haiku. Override with model: opus if you want more nuanced analysis.

Coordination Patterns

Parallel Tasks (Independent)

Launch multiple agents in a single message when tasks don't depend on each other:

[Task 1]: Explore agent to find authentication patterns
[Task 2]: Explore agent to find API endpoint structure
[Task 3]: Explore agent to find test patterns

All three run simultaneously, maximizing efficiency.

Sequential Tasks (Dependent)

Wait for results when later tasks depend on earlier ones:

Step 1: Explore agent finds relevant files
Step 2: (After results) Plan agent designs implementation
Step 3: (After approval) General-purpose agent implements

Fan-Out Pattern

When the same operation applies to multiple items:

For each of these 3 files, launch an Explore agent:
- src/auth/login.ts
- src/auth/register.ts
- src/auth/reset.ts

Each agent analyzes validation patterns in its assigned file.

Background vs Foreground Execution

Foreground (default): Blocks main conversation, can prompt for permissions.

Background: Runs concurrently. Important limitations:

• Auto-denies permissions not pre-approved
• MCP tools unavailable
• Can resume failed agents in foreground later

When to run in background:

• Long-running analysis you don't need immediately
• Tasks where permissions are already approved
• Parallel research that shouldn't block other work

Tip: Press Ctrl+B to background a running task.

Resuming Agents

Each Task invocation creates fresh context by default. To continue previous work, ask to resume:

Continue the previous code review and now analyze authorization logic

Resumed agents retain full context (tool calls, results, reasoning). Useful for:

• Extending analysis based on initial findings
• Retrying failed background agents in foreground
• Multi-turn delegation where context matters

Context Passing

What to Include

• File paths (absolute or relative to project root)
• Relevant code snippets or function names
• Constraints and requirements
• Expected output format
• Any skills the agent should invoke

What to Omit

• Full conversation history (agents have context awareness)
• Redundant explanations
• Unrelated background information

Common Mistakes

1. Forgetting Skill Invocation Syntax

Wrong: "Use the citation-audit skill"

Right: "Invoke the Skill tool: Skill(skill: 'auditing-citations')"

2. Over-Parallelizing Dependent Tasks

Wrong: Launching Plan and Implementation agents simultaneously

Right: Wait for Plan results before launching Implementation agent

3. Vague Instructions

Wrong: "Look into the auth system"

Right: "Read src/auth/*.ts and identify how session tokens are validated"

4. Missing Output Format

Wrong: "Analyze the code"

Right: "Analyze the code and return a markdown table with columns: Function, Purpose, Concerns"

5. Wrong Agent Type

Wrong: Using general-purpose for simple file searches

Right: Using Explore for searches, reserving general-purpose for implementation work

6. Task Agents Using Bash for File Operations

Task agents sometimes use cat heredocs instead of Write tool, triggering permission prompts.

Mitigations:

• For custom agents: see ./references/custom-agent-coordination.md
• For built-in general-purpose agents: explicitly instruct "Use the Write tool, not bash commands"

7. Command Variations Triggering Re-Approval

Minor command variations (like adding 2>/dev/null) don't match previously approved commands, causing repeated permission prompts.

Mitigations:

• Specify exact command patterns in task prompts when consistency matters
• Have main agent run commands that need specific approval patterns

8. Expecting Subagents to Spawn Subagents

Limitation: Subagents cannot spawn other subagents.

Wrong: Expecting a task agent to delegate subtasks to other agents

Right: Chain from main conversation:

1. Agent 1 completes → returns results
2. Main agent launches Agent 2 with Agent 1's results
3. Repeat as needed

Reference Files

• ./references/task-prompt-templates.md — Copy-paste ready templates for common scenarios
• ./references/custom-agent-coordination.md — Patterns for coordinating user-defined agents (tool access, feedback loops)
• ./references/prompt-engineering-tips.md — Curated tips from official Claude documentation