n8n Workflow Skills

name: n8n-workflows

description: Use when building n8n workflows, writing Code node scripts, configuring nodes, debugging validation errors, or using n8n-mcp tools. Covers expression syntax, workflow patterns, node configuration, validation, and JavaScript/Python code nodes.

# n8n Workflow Skills

Based on the open-source n8n-skills project: https://github.com/czlonkowski/n8n-skills

Install all 7 skills: git clone https://github.com/czlonkowski/n8n-skills.git && cp -r n8n-skills/skills/* .claude/skills/

Quick Start

Install via Git

git clone https://github.com/czlonkowski/n8n-skills.git
cp -r n8n-skills/skills/* .claude/skills/

The 7 Skills

• n8n-expression-syntax - Correct {{}} patterns and variable access
• n8n-mcp-tools-expert - How to use n8n-mcp MCP tools effectively (HIGHEST PRIORITY)
• n8n-workflow-patterns - 5 proven architectural patterns from 2,600+ templates
• n8n-validation-expert - Interpret and fix validation errors
• n8n-node-configuration - Operation-aware node setup and property dependencies
• n8n-code-javascript - JavaScript Code node patterns, $input/$json syntax
• n8n-code-python - Python Code node patterns and limitations

Expression Syntax

Core Variables

• $json - Current item data (most common)
• $node["Node Name"].json - Data from a specific node
• $now - Current DateTime (Luxon)
• $env - Environment variables
• $input.all() - All items from previous node
• $input.first() - First item only

CRITICAL: Webhook Data Structure

Webhook data is ALWAYS nested under .body:

// WRONG: $json.email
// CORRECT: $json.body.email

Common Expression Patterns

{{ $json.body.user.name }}
{{ $json.body.name || "Unknown" }}
{{ $now.toFormat("yyyy-MM-dd") }}
{{ $json["My Field"] }}
{{ $json.status === "active" ? "Yes" : "No" }}

Where NOT to Use Expressions

• Code node scripts (use plain JavaScript/Python)
• Webhook paths
• Credential fields

MCP Tools Guide

nodeType Format (Critical Gotcha)

• Search/validate tools: nodes-base.httpRequest (without n8n- prefix)
• Workflow create/update: n8n-nodes-base.httpRequest (with prefix)

Key Tools

Validation Profiles

• minimal - Syntax only (fastest)
• runtime - Simulates execution (RECOMMENDED)
• ai-friendly - Detailed error messages for AI
• strict - All checks enabled

Workflow Patterns

5 Core Patterns

• Webhook Processing (35% of workflows) - Trigger > Transform > Output
• Scheduled Tasks (28%) - Cron/Interval > Fetch > Process > Notify
• HTTP API Integration - Request > Parse > Transform > Store
• Database Operations - Query > Transform > Upsert > Verify
• AI Agent Workflow - Trigger > AI Agent > Tools > Response

Workflow Creation Checklist

• Choose trigger node (Webhook, Cron, Manual)
• Add data source nodes
• Transform data (Set, Code, IF nodes)
• Add output nodes (HTTP, DB, Email)
• Validate with validate_workflow
• Test with sample data

JavaScript Code Node

Mode Selection

• Run Once for All Items - Process all items as array (batch operations)
• Run Once for Each Item - Process items individually (transformations)

Data Access

// All items from previous node
const items = $input.all();

// Current item (Each Item mode)
const data = $input.item.json;

// From specific node
const nodeData = $node["HTTP Request"].json;

// CRITICAL: Webhook data
const email = $input.first().json.body.email;

Return Format (Required)

return items.map(item => ({
  json: {
    name: item.json.name,
    processed: true
  }
}));

HTTP Requests in Code

const response = await $helpers.httpRequest({
  method: 'GET',
  url: 'https://api.example.com/data',
  headers: { 'Authorization': 'Bearer token' }
});
return [{ json: response }];

Common Validation Errors

Best Practices

• Always validate before deploying workflows
• Use runtime profile for validation (catches most real issues)
• Test webhooks with sample payloads first
• Handle errors with Error Trigger node or try/catch in Code nodes
• Never edit production workflows directly with AI - make a copy first
• Check .body on every webhook-triggered workflow
• Use expressions in node fields, JavaScript/Python in Code nodes (not both)