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
• When NOT to use expressions (Code nodes!)

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

6. n8n Code JavaScript

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 $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

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