Expert Claude Code skills for building flawless n8n workflows using the n8n-mcp MCP server
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.
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
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
- When NOT to use expressions (Code nodes!)
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
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
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
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
Write effective JavaScript code in n8n Code nodes.
Activates when: Writing JavaScript in Code nodes, troubleshooting Code node errors, making HTTP requests with this.helpers (the $helpers global), working with dates.
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$helpersglobal 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
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
- Python data access (_input, _json, _node)
- Critical limitation: No external libraries (requests, pandas, numpy)
- Standard library reference (json, datetime, re, etc.)
- Workarounds for missing libraries
- Common Python patterns for n8n
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
toolWorkflowvs HTTP Request Tool
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+ wiremain[1]trap retryOnFailself-healing for flaky network calls- 4xx/5xx response-shape mapping (and the
responseCode-defaults-to-200 gotcha) - Error Trigger workflows for unattended runs
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:
$binaryvs$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
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: allvseachandwaitForSubWorkflow(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
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;
$fromAIparameter anatomy - Structured output with autoFix; memory + sessionId; human-in-the-loop review
- Chat shell+core+sub-agent topology with anti-loop filtering
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 a call returns an unexpected NOT_FOUND or wrong/empty data.
Key Features:
n8n_instanceslist/switchshapes and the real error envelope (UNKNOWN_INSTANCE,MULTI_INSTANCE_DISABLED, …)- Switching in its own turn; the per-session binding that persists across reconnects/deploys
- Verifying
currentbefore credential writes — the server fail-closes only the ambiguous case (INSTANCE_AMBIGUOUS); an explicit wrong switch still writes the secret silently - Recovering from a misroute (NOT_FOUND ≈ wrong instance, not a deletion) and copying objects between instances
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.
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 aSessionStarthook. 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. - PreToolUse hooks — before high-impact n8n-mcp calls, a short reminder points at the relevant skill. Looking up a Set, Code, Merge, Loop Over Items, DateTime, Data Table, or AI Agent node via
get_nodefires a node-specific reminder (and re-fires each time, because a re-lookup usually means you're reconsidering the same decision). Calls ton8n_instancesandn8n_manage_credentialsfire one-shot reminders pointing at the multi-instance and credential-discipline skills. - PostToolUse hook — after
validate_workflow, it inspects the workflow's node types and routes you to the skills that own the remaining risks, with the reminder that validation passing is necessary, not sufficient.
Hooks run only in the Claude Code / Codex plugin install. On Claude.ai (individual skill uploads) the skills still activate by description — the pack degrades gracefully, just without the proactive nudges. Every hook fails open and never blocks a tool call.
- n8n-mcp MCP server installed and configured (Installation Guide)
- Claude Code, Claude.ai, or Claude API access
.mcp.jsonconfigured with n8n-mcp server
Method 1: Plugin Installation (Recommended)
# Install directly as a Claude Code plugin
/plugin install czlonkowski/n8n-skillsMethod 2: Via Marketplace
# Add as marketplace, then browse and install
/plugin marketplace add czlonkowski/n8n-skills
# Then browse available plugins
/plugin install
# Select "n8n-mcp-skills" from the listMethod 3: Manual Installation
# 1. Clone this repository
git clone https://github.com/czlonkowski/n8n-skills.git
# 2. Copy skills to your Claude Code skills directory
cp -r n8n-skills/skills/* ~/.claude/skills/
# 3. Reload Claude Code
# Skills will activate automatically- Download individual skill folders from
skills/ - Zip each skill folder
- Upload via Settings → Capabilities → Skills
See docs/INSTALLATION.md for detailed instructions.
Skills activate automatically when relevant queries are detected:
"How do I write n8n expressions?"
→ Activates: n8n Expression Syntax
"Find me a Slack node"
→ Activates: n8n MCP Tools Expert
"Build a webhook workflow"
→ Activates: n8n Workflow Patterns
"Why is validation failing?"
→ Activates: n8n Validation Expert
"How do I configure the HTTP Request node?"
→ Activates: n8n Node Configuration
"How do I access webhook data in a Code node?"
→ Activates: n8n Code JavaScript
"Can I use pandas in Python Code node?"
→ Activates: n8n Code Python
"Why does my Code Tool throw 'Wrong output type returned'?"
→ Activates: n8n Code Tool
When you ask: "Build and validate a webhook to Slack workflow"
- n8n Workflow Patterns identifies webhook processing pattern
- n8n MCP Tools Expert searches for webhook and Slack nodes
- n8n Node Configuration guides node setup
- n8n Code JavaScript helps process webhook data with proper .body access
- n8n Expression Syntax helps with data mapping in other nodes
- n8n Validation Expert validates the final workflow
All skills compose seamlessly!
- Installation Guide - Detailed installation for all platforms
- Usage Guide - How to use skills effectively
- Development Guide - Contributing and testing
- MCP Testing Log - Real tool responses used in skills
Each skill includes 3+ evaluations for quality assurance:
# Run evaluations (if testing framework available)
npm test
# Or manually test with Claude
claude-code --skill n8n-expression-syntax "Test webhook data access"Contributions welcome! Please see DEVELOPMENT.md for guidelines.
- Evaluation-First: Write test scenarios before implementation
- MCP-Informed: Test tools, document real responses
- Iterative: Test against evaluations, iterate until 100% pass
- Concise: Keep SKILL.md under 500 lines
- Real Examples: All examples from real templates/tools
MIT License - see LICENSE file for details.
Conceived by Romuald Członkowski
- Website: www.aiadvisors.pl/en
- Part of the n8n-mcp project
The hooks enforcement layer adapts patterns from the official n8n Skills project (Apache-2.0), retargeted for n8n-mcp and rewritten in our own voice. See NOTICES.
- 14 complementary skills that work together
- 525+ n8n nodes supported
- 2,653+ workflow templates for examples
- 10 production-tested Code node patterns
- Comprehensive error catalogs and troubleshooting guides
Ready to build flawless n8n workflows? Get started now! 🚀