Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ray-amjad--claude-code-workflow-creator/badge.svg)](/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

i

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)

  1. ---
  2. name: workflow-creator
  3. description: >-
  4. Author runnable workflow scripts for Claude Code's Workflow tool — deterministic
  5. multi-agent orchestration files that fan out fresh-context subagents under plain
  6. JavaScript control flow. Use this skill whenever the user wants to create, write,
  7. build, scaffold, design, or fix a workflow: "make a workflow", "create a workflow
  8. for X", "write a workflow", "turn this into a workflow", "scaffold a multi-agent
  9. pipeline", "orchestrate this with subagents deterministically", or any request to
  10. author or edit a .js file under .claude/workflows/. Also use it when the user is
  11. confused about the workflow script format — the meta block, agent()/parallel()/
  12. pipeline()/phase(), schemas, the determinism rules — or when a workflow errors and
  13. needs debugging. Trigger this even when the user only describes a repeatable
  14. multi-step or parallel job and seems to want it packaged as a workflow, even if
  15. they never say the word "workflow". Do NOT use it to merely run an existing
  16. workflow, or for a one-off single-subagent task.
  17. ---
  18. # Workflow Creator
  19. Turn a goal into a **runnable workflow file** — a JavaScript orchestrator for
  20. Claude Code's `Workflow` tool.
  21. A workflow fans work out to fresh-context subagents under **deterministic
  22. JavaScript** control flow: the loops, the conditionals, the fan-out are plain
  23. code, and only the leaf `agent()` calls spend model tokens. The Workflow tool is
  24. new and undocumented, so this skill carries the format, the judgment calls, and a
  25. tested authoring procedure. Use it to write a new workflow, convert a multi-step
  26. job into one, or fix a broken script.
  27. The deep material lives in two reference files — read them when the step says so:
  28. - `references/api-reference.md` — the complete manual: every global, every option,
  29. every cap and constant, what happens at each limit.
  30. - `references/patterns.md` — copy-paste orchestration patterns (fan-out, pipeline,
  31. loop-until-budget, adversarial verify, judge panel, nested workflow).
  32. Starter files are in `assets/templates/`. Six complete, runnable example
  33. workflows are in `assets/examples/` — `assets/examples/README.md` maps each one
  34. to a topology and to the model / structured-output techniques it shows. A linter
  35. is in `scripts/`.
  36. ---
  37. ## Step 0 — Confirm the Workflow tool is available
  38. A workflow can only **run** if the Workflow tool is enabled. It is **off by
  39. default**, gated behind an environment variable. You can always *write* the file,
  40. but check this so you can tell the user the truth about running it:
  41. ```bash
  42. echo "${CLAUDE_CODE_WORKFLOWS:-<not set>}"
  43. ```
  44. If it is not set, the workflow file is still worth writing — but tell the user
  45. they must enable the tool before it will run, either of:
  46. ```bash
  47. # per session
  48. export CLAUDE_CODE_WORKFLOWS=1 && claude
  49. ```
  50. ```jsonc
  51. // or persistently, in .claude/settings.local.json
  52. { "env": { "CLAUDE_CODE_WORKFLOWS": "1" } }
  53. ```
  54. Workflow files live in `.claude/workflows/<name>.js` (project-local) or
  55. `~/.claude/workflows/<name>.js` (global). The filename is not the workflow name —
  56. the `name` inside the `meta` block is.
  57. ---
  58. ## Step 1 — Decide whether a workflow is even the right tool
  59. Do not reach for a workflow by default — it is the heaviest option and it is
  60. gated for a reason (it can spend a lot of tokens). Pick deliberately:
  61. | The job | Right tool |
  62. |---|---|
  63. | One subagent, one task | The plain **`Agent`** tool — no workflow |
  64. | A reusable procedure where **Claude** picks the steps each run | A **Skill** |
  65. | Many subagents in a **fixed** shape (fan-out / pipeline / loop), same every run, worth resuming | A **Workflow** ✅ |
  66. A workflow earns its cost when **all** of these are true: the work is parallel or
  67. multi-stage; you want the orchestration deterministic and resumable; and
  68. isolating each step in its own fresh context window is an advantage. If you are
  69. unsure, say so and offer the lighter option instead.
  70. ---
  71. ## Step 2 — Find the shape of the job
  72. Before writing a line of code, answer these. The answers pick the topology for you.
  73. 1. **What is the unit of work?** The thing one subagent does once — review one
  74. file, research one question, draft one platform. Name it concretely.
  75. 2. **How many units, and is the count known up front?** A known list → map over
  76. it. An unknown count (discovery, "find all the bugs") → a loop.
  77. 3. **What is the topology?**
  78. - Independent units, one pass each → **fan-out**.
  79. - Units flow through ordered stages (review → verify) → **pipeline**.
  80. - Keep going until a target count or a budget runs low → **loop**.
  81. 4. **Does any later step need *all* the earlier results at once** — to dedup,
  82. merge, count, or early-exit on a zero total? If yes, you need a **barrier**.
  83. If no, you do not — and you should prefer `pipeline`.
  84. 5. **Does a step need structured data back** (not free text)? Then that
  85. `agent()` call needs a `schema`.
  86. Write these five answers down for the user before coding. They are the design.
  87. ---
  88. ## Step 3 — The decision that matters most: `pipeline` vs `parallel`
  89. This is the call people get wrong, so make it explicitly.
  90. - **`pipeline(items, stage1, stage2, …)` is the default for multi-stage work.**
  91. Each item flows through every stage on its own — **there is no barrier between
  92. stages**. Item A can be in stage 3 while item B is still in stage 1.
  93. Wall-clock = the slowest single item's whole chain, not the sum of the slowest
  94. stage at each step.
  95. - **`parallel(thunks)` is a barrier.** It waits for every task before returning.
  96. Reach for it **only** when a stage genuinely needs the *entire* previous
  97. result set in hand — dedup across all findings, merge, a count-based
  98. early-exit. "It is cleaner code" or "the stages feel separate" are **not**
  99. reasons — a pipeline models separate stages fine.
  100. Smell test: if you would write `const a = await parallel(...)`, then a plain
  101. transform (`flat`/`map`/`filter`) with no cross-item dependency, then another
  102. `parallel(...)` — that middle transform does not need the barrier. Make it a
  103. pipeline stage instead. **When in doubt, `pipeline`.**
  104. ---
  105. ## Step 4 — Write the file
  106. A workflow file has exactly two parts, in this order. The parser is strict.
  107. ### Part 1 — the `meta` block (must be the very first statement)
  108. ```js
  109. export const meta = {
  110. name: 'review-changes', // required, non-empty
  111. description: 'Review changed files, verify each finding', // required — shown in the permission dialog
  112. whenToUse: 'Before shipping a branch', // optional — shown in the workflow list
  113. phases: [ // optional — one entry per phase() call
  114. { title: 'Review' },
  115. { title: 'Verify', model: 'haiku' },
  116. ],
  117. }
  118. ```
  119. `meta` **must be a pure literal** — no variables, function calls, spreads, or
  120. template strings inside it. Build dynamic values in the body, never in `meta`.
  121. Use the same phase `title` strings in `meta.phases` as in your `phase()` calls.
  122. ### Part 2 — the body (async JavaScript)
  123. Everything after `meta` is the body. It runs inside an `async` function, so you
  124. `await` at the top level. These globals are injected — **do not import anything**:
  125. | Global | Purpose |
  126. |---|---|
  127. | `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. |
  128. | `pipeline(items, s1, s2, …)` | Run each item through all stages, no barrier between stages. The default for multi-stage work. |
  129. | `parallel(thunks)` | Run an array of **functions** `() => Promise` concurrently. A barrier. |
  130. | `phase(title)` | Group the agents that follow under a heading in `/workflows`. |
  131. | `log(msg)` | Emit a narrator line above the progress tree. |
  132. | `console` | A standard-looking `console` — its output is routed into the workflow log. |
  133. | `budget` | `{ total, spent(), remaining() }` — token target for budget-aware loops. |
  134. | `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). |
  135. | `workflow(name, args?)` | Run another workflow inline. One level of nesting only. |
  136. The body's `return` value becomes the tool result handed back to Claude.
  137. > **Normalize `args` before reading fields.** Empirically (probed 2026-05-29), the
  138. > runtime **serializes `args` to a string** before the script runs — even when you
  139. > pass a JSON object or array via the tool's `args` field, the script's `args` is
  140. > the JSON *text*, so `args.minUsers` / `args.map(...)` do **not** work directly.
  141. > `Workflow({ args: { minUsers: 5 } })` gives the script the **string**
  142. > `'{"minUsers":5}'`; nothing passed gives `undefined`. The one normalizer below
  143. > covers every case — it parses a JSON string and is still correct if a future
  144. > runtime ever passes a live object through:
  145. >
  146. > ```js
  147. > // A JSON string parses to an object/array; plain text and `undefined`
  148. > // fall through unchanged; a live object (future-proofing) passes straight through.
  149. > const input = typeof args === 'string'
  150. > ? (() => { try { return JSON.parse(args) } catch { return args } })()
  151. > : args
  152. > const threshold = input?.minUsers ?? 20
  153. > ```
  154. >
  155. > Keep the `typeof === 'string'` guard rather than calling `JSON.parse(args)`
  156. > unconditionally: a bare-text arg (`"build a todo app"`) isn't valid JSON, and the
  157. > guard also protects you if the runtime's serialization behavior changes.
  158. ### Setting a model, and getting structured data back — the two `agent()` opts you tune most
  159. **Model — `agent(prompt, { model })`.** Each agent call runs on its own model.
  160. Accepts `'haiku'`, `'sonnet'`, `'opus'`, `'inherit'`, or a full model ID; omit it
  161. and the agent inherits the session's model. Drop **cheap, high-volume,
  162. mechanical** leaf work (per-item summaries, refute-this checks, classification)
  163. to `'haiku'`; leave judgement-heavy work on the inherited model. Two cautions:
  164. - **There is no validation.** A typo (`'hauku'`) is not rejected — it is passed
  165. through and the agent fails later. Spell the alias exactly.
  166. - **`model` on a `meta.phases[]` entry does nothing at runtime** — it is a label
  167. for the permission dialog only. The model is set *solely* by the `model` opt on
  168. the `agent()` call. For a Haiku phase, set `model` in *both* places: the phase
  169. entry (honest dialog) and every `agent()` call in it (actual effect).
  170. **Structured output — `agent(prompt, { schema })`.** Without `schema` you get the
  171. agent's final text as a **string**. Pass a JSON Schema and the agent is *forced*
  172. to return a **validated object** matching it — the runtime builds a hidden
  173. `StructuredOutput` tool from the schema, AJV-validates the result, and makes the
  174. agent retry on a mismatch. `agent()` returns the parsed object directly — no
  175. `JSON.parse`. Use `schema` for any result a later line of JavaScript reads a
  176. field off of; keep schemas small and `required`-tight. To pass data *between*
  177. stages, stringify it into the next prompt (`JSON.stringify`) — the orchestrator
  178. shares no memory with the subagent, only the prompt text.
  179. For full signatures, every option, and every cap, **read
  180. `references/api-reference.md` now.** For ready-made orchestration shapes, **read
  181. `references/patterns.md`** and copy the one that fits Step 2's answers. Or start
  182. from a file in `assets/templates/`, or adapt a full worked example from
  183. `assets/examples/` (its `README.md` says which one fits).
  184. ---
  185. ## Step 5 — Validate before running
  186. Catch the parser's hard rules before you waste a run. Use the bundled linter:
  187. ```bash
  188. node ~/.claude/skills/workflow-creator/scripts/validate-workflow.mjs <path-to-file.js>
  189. ```
  190. It flags: missing or non-first `meta`, a non-literal `meta`, a missing
  191. `name`/`description`, banned non-deterministic calls, and an oversized script.
  192. Fix every error it reports before invoking the workflow.
  193. ---
  194. ## Step 6 — Run, watch, iterate
  195. Run a named workflow with `Workflow({ name: 'review-changes' })`, or a file with
  196. `Workflow({ scriptPath: '…' })`. It runs in the **background** — the call returns
  197. a run ID immediately and a `<task-notification>` arrives on completion. Watch it
  198. live with the `/workflows` command, where you can also skip or retry a single
  199. agent mid-run.
  200. To iterate: **edit the saved file**, then re-invoke with
  201. `Workflow({ scriptPath, resumeFromRunId })`. Every `agent()` call before your
  202. first edit replays instantly from cache; only the changed call and everything
  203. after it re-runs. Same script + same args = a 100% cache hit. Never re-paste the
  204. whole script after the first run — edit the file.
  205. ---
  206. ## Gotchas — check every one before you hand over the file
  207. These are the mistakes that actually break workflows:
  208. - **Determinism bans.** `Date.now()`, `Math.random()`, and argless `new Date()`
  209. **throw** inside a workflow — they would break resume. Pass timestamps in via
  210. `args` and stamp results *after* the workflow returns; vary "randomness" by
  211. loop index instead. `new Date(specificValue)` is fine.
  212. - **No filesystem, no Node APIs** in the orchestrator. No `require`, `fs`,
  213. `process`. Any file read/write/Bash work belongs **inside an `agent()`** — the
  214. subagent has the normal tools; the orchestrator does not.
  215. - **`parallel()` takes thunks, not promises.** It must be
  216. `[() => agent(...), () => agent(...)]`, never `[agent(...), agent(...)]`. Bare
  217. calls start immediately and defeat the concurrency limiter.
  218. - **Always `.filter(Boolean)`.** `parallel()` and `pipeline()` put `null` in the
  219. slot of any item that threw, was skipped, or was dropped by the budget. The
  220. result arrays have holes by design.
  221. - **`meta` is a pure literal and the first statement.** No dynamic values, no
  222. code before it.
  223. - **Open-ended loops need a hard stop** — a counter (`while (found < 10)`) or a
  224. budget guard (`while (budget.total && budget.remaining() > 50_000)`). With no
  225. budget set, `budget.remaining()` is `Infinity`; an unguarded loop sprints into
  226. the 1000-agent lifetime cap and throws.
  227. - **`isolation: 'worktree'` is expensive** (~200–500 ms + disk per agent). Use it
  228. only when parallel agents mutate files and would otherwise collide.
  229. ---
  230. ## Worked example — review a branch, verify each finding
  231. The shape: fan out one reviewer per dimension; the moment a dimension's review
  232. returns, fan out a verifier per finding. `pipeline`, because a finding should
  233. verify as soon as *its* review is done — no waiting for the slowest dimension.
  234. ```js
  235. export const meta = {
  236. name: 'review-branch',
  237. description: 'Review the branch across dimensions, adversarially verify each finding',
  238. phases: [{ title: 'Review' }, { title: 'Verify' }],
  239. }
  240. const FINDINGS = { type: 'object', required: ['findings'], properties: {
  241. findings: { type: 'array', items: { type: 'object', required: ['title', 'file'],
  242. properties: { title: { type: 'string' }, file: { type: 'string' } } } } } }
  243. const VERDICT = { type: 'object', required: ['isReal'], properties: {
  244. isReal: { type: 'boolean' }, reason: { type: 'string' } } }
  245. const DIMENSIONS = [
  246. { key: 'bugs', prompt: 'Find logic bugs in the changed files on this branch.' },
  247. { key: 'perf', prompt: 'Find performance regressions in the changed files.' },
  248. { key: 'tests', prompt: 'Find missing or weak test coverage in the changes.' },
  249. ]
  250. const results = await pipeline(
  251. DIMENSIONS,
  252. d => agent(d.prompt, { label: `review:${d.key}`, phase: 'Review', schema: FINDINGS }),
  253. review => parallel((review?.findings ?? []).map(f => () =>
  254. agent(`Adversarially verify this finding. Try to refute it. Finding: ${f.title} (${f.file})`,
  255. { label: `verify:${f.file}`, phase: 'Verify', schema: VERDICT })
  256. .then(v => ({ ...f, verdict: v }))
  257. ))
  258. )
  259. const confirmed = results.flat().filter(Boolean).filter(f => f.verdict?.isReal)
  260. return { confirmedCount: confirmed.length, confirmed }
  261. ```
  262. Trace it: dimension `bugs` can be verifying its findings while `perf` is still
  263. being reviewed. No wasted wall-clock. Each agent reasons from a clean context.
  264. The orchestrator JavaScript spends zero model tokens.
  265. ---
  266. ## When the user wants to learn, not just get a file
  267. If the request is "explain how workflows work" rather than "build me one", walk
  268. them through `references/api-reference.md` — it is written to be read top to
  269. bottom as the missing manual. Then offer to scaffold their first workflow from a
  270. 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)

  1. # claude-code-workflow-creator
  2. A Claude Code **skill** that teaches Claude to author **workflows**: deterministic
  3. multi-agent orchestration scripts that fan work out to fresh-context subagents
  4. under plain JavaScript control flow.
  5. A workflow is a JavaScript file. The loops, the conditionals, the fan-out are
  6. ordinary code that you control. Only the leaf `agent()` calls spend model tokens,
  7. and each one runs in its own clean context window. The result is multi-agent work
  8. that behaves the same way every run and can be resumed if it stops partway.
  9. This skill carries the file format, the judgement calls, and a tested authoring
  10. procedure, so you can just ask Claude to "create a workflow for X" and get a
  11. correct, runnable file back.
  12. ## Heads up: the Workflow tool is not released yet
  13. This skill writes files for Claude Code's **Workflow tool**. As of right now that
  14. tool is **unreleased and unannounced**.
  15. It ships inside the Claude Code binary, but it stays hidden behind an environment
  16. variable, and Anthropic has not officially documented or announced it. That can
  17. change at any time, including how it is enabled and how it behaves.
  18. **What this means for you:**
  19. - You can install this skill today and read through it to understand workflows.
  20. - The workflows it writes will only actually *run* once the Workflow tool is
  21. switched on in a released version of Claude Code.
  22. - The right move is to wait for Anthropic to officially announce and release the
  23. feature, then come back and use this skill once it is live.
  24. Treat this repo as a preview until then. When the feature ships, everything here
  25. is ready to go.
  26. ## What is in this repo
  27. The repo root is the skill itself. Drop it into your Claude Code skills folder
  28. and Claude picks it up automatically.
  29. | Path | What it is |
  30. |------|------------|
  31. | `SKILL.md` | The skill entry point: the procedure Claude follows to design and write a workflow. |
  32. | `references/api-reference.md` | The complete manual: every global, every option, every cap and constant. |
  33. | `references/patterns.md` | Copy-paste orchestration patterns (fan-out, pipeline, loop-until-budget, judge panel, and more). |
  34. | `assets/templates/` | Starter files for the three core shapes: fan-out, pipeline, loop. |
  35. | `assets/examples/` | Six complete, runnable example workflows, with a README mapping each one to a technique. |
  36. | `scripts/validate-workflow.mjs` | A linter that checks a workflow file against the parser's hard rules before you run it. |
  37. ## Install
  38. Copy the skill into your global Claude Code skills folder:
  39. ```bash
  40. git clone https://github.com/ray-amjad/claude-code-workflow-creator.git
  41. mkdir -p ~/.claude/skills
  42. cp -R claude-code-workflow-creator ~/.claude/skills/workflow-creator
  43. ```
  44. That is all. The next time Claude Code starts, the skill is available. Ask Claude
  45. to "create a workflow" and it will trigger.
  46. ## Using it (once the Workflow tool is released)
  47. 1. Enable the Workflow tool. Today it is gated behind an environment variable:
  48. ```bash
  49. export CLAUDE_CODE_WORKFLOWS=1
  50. claude
  51. ```
  52. When the feature is officially released, follow Anthropic's instructions for
  53. turning it on, since the exact mechanism may change.
  54. 2. Ask Claude to build one, for example: "create a workflow that reviews my
  55. branch across bugs, security, and tests, then verifies each finding."
  56. 3. Claude uses this skill to write the file, validate it, and run it. Watch live
  57. progress with the `/workflows` command.
  58. ## A note on accuracy
  59. The details in this skill (the file format, the determinism rules, the caps, how
  60. to set a model, how structured output works) were checked directly against the
  61. Claude Code binary, not guessed. Because the feature is pre-release, some of it
  62. may shift before launch. If something stops matching once the feature is
  63. officially out, open an issue.
  64. ## Credits
  65. Built and maintained by [Ray Amjad](https://www.youtube.com/@RAmjad). If this is
  66. useful, the channel covers more agentic coding workflows like this one.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.