Skip to content
Skills Library
AI & agents · Automation

workflow-composer

/workflow-composer

MANDATORY: Read this skill before planning or calling search, fetch, or agent when the current task needs its own research, browsing, or judgment for each of 5 or more independent, comparable items (10 or more: always fan out), or when the user asks for comprehensive coverage, parallel research, or subagents. Use `workflow/run` (the `run` tool on the `workflow` MCP server, called with the `mcp` tool using server: `workflow`, name: `run`) to compose those internal units: one dedicated agent per item, structured results aggregated back into the current task. Not for shortlists, one question with

Licence
MIT
Last repository change
28.10.2026

Assessment and security

98/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene13 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 28.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

MANDATORY: Read this skill before planning or calling search, fetch, or agent when the current task needs its own research, browsing, or judgment for each of 5 or more independent, comparable items (10 or more: always fan out), or when the user asks for comprehensive coverage, parallel research, or subagents. Use `workflow/run` (the `run` tool on the `workflow` MCP server, called with the `mcp` tool using server: `workflow`, name: `run`) to compose those internal units: one dedicated agent per item, structured results aggregated back into the current task. Not for shortlists, one question with

Original author description

MANDATORY: Read this skill before planning or calling search, fetch, or agent when the current task needs its own research, browsing, or judgment for each of 5 or more independent, comparable items (10 or more: always fan out), or when the user asks for comprehensive coverage, parallel research, or subagents. Use `workflow/run` (the `run` tool on the `workflow` MCP server, called with the `mcp` tool using server: `workflow`, name: `run`) to compose those internal units: one dedicated agent per item, structured results aggregated back into the current task. Not for shortlists, one question with

How it works

  1. When to use
  2. MCP capability and concurrency contract
  3. Decomposition contract
  4. Map/reduce contract
  5. Discovering the item set
  6. Execution model
  7. Primitives
  8. Structured results
  9. Files
  10. Budget parameters
Original SKILL.md headings · 203 lines, 2,182 words
SKILL.md preview
---
name: workflow-composer
description: "MANDATORY: Read this skill before planning or calling search, fetch, or agent when the current task needs its own research, browsing, or judgment for each of 5 or more independent, comparable items (10 or more: always fan out), or when the user asks for comprehensive coverage, parallel research, or subagents. Use `workflow/run` (the `run` tool on the `workflow` MCP server, called with the `mcp` tool using server: `workflow`, name: `run`) to compose those internal units: one dedicated agent per item, structured results aggregated back into the current task. Not for shortlists, one question with several facets, work a handful of searches can finish, or the same command over many inputs (write one script with bounded concurrency). Also use for loops, conditions, multi-stage map/reduce work, and deterministic subagent orchestration."
---

# Workflow Composer

`workflow/run` in this document means the `run` tool on the `workflow` MCP server: call it with the `mcp` tool using `server: "workflow"`, `name: "run"`.

`workflow/run` executes a deterministic JavaScript orchestration script that coordinates multiple subagents. The whole workflow runs as one background job; its return value is injected into the parent conversation when it finishes.

## When to use

Required condition — every item must clear this bar:

- Each item requires non-trivial independent reasoning, research, browsing, or open-ended tool exploration. Item count alone is never sufficient. Before reaching for `workflow/run`, ask: "could this be a single script looping over the items?" — if yes, write that script and execute it directly with bounded concurrency instead.

With that condition met, use `workflow/run` when any of the following applies:

- The task contains 5 or more independent, comparable items processable concurrently. With 10 or more, fan out instead of working through them yourself.
- The user asks to research, compare, summarize, or analyze many entities with the same output structure.
- The outputs need to be collected into a table, report, ranking, dataset, or other combined deliverable.
- The orchestration needs loops, conditions, retries, staged execution, aggregation, or a large/dynamic fan-out.

Do **not** use it when there are only a few small independent tasks (direct `agent` calls are fine), when the whole task is a shortlist or recommendation, one question with several facets, or work a handful of searches can finish, when the items are answerable immediately from context, when the task is inherently sequential or tightly coupled, or when the per-item work is the same deterministic command or script with different parameters — that is a batch job for one script with bounded concurrency, not a workflow.

## MCP capability and concurrency contract

Before a workflow whose item agents depend on an MCP server, call `server.list` and obey that server description's `Subagents` and `Concurrency` contract.

