N8n Builder

[H1][N8N-BUILDER]

Dictum: Schema compliance enables n8n import without runtime validation errors.

Generate valid n8n workflow JSON.

Tasks:

1. Read schema.md — Root structure, settings
2. Read nodes.md — Node definition, typeVersion
3. Read connections.md — Graph topology, AI types
4. (dynamic values) Read expressions.md — Variables, functions
5. (specific nodes) Read integrations.md — Node parameters
6. Generate JSON — Apply template from workflow.template.md
7. Validate — Run uv run .claude/skills/n8n-builder/scripts/validate-workflow.py

References:

[0][N8N_2.0]

Dictum: Breaking changes invalidate pre-2025 patterns.

Breaking Changes (December 2025):

[CRITICAL]:

• [ALWAYS] Use Task Runners for Code node execution — default isolation mode since 2025.
• [ALWAYS] Use mcpClient node (not HTTP) for MCP server integration — handles protocol negotiation.
• [NEVER] Use deprecated "language": "python" — fails silently with Task Runners enabled.

[1][SCHEMA]

Dictum: Root structure enables n8n parser recognition and execution.

Guidance:

• AI Workflows — Require executionOrder: "v1" in settings; async node ordering fails without.
• Portability — Credential IDs and errorWorkflow UUIDs are instance-specific; expect reassignment post-import.
• Optional Fields — Include empty objects ("pinData": {}) over omission; prevents import edge cases.
• Sub-Workflow Typing — Use workflowInputs schema on trigger nodes to validate caller payloads before execution.
• pinData Limits — Keep under 12MB; large payloads slow editor rendering and cannot contain binary data.

Best-Practices:

• [ALWAYS] Set "active": false on generation; activation is a deployment decision.
• [NEVER] Hardcode credential IDs; use placeholder names for cross-instance transfer.

[2][NODES]

Dictum: Unique identity enables deterministic cross-node references.

Guidance:

• Name Collisions — n8n auto-renames duplicates (Set→Set1); breaks $('NodeName') expressions silently.
• Version Matching — typeVersion must match target n8n instance; newer versions may lack backward compatibility.
• Error Strategy — Use onError: "continueErrorOutput" for fault-tolerant pipelines; default stops execution.
• Node Documentation — Use notes field for inline documentation; notesInFlow: true displays on canvas.

Best-Practices:

• [ALWAYS] Generate UUID per node before building connections; connections reference node.name.
• [ALWAYS] Space nodes 200px horizontal, 150px vertical for canvas readability.

[3][CONNECTIONS]

Dictum: Connection types enable workflow mode distinction at parse time.

Guidance:

• AI vs Main — AI nodes require specialized types (ai_tool, ai_languageModel); main causes silent tool invisibility.
• Fan-out — Single output to multiple nodes executes in parallel; order within array is non-deterministic.
• Multi-output — Array index maps to output port; IF node: index 0 = true branch, index 1 = false branch.
• Single Model — Agent accepts exactly one ai_languageModel connection; multiple models conflict silently.
• Memory Scope — ai_memory persists within single trigger execution only; no cross-session persistence.

Best-Practices:

• [ALWAYS] Match connection key AND type property; mismatches cause silent failures.
• [NEVER] Connect AI tools via main type; agent cannot discover them.
• [NEVER] Connect multiple language models to single agent; use Model Selector node for dynamic selection.

[4][EXPRESSIONS]

Dictum: Dynamic evaluation eliminates hardcoded parameters.

Guidance:

• Static vs Dynamic — Prefix = signals evaluation; without it, value is literal string including {{ }}.
• Pinned Data — Test mode pins lack execution context; .item fails, use .first() or .all()[0] instead.
• Complex Logic — IIFE pattern {{(function(){ return ... })()}} enables multi-statement evaluation.
• Scope Confusion — $json accesses current node input only; use $('NodeName').item.json for other nodes.

Best-Practices:

• [ALWAYS] Use $('NodeName') for cross-node data; $json only accesses current node input.
• [ALWAYS] Escape quotes in JSON strings or use template literals to prevent invalid JSON.
• [NEVER] Assume .item works in all contexts; pinned data testing requires explicit accessors.

[5][INTEGRATIONS]

Dictum: Node type selection determines integration capability.

Guidance:

• Trigger Selection — Webhook for external calls, scheduleTrigger for periodic; choose based on initiation source.
• AI Tool Visibility — Sub-workflow tools require description parameter; agent uses it for tool selection reasoning.
• Code Language — Use "pythonNative" for Python; "python" is deprecated.
• Error Propagation — Use stopAndError node for controlled failures; triggers designated error workflow.
• MCP Client — mcpClient standalone node connects to external MCP servers; discovers tools dynamically via ai_tool connection. Supports OAuth 2.1.
• Guardrails — guardrails node enforces AI output safety with configurable rules and actions.
• HITL — Human-in-the-loop approval for AI agent tool calls; agent pauses execution until human approves.
• Output Parser — outputParserStructured jsonSchema must be static; expressions in schema are ignored silently.
• Batch Processing — Use splitInBatches for large datasets to prevent memory exhaustion; process in chunks.

Best-Practices:

• [ALWAYS] Set responseMode: "lastNode" for webhook→response patterns; ensures output reaches caller.
• [ALWAYS] Include description on HTTP nodes used as AI tools; undocumented tools are invisible to agent.
• [ALWAYS] Include unique webhookId per workflow to prevent path collisions across workflows.

[6][RAG]

Dictum: RAG pipelines ground LLM responses in domain-specific knowledge.

Guidance:

• Vector Store Selection — Simple for development; PGVector/Pinecone/Qdrant for production persistence.
• Embedding Consistency — Same embedding model required for insert and query; mismatch causes semantic drift.
• Chunk Strategy — Recursive Character splitter recommended; splits Markdown/HTML/code before character fallback.
• Memory vs Chains — Only agents support memory; chains are stateless single-turn processors.
• Retriever Modes — MultiQuery for complex questions; Contextual Compression for noise reduction.

Best-Practices:

• [ALWAYS] Match embedding model between document insert and query operations.
• [ALWAYS] Use ai_memory connection type for memory nodes; main silently fails.
• [NEVER] Use Simple Vector Store in production; data lost on restart, global user access.

[7][VALIDATION]

Dictum: Pre-export validation prevents n8n import failures.

Script:

uv run .claude/skills/n8n-builder/scripts/validate-workflow.py workflow.json
uv run .claude/skills/n8n-builder/scripts/validate-workflow.py workflow.json --strict

Checks (12 automated):

• root_required — name, nodes, connections present
• node_id_unique / node_name_unique — no duplicates
• node_id_uuid — valid UUID format
• conn_targets_exist — connection targets reference existing nodes
• conn_ai_type_match — AI connection key matches type property
• settings_exec_order_ai — LangChain workflows require executionOrder: "v1"
• settings_caller_policy / node_on_error — enum value validation

Guidance:

• API Deployment — Use POST then PUT pattern; single POST may ignore settings due to API bug.
• Performance — saveExecutionProgress: true triggers DB I/O per node; disable for high-throughput (>1000 RPM).
• Source Control — Strip instanceId when sharing; credential files contain stubs only, not secrets.