[H1][N8N-BUILDER]

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

Generate valid n8n workflow JSON.

Tasks:

• Read schema.md — Root structure, settings

• Read nodes.md — Node definition, typeVersion

• Read connections.md — Graph topology, AI types

• (dynamic values) Read expressions.md — Variables, functions

• (specific nodes) Read integrations.md — Node parameters

• Generate JSON — Apply template from workflow.template.md

• Validate — Run uv run .claude/skills/n8n-builder/scripts/validate-workflow.py

REFERENCE: index.md — File listing.

[0][N8N_2.0]

Dictum: Breaking changes invalidate pre-2025 patterns.

Breaking Changes (December 2025):

• Database — PostgreSQL required; MySQL/MariaDB support dropped.

• Python — "language": "python" removed; use "pythonNative" with task runners.

• Security — ExecuteCommand and LocalFileTrigger disabled by default.

• Code Isolation — Environment variable access blocked in Code nodes (N8N_BLOCK_ENV_ACCESS_IN_NODE=true ).

• Agent Type — Agent type selection removed (v1.82+); all agents are Tools Agent.

[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.

• 2025 Features — MCP nodes enable cross-agent interoperability; Guardrails nodes enforce AI output safety.

• 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.