- Use `sandbox: 'isolated'` when stateful tasks must proceed independently in parallel.
- Give parallel file-producing agents deterministic, distinct output paths.
- Keep operations marked parent-only in the parent agent; subagents cannot make them available by retrying through another interface.
- If a required tool is unavailable or fails, collect and report the blocker. Never fabricate completion, reuse another item's artifact, or substitute a different artifact type unless the task explicitly allows that fallback.

## Decomposition contract

For item-based fan-out:

1. Exactly one dedicated `agent()` call per independent item — never bundle several items into one subagent.
2. The parent agent must not perform item-level research before or alongside the workflow; it orchestrates.
3. Every subagent gets one clearly bounded subject and a fully self-contained prompt.
4. Comparable subagents share the same structured output fields (group `{schema}`).
5. Item agents run inside one named `parallel` group, preserving input order so outputs map back to inputs.
6. Handle individual failures without discarding successful results.

Bad: `agent('Research Nintendo, PlayStation, Xbox, Atari, Sega, …', {brief: 'Research all consoles'})`

Bad: `agent('run enrich.sh item-42')` × 230 — deterministic command fan-out belongs in a single script with bounded concurrency, not in per-item subagents.

Correct:

```javascript
const consoles = ['Nintendo NES', 'PlayStation', 'Xbox', 'Atari 2600', 'Sega Dreamcast']
const results = await parallel('Research consoles', () =>
  consoles.map(name =>
    agent(`Research ${name} and return the requested structured information.`, {brief: `Research ${name}`})
  )
)
```

## Map/reduce contract

When the final deliverable requires cross-item synthesis (comparative report, ranking, merged document, executive summary):

1. Map: one agent per item inside a `parallel` group.
2. Collect: keep successful structured results, record failures.
3. Reduce: exactly one reducer agent over the collected results.
4. Return: reducer output plus useful map results and explicit report paths. Have the parent confirm the files exist and deliver them from the shared sandbox, without re-researching the items.

Count the reducer in both `estimated_agent_calls` and `max_agent_calls`. If deterministic code can combine the results without judgment (joining strings, returning rows), skip the reducer agent.

## Discovering the item set

- Items given by the user → use that list directly.
- Item set scopable from stable domain knowledge → define a reasonable list and state the selection criteria.
- Discovery itself requires research → run one discovery agent with a JSON Schema, read the array from its structured result, then fan out one agent per discovered item. Use a conservative high-side `estimated_agent_calls` and count the discovery agent (and any reducer) in the budgets. Fan out only for work discovery did not already do; if its result already answers the task, stop there.

## Execution model

- The script runs in a sandboxed JavaScript environment with **no I/O**: no filesystem, network, timers, or `require`/`import`. Subagents use their own tools and filesystem.
- The script **must be deterministic**: `Math.random()` and the entire `Date` object (including `new Date(...)` with arguments) are unavailable. Workflows survive restarts by replaying the script against a journal of completed `agent` calls; nondeterministic control flow breaks replay. Vary prompts by stable inputs or array indexes.
- Plain JavaScript control flow (variables, loops, conditionals, array methods, async/await, string/JSON operations) is fully available; the script body may use `await` directly.
- The script's completion value (`return` or last expression) becomes the workflow result.
- Workflow completion is a barrier over every `agent()` call: even if a Promise is not explicitly awaited, the job waits for that subagent to finish. Still use `await` or `parallel()` whenever its result participates in the returned value; an unawaited result is discarded.
- `script` must contain only a syntactically valid JavaScript function body — no Markdown fences or surrounding prose.

## Primitives

- `agent(prompt, {brief, schema, input_files, sandbox, effort_level})` returns a Promise of one subagent result. `brief` is **required** (≤120 chars): a self-explanatory title of what THIS subtask does, written in the user's language and specific to the item — shown verbatim as the subtask's row title in the user-facing task board. Say what is being done to what (e.g. `Scrape ACME pricing page`); never a generic label like `agent 3` / `subtask` / `Product 3`. Prompts must be self-contained (exact item, goal, required fields, source/verification requirements, constraints, expected file paths and output format): the subagent does not see the parent conversation.
- `parallel(brief, factory, {schema}?)` concurrently runs the agent promises returned by `factory` as a named group. `brief` is **required** (≤80 chars): a descriptive group name summarizing the whole batch, shown as the group header. `factory` must be a **function** returning an array of `agent()` promises — a bare promise array is rejected. Optional `{schema}` is the group default JSON Schema: agents created inside without their own `schema` inherit it; a per-agent `schema` overrides it; nested groups use the nearest enclosing schema.
- `log(message)` publishes concise progress, visible via `job` info.

