n8n-mcp-skills

n8n-skills

Expert Claude Code skills for building flawless n8n workflows using the n8n-mcp MCP server

Watch the Introduction Video

💼 Need it built for you? Work with AiAdvisors — n8n automation audits, builds, and operations, run by the author of n8n-mcp and n8n-skills.

---

🎯 What is this?

This repository contains 14 complementary Claude Code skills — plus an always-on router skill and a hooks enforcement layer — that teach AI assistants how to build production-ready n8n workflows using the n8n-mcp MCP server, and how to deploy the self-hosted n8n that runs them.

Why These Skills Exist

Building n8n workflows programmatically can be challenging. Common issues include:

• Using MCP tools incorrectly or inefficiently
• Getting stuck in validation error loops
• Not knowing which workflow patterns to use
• Misconfiguring nodes and their dependencies

These skills solve these problems by teaching Claude:

• ✅ Correct n8n expression syntax ({{}} patterns)
• ✅ How to use n8n-mcp tools effectively
• ✅ Proven workflow patterns from real-world usage
• ✅ Validation error interpretation and fixing
• ✅ Operation-aware node configuration

---

📚 The 14 Skills

1. n8n Expression Syntax

Teaches correct n8n expression syntax and common patterns.

Activates when: Writing expressions, using {{}} syntax, accessing $json/$node variables, troubleshooting expression errors.

Key Features:

• Core variables ($json, $node, $now, $env)
• Critical gotcha: Webhook data is under $json.body
• Common mistakes catalog with fixes
• The transform gatekeeper: service node → native node → short expression → Code; a function body in {{ }} is code
• Built-in helpers (.pluck(), .sum(), $ifEmpty(), .diffTo()), expression-only

2. n8n MCP Tools Expert (HIGHEST PRIORITY)

Expert guide for using n8n-mcp MCP tools effectively.

Activates when: Searching for nodes, validating configurations, accessing templates, managing workflows.

Key Features:

• Tool selection guide (which tool for which task)
• nodeType format differences (nodes-base.* vs n8n-nodes-base.*)
• Validation profiles (minimal/runtime/ai-friendly/strict)
• Smart parameters (branch="true" for IF nodes)
• Auto-sanitization system explained

Most Important: Teaches correct MCP tool usage patterns and parameter formats

3. n8n Workflow Patterns

Build workflows using 5 proven architectural patterns.

Activates when: Creating workflows, connecting nodes, designing automation.

Key Features:

• 5 proven patterns (webhook processing, HTTP API, database, AI, scheduled)
• Workflow creation checklist
• Real examples from 2,653+ n8n templates
• Connection best practices
• Pattern selection guide

4. n8n Validation Expert

Interpret validation errors and guide fixing.

Activates when: Validation fails, debugging workflow errors, handling false positives.

Key Features:

• Validation loop workflow
• Real error catalog
• Auto-sanitization behavior explained
• False positives guide
• Profile selection for different stages

5. n8n Node Configuration

Operation-aware node configuration guidance.

Activates when: Configuring nodes, understanding property dependencies, setting up AI workflows.

Key Features:

• Property dependency rules (e.g., sendBody → contentType)
• Operation-specific requirements
• AI connection types (8 types for AI Agent workflows)
• Common configuration patterns
• Configs for the native nodes that replace Code (Summarize, Aggregate, Split Out, Merge, Compare Datasets, Remove Duplicates, Sort/Limit, Date & Time, HTTP Request pagination, Webhook raw body + Crypto) — NATIVE_NODES.md

6. n8n Code JavaScript

Write effective JavaScript code in n8n Code nodes.

Activates when: Editing or debugging a Code node, or writing a new one after native nodes and expressions are ruled out (the closed list: loops or recursion, state across runs, custom parsing, libraries, heavy all-items work).

Key Features:

• Data access patterns ($input.all(), $input.first(), $input.item)
• Critical gotcha: Webhook data under $json.body
• Correct return format: [{json: {...}}]
• Built-in functions (this.helpers.httpRequest() — the bare $helpers global is undefined in the task-runner sandbox; prefer the HTTP Request node for non-trivial/authenticated calls — DateTime, $jmespath())
• Top 5 error patterns with solutions (covering 62%+ of failures)
• 10 production-tested patterns, each opening with its native-node alternative
• The Why Code: note every kept Code node carries

7. n8n Code Python

Write Python code in n8n Code nodes with proper limitations awareness.

Activates when: Writing Python in Code nodes, need to know Python limitations, working with standard library.

Key Features:

• Important: Use JavaScript for 95% of use cases
• Native Python (n8n 2.x): only _items / _item, dict access — the Pyodide helpers (_input, _json, _node, _now) are gone
• Critical limitation: every import is blocked unless the instance allowlists it (none on n8n Cloud)
• Sandbox limits (no classes, type(), getattr, dunders; nonlocal not global) and verified return shapes
• 12 import-free patterns, each verified on a live instance

8. n8n Code Tool

