n8n-io/skills

# n8n Agents

A first-class n8n Agent is a saved resource with its own instructions, model, tools, skills, sub-agents, memory, channels, scheduled tasks, versions, and spend limits. It is configured as JSON through the Agent MCP tools, never with Workflow SDK code. The AI Agent node inside a workflow is a different thing, covered by `n8n-ai-nodes-official`.

<!-- TEMPORARY: revisit when the Preview tag is removed from Agents in the UI, and when Agents are declared ready for Enterprise. -->
Agents are generally available. The UI shows a Preview tag because they change often and some features you might expect aren't there yet. They aren't ready for Enterprise yet: an Enterprise instance may have them enabled, but don't assume it. If `create_agent` isn't in your tool list, Agents aren't enabled on this instance. Say so and offer a workflow instead of guessing.

## Non-negotiables

1. **Always send a memory block when creating over MCP:** `"memory": { "enabled": true, "storage": "n8n" }`. The UI adds it on every save. `create_agent` saves exactly what you send, and without it the Agent forgets the previous turn even inside one session (verified live).
2. **Never publish without the user's explicit OK.** A built Agent is a draft. Configuring a channel on an already published Agent connects it immediately, so confirm that too.
3. **Publish what the Agent calls.** Workflow tools need a When Executed by Another Workflow trigger, the same project, and a published workflow (`validate_agent` reports it). Saved sub-agents must be published too, and nothing checks that: validation and publishing pass, then production delegation fails and the parent quietly answers on its own.
4. **Approval on anything that sends, changes, deletes, or spends**, and know what the approver will see. See `references/APPROVALS.md`.
5. **One `mutate_agent` per change, always with the latest `configHash`.** A stale hash returns `stale_config`: call `get_agent` and retry.

# n8n AI nodes

The AI Agent node (`@n8n/n8n-nodes-langchain.agent`) is a multi-turn LLM driver with sub-nodes for the model, memory, tools, and optional output parser. It lives inside a workflow, which owns its trigger, control flow, and lifecycle.

## AI Agent node or first-class n8n Agent?

"Build me an agent" means a first-class n8n Agent (`n8n-agents-official`) by default. Use the node when the workflow owns the control flow and AI is one bounded step, or when the first-class Agent hits a limit:

<!-- TEMPORARY: revisit each limit below when n8n adds tool access to run data, sessions shared between channels and workflows, or Agents on every instance (Enterprise). -->
| Need | Why the node wins today |
|---|---|
| Trigger or upstream data mapped exactly into a tool parameter | Agent tool expressions only see the model's own arguments. Node tools can use `$('Webhook').item.json...` |
| One conversation shared between a chat channel and other workflows | Agent channel sessions and workflow sessions never meet |
| `create_agent` isn't in the MCP tool list | Agents aren't enabled on this instance |

# n8n Binary and Data

n8n handles two kinds of data: JSON (in `$json`) and binary (in `$binary`), flowing side-by-side. Binary has sharp edges around agent tools, storage, and display contexts (chat surfaces, message rendering).

For tabular storage (Data Tables), see the **`n8n-data-tables-official`** skill.

## Non-negotiables

1. **Binary is in `$binary`, not `$json`.** Don't read file contents from `$json`.
2. **Binary cannot cross the agent tool boundary in either direction.** Tool parameters are JSON only (via `fromAi()`), and tool results are JSON only. Pre-stage binary in storage and pass keys/URLs through JSON. The agent's `passthroughBinaryImages: true` lets the LLM *see* uploaded images for vision, but it does NOT enable tools to receive them. See `references/AGENT_TOOL_BINARY.md`.

## Strong defaults

- **Merge nodes keep binary in context.** When a side computation strips binary, merge it back rather than re-fetching. See `references/MERGE_FOR_CONTEXT.md`.

# n8n Code Nodes

The Code node is powerful and often the wrong tool. The n8n equivalent of dropping into raw SQL when an ORM would do: real cases exist, but the moment a Code node handles logic an expression could, the workflow is harder to read, debug, and maintain. There's also a real perf gap: Code runs in a sandboxed JS runtime, expressions and Edit Fields run in-process, and the per-invocation overhead can be hundreds of times higher in Code (anecdotally ~2ms vs ~600ms for equivalent logic). For hot paths and large item counts, that compounds.

## Strong defaults

1. **Code node is a last resort.** Decision order: expression (`{{...}}`) → arrow function inside Edit Fields → Code node. The first two paths cover most "transform this data" tasks. Code earns its place for multi-source aggregation, external libraries, and a few specific patterns documented below.

