Orchestrate parallel execution of batch tasks by splitting work into independent units and dispatching them to multiple subagents simultaneously. Use this skill whenever the user has multiple similar independent tasks — such as processing a batch of files (PDFs, DOCX, images, CSVs), developing multiple pages or components, generating multiple reports, or any scenario involving 'each', 'every', 'all', 'batch', or a list of similar items. Also trigger when the user provides a numbered list of tasks, references a folder of files to process, or describes repetitive work across multiple inputs. Even if the user doesn't explicitly say 'parallel' or 'batch', if the work naturally decomposes into 3+ independent units of similar type, use this skill to maximize throughput.
When users present tasks that decompose into multiple independent work units, serial execution wastes time. This skill guides you to identify batch opportunities, construct self-contained prompts for each unit, and dispatch them as parallel subagents via the Task tool — completing in minutes what would otherwise take much longer sequentially.
The core insight: a single message can contain multiple Task tool calls, and they all execute concurrently. Your job is to make each subagent's prompt fully self-contained (they cannot see this conversation) and to coordinate the results.
Strong signals:
Also consider using when:
Do NOT use when:
Before dispatching anything, enumerate what needs to be done:
references/advanced-patterns.md for dependency handling strategies. If all units are independent (the common case), proceed directly.Present your analysis to the user:
Found N work units: [brief list]
Operation: [what will happen to each]
Shared context: [any common dependencies]
Dependencies: [none / description]
Strategy: [single wave / M waves of ~K / pilot + waves]
Wait for user confirmation before dispatching, especially for large batches.
For each work unit, define:
Output path strategy: Create a dedicated output directory to keep results organized:
<project-dir>/multi-task-output/
├── task-001/
├── task-002/
└── ...
Use mkdir -p to create the output directory structure before dispatching.
Each subagent starts with a blank context — it cannot see this conversation. Every prompt must be completely self-contained. Use this template:
## Task [task-ID]: [Brief description]
### Skill Recommendation
[If a matching skill is available]:
You have access to the `/[skill-name]` skill which is ideal for this task.
Invoke it using the Skill tool with skill="[skill-name]" to get specialized
instructions before proceeding.
### Context
[Any shared context the subagent needs — project background, conventions,
templates, reference data. Include the actual content, not references to
"the conversation above".]
### Input
- File: [absolute path]
- [Any other inputs, with absolute paths]
### Instructions
[Clear, step-by-step instructions for what to do]
1. [Step 1]
2. [Step 2]
...
### Output
- Save results to: [absolute path to task-specific output directory]
- Expected deliverables: [list of output files]
- [Any format requirements]
### Important Notes
- Use absolute paths for all file operations
- Do not modify the input file(s)
- If you encounter an error, save error details to [output-dir]/error.log
Prompt quality checklist:
The critical mechanism: Include multiple Task tool calls in a single message. This is what makes them parallel. If you send them in separate messages, they run serially.
For 3-10 tasks: Send all in one message:
[Single message containing:]
Task(subagent_type="general-purpose", prompt="## Task task-001: ...", description="Process file-001")
Task(subagent_type="general-purpose", prompt="## Task task-002: ...", description="Process file-002")
Task(subagent_type="general-purpose", prompt="## Task task-003: ...", description="Process file-003")
...
For 11-50 tasks: Dispatch in waves of 8-10. Wait for each wave to complete before starting the next:
Wave 1: task-001 through task-010 (single message, all parallel)
[Wait for completion, report progress]
Wave 2: task-011 through task-020 (single message, all parallel)
[Wait for completion, report progress]
...
For 50+ tasks: Run a pilot first:
Subagent type selection:
general-purpose (has access to all tools including Skill)BashExploreRun tasks in background when appropriate: For large batches, use run_in_background: true so you can monitor progress and report to the user incrementally.
As results come back:
Wave 1 complete: 9/10 succeeded, 1 failed (task-007: [reason])
Starting wave 2...
After all waves complete:
Batch complete: N/M tasks succeeded
Successful:
- task-001: [output path] — [brief description]
- task-002: [output path] — [brief description]
...
Failed (if any):
- task-007: [error reason] — [suggested fix]
When planning tasks, match each work unit against installed skills. This dramatically improves subagent performance because skills provide specialized, tested instructions.
Matching rules:
| Task involves... | Recommend skill |
|---|---|
| PDF files (read, create, merge, extract) | /pdf |
| Word documents (.docx read, create, edit) | /docx |
| PowerPoint files (.pptx) | /pptx |
| Spreadsheets (.xlsx, .csv, .tsv) | /xlsx |
| Web pages, components, HTML/CSS | /frontend-design |
| Visual design, posters, art | /canvas-design |
| Styling artifacts with themes | /theme-factory |
How to include skill recommendations in prompts:
In each subagent's prompt, add the skill invocation instruction:
### Skill Recommendation
You have access to the `/pdf` skill. Before starting work, invoke it using
the Skill tool: Skill(skill="pdf"). This will load specialized instructions
for PDF processing that will help you complete this task more effectively.
If no installed skill matches, omit the skill recommendation section — the subagent will use its general capabilities.
User: "Extract text from all PDFs in /Users/me/reports/ and save as markdown files"
Analysis:
Found 12 PDF files in /Users/me/reports/
Operation: Extract text from each PDF, save as .md
Shared context: None
Dependencies: None
Strategy: 2 waves of 6
Subagent prompt (each task):
## Task task-001: Extract text from Q1-report.pdf
### Skill Recommendation
You have access to the `/pdf` skill. Invoke it using the Skill tool with
skill="pdf" to get specialized PDF processing instructions.
### Input
- File: /Users/me/reports/Q1-report.pdf
### Instructions
1. Read the PDF file and extract all text content
2. Preserve heading structure where possible
3. Format the output as clean Markdown
4. Include page breaks as horizontal rules (---)
### Output
- Save to: /Users/me/reports/multi-task-output/task-001/Q1-report.md
- Create the output directory if it doesn't exist
User: "Build 5 pages for our marketing site: Home, About, Pricing, Blog, Contact"
Analysis:
Found 5 work units: Home, About, Pricing, Blog, Contact pages
Operation: Generate frontend code for each page
Shared context: Brand guidelines, shared layout components, color scheme
Dependencies: None (each page is independent)
Strategy: Single wave, all 5 parallel
Key considerations:
/frontend-design skill recommendationpages/home/, pages/about/, etc.User: "Convert all CSV files in /data/raw/ to JSON format with proper types"
Analysis:
Found 25 CSV files in /data/raw/
Operation: Parse CSV, infer types, convert to JSON
Shared context: Type inference rules (dates, numbers, booleans)
Dependencies: None
Strategy: 3 waves of ~8-9
Key considerations:
/xlsx skill recommendation (handles CSV)| Problem | Cause | Fix |
|---|---|---|
| Tasks run serially, not parallel | Task calls sent in separate messages | Put ALL Task calls in a single message |
| Subagent says "I don't have context" | Prompt references conversation history | Make prompt fully self-contained |
| File not found errors | Relative paths used | Use absolute paths everywhere |
| Output files overwrite each other | Same output path for multiple tasks | Use task-ID in output directory path |
| Subagent doesn't use recommended skill | Skill instruction unclear | Add explicit Skill(skill="name") call instruction |
| Too many tasks overwhelm the system | Dispatching 50+ at once | Use waves of 8-10 |
| Results arrive in wrong order | Relying on completion order | Sort by task-ID, not completion time |
| One failure cascades to others | Shared state between tasks | Ensure full isolation — separate dirs, no shared files |
For handling tasks with dependencies (linear chains, fan-in/fan-out, partial dependencies), dynamic batch sizing, and conditional dispatch, read references/advanced-patterns.md.