n8n Expert Skill

Core Concepts

Workflow Architecture

┌─────────┐    ┌──────────┐    ┌─────────────┐    ┌────────┐
│ Trigger │───▶│ Process  │───▶│ Transform   │───▶│ Output │
└─────────┘    └──────────┘    └─────────────┘    └────────┘
                    │                                  │
                    ▼                                  ▼
              ┌──────────┐                      ┌──────────┐
              │ Branch   │                      │ Error    │
              │ Logic    │                      │ Handler  │
              └──────────┘                      └──────────┘

Expression Syntax

n8n uses JavaScript expressions with special syntax:

// Access current node input
{{ $json.fieldName }}
{{ $json["field-with-dashes"] }}
{{ $json.nested.field }}

// Access specific node output
{{ $node["Node Name"].json.field }}

// Access all items from a node
{{ $items("Node Name") }}

// Binary data
{{ $binary.data }}

// Workflow variables
{{ $vars.myVariable }}

// Environment variables
{{ $env.API_KEY }}

// Execution metadata
{{ $execution.id }}
{{ $workflow.name }}
{{ $now }}  // Current timestamp
{{ $today }} // Today's date

// Item index in loop
{{ $itemIndex }}

// Previous node
{{ $input.first().json.field }}
{{ $input.all() }}

Data Structures

n8n passes data as arrays of items:

[
  { json: { id: 1, name: "Item 1" }, binary: {} },
  { json: { id: 2, name: "Item 2" }, binary: {} }
]

Transform with Code node:

// Return array of items
return items.map(item => ({
  json: {
    ...item.json,
    processed: true,
    timestamp: new Date().toISOString()
  }
}));

Workflow Patterns

1. Sequential Processing

Trigger → Fetch Data → Transform → Save → Notify

2. Parallel Branches (Split/Merge)

                 ┌─→ Process A ─┐
Trigger → Split ─┼─→ Process B ─┼─→ Merge → Output
                 └─→ Process C ─┘

Use Split Out node to branch, Merge node to combine.

3. Conditional Routing

Trigger → IF/Switch → Route 1 → Output 1
                   → Route 2 → Output 2
                   → Default → Output 3

4. Loop Processing

Trigger → Split In Batches → Process → Loop (back to Split)
                                    → When done → Complete

5. Error Handling

Main Flow ──────────────────→ Success Output
    │ (on error)
    └──→ Error Trigger → Log Error → Alert → Retry/Fail

AI Agent Workflows

Agent Architecture

┌──────────────────────────────────────────────────────────┐
│                      AI Agent Node                        │
├──────────────────────────────────────────────────────────┤
│  System Prompt    │  Tools/Functions  │  Memory          │
│  ───────────────  │  ───────────────  │  ──────────────  │
│  Role definition  │  - HTTP Request   │  - Window Buffer │
│  Constraints      │  - Code Execute   │  - Vector Store  │
│  Output format    │  - Database Query │  - Summary       │
└──────────────────────────────────────────────────────────┘
                            │
                            ▼
              ┌─────────────────────────────┐
              │    Tool Execution Loop      │
              │  Agent calls tool → Result  │
              │  → Agent reasons → Next     │
              └─────────────────────────────┘

Agent System Prompt Template

## Role
You are a [specific role] assistant that [primary function].

## Capabilities
You have access to these tools:
- **tool_name**: Description and when to use it
- **another_tool**: Description and when to use it

## Constraints
- Always [constraint 1]
- Never [constraint 2]
- When uncertain, [fallback behavior]

## Output Format
Respond in this structure:
1. [Section 1]: Brief description
2. [Section 2]: Brief description

## Examples
User: [example input]
Assistant: [example output with tool usage]

Tool Definition Pattern

// In HTTP Request Tool or Code node
{
  "name": "search_database",
  "description": "Search the product database by query. Use when user asks about products, inventory, or pricing.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query for products"
      },
      "limit": {
        "type": "integer",
        "description": "Max results to return",
        "default": 10
      }
    },
    "required": ["query"]
  }
}

Complex Data Transformations

Aggregation Pattern

// Code node: Aggregate items by category
const grouped = {};

for (const item of items) {
  const category = item.json.category;
  if (!grouped[category]) {
    grouped[category] = { items: [], total: 0 };
  }
  grouped[category].items.push(item.json);
  grouped[category].total += item.json.amount;
}

return Object.entries(grouped).map(([category, data]) => ({
  json: { category, ...data }
}));

Lookup/Join Pattern

// Code node: Join data from two sources
const mainData = $items("Main Data Node");
const lookupData = $items("Lookup Node");

// Create lookup map
const lookupMap = new Map(
  lookupData.map(item => [item.json.id, item.json])
);

// Join
return mainData.map(item => ({
  json: {
    ...item.json,
    details: lookupMap.get(item.json.referenceId) || null
  }
}));

State Machine Pattern

// Code node: Process based on state
const item = $input.first().json;
const transitions = {
  'pending': ['approved', 'rejected'],
  'approved': ['processing', 'cancelled'],
  'processing': ['completed', 'failed'],
  'failed': ['processing', 'cancelled']
};

const currentState = item.status;
const requestedState = item.newStatus;

if (transitions[currentState]?.includes(requestedState)) {
  return [{ json: { ...item, status: requestedState, valid: true } }];
} else {
  return [{ json: { ...item, valid: false, error: `Invalid transition: ${currentState} → ${requestedState}` } }];
}

Error Handling Strategies

Retry with Backoff

// Code node: Implement retry logic
const maxRetries = 3;
const retryCount = $json.retryCount || 0;

if ($json.error && retryCount < maxRetries) {
  const delay = Math.pow(2, retryCount) * 1000; // Exponential backoff
  await new Promise(resolve => setTimeout(resolve, delay));
  
  return [{
    json: {
      ...$json,
      retryCount: retryCount + 1,
      retryAt: new Date().toISOString()
    }
  }];
}

// Max retries reached or no error
return [{ json: $json }];

Error Workflow Pattern

Main Workflow:
  [Nodes] → Error Trigger (on failure) → [continues normally]
                    │
                    ▼
Error Handler Workflow:
  Error Trigger → Extract Error Info → Log to DB → 
  Send Alert → Determine Recovery → Retry/Escalate

Performance Optimization

Batch Processing

// Process in batches to avoid memory issues
const BATCH_SIZE = 100;
const allItems = $input.all();
const results = [];

for (let i = 0; i < allItems.length; i += BATCH_SIZE) {
  const batch = allItems.slice(i, i + BATCH_SIZE);
  // Process batch
  const processed = batch.map(item => ({
    json: { ...item.json, processed: true }
  }));
  results.push(...processed);
}

return results;

Caching Pattern

// Use static variables for caching within execution
const cacheKey = 'myCache';
if (!$execution.customData[cacheKey]) {
  // Expensive operation - do once
  $execution.customData[cacheKey] = await fetchExpensiveData();
}
return [{ json: { data: $execution.customData[cacheKey] } }];

Best Practices

1. Naming: Use descriptive node names that explain purpose
2. Notes: Add sticky notes explaining complex logic
3. Error handling: Always add error workflows for production
4. Testing: Use manual trigger + sample data during development
5. Credentials: Never hardcode secrets; use n8n credentials
6. Modularity: Break complex workflows into sub-workflows
7. Logging: Add Set nodes to log intermediate states for debugging

Additional Resources

• Node reference: See references/nodes-reference.md for common nodes
• AI patterns: See references/ai-patterns.md for agent architectures
• Integration examples: See references/integrations.md for API connections