n8n-subworkflows

Files (4)

• NAMING_AND_DISCOVERY.md
• README.md
• SKILL.md
• SUBWORKFLOW_PATTERNS.md

SKILL.md (first lines)

# n8n Sub-workflows

A 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.

That 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.

This skill is about when to reach for a sub-workflow, how to define its input/output 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.

---

## The two non-negotiables

Everything else is judgement. These two are not.

### 1. Search before you build

Before 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**:

```
n8n_list_workflows()                          # scan the library
n8n_get_workflow({ id: "<candidate>" })       # read its inputs/outputs + body
```

If 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**.

### 2. The Execute Workflow Trigger uses "Define Below" with typed fields — not passthrough

The 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.

Two exceptions, and only two:

- **Binary input.** Typed fields are JSON-only. If the sub-workflow must receive an image/file/PDF, you need passthrough so the `binary` slot flows through.
- **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.

Outside those two cases, passthrough is a bug. See "Inputs and outputs as a contract" below.

---

## Should this be a sub-workflow?

You're about to write a chunk of logic. Run it through this:

```
Could this plausibly be needed in another workflow?
  └─ Yes → extract.

Is it a generic concern (auth, retry, parsing, formatting, ID generation)?
  └─ Almost always → extract. These are the canonical reusable sub-workflows.

Is it >5 nodes and conceptually one thing?
  └─ Probably extract, even if reuse isn't certain. It's better isolated.

Is it one HTTP call with no logic around it?
  └─ Don't. A sub-workflow that's just trigger → HTTP → return adds a boundary
     for nothing.

Is it tightly coupled to this one caller's data shape?
  └─ Don't extract yet — fix the data shape first, or you just relocate the coupling.
```

The reasons to extract go beyond reuse:

- **Readability.** The caller shows one node ("Parse date") instead of five.
- **Testability.** Run the sub-workflow alone with pinned input: `n8n_test_workflow({workflowId, method: "prepare"})` names the nodes that need data, then `method: "pinned"` runs it with what you build (needs `N8N_MCP_ACCESS_TOKEN` and the workflow's "Available in MCP" setting — see **n8n-mcp-tools-expert**). A sub-workflow has no HTTP trigger, so the default `method: "auto"` cannot run it.
- **Replaceability.** Swap the implementation without rippling to callers.

A 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.

---

## Stateless vs. stateful (deliberately)

Both are first-class. The choice is about intent and what the contract promises.

**Stateless** — input in, output out, no I/O beyond that. The default for pure logic. When you need it again, you call it without worrying about side effects firing.

- `Subworkflow: Parse RFC2822 date` — date string → ISO date or error.
- `Subworkflow: Compute MRR from subscription` — subscription object → number.
- `Subworkflow: Format invoice as HTML` — invoice data → HTML string.

**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.

- `Customer: get by id` — id → customer object or `{ ok: false, error: "not_found" }`. Reads the DB.
- `Customer: write billing record` — record → `{ ok: true, id }`. Writes the DB.
- `Notify: send to on-call` — channel, message → `{ ok: true, messageId }`. Calls Slack/SMTP.

Why 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.

What 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.

---

## Inputs and outputs as a contract

The trigger's declared fields and the last node's output shape *are* the sub-workflow's API. Treat them like one.

### Declaring typed inputs (Define Below)

Each 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:

```json
{
  "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, read them as `$json.list_of_ids`, or from anywhere downstream as `$('When Executed by Another Workflow').first().json.<field>` (see **n8n-expression-syntax**).

### The contract rules

From czlonkowski/n8n-skills, MIT.

More from czlonkowski/n8n-skills