[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6JER50MQ08HBEE1MPEKBTYH":3,"skill-same:01M6JER50MQ08HBEE1MPEKBTYH":70},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":22,"publishedAt":43,"linkOnly":44,"markdownContent":45,"markdownBody":46,"frontMatter":47,"refName":48,"commitSha":49,"skillDirectory":50,"forksCount":51,"repositoryHtmlUrl":52,"repositoryHomepageUrl":53,"ownerHtmlUrl":54,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":55,"install":56,"resources":69},"01M6JER50MQ08HBEE1MPEKBTYH","n8n-subworkflows",null,"Build reusable, composable n8n sub-workflows. Use when extracting shared logic, building anything multi-step or reused across workflows, or any workflow over ~10 nodes — and whenever the user mentions sub-workflows, Execute Workflow, reuse, shared\u002Fcommon logic, modular workflows, \"Define Below\" inputs, waitForSubWorkflow, mode each vs all, or exposing a workflow as an agent tool. Covers typed sub-workflow inputs, all-vs-each execution, verb-first naming for discovery, stateless vs stateful design, and splitting by input shape.","S3YED\u002Fappie-kit","S3YED","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F62743867?v=4","01M6JBKBRRVP6KMS0VWZ27T3R6","01M6JBKBX0KG30284PW1DBYJT1",14,"MIT","https:\u002F\u002Fgithub.com\u002FS3YED\u002Fappie-kit\u002Fblob\u002Fmaster\u002Fskills\u002Fmisc\u002Fn8n-subworkflows\u002FSKILL.md",[17],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42],"n8n subworkflows","n8n","across","stateful","for","mode","extracting","reuse","input","as","shared","design","common","tool","discovery","execution","composable","modular","workflows","workflow","2026-11-10 10:12:30",false,"---\nname: n8n-subworkflows\ndescription: Build reusable, composable n8n sub-workflows. Use when extracting shared logic, building anything multi-step or reused across workflows, or any workflow over ~10 nodes — and whenever the user mentions sub-workflows, Execute Workflow, reuse, shared\u002Fcommon logic, modular workflows, \"Define Below\" inputs, waitForSubWorkflow, mode each vs all, or exposing a workflow as an agent tool. Covers typed sub-workflow inputs, all-vs-each execution, verb-first naming for discovery, stateless vs stateful design, and splitting by input shape.\n---\n\n# n8n Sub-workflows\n\nA sub-workflow is a reusable function. An **Execute Workflow Trigger** declares typed inputs, the body does the work, and the last node returns the output. A caller invokes it through an **Execute Workflow** node like any other step.\n\nThat framing buys you the things functions buy you everywhere: encapsulation, reuse, testability, replaceability. It's the primary reuse mechanism in n8n, and it's badly underused. Without it, the same logic gets copy-pasted across workflows — then a bug gets fixed in two places, the third copy gets missed, and your \"identical\" copies quietly drift apart.\n\nThis skill is about when to reach for a sub-workflow, how to define its input\u002Foutput contract so callers (and agents) can actually use it, how to call it correctly (`all` vs `each`, blocking vs fire-and-forget), and how to name it so it gets found instead of rebuilt.\n\n---\n\n## The two non-negotiables\n\nEverything else is judgement. These two are not.\n\n### 1. Search before you build\n\nBefore you write logic for a generic problem, check whether a sub-workflow already does it. The community MCP can't filter workflows by tag, so the **name is the discovery surface**:\n\n```\nn8n_list_workflows()                          # scan the library\nn8n_get_workflow({ id: \"\u003Ccandidate>\" })       # read its inputs\u002Foutputs + body\n```\n\nIf something fits, use it and tell the user (\"I found `Subworkflow: Parse RFC2822 date` — using that\"). If nothing fits, build it *with a discoverable name* so the next search finds it. The discovery convention (verb-first prefixes) lives in **NAMING_AND_DISCOVERY.md**.\n\n### 2. The Execute Workflow Trigger uses \"Define Below\" with typed fields — not passthrough\n\nThe trigger has two input modes. **Default to \"Define Below\"** with explicit typed fields. Define Below is the only mode that gives callers a schema to fill — it's what lets an AI agent pass values via `$fromAI` and what lets structured callers map fields cleanly. Passthrough has no schema, so the trigger can't be wired as a clean agent tool and structured callers have nothing to bind to.\n\nTwo exceptions, and only two:\n\n- **Binary input.** Typed fields are JSON-only. If the sub-workflow must receive an image\u002Ffile\u002FPDF, you need passthrough so the `binary` slot flows through.\n- **Zero inputs.** Define Below requires at least one field. A genuinely no-arg operation (\"list active credentials\", \"current count\") has nowhere to put an empty schema, so passthrough is the only option.\n\nOutside those two cases, passthrough is a bug. See \"Inputs and outputs as a contract\" below.\n\n---\n\n## Should this be a sub-workflow?\n\nYou're about to write a chunk of logic. Run it through this:\n\n```\nCould this plausibly be needed in another workflow?\n  └─ Yes → extract.\n\nIs it a generic concern (auth, retry, parsing, formatting, ID generation)?\n  └─ Almost always → extract. These are the canonical reusable sub-workflows.\n\nIs it >5 nodes and conceptually one thing?\n  └─ Probably extract, even if reuse isn't certain. It's better isolated.\n\nIs it one HTTP call with no logic around it?\n  └─ Don't. A sub-workflow that's just trigger → HTTP → return adds a boundary\n     for nothing.\n\nIs it tightly coupled to this one caller's data shape?\n  └─ Don't extract yet — fix the data shape first, or you just relocate the coupling.\n```\n\nThe reasons to extract go beyond reuse:\n\n- **Readability.** The caller shows one node (\"Parse date\") instead of five.\n- **Testability.** Run the sub-workflow alone with pinned input (`n8n_test_workflow`).\n- **Replaceability.** Swap the implementation without rippling to callers.\n\nA 20-node workflow is fine *if it's mostly a linear sequence of Execute Workflow calls and decisions* — each node has one purpose, and you inspect a section by opening the sub-workflow it calls. A 20-node workflow of inline transformations is not fine. If yours has 15+ nodes and isn't mostly sub-workflow calls and branches, extract more.\n\n---\n\n## Stateless vs. stateful (deliberately)\n\nBoth are first-class. The choice is about intent and what the contract promises.\n\n**Stateless** — input in, output out, no I\u002FO beyond that. The default for pure logic. When you need it again, you call it without worrying about side effects firing.\n\n- `Subworkflow: Parse RFC2822 date` — date string → ISO date or error.\n- `Subworkflow: Compute MRR from subscription` — subscription object → number.\n- `Subworkflow: Format invoice as HTML` — invoice data → HTML string.\n\n**Stateful (deliberate)** — reads or writes external state *behind a clean contract*. This is the repository pattern: the sub-workflow abstracts the storage operation so callers think in domain terms, not SQL.\n\n- `Customer: get by id` — id → customer object or `{ ok: false, error: \"not_found\" }`. Reads the DB.\n- `Customer: write billing record` — record → `{ ok: true, id }`. Writes the DB.\n- `Notify: send to on-call` — channel, message → `{ ok: true, messageId }`. Calls Slack\u002FSMTP.\n\nWhy build these as sub-workflows: callers think `get customer by id` instead of writing the query; you can swap the store (Postgres → Supabase, native node → HTTP) without touching a single caller; and idempotency, retry, and validation get centralized in one place.\n\nWhat to avoid is **accidental state** — a sub-workflow named and described as pure that quietly writes to a log table. That ambushes every caller who reasonably assumed it was safe to retry or compose. Either make the side effect part of the contract (rename it, document it, return its result) or move it out.\n\n---\n\n## Inputs and outputs as a contract\n\nThe trigger's declared fields and the last node's output shape *are* the sub-workflow's API. Treat them like one.\n\n### Declaring typed inputs (Define Below)\n\nEach declared input is a typed parameter the caller fills. Pick types deliberately (`string`, `number`, `boolean`, `array`, `object`) — an agent uses these as the required types when filling tool parameters, and humans rely on them when wiring callers. The trigger node parameters look like this:\n\n```json\n{\n  \"type\": \"n8n-nodes-base.executeWorkflowTrigger\",\n  \"parameters\": {\n    \"workflowInputs\": {\n      \"values\": [\n        { \"name\": \"list_of_ids\",        \"type\": \"array\" },\n        { \"name\": \"include_transcript\", \"type\": \"boolean\" },\n        { \"name\": \"session_id\",          \"type\": \"string\" }\n      ]\n    }\n  }\n}\n```\n\nInside the body, read them as `$json.list_of_ids`, or from anywhere downstream as `$('When Executed by Another Workflow').first().json.\u003Cfield>` (see **n8n-expression-syntax**).\n\n### The contract rules\n\n- **Document inputs and outputs in the workflow `description`.** Field names, types, purpose, and a few representative keywords. The description is what callers (human and agent) read for the contract, and it's what `n8n_list_workflows` matches against.\n- **Return consistent, natural shapes — not storage shapes.** A sub-workflow that owns a Data Table or an S3 file hides that representation from callers. Arrays return as arrays, objects as objects, dates as ISO strings — regardless of whether the underlying storage was JSON-stringified text. The return contract is the *interface*; the storage layout is *implementation detail*. Common slip: a sub-workflow with a \"fresh\" path (just-computed, natural shape) and a \"cached\" path (just read from a stringified column). Wrong instinct: stringify the fresh path to match the cached one. Right instinct: parse the cached path so both return the natural shape.\n- **Return errors, don't always throw.** For *expected* failures (a parse error, a not-found), return `{ ok: false, error: \"...\" }` so the caller can branch without wiring an error output. Reserve throwing for genuinely unexpected failures — see **n8n-error-handling**.\n- **The contract is frozen once it has callers.** Adding *optional* fields is safe. Renaming or removing a field is dangerous: n8n won't error on an unrecognized input field — the body just sees `undefined`, the caller has no idea, and you get a silent contract break. To change a field, enumerate every caller (`n8n_list_workflows` + inspect each one's Execute Workflow node), migrate them in the same change, and verify with `validate_workflow` and `n8n_get_workflow` before you're done.\n\n### The final Return node — the legitimate Set exception\n\nShape the output with a final **Set \u002F Edit Fields** node, named `Return` or `Return \u003Cthing>`. This is the one place a Set node earns its keep against the usual \"don't add a trailing Set node\" advice from **n8n-expression-syntax**: the implicit consumer of a sub-workflow's last node is *every caller*, so an explicit Set makes the return contract visible — a reader sees the whole API by reading one node, and you strip any noise fields the last computation node carried.\n\n---\n\n## Calling sub-workflows: `mode` and `waitForSubWorkflow`\n\nTwo settings on the caller's **Execute Workflow** node decide how the sub-workflow runs.\n\n### `mode`: `all` vs `each`\n\n| `mode` | Sub-workflow runs | Items per run |\n|---|---|---|\n| `all` (default) | once | all N items (flowing per-item through nodes as usual) |\n| `each` | N times | exactly one item per run |\n\nFor a body that just processes items the normal way, the two are equivalent — n8n nodes iterate per-item either way. **The split only matters when the body assumes it sees exactly one item**: a per-run aggregation, \"this is THE customer to act on\" logic, or a final write that should fire once per input. With `all`, that body gets all N items at once and the assumption breaks (you aggregate everyone into one result instead of one-per-input). With `each`, each invocation gets one item and the assumption holds.\n\nSo: when you need per-item iteration, prefer `mode: each` over dropping a Loop Over Items node *inside* the sub-workflow. The mode does the iteration for you, and the body stays simple and single-item.\n\n### `waitForSubWorkflow`: `true` vs `false`\n\n`waitForSubWorkflow` defaults to `true` — the caller blocks until the sub-workflow returns, then continues with its output. Set `options.waitForSubWorkflow: false` to fire-and-forget: the call dispatches, the caller moves on immediately, the sub-workflow runs in the background, and downstream sees no return data.\n\n### The only true parallelization n8n offers\n\n`mode: each` + `waitForSubWorkflow: false` is **the only way to get genuinely concurrent sub-workflow execution**: N items dispatch N runs that execute in parallel (still bounded by per-instance concurrency limits). The caller doesn't know when — or whether — any of them finished, so it's only useful with a separate completion-tracking mechanism, typically a Data Table the sub-workflow updates as it progresses. The full stage → dispatch → poll pattern is in **SUBWORKFLOW_PATTERNS.md** (\"Fire-and-forget parallelization\").\n\n---\n\n## Splitting by input shape (the N+1 pattern)\n\nWhen a sub-workflow has multiple input paths whose contracts *genuinely* differ — binary vs JSON, sync vs async, divergent auth schemes — don't cram them under one trigger with passthrough + an internal Switch. The forcing function is real: passthrough (for binary or zero-input) and Define Below (for typed inputs) are mutually exclusive on a single trigger. The reflex to \"pick passthrough because it's most permissive, then branch inside\" costs you the typed schema (no clean agent tool), grows branch-shape cruft, and turns every new input shape into more branching.\n\nThe fix: for N divergent input contracts, build **N+1 sub-workflows** — one outer per contract, each doing its input-specific prep (validation, fetching, hashing, extraction) and calling **one shared downstream** sub-workflow with a normalized shape. The shared core has a single typed input contract and knows nothing about which outer called it. The worked example (process a paper from an external ID *or* an uploaded PDF) is in **SUBWORKFLOW_PATTERNS.md**.\n\n---\n\n## Sub-workflow as an agent tool\n\nA sub-workflow with a typed Define Below trigger doubles as an AI-agent tool: the agent fills the declared fields via `$fromAI`, the body runs, the result comes back as the tool observation. This is the high-value reason to default to Define Below — passthrough triggers can't expose a fill-able schema.\n\nThe zero-input case still works as a tool: the agent's only decision is whether to invoke. The binary case does *not* wire cleanly as a tool, because agents can't pass binary directly.\n\nFor tool naming, descriptions, and the binary-input workaround, see **n8n-agents**; for the binary handling itself, **n8n-binary-and-data**.\n\n---\n\n## Anti-patterns\n\n| Anti-pattern | What goes wrong | Fix |\n|---|---|---|\n| Duplicating the same logic in three workflows | A bug gets fixed in two places, the third drifts | Extract once to a named sub-workflow |\n| Building a new sub-workflow without searching | The library grows duplicates; future searches find both | `n8n_list_workflows` \u002F `n8n_get_workflow` first |\n| Trigger set to passthrough when not handling binary and not zero-input | No schema → agents can't fill params, structured callers can't bind | Use Define Below with typed `workflowInputs.values` |\n| Zero-input passthrough with no clear-and-document | Body silently reads stray fields from whatever the caller forwarded | Start with a Set (\"Keep Only Set\", no fields) and a sticky noting \"no inputs expected\" |\n| Sub-workflow named\u002Fdescribed as pure that quietly writes state | Callers can't reason about retry\u002Fidempotency; the side effect ambushes them | Make the side effect part of the contract, or move it out |\n| Sub-workflow with no `description` | Won't be found in future searches; nobody knows what it does | Set `description` with input\u002Foutput shape + keywords |\n| Name like `Helper 3` \u002F no prefix | Doesn't say what it does, matches no prefix search | Verb-first prefix (`Subworkflow:`, `\u003CDomain>:`, `Tool:`) |\n| `mode: all` on a body that assumes one item | Aggregates all inputs into one result instead of one-per-input | `mode: each` (and skip the internal Loop Over Items) |\n| Renaming a live input field without migrating callers | Callers send the old name → body sees `undefined`, no error anywhere | Migrate every caller in the same change; verify with `validate_workflow` |\n| 30-node workflow with no extraction | Hard to read, test, and replace | Extract logical sections into sub-workflows |\n\n---\n\n## What's NOT available via the community MCP\n\n| Want to do | Reality |\n|---|---|\n| Filter\u002Fdiscover workflows by **tag** | The MCP can't read or filter by tags (UI-only). Discovery is the *name* — use verb-first prefixes and `n8n_list_workflows`. |\n| Catch an **unrecognized input field** | n8n doesn't error on one. The body sees `undefined` and the caller never knows — a silent contract break. Verify field renames by hand across callers. |\n| Set the input mode \u002F fields without a typed trigger | The trigger node itself must declare `workflowInputs.values`. Configure it with `n8n_update_partial_workflow` (`updateNode` \u002F `patchNodeField`); validate with `get_node` \u002F `validate_node`. |\n\nWhat the MCP **can** do: build the sub-workflow and its callers (`n8n_update_partial_workflow` with `addNode` \u002F `addConnection` \u002F `updateNode` \u002F `patchNodeField`), discover existing ones (`n8n_list_workflows`, `n8n_get_workflow`), validate (`validate_workflow`, `n8n_validate_workflow`), test in isolation (`n8n_test_workflow`), inspect runs (`n8n_executions`), back a stateful sub-workflow with a Data Table (`n8n_manage_datatable`), and activate (`activateWorkflow`).\n\n---\n\n## Reference files\n\n| File | Read when |\n|---|---|\n| **SUBWORKFLOW_PATTERNS.md** | `mode: all` vs `each` in depth, splitting by input shape (the N+1 worked example), fire-and-forget parallelization with Data Table polling |\n| **NAMING_AND_DISCOVERY.md** | Naming a new sub-workflow, the verb-first prefix convention, searching for existing ones, writing a discoverable description |\n\n---\n\n## Integration with other skills\n\n- **n8n-workflow-patterns** — use it for the overall shape of the orchestrating workflow; use this skill to decide which sections become sub-workflows.\n- **n8n-mcp-tools-expert** — parameter formats for `n8n_list_workflows`, `n8n_get_workflow`, `n8n_update_partial_workflow`, and `n8n_manage_datatable` (the Data Table behind a stateful sub-workflow and the fire-and-forget poll).\n- **n8n-node-configuration** — `workflowInputs` and the `inputSource` (Define Below vs passthrough) toggle are displayOptions-driven config on the Execute Workflow Trigger.\n- **n8n-expression-syntax** — reading inputs (`$json`, `$('When Executed by Another Workflow')`) and the legitimate final-Set exception both live here.\n- **n8n-error-handling** — expected failures return `{ ok: false, error }`; unexpected ones throw and route through error outputs. A sub-workflow boundary is a natural place to define that line.\n- **n8n-validation-expert** — validate the sub-workflow and its callers; an unrecognized input field won't surface here, so verify field changes manually.\n- **n8n-code-javascript \u002F n8n-code-python** — when a sub-workflow's body is a single Code node, its contract is still the trigger's typed inputs and the returned shape, not the Code node's internals.\n- **n8n-code-tool** — the Custom Code Tool is the *inline* agent-tool option; a sub-workflow tool is the reusable, multi-step one. Pick the sub-workflow when the logic is shared across agents or needs the full Code-node sandbox.\n- **n8n-agents** — wiring a typed sub-workflow as an agent tool, including the zero-input and binary cases.\n- **n8n-binary-and-data** — passthrough triggers for binary input, and why binary can't flow through an agent tool directly.\n- **using-n8n-mcp-skills** — when to consult which skill across a build.\n\n---\n\n## Quick reference checklist\n\nBefore shipping a sub-workflow:\n\n- [ ] **Searched first** with `n8n_list_workflows` \u002F `n8n_get_workflow` — it doesn't already exist\n- [ ] **Trigger uses Define Below** with typed `workflowInputs.values` (unless binary or zero-input)\n- [ ] **Zero-input passthrough** (if used) starts with a \"Keep Only Set\" Set node + a sticky noting no inputs\n- [ ] **Name** has a verb-first prefix (`Subworkflow:`, `\u003CDomain>:`, `Tool:`)\n- [ ] **Description** documents input\u002Foutput shape and carries searchable keywords\n- [ ] **Returns a natural, consistent shape** via a final `Return` Set node — not a storage shape\n- [ ] **Expected failures** return `{ ok: false, error }`; only unexpected ones throw\n- [ ] **Caller `mode`** is `each` if the body assumes a single item (not an internal Loop Over Items)\n- [ ] **`waitForSubWorkflow`** is set deliberately (`false` only with a completion-tracking mechanism)\n- [ ] **Stateful sub-workflows** declare their side effect in name + description — no accidental state\n- [ ] **Validated** with `validate_workflow`; tested in isolation with `n8n_test_workflow`\n\n---\n\n**Remember**: a sub-workflow is a function. Its API is the trigger's typed inputs and the last node's output shape — make both explicit, name it so it's found, and call it with the `mode` its body expects. A passthrough trigger that isn't for binary or a zero-arg op, or a name nobody can search, is how a reusable function quietly becomes the next duplicate.","# n8n Sub-workflows\n\nA sub-workflow is a reusable function. An **Execute Workflow Trigger** declares typed inputs, the body does the work, and the last node returns the output. A caller invokes it through an **Execute Workflow** node like any other step.\n\nThat framing buys you the things functions buy you everywhere: encapsulation, reuse, testability, replaceability. It's the primary reuse mechanism in n8n, and it's badly underused. Without it, the same logic gets copy-pasted across workflows — then a bug gets fixed in two places, the third copy gets missed, and your \"identical\" copies quietly drift apart.\n\nThis skill is about when to reach for a sub-workflow, how to define its input\u002Foutput contract so callers (and agents) can actually use it, how to call it correctly (`all` vs `each`, blocking vs fire-and-forget), and how to name it so it gets found instead of rebuilt.\n\n---\n\n## The two non-negotiables\n\nEverything else is judgement. These two are not.\n\n### 1. Search before you build\n\nBefore you write logic for a generic problem, check whether a sub-workflow already does it. The community MCP can't filter workflows by tag, so the **name is the discovery surface**:\n\n```\nn8n_list_workflows()                          # scan the library\nn8n_get_workflow({ id: \"\u003Ccandidate>\" })       # read its inputs\u002Foutputs + body\n```\n\nIf something fits, use it and tell the user (\"I found `Subworkflow: Parse RFC2822 date` — using that\"). If nothing fits, build it *with a discoverable name* so the next search finds it. The discovery convention (verb-first prefixes) lives in **NAMING_AND_DISCOVERY.md**.\n\n### 2. The Execute Workflow Trigger uses \"Define Below\" with typed fields — not passthrough\n\nThe trigger has two input modes. **Default to \"Define Below\"** with explicit typed fields. Define Below is the only mode that gives callers a schema to fill — it's what lets an AI agent pass values via `$fromAI` and what lets structured callers map fields cleanly. Passthrough has no schema, so the trigger can't be wired as a clean agent tool and structured callers have nothing to bind to.\n\nTwo exceptions, and only two:\n\n- **Binary input.** Typed fields are JSON-only. If the sub-workflow must receive an image\u002Ffile\u002FPDF, you need passthrough so the `binary` slot flows through.\n- **Zero inputs.** Define Below requires at least one field. A genuinely no-arg operation (\"list active credentials\", \"current count\") has nowhere to put an empty schema, so passthrough is the only option.\n\nOutside those two cases, passthrough is a bug. See \"Inputs and outputs as a contract\" below.\n\n---\n\n## Should this be a sub-workflow?\n\nYou're about to write a chunk of logic. Run it through this:\n\n```\nCould this plausibly be needed in another workflow?\n  └─ Yes → extract.\n\nIs it a generic concern (auth, retry, parsing, formatting, ID generation)?\n  └─ Almost always → extract. These are the canonical reusable sub-workflows.\n\nIs it >5 nodes and conceptually one thing?\n  └─ Probably extract, even if reuse isn't certain. It's better isolated.\n\nIs it one HTTP call with no logic around it?\n  └─ Don't. A sub-workflow that's just trigger → HTTP → return adds a boundary\n     for nothing.\n\nIs it tightly coupled to this one caller's data shape?\n  └─ Don't extract yet — fix the data shape first, or you just relocate the coupling.\n```\n\nThe reasons to extract go beyond reuse:\n\n- **Readability.** The caller shows one node (\"Parse date\") instead of five.\n- **Testability.** Run the sub-workflow alone with pinned input (`n8n_test_workflow`).\n- **Replaceability.** Swap the implementation without rippling to callers.\n\nA 20-node workflow is fine *if it's mostly a linear sequence of Execute Workflow calls and decisions* — each node has one purpose, and you inspect a section by opening the sub-workflow it calls. A 20-node workflow of inline transformations is not fine. If yours has 15+ nodes and isn't mostly sub-workflow calls and branches, extract more.\n\n---\n\n## Stateless vs. stateful (deliberately)\n\nBoth are first-class. The choice is about intent and what the contract promises.\n\n**Stateless** — input in, output out, no I\u002FO beyond that. The default for pure logic. When you need it again, you call it without worrying about side effects firing.\n\n- `Subworkflow: Parse RFC2822 date` — date string → ISO date or error.\n- `Subworkflow: Compute MRR from subscription` — subscription object → number.\n- `Subworkflow: Format invoice as HTML` — invoice data → HTML string.\n\n**Stateful (deliberate)** — reads or writes external state *behind a clean contract*. This is the repository pattern: the sub-workflow abstracts the storage operation so callers think in domain terms, not SQL.\n\n- `Customer: get by id` — id → customer object or `{ ok: false, error: \"not_found\" }`. Reads the DB.\n- `Customer: write billing record` — record → `{ ok: true, id }`. Writes the DB.\n- `Notify: send to on-call` — channel, message → `{ ok: true, messageId }`. Calls Slack\u002FSMTP.\n\nWhy build these as sub-workflows: callers think `get customer by id` instead of writing the query; you can swap the store (Postgres → Supabase, native node → HTTP) without touching a single caller; and idempotency, retry, and validation get centralized in one place.\n\nWhat to avoid is **accidental state** — a sub-workflow named and described as pure that quietly writes to a log table. That ambushes every caller who reasonably assumed it was safe to retry or compose. Either make the side effect part of the contract (rename it, document it, return its result) or move it out.\n\n---\n\n## Inputs and outputs as a contract\n\nThe trigger's declared fields and the last node's output shape *are* the sub-workflow's API. Treat them like one.\n\n### Declaring typed inputs (Define Below)\n\nEach declared input is a typed parameter the caller fills. Pick types deliberately (`string`, `number`, `boolean`, `array`, `object`) — an agent uses these as the required types when filling tool parameters, and humans rely on them when wiring callers. The trigger node parameters look like this:\n\n```json\n{\n  \"type\": \"n8n-nodes-base.executeWorkflowTrigger\",\n  \"parameters\": {\n    \"workflowInputs\": {\n      \"values\": [\n        { \"name\": \"list_of_ids\",        \"type\": \"array\" },\n        { \"name\": \"include_transcript\", \"type\": \"boolean\" },\n        { \"name\": \"session_id\",          \"type\": \"string\" }\n      ]\n    }\n  }\n}\n```\n\nInside the body, read them as `$json.list_of_ids`, or from anywhere downstream as `$('When Executed by Another Workflow').first().json.\u003Cfield>` (see **n8n-expression-syntax**).\n\n### The contract rules\n\n- **Document inputs and outputs in the workflow `description`.** Field names, types, purpose, and a few representative keywords. The description is what callers (human and agent) read for the contract, and it's what `n8n_list_workflows` matches against.\n- **Return consistent, natural shapes — not storage shapes.** A sub-workflow that owns a Data Table or an S3 file hides that representation from callers. Arrays return as arrays, objects as objects, dates as ISO strings — regardless of whether the underlying storage was JSON-stringified text. The return contract is the *interface*; the storage layout is *implementation detail*. Common slip: a sub-workflow with a \"fresh\" path (just-computed, natural shape) and a \"cached\" path (just read from a stringified column). Wrong instinct: stringify the fresh path to match the cached one. Right instinct: parse the cached path so both return the natural shape.\n- **Return errors, don't always throw.** For *expected* failures (a parse error, a not-found), return `{ ok: false, error: \"...\" }` so the caller can branch without wiring an error output. Reserve throwing for genuinely unexpected failures — see **n8n-error-handling**.\n- **The contract is frozen once it has callers.** Adding *optional* fields is safe. Renaming or removing a field is dangerous: n8n won't error on an unrecognized input field — the body just sees `undefined`, the caller has no idea, and you get a silent contract break. To change a field, enumerate every caller (`n8n_list_workflows` + inspect each one's Execute Workflow node), migrate them in the same change, and verify with `validate_workflow` and `n8n_get_workflow` before you're done.\n\n### The final Return node — the legitimate Set exception\n\nShape the output with a final **Set \u002F Edit Fields** node, named `Return` or `Return \u003Cthing>`. This is the one place a Set node earns its keep against the usual \"don't add a trailing Set node\" advice from **n8n-expression-syntax**: the implicit consumer of a sub-workflow's last node is *every caller*, so an explicit Set makes the return contract visible — a reader sees the whole API by reading one node, and you strip any noise fields the last computation node carried.\n\n---\n\n## Calling sub-workflows: `mode` and `waitForSubWorkflow`\n\nTwo settings on the caller's **Execute Workflow** node decide how the sub-workflow runs.\n\n### `mode`: `all` vs `each`\n\n| `mode` | Sub-workflow runs | Items per run |\n|---|---|---|\n| `all` (default) | once | all N items (flowing per-item through nodes as usual) |\n| `each` | N times | exactly one item per run |\n\nFor a body that just processes items the normal way, the two are equivalent — n8n nodes iterate per-item either way. **The split only matters when the body assumes it sees exactly one item**: a per-run aggregation, \"this is THE customer to act on\" logic, or a final write that should fire once per input. With `all`, that body gets all N items at once and the assumption breaks (you aggregate everyone into one result instead of one-per-input). With `each`, each invocation gets one item and the assumption holds.\n\nSo: when you need per-item iteration, prefer `mode: each` over dropping a Loop Over Items node *inside* the sub-workflow. The mode does the iteration for you, and the body stays simple and single-item.\n\n### `waitForSubWorkflow`: `true` vs `false`\n\n`waitForSubWorkflow` defaults to `true` — the caller blocks until the sub-workflow returns, then continues with its output. Set `options.waitForSubWorkflow: false` to fire-and-forget: the call dispatches, the caller moves on immediately, the sub-workflow runs in the background, and downstream sees no return data.\n\n### The only true parallelization n8n offers\n\n`mode: each` + `waitForSubWorkflow: false` is **the only way to get genuinely concurrent sub-workflow execution**: N items dispatch N runs that execute in parallel (still bounded by per-instance concurrency limits). The caller doesn't know when — or whether — any of them finished, so it's only useful with a separate completion-tracking mechanism, typically a Data Table the sub-workflow updates as it progresses. The full stage → dispatch → poll pattern is in **SUBWORKFLOW_PATTERNS.md** (\"Fire-and-forget parallelization\").\n\n---\n\n## Splitting by input shape (the N+1 pattern)\n\nWhen a sub-workflow has multiple input paths whose contracts *genuinely* differ — binary vs JSON, sync vs async, divergent auth schemes — don't cram them under one trigger with passthrough + an internal Switch. The forcing function is real: passthrough (for binary or zero-input) and Define Below (for typed inputs) are mutually exclusive on a single trigger. The reflex to \"pick passthrough because it's most permissive, then branch inside\" costs you the typed schema (no clean agent tool), grows branch-shape cruft, and turns every new input shape into more branching.\n\nThe fix: for N divergent input contracts, build **N+1 sub-workflows** — one outer per contract, each doing its input-specific prep (validation, fetching, hashing, extraction) and calling **one shared downstream** sub-workflow with a normalized shape. The shared core has a single typed input contract and knows nothing about which outer called it. The worked example (process a paper from an external ID *or* an uploaded PDF) is in **SUBWORKFLOW_PATTERNS.md**.\n\n---\n\n## Sub-workflow as an agent tool\n\nA sub-workflow with a typed Define Below trigger doubles as an AI-agent tool: the agent fills the declared fields via `$fromAI`, the body runs, the result comes back as the tool observation. This is the high-value reason to default to Define Below — passthrough triggers can't expose a fill-able schema.\n\nThe zero-input case still works as a tool: the agent's only decision is whether to invoke. The binary case does *not* wire cleanly as a tool, because agents can't pass binary directly.\n\nFor tool naming, descriptions, and the binary-input workaround, see **n8n-agents**; for the binary handling itself, **n8n-binary-and-data**.\n\n---\n\n## Anti-patterns\n\n| Anti-pattern | What goes wrong | Fix |\n|---|---|---|\n| Duplicating the same logic in three workflows | A bug gets fixed in two places, the third drifts | Extract once to a named sub-workflow |\n| Building a new sub-workflow without searching | The library grows duplicates; future searches find both | `n8n_list_workflows` \u002F `n8n_get_workflow` first |\n| Trigger set to passthrough when not handling binary and not zero-input | No schema → agents can't fill params, structured callers can't bind | Use Define Below with typed `workflowInputs.values` |\n| Zero-input passthrough with no clear-and-document | Body silently reads stray fields from whatever the caller forwarded | Start with a Set (\"Keep Only Set\", no fields) and a sticky noting \"no inputs expected\" |\n| Sub-workflow named\u002Fdescribed as pure that quietly writes state | Callers can't reason about retry\u002Fidempotency; the side effect ambushes them | Make the side effect part of the contract, or move it out |\n| Sub-workflow with no `description` | Won't be found in future searches; nobody knows what it does | Set `description` with input\u002Foutput shape + keywords |\n| Name like `Helper 3` \u002F no prefix | Doesn't say what it does, matches no prefix search | Verb-first prefix (`Subworkflow:`, `\u003CDomain>:`, `Tool:`) |\n| `mode: all` on a body that assumes one item | Aggregates all inputs into one result instead of one-per-input | `mode: each` (and skip the internal Loop Over Items) |\n| Renaming a live input field without migrating callers | Callers send the old name → body sees `undefined`, no error anywhere | Migrate every caller in the same change; verify with `validate_workflow` |\n| 30-node workflow with no extraction | Hard to read, test, and replace | Extract logical sections into sub-workflows |\n\n---\n\n## What's NOT available via the community MCP\n\n| Want to do | Reality |\n|---|---|\n| Filter\u002Fdiscover workflows by **tag** | The MCP can't read or filter by tags (UI-only). Discovery is the *name* — use verb-first prefixes and `n8n_list_workflows`. |\n| Catch an **unrecognized input field** | n8n doesn't error on one. The body sees `undefined` and the caller never knows — a silent contract break. Verify field renames by hand across callers. |\n| Set the input mode \u002F fields without a typed trigger | The trigger node itself must declare `workflowInputs.values`. Configure it with `n8n_update_partial_workflow` (`updateNode` \u002F `patchNodeField`); validate with `get_node` \u002F `validate_node`. |\n\nWhat the MCP **can** do: build the sub-workflow and its callers (`n8n_update_partial_workflow` with `addNode` \u002F `addConnection` \u002F `updateNode` \u002F `patchNodeField`), discover existing ones (`n8n_list_workflows`, `n8n_get_workflow`), validate (`validate_workflow`, `n8n_validate_workflow`), test in isolation (`n8n_test_workflow`), inspect runs (`n8n_executions`), back a stateful sub-workflow with a Data Table (`n8n_manage_datatable`), and activate (`activateWorkflow`).\n\n---\n\n## Reference files\n\n| File | Read when |\n|---|---|\n| **SUBWORKFLOW_PATTERNS.md** | `mode: all` vs `each` in depth, splitting by input shape (the N+1 worked example), fire-and-forget parallelization with Data Table polling |\n| **NAMING_AND_DISCOVERY.md** | Naming a new sub-workflow, the verb-first prefix convention, searching for existing ones, writing a discoverable description |\n\n---\n\n## Integration with other skills\n\n- **n8n-workflow-patterns** — use it for the overall shape of the orchestrating workflow; use this skill to decide which sections become sub-workflows.\n- **n8n-mcp-tools-expert** — parameter formats for `n8n_list_workflows`, `n8n_get_workflow`, `n8n_update_partial_workflow`, and `n8n_manage_datatable` (the Data Table behind a stateful sub-workflow and the fire-and-forget poll).\n- **n8n-node-configuration** — `workflowInputs` and the `inputSource` (Define Below vs passthrough) toggle are displayOptions-driven config on the Execute Workflow Trigger.\n- **n8n-expression-syntax** — reading inputs (`$json`, `$('When Executed by Another Workflow')`) and the legitimate final-Set exception both live here.\n- **n8n-error-handling** — expected failures return `{ ok: false, error }`; unexpected ones throw and route through error outputs. A sub-workflow boundary is a natural place to define that line.\n- **n8n-validation-expert** — validate the sub-workflow and its callers; an unrecognized input field won't surface here, so verify field changes manually.\n- **n8n-code-javascript \u002F n8n-code-python** — when a sub-workflow's body is a single Code node, its contract is still the trigger's typed inputs and the returned shape, not the Code node's internals.\n- **n8n-code-tool** — the Custom Code Tool is the *inline* agent-tool option; a sub-workflow tool is the reusable, multi-step one. Pick the sub-workflow when the logic is shared across agents or needs the full Code-node sandbox.\n- **n8n-agents** — wiring a typed sub-workflow as an agent tool, including the zero-input and binary cases.\n- **n8n-binary-and-data** — passthrough triggers for binary input, and why binary can't flow through an agent tool directly.\n- **using-n8n-mcp-skills** — when to consult which skill across a build.\n\n---\n\n## Quick reference checklist\n\nBefore shipping a sub-workflow:\n\n- [ ] **Searched first** with `n8n_list_workflows` \u002F `n8n_get_workflow` — it doesn't already exist\n- [ ] **Trigger uses Define Below** with typed `workflowInputs.values` (unless binary or zero-input)\n- [ ] **Zero-input passthrough** (if used) starts with a \"Keep Only Set\" Set node + a sticky noting no inputs\n- [ ] **Name** has a verb-first prefix (`Subworkflow:`, `\u003CDomain>:`, `Tool:`)\n- [ ] **Description** documents input\u002Foutput shape and carries searchable keywords\n- [ ] **Returns a natural, consistent shape** via a final `Return` Set node — not a storage shape\n- [ ] **Expected failures** return `{ ok: false, error }`; only unexpected ones throw\n- [ ] **Caller `mode`** is `each` if the body assumes a single item (not an internal Loop Over Items)\n- [ ] **`waitForSubWorkflow`** is set deliberately (`false` only with a completion-tracking mechanism)\n- [ ] **Stateful sub-workflows** declare their side effect in name + description — no accidental state\n- [ ] **Validated** with `validate_workflow`; tested in isolation with `n8n_test_workflow`\n\n---\n\n**Remember**: a sub-workflow is a function. Its API is the trigger's typed inputs and the last node's output shape — make both explicit, name it so it's found, and call it with the `mode` its body expects. A passthrough trigger that isn't for binary or a zero-arg op, or a name nobody can search, is how a reusable function quietly becomes the next duplicate.",{"name":5,"description":7},"master","8ec37df6d71fb664ea19d32c079e7d3ff931a8e0","skills\u002Fmisc\u002Fn8n-subworkflows",3,"https:\u002F\u002Fgithub.com\u002FS3YED\u002Fappie-kit","https:\u002F\u002Fweblyfe.ai","https:\u002F\u002Fgithub.com\u002FS3YED","2026-08-27 01:54:02",{"source":8,"skillName":5,"commands":57,"prompt":67,"zipAvailable":68},[58,61,64],{"tool":59,"command":60},"npx","npx skills add S3YED\u002Fappie-kit --skill n8n-subworkflows",{"tool":62,"command":63},"bunx","bunx skills add S3YED\u002Fappie-kit --skill n8n-subworkflows",{"tool":65,"command":66},"pnpm","pnpm dlx skills add S3YED\u002Fappie-kit --skill n8n-subworkflows","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FS3YED\u002Fappie-kit\u002Fblob\u002Fmaster\u002Fskills\u002Fmisc\u002Fn8n-subworkflows\u002FSKILL.md",true,[],[71,103,137,162,193,215],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":84,"publishedAt":43},"01M6JFD4M6N4DSGC7TXEJ5R3J2","ai-music","AI music generation and audio tools: HeartMuLa lyrics-to-music generation, songwriting craft (+ Suno prompts), and audio spectrogram\u002Ffeature visualization.","https:\u002F\u002Fgithub.com\u002FS3YED\u002Fappie-kit\u002Fblob\u002Fmaster\u002Fskills\u002Fwethlete\u002Fai-music\u002FSKILL.md",[77,80,83],{"categoryNo":78,"categoryName":79,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000013","分析与可视化",{"categoryNo":81,"categoryName":82,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000016","图像与多媒体",{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},[85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102],"music","ai music","humanizer","visualization","Tools","Audio","hermes","hermes agent","songwriting","suno","lyrics","prompts","heartmula","craft","generation","feature","ai music generation","music generation",{"skillNo":104,"name":105,"nameZh":6,"description":106,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":117,"publishedAt":43},"01M6JFCZE4XNFQFMNZDHKHT5V5","agentic-webdesign-design-system-ingestion","Use v0 Design Systems 2.0, Bolt Design System Agents, or Lovable to generate production UI from a client's real design system components — not generic Tailwind. Use when building a client website where brand consistency matters.","https:\u002F\u002Fgithub.com\u002FS3YED\u002Fappie-kit\u002Fblob\u002Fmaster\u002Fskills\u002Fweb-design\u002Fagentic-webdesign-design-system-ingestion\u002FSKILL.md",[109,112],{"categoryNo":110,"categoryName":111,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":113,"categoryName":114,"taxonomyType":115,"taxonomyTypeDesc":116},"01JBSEEDCAT000000000000032","设计师","PROFESSION","适用职业",[34,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136],"agentic","design system","system","ingestion","webdesign","agentic webdesign design system ingestion","components","generate","design systems","website","ui","Tailwind","bolt","lovable","v0","design-system","wed","design system components","appie",{"skillNo":138,"name":139,"nameZh":6,"description":140,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":141,"categories":142,"keywords":145,"publishedAt":43},"01M6JFCVPX3913CFAS6QQJ33ZB","agentic-webdesign-agent-elements","Use 21st.dev Agent Elements — 25 shadcn\u002Fui components purpose-built for AI agent UIs. Tool cards (Bash, Edit, Search, Plan, Subagent, MCP), chat, input, streaming. Open source, shadcn-registry install, no runtime lock-in.","https:\u002F\u002Fgithub.com\u002FS3YED\u002Fappie-kit\u002Fblob\u002Fmaster\u002Fskills\u002Fweb-design\u002Fagentic-webdesign-agent-elements\u002FSKILL.md",[143,144],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},{"categoryNo":113,"categoryName":114,"taxonomyType":115,"taxonomyTypeDesc":116},[118,146,122,147,148,149,124,150,151,152,153,154,155,156,157,158,159,31,160,161],"elements","agentic webdesign agent elements","MCP","ai agent","registry","search","streaming","open source","open","Bash","plan","subagent","edit","install","lock","source",{"skillNo":163,"name":164,"nameZh":6,"description":165,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":166,"categories":167,"keywords":172,"publishedAt":43},"01M6JFCQC7H65M9QJ6TRE71BS1","vercel-deployment","Deploy static sites and frontends to Vercel — handles both CLI and REST API paths, including the CLI token sanitization workaround.","https:\u002F\u002Fgithub.com\u002FS3YED\u002Fappie-kit\u002Fblob\u002Fmaster\u002Fskills\u002Fsoftware-development\u002Fvercel-deployment\u002FSKILL.md",[168,171],{"categoryNo":169,"categoryName":170,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000011","运维与部署",{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},[173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,192],"deployment","vercel deployment","vercel","macos","cli","linux","windows","deploy","vercel deploy","REST","api","site","deploy to vercel","token","rest api","host","sites","paths","sanitization","static site",{"skillNo":194,"name":195,"nameZh":6,"description":196,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":197,"categories":198,"keywords":200,"publishedAt":43},"01M6JFCM4SMTXBM5A01BK2YQG1","software-quality-workflows","Umbrella workflow for TDD, debugging, code simplification, spikes, pre-commit review, and debugger-assisted investigation.","https:\u002F\u002Fgithub.com\u002FS3YED\u002Fappie-kit\u002Fblob\u002Fmaster\u002Fskills\u002Fsoftware-development\u002Fsoftware-quality-workflows\u002FSKILL.md",[199],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},[41,201,202,203,204,205,42,206,207,208,209,210,211,212,213,214,27],"quality","software","software quality workflows","review","tdd","commit","debugging","code","debugger","pre-commit","investigation","code simplification","user","simplification",{"skillNo":216,"name":217,"nameZh":6,"description":218,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":219,"categories":220,"keywords":228,"publishedAt":43},"01M6JFCGD0M6CEATY01W7YN6DB","react-component-refactoring","Safely refactor large React components into smaller, maintainable pieces using proven patterns","https:\u002F\u002Fgithub.com\u002FS3YED\u002Fappie-kit\u002Fblob\u002Fmaster\u002Fskills\u002Fsoftware-development\u002Freact-component-refactoring\u002FSKILL.md",[221,224,227],{"categoryNo":222,"categoryName":223,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000007","代码审查",{"categoryNo":225,"categoryName":226,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000009","前端开发",{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},[229,230,231,232,233,234,235,236,176,237,238,124,239,179,40,208,240,241,242,243],"react","component","refactoring","component refactoring","react component","react component refactoring","frontend","writing","safe","typescript","react components","refactor","simplify","patterns","test-driven-development"]