n8n-mcp-skills

n8n-skills

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

Watch the Introduction Video

---

🎯 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
• 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