claude-code-workflow-creator
A Claude Code skill for authoring Workflow tool scripts: deterministic multi-agent orchestration. Preview of an unreleased feature.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/ray-amjad--claude-code-workflow-creator)HTML
<a href="/listings/ray-amjad--claude-code-workflow-creator"><img src="/api/listings/ray-amjad--claude-code-workflow-creator/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Copy the skill into your global Claude Code skills folder:
git clone https://github.com/ray-amjad/claude-code-workflow-creator.git mkdir -p ~/.claude/skills cp -R claude-code-workflow-creator ~/.claude/skills/workflow-creator
That is all. The next time Claude Code starts, the skill is available. Ask Claude to "create a workflow" and it will trigger.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 341 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: workflow-creator
- description: >-
- Author runnable workflow scripts for Claude Code's Workflow tool — deterministic
- multi-agent orchestration files that fan out fresh-context subagents under plain
- JavaScript control flow. Use this skill whenever the user wants to create, write,
- build, scaffold, design, or fix a workflow: "make a workflow", "create a workflow
- for X", "write a workflow", "turn this into a workflow", "scaffold a multi-agent
- pipeline", "orchestrate this with subagents deterministically", or any request to
- author or edit a .js file under .claude/workflows/. Also use it when the user is
- confused about the workflow script format — the meta block, agent()/parallel()/
- pipeline()/phase(), schemas, the determinism rules — or when a workflow errors and
- needs debugging. Trigger this even when the user only describes a repeatable
- multi-step or parallel job and seems to want it packaged as a workflow, even if
- they never say the word "workflow". Do NOT use it to merely run an existing
- workflow, or for a one-off single-subagent task.
- ---
- # Workflow Creator
- Turn a goal into a **runnable workflow file** — a JavaScript orchestrator for
- Claude Code's `Workflow` tool.
- A workflow fans work out to fresh-context subagents under **deterministic
- JavaScript** control flow: the loops, the conditionals, the fan-out are plain
- code, and only the leaf `agent()` calls spend model tokens. The Workflow tool is
- new and undocumented, so this skill carries the format, the judgment calls, and a
- tested authoring procedure. Use it to write a new workflow, convert a multi-step
- job into one, or fix a broken script.
- The deep material lives in two reference files — read them when the step says so:
- - `references/api-reference.md` — the complete manual: every global, every option,
- every cap and constant, what happens at each limit.
- - `references/patterns.md` — copy-paste orchestration patterns (fan-out, pipeline,
- loop-until-budget, adversarial verify, judge panel, nested workflow).
- Starter files are in `assets/templates/`. Six complete, runnable example
- workflows are in `assets/examples/` — `assets/examples/README.md` maps each one
- to a topology and to the model / structured-output techniques it shows. A linter
- is in `scripts/`.
- ---
- ## Step 0 — Confirm the Workflow tool is available
- A workflow can only **run** if the Workflow tool is enabled. It is **off by
- default**, gated behind an environment variable. You can always *write* the file,
- but check this so you can tell the user the truth about running it:
- ```bash
- echo "${CLAUDE_CODE_WORKFLOWS:-<not set>}"
- ```
- If it is not set, the workflow file is still worth writing — but tell the user
- they must enable the tool before it will run, either of:
- ```bash
- # per session
- export CLAUDE_CODE_WORKFLOWS=1 && claude
- ```
- ```jsonc
- // or persistently, in .claude/settings.local.json
- { "env": { "CLAUDE_CODE_WORKFLOWS": "1" } }
- ```
- Workflow files live in `.claude/workflows/<name>.js` (project-local) or
- `~/.claude/workflows/<name>.js` (global). The filename is not the workflow name —
- the `name` inside the `meta` block is.
- ---
- ## Step 1 — Decide whether a workflow is even the right tool
- Do not reach for a workflow by default — it is the heaviest option and it is
- gated for a reason (it can spend a lot of tokens). Pick deliberately:
- | The job | Right tool |
- |---|---|
- | One subagent, one task | The plain **`Agent`** tool — no workflow |
- | A reusable procedure where **Claude** picks the steps each run | A **Skill** |
- | Many subagents in a **fixed** shape (fan-out / pipeline / loop), same every run, worth resuming | A **Workflow** ✅ |
- A workflow earns its cost when **all** of these are true: the work is parallel or
- multi-stage; you want the orchestration deterministic and resumable; and
- isolating each step in its own fresh context window is an advantage. If you are
- unsure, say so and offer the lighter option instead.
- ---
- ## Step 2 — Find the shape of the job
- Before writing a line of code, answer these. The answers pick the topology for you.
- 1. **What is the unit of work?** The thing one subagent does once — review one
- file, research one question, draft one platform. Name it concretely.
- 2. **How many units, and is the count known up front?** A known list → map over
- it. An unknown count (discovery, "find all the bugs") → a loop.
- 3. **What is the topology?**
- - Independent units, one pass each → **fan-out**.
- - Units flow through ordered stages (review → verify) → **pipeline**.
- - Keep going until a target count or a budget runs low → **loop**.
- 4. **Does any later step need *all* the earlier results at once** — to dedup,
- merge, count, or early-exit on a zero total? If yes, you need a **barrier**.
- If no, you do not — and you should prefer `pipeline`.
- 5. **Does a step need structured data back** (not free text)? Then that
- `agent()` call needs a `schema`.
- Write these five answers down for the user before coding. They are the design.
- ---
- ## Step 3 — The decision that matters most: `pipeline` vs `parallel`
- This is the call people get wrong, so make it explicitly.
- - **`pipeline(items, stage1, stage2, …)` is the default for multi-stage work.**
- Each item flows through every stage on its own — **there is no barrier between
- stages**. Item A can be in stage 3 while item B is still in stage 1.
- Wall-clock = the slowest single item's whole chain, not the sum of the slowest
- stage at each step.
- - **`parallel(thunks)` is a barrier.** It waits for every task before returning.
- Reach for it **only** when a stage genuinely needs the *entire* previous
- result set in hand — dedup across all findings, merge, a count-based
- early-exit. "It is cleaner code" or "the stages feel separate" are **not**
- reasons — a pipeline models separate stages fine.
- Smell test: if you would write `const a = await parallel(...)`, then a plain
- transform (`flat`/`map`/`filter`) with no cross-item dependency, then another
- `parallel(...)` — that middle transform does not need the barrier. Make it a
- pipeline stage instead. **When in doubt, `pipeline`.**
- ---
- ## Step 4 — Write the file
- A workflow file has exactly two parts, in this order. The parser is strict.
- ### Part 1 — the `meta` block (must be the very first statement)
- ```js
- export const meta = {
- name: 'review-changes', // required, non-empty
- description: 'Review changed files, verify each finding', // required — shown in the permission dialog
- whenToUse: 'Before shipping a branch', // optional — shown in the workflow list
- phases: [ // optional — one entry per phase() call
- { title: 'Review' },
- { title: 'Verify', model: 'haiku' },
- ],
- }
- ```
- `meta` **must be a pure literal** — no variables, function calls, spreads, or
- template strings inside it. Build dynamic values in the body, never in `meta`.
- Use the same phase `title` strings in `meta.phases` as in your `phase()` calls.
- ### Part 2 — the body (async JavaScript)
- Everything after `meta` is the body. It runs inside an `async` function, so you
- `await` at the top level. These globals are injected — **do not import anything**:
- | Global | Purpose |
- |---|---|
- | `agent(prompt, opts?)` | Spawn one fresh-context subagent. Returns its final text, or a validated object if `opts.schema` is set. Returns `null` if the user skips it. |
- | `pipeline(items, s1, s2, …)` | Run each item through all stages, no barrier between stages. The default for multi-stage work. |
- | `parallel(thunks)` | Run an array of **functions** `() => Promise` concurrently. A barrier. |
- | `phase(title)` | Group the agents that follow under a heading in `/workflows`. |
- | `log(msg)` | Emit a narrator line above the progress tree. |
- | `console` | A standard-looking `console` — its output is routed into the workflow log. |
- | `budget` | `{ total, spent(), remaining() }` — token target for budget-aware loops. |
- | `args` | Whatever was passed as the Workflow tool's `args` input — but the runtime **serializes it to a string** before the script sees it (so a JSON object/array arrives as JSON *text*, not a live value). `undefined` if nothing was passed. Normalize it before reading fields (see below). |
- | `workflow(name, args?)` | Run another workflow inline. One level of nesting only. |
- The body's `return` value becomes the tool result handed back to Claude.
- > **Normalize `args` before reading fields.** Empirically (probed 2026-05-29), the
- > runtime **serializes `args` to a string** before the script runs — even when you
- > pass a JSON object or array via the tool's `args` field, the script's `args` is
- > the JSON *text*, so `args.minUsers` / `args.map(...)` do **not** work directly.
- > `Workflow({ args: { minUsers: 5 } })` gives the script the **string**
- > `'{"minUsers":5}'`; nothing passed gives `undefined`. The one normalizer below
- > covers every case — it parses a JSON string and is still correct if a future
- > runtime ever passes a live object through:
- >
- > ```js
- > // A JSON string parses to an object/array; plain text and `undefined`
- > // fall through unchanged; a live object (future-proofing) passes straight through.
- > const input = typeof args === 'string'
- > ? (() => { try { return JSON.parse(args) } catch { return args } })()
- > : args
- > const threshold = input?.minUsers ?? 20
- > ```
- >
- > Keep the `typeof === 'string'` guard rather than calling `JSON.parse(args)`
- > unconditionally: a bare-text arg (`"build a todo app"`) isn't valid JSON, and the
- > guard also protects you if the runtime's serialization behavior changes.
- ### Setting a model, and getting structured data back — the two `agent()` opts you tune most
- **Model — `agent(prompt, { model })`.** Each agent call runs on its own model.
- Accepts `'haiku'`, `'sonnet'`, `'opus'`, `'inherit'`, or a full model ID; omit it
- and the agent inherits the session's model. Drop **cheap, high-volume,
- mechanical** leaf work (per-item summaries, refute-this checks, classification)
- to `'haiku'`; leave judgement-heavy work on the inherited model. Two cautions:
- - **There is no validation.** A typo (`'hauku'`) is not rejected — it is passed
- through and the agent fails later. Spell the alias exactly.
- - **`model` on a `meta.phases[]` entry does nothing at runtime** — it is a label
- for the permission dialog only. The model is set *solely* by the `model` opt on
- the `agent()` call. For a Haiku phase, set `model` in *both* places: the phase
- entry (honest dialog) and every `agent()` call in it (actual effect).
- **Structured output — `agent(prompt, { schema })`.** Without `schema` you get the
- agent's final text as a **string**. Pass a JSON Schema and the agent is *forced*
- to return a **validated object** matching it — the runtime builds a hidden
- `StructuredOutput` tool from the schema, AJV-validates the result, and makes the
- agent retry on a mismatch. `agent()` returns the parsed object directly — no
- `JSON.parse`. Use `schema` for any result a later line of JavaScript reads a
- field off of; keep schemas small and `required`-tight. To pass data *between*
- stages, stringify it into the next prompt (`JSON.stringify`) — the orchestrator
- shares no memory with the subagent, only the prompt text.
- For full signatures, every option, and every cap, **read
- `references/api-reference.md` now.** For ready-made orchestration shapes, **read
- `references/patterns.md`** and copy the one that fits Step 2's answers. Or start
- from a file in `assets/templates/`, or adapt a full worked example from
- `assets/examples/` (its `README.md` says which one fits).
- ---
- ## Step 5 — Validate before running
- Catch the parser's hard rules before you waste a run. Use the bundled linter:
- ```bash
- node ~/.claude/skills/workflow-creator/scripts/validate-workflow.mjs <path-to-file.js>
- ```
- It flags: missing or non-first `meta`, a non-literal `meta`, a missing
- `name`/`description`, banned non-deterministic calls, and an oversized script.
- Fix every error it reports before invoking the workflow.
- ---
- ## Step 6 — Run, watch, iterate
- Run a named workflow with `Workflow({ name: 'review-changes' })`, or a file with
- `Workflow({ scriptPath: '…' })`. It runs in the **background** — the call returns
- a run ID immediately and a `<task-notification>` arrives on completion. Watch it
- live with the `/workflows` command, where you can also skip or retry a single
- agent mid-run.
- To iterate: **edit the saved file**, then re-invoke with
- `Workflow({ scriptPath, resumeFromRunId })`. Every `agent()` call before your
- first edit replays instantly from cache; only the changed call and everything
- after it re-runs. Same script + same args = a 100% cache hit. Never re-paste the
- whole script after the first run — edit the file.
- ---
- ## Gotchas — check every one before you hand over the file
- These are the mistakes that actually break workflows:
- - **Determinism bans.** `Date.now()`, `Math.random()`, and argless `new Date()`
- **throw** inside a workflow — they would break resume. Pass timestamps in via
- `args` and stamp results *after* the workflow returns; vary "randomness" by
- loop index instead. `new Date(specificValue)` is fine.
- - **No filesystem, no Node APIs** in the orchestrator. No `require`, `fs`,
- `process`. Any file read/write/Bash work belongs **inside an `agent()`** — the
- subagent has the normal tools; the orchestrator does not.
- - **`parallel()` takes thunks, not promises.** It must be
- `[() => agent(...), () => agent(...)]`, never `[agent(...), agent(...)]`. Bare
- calls start immediately and defeat the concurrency limiter.
- - **Always `.filter(Boolean)`.** `parallel()` and `pipeline()` put `null` in the
- slot of any item that threw, was skipped, or was dropped by the budget. The
- result arrays have holes by design.
- - **`meta` is a pure literal and the first statement.** No dynamic values, no
- code before it.
- - **Open-ended loops need a hard stop** — a counter (`while (found < 10)`) or a
- budget guard (`while (budget.total && budget.remaining() > 50_000)`). With no
- budget set, `budget.remaining()` is `Infinity`; an unguarded loop sprints into
- the 1000-agent lifetime cap and throws.
- - **`isolation: 'worktree'` is expensive** (~200–500 ms + disk per agent). Use it
- only when parallel agents mutate files and would otherwise collide.
- ---
- ## Worked example — review a branch, verify each finding
- The shape: fan out one reviewer per dimension; the moment a dimension's review
- returns, fan out a verifier per finding. `pipeline`, because a finding should
- verify as soon as *its* review is done — no waiting for the slowest dimension.
- ```js
- export const meta = {
- name: 'review-branch',
- description: 'Review the branch across dimensions, adversarially verify each finding',
- phases: [{ title: 'Review' }, { title: 'Verify' }],
- }
- const FINDINGS = { type: 'object', required: ['findings'], properties: {
- findings: { type: 'array', items: { type: 'object', required: ['title', 'file'],
- properties: { title: { type: 'string' }, file: { type: 'string' } } } } } }
- const VERDICT = { type: 'object', required: ['isReal'], properties: {
- isReal: { type: 'boolean' }, reason: { type: 'string' } } }
- const DIMENSIONS = [
- { key: 'bugs', prompt: 'Find logic bugs in the changed files on this branch.' },
- { key: 'perf', prompt: 'Find performance regressions in the changed files.' },
- { key: 'tests', prompt: 'Find missing or weak test coverage in the changes.' },
- ]
- const results = await pipeline(
- DIMENSIONS,
- d => agent(d.prompt, { label: `review:${d.key}`, phase: 'Review', schema: FINDINGS }),
- review => parallel((review?.findings ?? []).map(f => () =>
- agent(`Adversarially verify this finding. Try to refute it. Finding: ${f.title} (${f.file})`,
- { label: `verify:${f.file}`, phase: 'Verify', schema: VERDICT })
- .then(v => ({ ...f, verdict: v }))
- ))
- )
- const confirmed = results.flat().filter(Boolean).filter(f => f.verdict?.isReal)
- return { confirmedCount: confirmed.length, confirmed }
- ```
- Trace it: dimension `bugs` can be verifying its findings while `perf` is still
- being reviewed. No wasted wall-clock. Each agent reasons from a clean context.
- The orchestrator JavaScript spends zero model tokens.
- ---
- ## When the user wants to learn, not just get a file
- If the request is "explain how workflows work" rather than "build me one", walk
- them through `references/api-reference.md` — it is written to be read top to
- bottom as the missing manual. Then offer to scaffold their first workflow from a
- template so they have something runnable to poke at.
README.md · README · 92 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # claude-code-workflow-creator
- A Claude Code **skill** that teaches Claude to author **workflows**: deterministic
- multi-agent orchestration scripts that fan work out to fresh-context subagents
- under plain JavaScript control flow.
- A workflow is a JavaScript file. The loops, the conditionals, the fan-out are
- ordinary code that you control. Only the leaf `agent()` calls spend model tokens,
- and each one runs in its own clean context window. The result is multi-agent work
- that behaves the same way every run and can be resumed if it stops partway.
- This skill carries the file format, the judgement calls, and a tested authoring
- procedure, so you can just ask Claude to "create a workflow for X" and get a
- correct, runnable file back.
- ## Heads up: the Workflow tool is not released yet
- This skill writes files for Claude Code's **Workflow tool**. As of right now that
- tool is **unreleased and unannounced**.
- It ships inside the Claude Code binary, but it stays hidden behind an environment
- variable, and Anthropic has not officially documented or announced it. That can
- change at any time, including how it is enabled and how it behaves.
- **What this means for you:**
- - You can install this skill today and read through it to understand workflows.
- - The workflows it writes will only actually *run* once the Workflow tool is
- switched on in a released version of Claude Code.
- - The right move is to wait for Anthropic to officially announce and release the
- feature, then come back and use this skill once it is live.
- Treat this repo as a preview until then. When the feature ships, everything here
- is ready to go.
- ## What is in this repo
- The repo root is the skill itself. Drop it into your Claude Code skills folder
- and Claude picks it up automatically.
- | Path | What it is |
- |------|------------|
- | `SKILL.md` | The skill entry point: the procedure Claude follows to design and write a workflow. |
- | `references/api-reference.md` | The complete manual: every global, every option, every cap and constant. |
- | `references/patterns.md` | Copy-paste orchestration patterns (fan-out, pipeline, loop-until-budget, judge panel, and more). |
- | `assets/templates/` | Starter files for the three core shapes: fan-out, pipeline, loop. |
- | `assets/examples/` | Six complete, runnable example workflows, with a README mapping each one to a technique. |
- | `scripts/validate-workflow.mjs` | A linter that checks a workflow file against the parser's hard rules before you run it. |
- ## Install
- Copy the skill into your global Claude Code skills folder:
- ```bash
- git clone https://github.com/ray-amjad/claude-code-workflow-creator.git
- mkdir -p ~/.claude/skills
- cp -R claude-code-workflow-creator ~/.claude/skills/workflow-creator
- ```
- That is all. The next time Claude Code starts, the skill is available. Ask Claude
- to "create a workflow" and it will trigger.
- ## Using it (once the Workflow tool is released)
- 1. Enable the Workflow tool. Today it is gated behind an environment variable:
- ```bash
- export CLAUDE_CODE_WORKFLOWS=1
- claude
- ```
- When the feature is officially released, follow Anthropic's instructions for
- turning it on, since the exact mechanism may change.
- 2. Ask Claude to build one, for example: "create a workflow that reviews my
- branch across bugs, security, and tests, then verifies each finding."
- 3. Claude uses this skill to write the file, validate it, and run it. Watch live
- progress with the `/workflows` command.
- ## A note on accuracy
- The details in this skill (the file format, the determinism rules, the caps, how
- to set a model, how structured output works) were checked directly against the
- Claude Code binary, not guessed. Because the feature is pre-release, some of it
- may shift before launch. If something stops matching once the feature is
- officially out, open an issue.
- ## Credits
- Built and maintained by [Ray Amjad](https://www.youtube.com/@RAmjad). If this is
- useful, the channel covers more agentic coding workflows like this one.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.