Build reusable sub-workflows in n8n with typed contracts

n8n Sub-workflows teaches how to build reusable n8n sub-workflows with typed inputs, the right execution mode, discoverable names and exposure as AI-agent tools. It is a community skill by Romuald Czlonkowski (czlonkowski/n8n-skills) under the MIT license. A sub-workflow is treated as a reusable function: an Execute Workflow Trigger declares typed inputs, the body does the work, the last node returns the output, and a caller invokes it through an Execute Workflow node. This is n8n's primary reuse mechanism, and it is often underused; without it the same logic gets copy-pasted, a bug is fixed in two places, and the third copy drifts.

Two rules are non-negotiable. The first is to search before building: the community MCP cannot filter workflows by tag, so the name is the discovery surface. Scan the library with n8n_list_workflows, read a candidate with n8n_get_workflow, and reuse it if it fits, telling the user. The second is that the trigger uses Define Below with typed fields rather than passthrough, since only Define Below gives callers and AI agents a schema to fill through $fromAI. There are exactly two exceptions: binary input, because typed fields carry JSON only, and zero inputs, because Define Below needs at least one field. The typed inputs are declared like this:

{
  "type": "n8n-nodes-base.executeWorkflowTrigger",
  "parameters": {
    "workflowInputs": {
      "values": [
        { "name": "list_of_ids",        "type": "array" },
        { "name": "include_transcript", "type": "boolean" },
        { "name": "session_id",          "type": "string" }
      ]
    }
  }
}

Inside the body inputs are read as $json.list_of_ids, or from downstream nodes through the trigger node's name.

A decision tree says when to extract: if the logic could plausibly be needed in another workflow, extract; generic concerns such as auth, retry, parsing, formatting and ID generation almost always deserve extraction; a chunk of more than five nodes that is conceptually one thing probably should be extracted; a single HTTP call with no logic should not; and logic tightly coupled to one caller's data shape should not be extracted until the data shape is fixed. A 20-node workflow is fine if it is mostly Execute Workflow calls and branches, but one with 15 or more nodes of inline transformations needs more extraction. Benefits beyond reuse are readability, testability (run it alone with pinned input via n8n_test_workflow) and replaceability.

Sub-workflows may be stateless (pure input to output, such as parsing a date or computing MRR) or deliberately stateful behind a clean contract, following the repository pattern (get a customer by ID, write a billing record, notify on-call). Accidental state is the anti-pattern: a workflow described as pure that quietly writes to a log table ambushes callers who assumed it was safe to retry.

Use it when shared or multi-step logic should become a typed reusable workflow, when a workflow is becoming hard to reason about, or when an agent needs a workflow exposed as a tool. Preserve authentication and authorization boundaries when extracting logic, keep credentials out of inputs and returned data, declare state-changing behavior explicitly, and ask before running or activating a sub-workflow that sends, writes, deletes or calls a billable external service. Validation does not catch every caller contract mismatch, side effect or item-linking error, tags and some settings remain UI-only, and refactoring requires checking every caller.

The trigger's declared fields and the last node's output shape are the sub-workflow's API. Document inputs and outputs in the workflow description, since that is what callers and n8n_list_workflows read. Return natural, consistent shapes (arrays as arrays, objects as objects, dates as ISO strings) rather than storage shapes, and return { ok: false, error: "..." } for expected failures while throwing only for unexpected ones. A contract is frozen once it has callers: adding optional fields is safe, but renaming or removing a field is dangerous, because n8n does not error on an unrecognized input and the body just sees undefined, so every caller must be migrated in the same change and verified with validate_workflow. Shape the output with a final Set node named Return, the legitimate exception to the advice against trailing Set nodes.

On the caller side, mode set to all (the default) runs the sub-workflow once with all N items, while each runs it N times with one item each. The difference matters only when the body assumes one item, such as per-run aggregation, logic about the one entity to act on, or a final write that should fire once per input; prefer each over a Loop Over Items node inside. waitForSubWorkflow defaults to true, and setting it to false makes the call fire-and-forget. Combining each with waitForSubWorkflow: false is the only true concurrency n8n offers, and it needs separate completion tracking, typically a Data Table. When input contracts genuinely diverge (binary versus JSON, sync versus async), build N+1 sub-workflows: one outer per contract and one shared downstream core with a single typed contract.

Naming is the discovery mechanism. Use verb-first prefixes: Subworkflow: <verb> <object> for generic stateless ones, <Domain>: <verb> <object> for domain-specific ones such as Customer or Billing, and Tool: <description> for agent tools, set at creation together with a description that states inputs, outputs and keywords. A healthy library has roughly 5 to 20 generic entries; 100 suggests duplicates and many entries named Helper signals broken discoverability. Renaming keeps the workflow ID, so callers keep working. Cross-project sharing on project-enabled instances is opt-in and should be limited to stateless, generic workflows.

A sub-workflow with a typed Define Below trigger doubles as an agent tool, with the agent filling fields via $fromAI. A zero-input one works too, but a binary-input one does not wire cleanly as a tool.

It works with n8n and its MCP tools (n8n_list_workflows, n8n_get_workflow, n8n_update_partial_workflow, n8n_test_workflow, n8n_executions, n8n_manage_datatable, validate_workflow), and with the companion n8n skills for workflow patterns, expressions, error handling, agents and binary data.

It suits n8n builders who want to stop duplicating logic and instead maintain a small, well-named library of typed, testable building blocks that callers and agents can rely on.