N8n

n8n Automation Skill

Build, test, and deploy n8n workflows via REST API with incremental testing.

When This Skill Loads (DO THIS IMMEDIATELY)

Step 1: Read Reference Files

Use the Read tool to read these files NOW:
1. Read references/pitfalls.md (critical command format rules)
2. Read references/build-process.md (step-by-step build workflow)

Step 2: Check .env Configuration

Read the .env file in the working directory to verify:
- N8N_API_URL is set
- N8N_API_KEY is set
- N8N_CREDENTIALS_TEMPLATE_URL is set

If any values are missing, ask the user for ALL of them in a single prompt.

Step 3: Create a Todo List

After understanding the user's request, create a todo list using TaskCreate.

SKILL LOADS -> READ FILES IMMEDIATELY -> CHECK .env -> THEN respond to user

Critical Rules

1. USE THE TOOLS THE USER SPECIFIES

If the user mentions specific tools, nodes, or services - YOU MUST USE THEM.

User says "use Apify" -> You use Apify node
User says "use OpenAI" -> You use OpenAI Chat Model

Never substitute, skip, or defer user-requested tools.

2. NEVER Simplify When Hitting Errors - FIX THE ISSUE

Loop node has error -> Debug why -> Fix the loop configuration

Don't switch to "simpler" approaches. Keep the correct architecture.

3. Only Use Nodes From Credentials Template

Never add nodes requiring authentication unless:

1. The node exists in the user's credentials template, OR
2. The user explicitly asks to use that specific tool/service

4. Only Use Node Types/Versions That Are INSTALLED

Always copy type AND typeVersion from the credentials template.

5. One Node at a Time

ADD NODE -> TEST -> ADD NEXT NODE -> TEST -> REPEAT

NEVER add 2+ nodes without testing between them.

6. NEVER Delete or Deactivate Workflows - UPDATE Instead

Node fails -> Debug the error -> Update the same workflow (PUT)

One workflow ID for the entire build process.

7. Use Native Nodes First

8. No Mock Data

Never use placeholder URLs, fake IDs, or "REPLACE_ME" values.

9. Test with 2 Items

Always set limit=2 on data-fetching nodes for fast testing.

10. Only Work With User-Specified Workflows

Never check, run, or modify workflows the user didn't mention.

Build Process

Step 0: Fetch Schema (If Database Involved)

1. Create temp workflow: Webhook + getSchema/getAll node
2. Execute to fetch actual field names
3. Use exact field names in main workflow

Step 1: Create Workflow with Trigger

1. Read references/triggers.md
2. Create workflow with trigger only
3. Test trigger

Step 2: Add Each Node

1. Read relevant reference file for this node type
2. Add ONE node to workflow
3. Test workflow
4. If ERROR -> fix -> retry
5. If SUCCESS -> move to next node

Step 3: Final Verification

1. All nodes added and tested
2. Workflow activated
3. Report success to user

API Methods Quick Reference

API Call Format

CRITICAL RULES:

1. NEVER write JSON files to disk - Always use API directly
2. NEVER use \ line continuations - Causes errors
3. Always single-line commands - Or heredoc for large JSON

GET:

export $(cat .env | grep -v '^#' | xargs) && curl -s "${N8N_API_URL}/api/v1/ENDPOINT" -H "X-N8N-API-KEY: ${N8N_API_KEY}" | jq .

POST/PUT (large JSON):

export $(cat .env | grep -v '^#' | xargs) && curl -s -X POST "${N8N_API_URL}/api/v1/workflows" -H "X-N8N-API-KEY: ${N8N_API_KEY}" -H "Content-Type: application/json" -d "$(cat <<'EOF'
{
  "name": "My Workflow",
  "nodes": [...],
  "connections": {},
  "settings": {"executionOrder": "v1"}
}
EOF
)"

Workflow JSON Structure

{
  "name": "Workflow Name",
  "nodes": [
    {
      "id": "unique-node-id",
      "name": "Node Display Name",
      "type": "n8n-nodes-base.nodeName",
      "typeVersion": 1,
      "position": [250, 300],
      "parameters": {},
      "credentials": {}
    }
  ],
  "connections": {
    "Source Node Name": {
      "main": [[{"node": "Target Node Name", "type": "main", "index": 0}]]
    }
  },
  "settings": {"executionOrder": "v1"}
}

Reference Files

Read these files as needed using the Read tool:

Core API & Build Process

Node Reference

Code & Expressions

Node Selection Flow

Before adding ANY node:

1. Read the relevant reference file (triggers.md, ai-nodes.md, etc.)
2. Check if node is in credentials template
3. Get correct typeVersion and parameters
4. If DATABASE node -> FETCH SCHEMA first
5. Add node with correct config

Expression Quick Reference

// Webhook body (CRITICAL - data is under .body!)
{{ $json.body.fieldName }}

// Other node reference
{{ $('Node Name').item.json.field }}

// Default value
{{ $json.field ?? 'default' }}

// Safe access
{{ $json.obj?.nested?.field }}

// Current date
{{ $now.toFormat('yyyy-MM-dd') }}

In Code nodes, use plain JavaScript - NOT {{ }}:

const data = $input.first().json.body;
return [{ json: { result: data.fieldName } }];

Code Node Quick Reference

JavaScript

// Input access
const items = $input.all();
const first = $input.first().json;

// Other nodes
const data = $('Node Name').first().json;

// Return (MUST be array with json key)
return [{ json: { result: 'value' } }];

Python

# Input access
items = _input.all()
first = _input.first().json

# Return (MUST be list)
return [{"json": {"result": "value"}}]

Testing After Each Node

# 1. Activate
curl -X POST "${N8N_API_URL}/api/v1/workflows/{id}/activate"

# 2. Execute
curl -X POST "${N8N_API_URL}/webhook/{path}" -d '{}'

# 3. Check status
curl "${N8N_API_URL}/api/v1/executions?limit=1" | jq '.data[0].status'

# 4. Verify node ran
curl "${N8N_API_URL}/api/v1/executions/{id}?includeData=true" | jq '.data.resultData.runData | keys'

Do NOT proceed until status = "success" and new node appears in runData.

What to Report to User

After successful build:

Build Progress:
1. Webhook trigger - working
2. HTTP Request - working (2 results)
3. Google Sheets - working

- Workflow: My Workflow
- URL: https://n8n.example.com/workflow/abc123
- Status: Active

If manual config needed:

Workflow built and partially tested!

Google Sheets requires manual setup:
- Open workflow in n8n UI
- Select your spreadsheet
- Save