agent-orchestration-skill

name: agent-orchestration-skill description: > Triggers when the master Agent faces a multi-step complex task and is deciding whether / how to outsource sub-tasks to built-in subagents (browser / doc-editor / data-analyst / extractor / canvas-designer / coder, etc.). Not for: single-step Q&A / reads / simple side effects (master Agent handles directly), or scenarios where Agent is already confirmed and subagent_type is known. version: 5.0.0

Subagent Delegation & the Agent Tool

The master Agent can dispatch built-in or custom subagents on demand via the Agent tool, outsourcing specialized sub-tasks. This skill answers four questions: when to delegate, to whom, how to invoke, and what the system constraints are.

Tool Inventory

Loading: Agent is a core tool — always available, no ToolSearch activation required.

Delegation Decision

User message →
  ├─ Simple Q&A / chat / read / query / single-step side effect (create event, send email, create project) → master Agent handles directly
  └─ Multi-step complex task →
      ├─ Web interaction (click/fill form/login/screenshot/paginated scraping) → browser
      ├─ Rich text / long document editing (Markdown, DOCX, PDF) → doc-editor
      ├─ Spreadsheet data analysis / chart generation → data-analyst
      ├─ Structured extraction from PDF / images / web pages → extractor
      ├─ Canvas node operations / layout → canvas-designer
      ├─ Code writing / debugging (global mode only; in project mode the PM does it themselves) → coder
      └─ Mixed task → master Agent decomposes, then delegates to multiple subagents sequentially or in parallel

Don't "delegate everything": simple Q&A, single-step operations, and pure reads should be handled directly by the master Agent. Delegation itself introduces context-passing overhead and extra steps — for small tasks the cost outweighs the benefit.

Six Built-in Subagents

Each subagent has its own system prompt and tool set, with step counts tuned to the task profile.

Agent Tool Invocation

Agent { description: "Scrape product table from site A", prompt: "...", subagent_type: "browser" }

The Agent tool waits synchronously by default for the subagent to complete and return — after calling, you immediately get the output and proceed to the next step; no extra wait tool needed.

SendMessage: Follow-up Instructions

When a subagent is already running but needs additional instructions or a course correction:

SendMessage { toolCallId: "agent-xxx", message: "Additional requirement: output results in JSON format" }

SendMessage auto-resumes a stopped agent — no need to recreate via Agent, avoiding the cost of re-passing the full context.

Parallel Fan-out & Aggregation

When sub-tasks are independent of each other, issue multiple Agent calls in the same turn; each returns synchronously, and the master Agent aggregates:

Master Agent decomposes task → issues in parallel:
  Agent { description: "Scrape site A", subagent_type: "browser", prompt: "..." }
  Agent { description: "Scrape site B", subagent_type: "browser", prompt: "..." }
  Agent { description: "Scrape site C", subagent_type: "browser", prompt: "..." }
  ↓ Each returns synchronously: A / B / C
Master Agent aggregates → final response

Good for parallel: sub-tasks are independent and parallelism meaningfully shortens total runtime. Not for parallel: later tasks depend on earlier tasks' output (serial dependency); total count exceeds the concurrency limit of 4 and needs batching.

Context Inheritance

Subagents automatically inherit from the master Agent:

• projectId — same project sandbox; path permissions and file access stay consistent
• Skills tied to pageContext — the subagent sees the same capability awareness (if the master Agent creates an extractor on the email page, the extractor also sees email-ops)
• Temporary project path — if the master Agent has created a temp project, subagents share that directory

This means you don't need to repeat environment information in the prompt — the subagent can derive it from inherited context.

System Hard Limits

Subagent streaming output is pushed to the frontend via data-sub-agent-start / delta / chunk / end events. Each toolCallId corresponds to one independent stream, supporting multiple concurrent subagents streaming simultaneously. State transitions: output-streaming → output-available | output-error.

Common Misjudgments

• Don't nest hierarchically: subagents cannot spawn further subagents. When deeper nesting seems needed, re-decompose so the master Agent invokes multiple subagents in sequence.
• Don't pick the wrong type: for page interaction choose browser; to merely read a static page use WebFetch (the master Agent can call it directly); for OCR choose extractor; for precise DOM manipulation choose browser.
• Don't re-Agent when one already exists: use SendMessage to append instructions and reuse the existing context.
• Don't delegate simple tasks: a single read, a single query, a single create — the master Agent doing it itself is far faster than delegating.