## Structured results

Give every comparable-item group a shared JSON Schema: outputs stay structurally consistent, aggregation is reliable, and the UI renders the group as a table (columns from the schema's `properties`, one row per subagent result).

A successful `value` is already JSON-decoded when the subagent returned valid JSON — **never call `JSON.parse()` on a schema-constrained result**. Results are rejected unless they are valid JSON conforming to the effective schema (own `schema`, else nearest group `{schema}`).

## Files

- Return structured data for aggregation. The current Sandbox Host does not populate durable artifact refs in a child result's `files`; do not rely on `type: "file"` or `previous.files` to deliver or transfer output files. For file-producing work, use shared mode with explicit, unique parent-sandbox paths and have the parent task verify and deliver those files through its normal file tools.
- Declare every child input file explicitly in `input_files`: `{path: '/home/ubuntu/input.csv', name: 'data'}` for an existing parent-sandbox file. ArtifactRef inputs are not supported by the current Sandbox Host. A path merely mentioned in prompt text is never transferred.
- `sandbox: 'shared'` (default) runs subagents in the parent sandbox — give each item a deterministic, collision-free output path. `sandbox: 'isolated'` gives a fresh disposable sandbox for untrusted/heavy work; declared inputs are transferred and the child receives its actual local path.

## Budget parameters

- `effort_level`: default effort for every subagent in the workflow; defaults to `lite`. Each `agent()` may override it with `lite`, `standard`, or `max`. Keep independent research, extraction, and transformation on `lite`; use `standard` for reducers or complex judgment, and reserve `max` for exceptional cases.
  `effort_level` is only supported by the workflow input and each `agent()` options object; `parallel()` group options support only `schema`.

- `max_agent_calls`: requested `agent()` budget (1–2000), not a credit limit. At creation the addon adds `max(2, floor(requested * 0.1))`, capped at 2000. The returned effective limit is persisted as the hard upper bound; restarting does not add another allowance. Report that effective limit when discussing the budget. Put the full intended fan-out in one workflow rather than splitting it into trial batches.
- `estimated_agent_calls`: conservative high-side estimate of calls actually executed (≤ `max_agent_calls`). Count everything: discovery + item/map + reducer + validation agents. Exact count for deterministic lists; realistic high-side estimate for dynamic branches — never intentionally underestimate.
- Agent registrations are paced by the worker, separately from Host execution concurrency. `parallel` expresses independence, not an immediate burst; do not split the workflow to bypass submission pacing.

## Failure policy

Default and recommended for item fan-out: `collect`. Every `agent()` resolves to `{ok: true, value, files}` or `{ok: false, error}` in input order. `error` is `{code, message}` — read the fields; do not interpolate the whole object as a string. Preserve successful results even when some items fail:

```javascript
const successful = results.filter(r => r.ok).map(r => r.value)
const failures = results
  .map((r, i) => (r.ok ? null : {item: items[i], code: r.error.code, message: r.error.message}))
  .filter(Boolean)
```

Use `fail_fast` only when later work would be invalid after any individual failure.

## Confirmation gate

The Host checks confirmation before subagents start: absent an existing auto-start authorization, an estimate or effective budget above 20 requires confirmation (for example, requested 20 becomes effective 22). A pending workflow is **already registered** — never call `workflow/run` again for the same task. Stop the turn and wait; on explicit acceptance use `job` to approve the exact job id, on explicit rejection use `job` to reject it. Never approve without a new user reply. Approval does not remove the saved effective budget.

If the effective budget is exhausted on a compatible Host, the workflow pauses instead of marking the remaining items failed. Do not submit another `workflow/run`. If the effective limit is already 2000, no increase is possible: keep the job paused, inspect retained results and in-flight subtasks with `job list`/`job info`, or use `job kill` to stop. Otherwise, use `job continue` to propose a higher absolute `max_agent_calls` (never above 2000), present that exact total, and repeat it only after a new explicit approving user reply. Never interpret refusal or unrelated input as approval. Completed results are reused. An older Host may instead report that resumable pause is unsupported; do not claim it paused successfully.

## Recommended item-research template

```javascript
const items = [
  {id: 'item-a', name: 'Item A'},
  {id: 'item-b', name: 'Item B'},
  {id: 'item-c', name: 'Item C'}
]

const itemSchema = JSON.stringify({
  type: 'object',
  properties: {
    id: {type: 'string'},
    name: {type: 'string'},
    summary: {type: 'string'},
    key_facts: {type: 'array', items: {type: 'string'}},
    report_path: {type: 'string'}
  },
  required: ['id', 'name', 'summary', 'key_facts', 'report_path']
})

const mapped = await parallel(
  'Research all items',
  () => items.map((item, index) =>
    agent(
      'Research exactly one item: ' + item.name + '.\n' +
      'Verify important facts using authoritative sources.\n' +
      'Return the requested structured fields.\n' +
      'Write the detailed report to /home/ubuntu/reports/' +
      String(index + 1).padStart(2, '0') + '-' + item.id + '.md. ' +
      'Return that exact path in report_path.',
      {brief: `Research ${item.name}`, sandbox: 'shared'}
    )
  ),
  {schema: itemSchema}
)

const successful = mapped.filter(r => r.ok).map(r => r.value)
const failures = mapped
  .map((r, i) => (r.ok ? null : {item: items[i].name, code: r.error.code, message: r.error.message}))
  .filter(Boolean)

const reduced = await agent(
  'Create the final cross-item report using these structured results:\n' +
  JSON.stringify(successful) + '\n' +
  'Include a comparison table, key differences, shared patterns, and a clear conclusion. ' +
  'Save it to /home/ubuntu/reports/final-report.md and return that path in report_path.',
  {
    brief: 'Synthesize final report',
    sandbox: 'shared',
    schema: JSON.stringify({
      type: 'object',
      properties: {report_path: {type: 'string'}, summary: {type: 'string'}},
      required: ['report_path', 'summary']
    })
  }
)

return {items: successful, failures, final: reduced.ok ? reduced.value : null}
```

Budgets for this shape: `estimated_agent_calls = items.length + 1`, `max_agent_calls = items.length + 1`, `failure_policy = collect`.

## Final checklist

Before calling `workflow/run`, verify:

- The task genuinely contains multiple independent units of work — each needing independent research or judgment, not the same deterministic command with different parameters — with one agent per item and no bundling.
- Item prompts are self-contained; comparable agents share a JSON Schema; the group has a clear user-facing brief.
- File paths are deterministic and collision-free; shared-mode outputs are verified by the parent task; inputs are declared as parent-sandbox paths in `input_files`.
- Discovery and reducer agents are counted in the budgets; `collect` failures are handled explicitly.
- The script is valid deterministic JavaScript only.
- The parent agent is orchestrating, not doing item-level work itself.

Versions

The database has no other skills named workflow-composer.

Database snapshot: 13.11.2026 · package version 34c87d62f9fb (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90parallel-delegation
    How to split a task into parallel subagents and pick a model for each. Use when planning or running work with 2 or more independent parts, before calling the Agent tool, and when the user asks for parallelism, subagents or delegation. Do not use for single-part tasks.
  • 100run-workflow
    How to write and run a dynamic workflow script with the `run_workflow` tool: a Python script that orchestrates many agents with `agent`, `parallel`, `pipeline`, and `phase`. Use when a task splits into many independent or staged pieces of agent work (fan out over files, modules,…
  • 100agent-workflow
    Run, watch, stop, resume and report agent-workflow workflows (deep-review, deep-research, spec-review, impact-review or a dynamic workflow) through the agent-workflow MCP tools. Use when the user asks to run a workflow, to review/research/check something "with a workflow" or…
  • 100codex-workflow
    Run deterministic multi-step agent workflows in Codex - fan-out, parallel, schema-validated structured output - via the codex-workflow MCP orchestrator (run_workflow), with native in-chat fallbacks. Use when you want Claude-Code-Workflow-style orchestration in Codex: 'run a…
  • 100run-wave
    Front door for running a multi-item wave of MCP work items through a generated run plan — resolves a frontier of ready/resumed items, derives per-item seat stages from their resolved schemas, opens a server run for them, and executes the plan via the Workflow tool (Method A) or…
  • 95agent-composer
    Reads the current work context and plans the optimal agent dispatch. Clarifies direction with 1-2 questions when unclear; infers and proceeds immediately when execution path is unclear. Runs an automatic recording gate after each Wave completes. Triggered by "compose agents",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.