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

bash

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.

n8n-builder

NPX Install

Tags

SKILL.md Content

[H1][N8N-BUILDER]

[0][N8N_2.0]

[1][SCHEMA]

[2][NODES]

[3][CONNECTIONS]

[4][EXPRESSIONS]

[5][INTEGRATIONS]

[6][RAG]

[7][VALIDATION]