author-workflow-fanout
Skill2 starsChanged 13 days agoMITView on GitHub
Use when authoring a Claude Code Workflow scriptPath / multi-agent fan-out script: deciding pipeline vs a parallel barrier, wiring per-agent() error handling, choosing schema vs longform output, persisting bulk results, or writing a budget/cap loop. Symptoms this skill exists for: one dead search or rate-limit crashing the whole fan-out because an agent() call had no .catch, a barrier stalling fast agents behind the slowest, a budget loop running to the 1000-agent cap because it was not guarded on budget.total, bulk output stuffed into return values instead of disk.
In this repository29 other files it gives its agents.
- AGENTS.mdAGENTS.md
- apply-review-findingsSkill
- chain-launcherSkill
- delegateSkill
- design-consultationSkill
- design-fail-closed-gateSkill
- document-releaseSkill
- gistSkill
- goal-promptSkill
- grokbotSkill
- incident-as-codeSkill
- investigateSkill
- learn-captureSkill
- office-hoursSkill
- orion-deep-researchSkill
- oss-loopSkill
- pre-compactSkill
- pre-prSkill
- prove-control-bindsSkill
- prove-deploy-is-liveSkill
- readonlySkill
- reassert-guards-on-rewriteSkill
- reprobe-stale-premiseSkill
- scope-guardSkill
- shipSkill
- tdd-loopSkill
- tools-routerSkill
- triage-fanout-verdictsSkill
- xSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 22
NOT for deciding WHETHER to fan out (that is a parallel-dispatch decision), and NOT for reading the verdicts a fan-out returns (that is a …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Authoring Workflow Fan-Out Scripts
Overview
A fan-out script spends real tokens across many subagents, and its failure
modes are silent: an un-caught reject kills the whole run, an unguarded loop
burns the agent cap, a barrier stalls every fast agent behind the slowest.
Author defensively: every agent() call handles its own failure into a ledger
plus abstention, the topology is a pipeline unless a barrier is genuinely
needed, and any budget loop is guarded so it cannot run unbounded. Run the
linter before you launch.
When to use
- Writing or editing a
Workflow({scriptPath})script, or any multi-agent()fan-out. - NOT for deciding WHETHER to fan out (that is a parallel-dispatch decision), and NOT for reading the verdicts a fan-out returns (that is a verdict-triage discipline).
Rules the linter enforces (run it before launch)
python3 workflow_lint.py <script.js> (exit 0 clean, 1 findings, 2 error).
| Rule | Why it matters |
no-catch | Every agent() must carry .catch (or a wrapper that does). One rate-limit or dead-search reject otherwise rejects the whole parallel/pipeline; the failure must become a ledger entry plus abstention, not a crash |
budget-unguarded | while (budget.remaining() ...) with no budget.total in the condition runs to the 1000-agent cap: with no target, remaining() is Infinity. Guard: while (budget.total && budget.remaining() > N) |
meta-missing | A script with no export const meta = { is rejected at load |
unbounded-agent-hoard | A schema-less (longform) agent() whose returns are accumulated (pipeline/parallel/.push/+=) with NO bound accumulator hoards unbounded bulk in the orchestrator's live context. Fix: pass a schema (small structured return), or route returns through a bounded accumulator (see Judgment section below) |
Judgment the linter cannot check
- Pipeline by default; barrier only for cross-item need.
pipeline()has no barrier, so a fast item is not stalled behind the slowest. Useparallel()between stages ONLY when a stage genuinely needs ALL prior results at once (dedup/merge, zero-count early-exit, "compare to the others"). - schema vs longform. Structured data (findings, verdicts) takes a
schema. Human or prose output stays plain text; a schema mangles longform. - Persist bulk to disk. Subagents write artifacts to files and return
pointers or summaries; do not stuff large bodies into
agent()return values. When you DO accumulate many returns, cap and dedupe them in-flight with a small bounded accumulator: budget a total byte cap plus a per-item byte cap, and preserve complete recoverable artifacts before omitting any inline output. The optional local JavaScript helper provides this boundary for a Node.js consumer; its usage and recovery guide defines the complete JSON byte budget, private storage and explicit failures. It needs filesystem access and cannot run inside a Workflow sandbox. In that sandbox, use the worker's storage interface and verify references yourself. Prose-only usage remains supported; the helper is optional. A recognized helper name is only a linter hint, never proof of persistence or an effective cap. .filter(Boolean)before using results. A failed thunk resolves tonullinparallel()/pipeline()output; filter before you map.- No
Date.now()/Math.random()in the script body (they throw in the sandbox and break resume); vary by index, stamp timestamps after the run.
Rationalizations
| Excuse | Reality |
| "The agents almost never fail, .catch is noise" | One 429 or dead search rejects the entire parallel()/pipeline(); the run dies at 90% |
| "A barrier is cleaner than a pipeline" | Barrier latency is real: the slowest item blocks every fast one; use pipeline unless a stage needs all prior results |
| "The budget loop is fine, it'll stop eventually" | With no budget.total, remaining() is Infinity; it stops at the 1000-agent backstop, not where you meant |
| "I'll return the full text and parse it later" | Bulk in return values bloats orchestrator context; persist to disk, return a pointer |
Red flags
- An
await agent(...)with no.catchanywhere in its statement. parallel()whose result feeds a transform that feeds anotherparallel()(that is a pipeline wearing a barrier).- A
whileonbudget.remaining()/spent()with nobudget.totalguard. Date.now()/Math.random()/ barenew Date()in the script body.- Launching without running the linter.
Related
Complements a "whether to fan out" parallel-dispatch decision and a verdict-triage discipline (reading the results a fan-out returns). Note the name "workflow" collides with unrelated durable-execution frameworks: this is about the Claude Code Workflow tool's fan-out script, not those.
Boundary
This is an authoring discipline plus a shipped linter, not a runtime. The
linter (workflow_lint.py, co-located here) is a heuristic smell-detector: it
flags an agent() call with no .catch, an unguarded budget loop, and a
missing meta block, by blanking string/comment bodies before it tracks paren
depth so a prompt's punctuation cannot fool it. Wire it into your own
pre-launch step. The harness that runs the fan-out, the failure-ledger format,
and where you persist bulk output are your repo's mechanics. The discipline is
invariant: every agent() handles its own failure, pipeline unless a barrier
is needed, guard every budget loop. Selftest the linter in your own suite
before trusting it.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

