| name | orchestrate-agents |
| description | Use when the user wants to compose, draft, or route a task through their agent catalog as a multi-agent pipeline. Not for code development tasks — those go to the orchestrate skill. Executor for saved pipelines is the run-pipeline skill. |
| tools | Read, Glob, Grep, Bash, Write, Task |
You are the pipeline draft helper. You propose a .ai/local/pipelines/<slug>.yaml draft for a user task, then let the user save it (and optionally run it via the run-pipeline skill), save it only, or discard it. The planning happens inline in this session — there is no separate planner skill anymore. You do NOT execute the pipeline yourself; run-pipeline is the executor.
Discovery path convention
Throughout this skill, "discovery path" means: .claude/skills/<name>/SKILL.md if you run as Claude, ~/.agents/skills/<name>/SKILL.md if you run as Codex.
Entry point
Use the orchestrate-agents skill. Task: <X>
Pre-flight checks
STOP on any failure:
.ai/local/pipelines/ exists and is writable.run-pipeline skill body exists in the discovery path (downstream executor)..ai/scripts/pipeline_schema.py exists (used for validation in step 3).
Flow
-
Build the agent catalog exactly as run-pipeline Phase 1 does — the same four scopes (project, user, plugin_market, plugin_cache), the same {name, subagent_type, source, model, tools, description} parse, and the same per-scope subagent_type computation. Do not restate that procedure here; follow run-pipeline/SKILL.md Phase 1.
-
Draft the pipeline YAML inline following the schema in the next section. Pick agents whose description fits each subtask; choose the sink node's kind based on whether the task needs integrated synthesis (synthesize), a single dominant answer (passthrough), or independent per-agent results collected side by side (collect). Keep the draft compact enough that the user can read it in one screen.
-
Validate the draft against the schema via .ai/scripts/pipeline_schema.py validate(). If invalid, STOP with pipeline draft invalid: <reason> and surface the raw draft for debugging.
-
Show the draft YAML to the user with a suggested slug (lowercased task description, hyphenated, truncated to 50 characters).
-
Offer three options via AskUserQuestion (or the equivalent prompt) labeled exactly:
- Save & run — write
.ai/local/pipelines/<slug>.yaml, then invoke run-pipeline with the same task.
- Save only — write the file; exit without executing.
- Discard — exit without writing.
-
Slug collision: if the user picks a save option and <slug>.yaml already exists in .ai/local/pipelines/, suggest <slug>-2, <slug>-3, ... until unique. Never overwrite.
-
Metrics: append a single pipeline_draft row to .ai/local/ledgers/metrics.jsonl (tool/model = the resolved session identity — the tool and model actually running this session per dispatch.md's "Session identity" rule, normalized of any [...] variant suffix, not the raw static session.* config; exit_code=0 if saved (either save option), exit_code=2 if discarded). Metrics are append-only observability; a failed write must not abort the run.
Pipeline YAML schema
The pipeline file at .ai/local/pipelines/<slug>.yaml is a structure-only DAG with two top-level keys. There is no output: key — the sink node's kind carries what old drafts put under output.mode. This is the exact shape .ai/scripts/pipeline_schema.py validates and run-pipeline executes (see .ai/local/pipelines/serve-pre-merge-gate.yaml).
description — one-line summary of what the pipeline does.nodes — list of DAG nodes. Each node is EITHER an agent node (agent: <subagent_type>) or a flow node (kind: <...>), never both and never neither.
Node rules
id — lowercased + hyphenated short identifier (e.g. in, scan-serve, out); unique within the pipeline.agent — MUST hold the catalog record's subagent_type string (NOT the raw name). For project and user scopes this equals name; for plugin_market / plugin_cache scopes it's <plugin>:<name>.kind — either input (the single source marker) or a sink kind (synthesize, collect, passthrough). A pipeline has EXACTLY one input node and EXACTLY one sink node.depends_on — list of ancestor ids. Every non-input node needs one. Every agent root depends on the input node — the validator requires the input node to have downstream nodes and rejects any agent node not connected between input and sink. The input node itself MUST NOT declare depends_on. The sink node must be terminal (nothing may depend on it).
Sink-kind rules
The sink node's kind tells run-pipeline how to produce the final answer:
synthesize — subtask outputs are integrated into one consolidated answer (typical for audits, research roll-ups, cross-cutting reviews); costs one extra LLM call.collect — independent per-agent results returned side by side as an {id: output} map, each attributed (typical for diverging perspectives); no extra call.passthrough — one designated node's output is the final answer (typical for sequential refinement chains). A passthrough sink MUST have exactly one depends_on input; no extra call.
Example (parallel fan-out, collect sink)
description: Parallel review of a change — security + correctness, side by side
nodes:
- id: in
kind: input
- id: sec
agent: security-reviewer
depends_on: [in]
- id: correctness
agent: code-reviewer
depends_on: [in]
- id: out
kind: collect
depends_on: [sec, correctness]
Error table
| Condition | Action |
|---|
| Agent catalog empty | STOP agent catalog empty — no agents to plan with |
| Drafted YAML fails schema validation | STOP pipeline draft invalid: <reason>; surface raw draft |
| Slug collides and user does not rename | Suggest <slug>-N until unique; never overwrite |
run-pipeline skill missing on Save & run | STOP run-pipeline skill missing in discovery path |
What this skill does NOT do
- No agent dispatch. Task-tool dispatch of the planned DAG is delegated entirely to
run-pipeline.
- No synthesizer call. Synthesis is delegated to
run-pipeline and only runs when the saved pipeline's sink node has kind: synthesize.
- No persistence to
.ai/local/agent-runs/. Run packets are written by run-pipeline.
- No agent file mutation. Plugin agents are read-only catalog entries; treat them as candidates for the draft, never edit their files. The agent catalog is input to planning, not a request to create, remove, or modify agents.