2. **Default to JavaScript.** Write JS unless the user explicitly asked for Python ("use Python here," "I'm a Python shop," pasted Python code). Everywhere else in n8n (expressions, Edit Fields) is JS, JS has a curated library allowlist (`lodash`, `crypto`, `luxon`).

## Decision tree

```
Need custom logic?

# n8n Credentials and Security

## Non-negotiables

1. **Secrets via the credential system, never in text fields or SDK code.** API keys, bearer tokens, OAuth secrets, passwords: all go through `newCredential()` or the node's `credentials` parameter. A Set node hardcoding a token and read via `{{$json.token}}` is a text field with extra steps.
2. **List credentials, then bind by ID.** Call `list_credentials({type})` before configuring an auth-needing node. One match: bind via 2-arg `newCredential('Label', 'credId')` at create time, or `setNodeCredential` op on `update_workflow`. Multiple matches: ask the user which. The one-arg `newCredential('Label')` is a placeholder; n8n auto-assigns the most recently edited credential of that type and silently picks wrong when the user has multiples.
3. **Credential creation is the user's job, not yours.** The n8n MCP doesn't expose credential creation. Tell the user the exact credential *type* to create in the UI, then reference it by label in your node config. Don't attempt to create credentials programmatically and don't accept secrets in chat to "set up later".

## Strong defaults

- **Use native credentials when available.** Every native node (Slack, Gmail, Postgres, OpenAI, etc.) has a credential type. Don't reach for generic credential types when a native option exists.
- **For multi-header or header-plus-query auth shapes**, use the `httpCustomAuth` credential type. See `references/CUSTOM_CREDENTIALS.md`.

## The credential system

# n8n Data Tables

Data Tables are n8n's **built-in tabular storage**: real tables inside the n8n instance with columns, types, rows, and CRUD via the `dataTable` node and data-table MCP tools.

Use them for local persistent state: lookup tables, recent events, per-session inventories, counters, idempotency tracking, dedup state when there's row-level logic or external visibility (plain "have I seen this value?" dedup belongs in the `Remove Duplicates` node). Small-to-moderate volume (tens of thousands of rows fine, millions belong in a real DB).

## Non-negotiables

1. **System-managed columns + external IDs.** Three columns auto-exist on every table: `id` (bigserial), `createdAt`, `updatedAt`. Don't declare them in `create_data_table` (errors or shadows the system column). Don't write them on insert. For domain identifiers from outside (arxivId, stripeCustomerId, requestId), add a separate column and key dedup/lookup on that.
2. **Only primitives in columns, nested data uses `string` + `_object` postfix.** No JSON/object/array column types exist. For nested data (arrays, parsed objects), use a `string` column with `JSON.stringify(...)` on write and `JSON.parse(...)` on read. Mark the column with `_object` (e.g., `keyInsights_object`). The postfix is the contract that tells readers to parse. See `references/SCHEMA_DESIGN.md`.

## Strong defaults

- **Don't add a Set node before a Data Table node to modify fields.** The Data Table node's per-column expression slots are just as powerful as Set fields, so the Set node is doing zero work the Data Table node can't do itself. (Same Set-node antipattern called out in `n8n-expressions-official`.)

# n8n Debugging

When something breaks, the cause is almost always:

1. **Parameter misconfiguration** (wrong value, wrong type, missing field).
2. **Stale assumptions** (different version, different behavior than you remember).
3. **Paths misconfigured or misconnected** (wrong output index, wrong merge input, missing wire, IF/Switch wired to the wrong branch).
4. **Upstream data stripped** (an intermediate node replaced `$json` with its own output, so downstream `$json.x` resolves to null even though "it should be there"). Fix: reference the stable upstream node by name (`$('Earlier Node').item.json.x`).
5. **Item context lost** (after Aggregate, Execute Once, or Split Out flows, n8n can't pair `.item` references deterministically, error reads like "The expression is referencing... multiple matching items"). Fix: Merge node to re-establish context, `$input.all().find(...)` for explicit lookup, or redesign to keep item correspondence stable (e.g., split into stateless sub-workflows).
6. **Logical errors** (the wires are right and the parameters are right, but the workflow does the wrong thing, same as a logic bug in code).
7. **Genuine bug** (rare but real).

Diagnose systematically: cheap checks first, deeper investigation only when those fail.

# n8n Error Handling

Default n8n node behavior: error → workflow halts → caller gets nothing useful. For unattended workflows (webhook APIs, scheduled jobs, queue workers), that default is wrong. The symptom is "the integration just stopped working" with no log, no message, no clue.

This skill is about handling errors so failures are loud, structured, and recoverable. Or best case scenario, handled in a way where it self heals.

## Non-negotiables

For any **API-shaped workflow** (webhook trigger paired with `Respond to Webhook`):

1. **Every fallible node's error output is wired, and both paths end at a `Respond to Webhook`.** No hanging error branches, or the caller would see a timeout. "Fallible" = HTTP, DB, third-party API, file operation, anything that throws.
2. **Status code maps to cause.** Caller's fault → 4xx, your fault → 5xx. A 200 default on an error path produces silent failure: caller thinks success, processes empty data.

For any **unattended workflow** (scheduled, cron, queue-driven, agent tool):

# n8n Expressions

n8n's expression language is JavaScript embedded in `{{...}}` blocks. They run synchronously, on a single item at a time (`$json`), with access to upstream nodes (`$('Name')`), Luxon for dates, and most of native JS.

## Non-negotiable

**Reference data by node name, not `$json`.** Use `$('Node Name').item.json.field` (or `.first().json.field`). `$json` works but breaks when any node clears item context (Aggregate, Code with Run for All, branching merges) or a refactor adds an intermediate. Failures are silent, and downstream gets the wrong data with no error. Node-name references are stable.

## Strong defaults

- **No Set nodes whose only purpose is to feed a single downstream field.** Inline the expression at the consumer. Set earns its place when 2+ consumers read the same derived value, the derivation is non-trivial, or the Set is a sub-workflow's final return-shaper. See "The Set-node antipattern" below.
- **Luxon for dates, not the DateTime node.** Date math, formatting, and parsing all work in expressions: `{{ DateTime.now().minus({ days: 7 }).toISO() }}`. The DateTime node is more visible on the canvas for beginner human users, but avoid it unless the user specifically asks for it.
- **Expressions over extra nodes generally.** Build the email body in the email node's body field, and compute the URL in the HTTP Request's URL field. Reach for an extra node when the transform is reused or the *primary purpose* of a section.
- **Multi-line expressions are indented and commented.** When an expression spans more than one line, format it like real code. Most n8n users are not coders, so explain the code with concise inline comments

<!-- TEMPORARY: update whenever n8n mcp capacities are added. a lot of listed functionalities missing are coming soon -->
# n8n Extending MCP

Any n8n workflow with MCP access enabled becomes a tool the coding agent can call by name. Two common cases:

1. **Wrap n8n capabilities the MCP doesn't expose.** The MCP covers workflow CRUD, validation, execution, data tables, credential listing, execution search, folder create/rename/move and folder/project listing, tag listing and attach/detach. Still missing: folder deletion, project create/rename, tag rename/delete, instance metadata, credential creation. Build a workflow that hits the n8n API and exposes the result as an agent tool.
2. **Expose a general-purpose workflow as a tool.** A workflow that has nothing to do with n8n itself (calls a third-party API, runs internal business logic, looks something up in a private system) can be MCP-callable. Lets the agent invoke real operations during a coding session.

The MCP calls your workflow as if it were a native tool: input from the `Execute Workflow Trigger`, output from the workflow's last node.

## When to reach for this

Case 1 (wrap n8n capability):

# n8n Loops

Three meanings of "loop" map to three mechanisms:

1. **"Run this node for every item."** Default. Most nodes loop automatically, so do nothing.
2. **"Run this node *once* with all items, not once per item."** The `executeOnce` setting (single boolean).
3. **"Process items in explicit batches with control flow between iterations."** The `Loop Over Items` node (formerly `Split In Batches`).

For paginated APIs, the HTTP Request node has built-in pagination. Almost always preferable to a hand-built page-counting loop.

## The model: items are an array

Data flows between nodes as an array of items, each `{ json: {...}, binary?: {...} }`. 50 items = 50-entry array.

# n8n Node Configuration

Each n8n node has its own parameter shape, often with conditional fields (parameter X only matters when parameter Y has value Z). Shapes evolve between versions. Guessing produces cryptic validation errors.

Don't guess, use the `get_node_types` tool.

## Non-negotiable

**Call `get_node_types` with discriminators (resource, operation, mode) before configuring a node.** Without discriminators you get the generic shape, missing operation-specific parameters and required fields. Build against the exact shape. Don't guess from memory.

**The live `get_node_types` output is the canonical parameter shape.** The references in this skill cover patterns, gotchas, security rules, and decision-making (when to use which operation, why credentials over text fields, engine retry caps, etc.) not parameter names or field structures. If a reference example conflicts with what `get_node_types` returns, trust the tool. Markdown drifts; the type def is generated from the live source.

**Never guess resource-locator or load-options values.** When `get_node_types` shows a param with `@searchListMethod` or `@loadOptionsMethod` (Slack channels, Sheets tabs/docs, DB tables/columns, model lists, labels), resolve the real value with `explore_node_resources` (pass a `credentialId` from `list_credentials`) and use a returned `value`. If you already know the exact ID, use it; if several match and intent is ambiguous, ask the user. An invented ID validates but points at nothing. Exception: `toolWorkflow.workflowId` has no search method, resolve it via `search_workflows` and use `mode: 'id'`.

# n8n Sub-workflows

Sub-workflows are reusable functions. The `Execute Workflow Trigger` declares input parameters, the body does work, the last node returns output. Callers invoke it like any other node.

That framing opens up the function-shaped wins: encapsulation, reuse, testability, replaceability. It's the primary reuse mechanism in n8n, and unfortunately underused.

Without sub-workflows, the same logic gets duplicated across workflows. Bug fixes happen in multiple places, one gets missed, and "identical" copies drift.

## Non-negotiables

1. **Search before you build.** Before writing logic that handles a generic problem, check if a sub-workflow already exists. Filter by tag (`search_workflows({ tags: ['subworkflow'] })`, a domain tag) and/or keyword (`query: '<keyword>'`). Tags are the discovery mechanism (n8n 2.27.0+).
2. **`Execute Workflow Trigger` uses "Define Below" with typed fields, not passthrough.** Define Below is the only mode that lets agent tools (`fromAi`) and structured callers pass values in. Two exceptions: (a) the sub-workflow specifically needs to receive binary (then it can't be wired as an agent tool directly), or (b) the sub-workflow takes no inputs at all (Define Below requires at least one field). See "Sub-workflow inputs and outputs" below.

## Strong defaults

# n8n Workflow Lifecycle

## The six stages

1. **PLAN.** Gather requirements, ask clarifying questions, search for existing workflows / sub-workflows that already do this.
2. **BUILD.** Write SDK code (with skills: subworkflows, node-config, expressions, code-nodes; readability section below). Use `validate_node_config` as a side-channel for iteration, debugging, or small single-node edits: clean per-parameter errors without full-graph noise. Not a replacement for `validate_workflow` in VALIDATE.
3. **VALIDATE.** `validate_workflow` + `get_workflow_details` for connections, then have the user verify per-node credentials and create anything you couldn't (missing credentials, folders, etc).
4. **TEST.** `test_workflow` with `prepare_workflow_pin_data`; iterate until output matches intent.
5. **PUBLISH.** `publish_workflow` only after stages 3 and 4 are clean.
6. **HANDOFF.** Production handoff: how to trigger it, what it returns, what to watch, what they should know to use it well.

Skipping a stage produces workflows that look done but break in production, or solve the wrong problem entirely. Three most common skips:

- **Build before plan.** "User asked for X, I'll start coding" without confirming what X means, whether the same logic already exists as a sub-workflow, or which folder/project it belongs in. Cheaper to ask one clarifying question than to rebuild after.

# Using n8n Skills

The official n8n MCP evolves over time, so tool names, parameters, and default behaviors can drift between versions. When you spot drift (a tool a skill names doesn't exist, a parameter shape doesn't match what `get_node_types` returns, or behavior differs from what the skill describes), suggest updating the skill and n8n instance to the latest stable.

## Non-negotiables

Three rules with no exceptions. Violating any produces workflows that look right but break in production.

1. **Invoke the relevant skill before any n8n action.** Not just MCP tool calls. Before writing SDK code, configuring a node, designing a workflow, wiring a connection, building an agent, or handling errors: invoke the matching skill via the Skill tool. This document is a router. The skill body has the actual rules. The PreToolUse hooks remind you on the highest-impact MCP calls if a plugin is installed. The responsibility is yours on everything else. Err on the side of reading extra documents.
2. **Validate AND verify before publishing.** `validate_workflow` before `publish_workflow`, and `get_workflow_details` after every create or update to check the `connections` object. Validation alone misses many issues documented in the skills that will silently break workflows.
3. **Tokens/secrets never go in text fields.** Always use the n8n credential system. If no native node exists, configure HTTP Request with the official credential type. See `n8n-credentials-and-security-official`.

## Lean on skills, not training data