using-n8n-mcp-skills

Files (2)

• README.md
• SKILL.md

SKILL.md (first lines)

# Using the n8n-mcp Skills

This is a **router**, not a reference. It tells you which skill owns the rules for what
you're about to do. The skill bodies hold the actual guidance — invoke them with the
Skill tool. When in doubt, load more skills rather than fewer.

The community **n8n-mcp** server and n8n itself move faster than any model's training
cutoff. Tool names, parameters, node `typeVersion`s, and default behaviors drift between
releases. When you spot drift — a tool a skill names doesn't exist, a parameter shape
doesn't match what `get_node` returns, behavior differs from what a skill describes —
trust the **live tool**, tell the user, and suggest updating the pack and the instance.

## Non-negotiables

Three rules with no exceptions. Each one prevents a class of workflow that looks correct
but breaks in production.

1. **Invoke the relevant skill before any n8n action** — not just before MCP calls.
   Before writing an expression, configuring a node, designing a workflow, wiring a
   connection, or writing Code, invoke the matching skill. PreToolUse hooks remind you on
   the highest-impact tool calls, but they exist **only in the Claude Code plugin
   install**. Everywhere else — Claude.ai skill uploads, and any client that loads this
   pack as an Agent Plugin (Codex, Cursor, Copilot and the rest) — nothing nudges you and
   it's on you. Assume you are un-hooked unless you have seen a
   hook fire this session.
2. **Validate AND verify before activating.** Run `validate_workflow` (or
   `n8n_validate_workflow` by id) before you activate, and call `n8n_get_workflow` after
   every create or update to inspect the `connections` object. Validation alone misses
   silently dropped wires, Merge index off-by-one, and error outputs that were never
   wired. Validation passing means the JSON is well-formed — not that the workflow is
   correct. A green test run isn't proof either: JS errors inside `{{ }}` resolve silently to
   `null` (a Filter with a broken condition drops every item and still shows success), so
   inspect the output values. See `n8n-expression-syntax`.
3. **Secrets never go in text fields.** Tokens, API keys, and passwords always go through
   the n8n credential system. If no native node exists, use the HTTP Request node with
   the official credential type. A Set node holding a token referenced via `{{ $json.token }}`
   is a leak with extra steps. See `n8n-mcp-tools-expert`.

## Lean on skills, not training data

n8n changes constantly. "Remembered" parameter names are often silently wrong — they
validate as plain strings and then do nothing at runtime. If a skill contradicts your
memory, trust the skill. If `get_node` contradicts a skill, trust the
tool and flag the drift.

## Strong defaults

These are the defaults; the Code exceptions below are a closed list.

**Native node first, Code last.** Pick in this order: the service's own node (HTTP Request
only when no node covers the operation), then a native node for the job, then a short
expression inside that node, then Code. A function body or several statements inside
`{{ }}` is code: it belongs in a Code node.

| Job | Use |
|---|---|
| Flag that only picks a route; dropping items | conditions in IF / Switch / Filter |
| Constant, error or return item | Edit Fields (Set) |
| Restore earlier context | `$('Node').item` |
| Pick rows after a Data Table get | the get's order by + limit |
| Group and sum | Summarize |
| Items to one array / array to items | Aggregate / Split Out |
| Join two lists | Merge (combine by fields) |
| Diff or sync two lists | Compare Datasets |
| Dedupe, also across runs | Remove Duplicates |
| Top-N | Sort + Limit |
| Dates | Date & Time, or a Luxon one-liner |
| XML / HTML / Markdown / CSV / XLSX | XML, HTML, Markdown, Extract From File / Convert To File |
| Paging an API (no service node) | HTTP Request's pagination option |
| Throttle calls | HTTP Request's batching option, or Loop + Wait |
| Hash, HMAC, UUID | Crypto (+ Webhook raw body) |

Code is right only for: loops or recursion no node expresses, state across runs, parsing no
node handles, libraries, heavy all-items work on queue-mode workers (thousands of items,
stated or measured), or one short Code node (~15 lines) replacing 4+ glue nodes that only
reshape data. Every Code or HTTP Request node that stays gets the note
`Why Code: <native node considered> — <reason>` (or `Why HTTP:`). See
`n8n-node-configuration` and `n8n-code-javascript`.

