create-workflow

Files (1)

• SKILL.md

SKILL.md (first lines)

## Codex execution

This skill describes another host. Claude Code/OpenCode commands, configuration, and hook examples below are artifacts for that host, not tools available in Codex. Use Codex tools to inspect or author them; launch the target host only when the user requests execution and it is installed. Do not configure Codex as Claude Code.

Here $ARGUMENTS means the user’s supplied skill arguments. Codex does not populate a shell variable for them. Pass arguments with shell quoting that preserves literal text; never evaluate user text as shell code.

## User Input

```text
$ARGUMENTS
```

When the user invokes `$claude-code:create-workflow`, help them produce a saved,
reusable workflow for the task in `$ARGUMENTS`. If empty, ask what repeatable
multi-agent task they want to codify.

**Always run the decision gate first** — most tasks should *not* be a workflow.
Only proceed to authoring when the gate says a workflow is the right tool.

---

## Step 1 — Decision gate (do this before anything else)

A workflow is the heaviest of four primitives. The real difference is **who holds
the plan**. Steer the user to the lightest tool that fits.

| Use… | When | Plan held by |
|------|------|--------------|
| **Skill** | Reusable *instructions* one agent follows | Claude, following the prompt |
| **Subagent** | Offload one focused side-task; only the summary matters | Claude, turn by turn |
| **Agent team** | A few workers that must **talk to each other** / challenge findings | Lead + teammates, turn by turn |
| **Workflow** | **Repeatable, codified** fan-out to **dozens–hundreds** of agents | The **JavaScript script** |

Pick a **workflow** only when *all* of these hold:

- The orchestration is worth **codifying and rerunning** (a per-branch review, a
  recurring audit), not a one-off.
- The task needs **more agents than one conversation can coordinate** — bug
  sweeps across a repo, 500-file migrations, research cross-checked across many
  sources, drafting a plan from several independent angles.
- You want intermediate results to stay in **script variables**, keeping Claude's
  context holding only the final answer.

If the user just needs collaboration between a handful of agents, that's an
**agent team** (`$claude-code:agent-teams`). If they want reusable instructions,
that's a **skill** (`/claude-code:...` via the skill catalog). If it's a single
delegated lookup, that's a **subagent**. Say so and stop.

> Subagents are the worker primitive a workflow orchestrates; an agent team can
> reuse subagent *definitions* as teammate roles. Workflows don't "call skills" —
> the agents they spawn load skills by context, the same as any session.

## Step 2 — Frame the task for the runtime

Workflows have a fixed shape you must design *for*, not against:

- **The script coordinates; agents do the work.** The script itself has **no
  filesystem or shell access** — only its spawned agents read, write, and run
  commands. Frame the task as "fan out N agents, each does X, collect/compare
  results," not "the script edits files."
- **Codify a quality pattern, not just parallelism.** The payoff over plain
  subagents is repeatable structure: have agents **adversarially review** each
  other's findings, or draft a plan from several angles and weigh them, before
  reporting.
- **Stage gating needs separate workflows.** There is **no mid-run user input** —
  a run pauses only for agent permission prompts and, from v2.1.271, a
  usage-limit wait. For sign-off between stages, run each stage as its own
  workflow.
- **Respect the caps:** up to **16 concurrent agents** by default (fewer on
  low-CPU machines; `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` sets 1–256 on
  v2.1.269+), **4,096 items** per `parallel()`/`pipeline()` call, and **1,000
  agents total per run**. Scripts cannot use `import()`. Design the fan-out to
  fit.

## Step 3 — Have Claude write it

You don't hand-author the JavaScript — **Claude writes the script** from the task
description. Trigger it one of two ways:

- **Single task:** include the keyword **`ultracode`** in the prompt (or just say
  "use a workflow"). Example: `ultracode: audit every API endpoint under
  src/routes/ for missing auth checks`.
- **Whole session:** `/effort ultracode` — Claude plans a workflow for every
  substantive task until the session ends or you turn it off with
  `/effort ultracode off` (v2.1.284+, where Ultracode is a toggle; earlier
  versions drop back by choosing another effort level such as `/effort high`).

Claude shows the planned phases and asks to approve before running (the prompt's
frequency depends on permission mode; `Ctrl+G` opens the script, `Tab` edits the
prompt first). Iterate on the task description until a run does what you want.

> The run writes its script to a file under `~/.claude/projects/` and Claude gets
> the path — ask for it to read, diff, or edit the orchestration directly.

## Step 4 — Save for reuse

Once a run is good, save its script as a command: run `/workflows`, select the
run, press **`s`**, and `Tab` to pick the location:

| Location | Scope |
|----------|-------|
| `.claude/workflows/` | **Project — committed to the repo, shared with everyone who clones it** |
| `~/.claude/workflows/` | Personal — every project, only you |

Saved workflows run as `/<name>` and appear in `/` autocomplete alongside
built-ins like `/deep-research`. If a project and personal workflow share a name,
the **project** one wins.

**Monorepo (v2.1.178+):** saving to the project location writes to the closest
existing `.claude/workflows/` between your cwd and the repo root (or the repo root
if none exists). Workflows load from *every* `.claude/workflows/` along that path;
on a name clash the one nearest your cwd runs.

## Step 5 — Parameterize with `args`

A saved workflow reads invocation input from a global named **`args`**:

```text
> Run /triage-issues on issues 1024, 1025, and 1030

From nq-rdl/agent-extensions, CC-BY-4.0.

More from nq-rdl/agent-extensions