Write code for the AI-agent-callable Custom Code Tool (@n8n/n8n-nodes-langchain.toolCode) — a different node from the regular Code node with a different contract.

Activates when: Building a Code Tool attached to an AI Agent, troubleshooting "Wrong output type returned" or "No execution data available" errors, deciding between unstructured query parsing and specifyInputSchema.

Key Features:

• Critical distinction: Code Tool ≠ Code node (different node type, different return format, different sandbox)
• Return format: a string (use JSON.stringify() for structured output) — NOT [{json:{...}}]
• Input binding: query (JS) / _query (Python) — $fromAI() does NOT work here
• Unstructured vs structured input modes (specifyInputSchema → DynamicStructuredTool)
• Sandbox limits: no $input, $helpers, $json, $getWorkflowStaticData, no state across calls
• Three signature error strings with causes and fixes
• When to use Code Tool vs toolWorkflow vs HTTP Request Tool

9. n8n Error Handling

Make failures loud, structured, and recoverable.

Activates when: Building webhook/API or unattended workflows, wiring error outputs, setting retries, designing 4xx/5xx responses, or chasing silent failures.

Key Features:

• Per-node error output: the two-step onError: continueErrorOutput + wire main[1] trap
• retryOnFail self-healing for flaky network calls
• 4xx/5xx response-shape mapping (and the responseCode-defaults-to-200 gotcha)
• Error Trigger workflows for unattended runs

10. n8n Binary & Data

Handle files, images, and binary data correctly.

Activates when: Working with files, images, PDFs, attachments, uploads/downloads, vision input, or passing a file to/from an AI agent tool.

Key Features:

• $binary vs $json — file contents never live in $json
• Keeping binary alive across JSON transforms with Merge
• The agent-tool binary boundary (pre-stage to storage, pass keys/URLs)
• CDN/URL requirement for showing images in chat surfaces

11. n8n Sub-workflows

Build reusable, composable sub-workflows.

Activates when: Extracting shared logic, building multi-step or reused workflows, or any workflow over ~10 nodes.

Key Features:

• Execute Workflow Trigger with "Define Below" typed inputs (not passthrough)
• mode: all vs each and waitForSubWorkflow (the only true parallelization)
• Verb-first prefix naming for discovery (MCP can't filter by tags)
• Stateless vs stateful design; N+1 split-by-input-shape

12. n8n AI Agents

Design n8n AI agents the right way.

Activates when: Building any @n8n/n8n-nodes-langchain.* node — AI Agent, LLM chain, Text Classifier — or working with tool calling, $fromAI, memory, structured output, RAG, or chat bots.

Key Features:

• Agent vs LLM Chain vs Text Classifier; the model/memory/tools/outputParser slots
• Tool names & descriptions ARE the prompt; $fromAI parameter anatomy
• Structured output with autoFix; memory + sessionId; human-in-the-loop review
• Chat shell+core+sub-agent topology with anti-loop filtering

13. n8n Multi-Instance

Target the right n8n instance when an account has more than one.

Activates when: The n8n_instances tool is available, the user mentions multiple instances/environments (prod vs staging, several clients) or several agents working at once, or a call returns an unexpected NOT_FOUND or wrong/empty data.

Key Features:

• The per-call instance argument: name the target on each call, so parallel agents on one connection can work on different instances at once
• n8n_instances list/switch shapes and the real error envelopes (INSTANCE_NOT_FOUND, INSTANCE_AMBIGUOUS, UNKNOWN_INSTANCE, …)
• switch as the shared default for unnamed calls, and why it moves every chat on a hosted connection
• Naming the instance on credential writes — a named write is never ambiguous
• Recovering from a misroute (NOT_FOUND ≈ wrong instance, not a deletion) and copying objects between instances

14. n8n Self-Hosting (deployment/ops)

Deploy a production self-hosted n8n end-to-end to a fresh Linux VM.

Activates when: Self-hosting, installing, or deploying n8n on your own server/VPS (Hetzner, DigitalOcean, EC2, bare metal) — single or queue mode — or updating/backing-up/hardening it. Not for n8n Cloud, and not for building workflows.

Key Features:

• Docker Compose behind Caddy with automatic HTTPS; asks single vs queue mode first
• Single (SQLite) and queue (main + Redis + Postgres + workers) templates, secret-free and domain-free
• Generates fresh secrets on the box; secure defaults (explicit encryption key, no published internal ports, telemetry off, env-access blocked, execution pruning)
• DNS/ports preflight, end-to-end verify (cert + reachability), and Day-2 (update / backup / restore)

This is the pack's one deployment skill; it triggers on its own description and is not part of the workflow-building router/hooks flow.

---

🪝 Enforcement Layer (hooks + router)

Beyond the capability skills, the plugin ships an always-on enforcement layer so the right guidance surfaces at the moment of decision — not only when a query happens to match a skill description.

• Router skill (using-n8n-mcp-skills) — loaded into every session by a SessionStart hook. It routes you to the right skill, summarizes every n8n-mcp tool, and states the cross-cutting rules. It re-fires on resume/clear/compact so it survives context compaction.