- **A Set that only re-maps fields for the next node is the antipattern.** Put those
  expressions in the next node. Edit Fields as a named step is fine. See `n8n-expression-syntax`.
- **Per-item iteration is automatic.** Don't add a Loop Over Items node to "make it loop"
  when default per-item execution already handles the case.
- **Configure from the live schema, never from memory.** `get_node` before you set
  parameters. See `n8n-node-configuration`.

## Red flags: "about to ___" → invoke ___

If you catch yourself thinking any of these, stop and invoke the named skill first.

| Thought | Invoke |
|---|---|
| "This workflow is simple, I'll just build it" | `n8n-workflow-patterns` — most "simple" flows ship at 10+ nodes |
| "I'll add a Set node to map these fields" | `n8n-expression-syntax` — a Set that only re-maps for the next node is the antipattern; named steps are fine |
| "I'll just use a Code node, it's easier" | the job table above, then `n8n-code-javascript` — Code only for the closed list, with a `Why Code:` note |
| "The user mentioned data, I'll write Python" | `n8n-code-javascript` — default JS; Python (`n8n-code-python`) only on explicit ask |
| "I'm writing code an AI agent will call" | `n8n-code-tool` — a different runtime contract from the Code node |
| "I'll call this API with HTTP Request" | `n8n-mcp-tools-expert` — `search_nodes` for the service's own node first; a kept HTTP node gets `Why HTTP:` |
| "I'll wire a Merge with 3 sources" | `n8n-node-configuration` — Merge defaults to 2 inputs (`numberInputs`); the 3rd silently drops |
| "Validation passed, I'm ready to activate" | `n8n-validation-expert` + `n8n-workflow-patterns` — run the antipattern scan |
| "Validation threw an error I don't understand" | `n8n-validation-expert` — what each error and warning means, and which are must-fix vs. best-practice advice |
| "I'll reference `$json.x` here" | `n8n-expression-syntax` — prefer `$('Node').item.json.x` in branchy workflows |
| "This webhook/scheduled flow is happy-path only" | `n8n-error-handling` — wire an error branch on every fallible node; 4xx caller faults, 5xx yours |
| "I'll pass this file/image through as JSON" | `n8n-binary-and-data` — file contents live in `$binary`, and can't cross the agent-tool boundary |
| "I'll wire up an AI agent and give the model some tools" | `n8n-agents` — tool names & descriptions ARE the prompt; memory, structured output, and topology have traps |
| "I'll copy this logic into another workflow" / "this is getting big" | `n8n-subworkflows` — extract a reusable sub-workflow; search before building |
| "I'll create that credential / open that workflow" (account has >1 instance) | `n8n-multi-instance` — name the target with `instance: "<name>"`; unnamed calls hit a default other chats can move |

## Skill index

| Skill | Reach for it when |
|---|---|
| `using-n8n-mcp-skills` | This router (auto-loaded). Names the skill that owns your task. |
| `n8n-mcp-tools-expert` | Choosing or calling any n8n-mcp tool; node discovery; credentials; data tables; security audit; templates |
| `n8n-workflow-patterns` | Designing or building a workflow; picking an architecture (webhook / HTTP API / database / AI agent / scheduled / batch) |
| `n8n-node-configuration` | Configuring any node; operation-aware required fields; property dependencies; surgical field edits |
| `n8n-expression-syntax` | Writing `{{ }}`, `$json`/`$node`/`$now`; mapping data between nodes; the transform gatekeeper; Set-node discipline |
| `n8n-validation-expert` | Interpreting validation errors/warnings; false positives; the validation loop; auto-fix; reviewing an existing workflow |
| `n8n-code-javascript` | Any Code node in JavaScript; data access; `this.helpers`; DateTime; SplitInBatches loop patterns |

From czlonkowski/n8n-skills, MIT.

More from czlonkowski/n8n-skills