n8n-workflow

name: n8n-workflow description: Create, modify, and understand n8n automation workflows. Use when building n8n workflow JSON files, configuring nodes (HTTP Request, Code, IF, Merge, Webhook, Schedule), writing expressions with {{ $json }}, or implementing flow logic (conditionals, loops, error handling). Triggers for requests involving n8n, workflow automation, or node-based pipeline creation.

n8n Workflow Creator

This skill provides guidance for creating valid n8n workflow JSON files.

🚨 Critical: Webhook Data Structure

Most common mistake: Webhook data is nested under .body, NOT at root!

// ❌ WRONG - Returns undefined
{{ $json.email }}

// ✅ CORRECT - Webhook data is under .body
{{ $json.body.email }}

This applies to expressions AND Code nodes.

Workflow Structure

{
  "name": "Workflow Name",
  "nodes": [...],
  "connections": {...},
  "active": false,
  "settings": { "executionOrder": "v1" }
}

The 5 Core Patterns

1. Webhook Processing - Webhook → Validate → Transform → Respond
2. HTTP API Integration - Trigger → HTTP Request → Transform → Action
3. Database Operations - Schedule → Query → Transform → Write → Verify
4. AI Agent Workflow - Trigger → AI Agent (Model + Tools) → Output
5. Scheduled Tasks - Schedule → Fetch → Process → Deliver → Log

See patterns.md for complete examples.

Essential Nodes

See nodes.md for full configurations.

Expression Syntax

Expressions use {{ }} syntax:

{{ $json.fieldName }}              // Current item
{{ $json.body.email }}             // Webhook data (under .body!)
{{ $('NodeName').item.json.field }} // Other node's output
{{ $now }}                         // Current timestamp

❌ Don't use {{ }} in:

• Code nodes (use JavaScript directly)
• Webhook paths
• Credential fields

See expressions.md for advanced patterns.

Code Node - Critical Rules

ALWAYS return array with json property:

// ✅ CORRECT
const items = $input.all();
return items.map(item => ({ json: { ...item.json, processed: true } }));

// ✅ CORRECT - Single item
return [{ json: { result: 'success' } }];

// ❌ WRONG - No return
const data = $input.first();
// forgot return!

// ❌ WRONG - Object instead of array
return { json: { result: 'success' } };

Best practices:

• Validate input: if (!items || items.length === 0) return [];
• Use null checks: item.json?.user?.email || 'default'
• Try-catch for API calls
• Filter early, process late

Common Gotchas

Connections Format

"connections": {
  "Source Node": {
    "main": [[{ "node": "Target Node", "type": "main", "index": 0 }]]
  }
}

IF node outputs: index: 0 = True, index: 1 = False

Best Practices

✅ Do:

• Use descriptive node names ("Fetch Users", not "HTTP Request 1")
• Set onError: "continueRegularOutput" for resilience
• Test incrementally, node by node
• Document complex workflows with notes
• Handle empty data cases

❌ Don't:

• Build workflows in one shot (iterate!)
• Skip error handling
• Hardcode credentials in parameters
• Use Code node when built-in nodes suffice
• Deploy without testing

Reference Documentation

• nodes.md - Node configurations
• expressions.md - Expression syntax
• patterns.md - Workflow patterns
• json-structure.md - JSON schema