N8

n8n-expression-syntax

Supports n8n expression syntax, data mapping, and troubleshooting for dynamic workflows.

Install

mkdir -p .claude/skills/n8n-expression-syntax && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/363" && unzip -o skill.zip -d .claude/skills/n8n-expression-syntax && rm skill.zip

Installs to .claude/skills/n8n-expression-syntax

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

Validate n8n expression syntax and fix common errors. Use when writing n8n expressions, using {{}} syntax, accessing $json/$node variables, troubleshooting expression errors, mapping data between nodes, or referencing webhook data in workflows. Use this skill whenever configuring node fields that reference data from previous nodes — expressions are how n8n passes data between nodes, and getting the syntax wrong is the most common source of workflow errors.
460 chars✓ has a “when” triggerlonger than Claude Code's old 250-char listing cap (fine on current versions)
Beginner

Key capabilities

  • →Validate {{}} expression syntax
  • →Map $json data between workflow nodes
  • →Debug $node references in node configurations
  • →Access current date/time via $now variable
  • →Extract environment variables using $env

How it works

Checks inputs against the required double-curly-brace format. It applies rules for node name access and variable types like $json and $node.

Inputs & outputs

You give it
N8n expression code
You get back
Corrected syntax or validation status

When to use n8n-expression-syntax

  • →Fix n8n expression syntax errors
  • →Correctly map data from previous nodes
  • →Debug webhook data references

About this skill

n8n Expression Syntax

Expert guide for writing correct n8n expressions in workflows.


Expression Format

All dynamic content in n8n uses double curly braces:

{{expression}}

Examples:

✅ {{$json.email}}
✅ {{$json.body.name}}
✅ {{$node["HTTP Request"].json.data}}
❌ $json.email  (no braces - treated as literal text)
❌ {$json.email}  (single braces - invalid)

Core Variables

$json - Current Node Output

Access data from the current node:

{{$json.fieldName}}
{{$json['field with spaces']}}
{{$json.nested.property}}
{{$json.items[0].name}}

$node - Reference Other Nodes

Access data from any previous node:

{{$node["Node Name"].json.fieldName}}
{{$node["HTTP Request"].json.data}}
{{$node["Webhook"].json.body.email}}

Important:

  • Node names must be in quotes
  • Node names are case-sensitive
  • Must match exact node name from workflow

$now - Current Timestamp

Access current date/time:

{{$now}}
{{$now.toFormat('yyyy-MM-dd')}}
{{$now.toFormat('HH:mm:ss')}}
{{$now.plus({days: 7})}}

$env - Environment Variables

Access environment variables:

{{$env.API_KEY}}
{{$env.DATABASE_URL}}

Warning: Some n8n instances have N8N_BLOCK_ENV_ACCESS_IN_NODE enabled, which blocks $env access entirely. If $env returns errors, use alternative approaches:

  • Store values in credentials instead
  • Use a Set node with manually entered values
  • Pass values through webhook query parameters

🚨 CRITICAL: Webhook Data Structure

Most Common Mistake: Webhook data is NOT at the root!

Webhook Node Output Structure

{
  "headers": {...},
  "params": {...},
  "query": {...},
  "body": {           // ⚠️ USER DATA IS HERE!
    "name": "John",
    "email": "[email protected]",
    "message": "Hello"
  }
}

Correct Webhook Data Access

❌ WRONG: {{$json.name}}
❌ WRONG: {{$json.email}}

✅ CORRECT: {{$json.body.name}}
✅ CORRECT: {{$json.body.email}}
✅ CORRECT: {{$json.body.message}}

Why: Webhook node wraps incoming data under .body property to preserve headers, params, and query parameters.


Common Patterns

Access Nested Fields

// Simple nesting
{{$json.user.email}}

// Array access
{{$json.data[0].name}}
{{$json.items[0].id}}

// Bracket notation for spaces
{{$json['field name']}}
{{$json['user data']['first name']}}

Reference Other Nodes

// Node without spaces
{{$node["Set"].json.value}}

// Node with spaces (common!)
{{$node["HTTP Request"].json.data}}
{{$node["Respond to Webhook"].json.message}}

// Webhook node
{{$node["Webhook"].json.body.email}}

Combine Variables

// Concatenation (automatic)
Hello {{$json.body.name}}!

// In URLs
https://api.example.com/users/{{$json.body.user_id}}

// In object properties
{
  "name": "={{$json.body.name}}",
  "email": "={{$json.body.email}}"
}

When NOT to Use Expressions

❌ Code Nodes

Code nodes use direct JavaScript access, NOT expressions!

// ❌ WRONG in Code node
const email = '={{$json.email}}';
const name = '{{$json.body.name}}';

// ✅ CORRECT in Code node
const email = $json.email;
const name = $json.body.name;

// Or using Code node API
const email = $input.item.json.email;
const allItems = $input.all();

❌ Webhook Paths

// ❌ WRONG
path: "{{$json.user_id}}/webhook"

// ✅ CORRECT
path: "user-webhook"  // Static paths only

❌ Credential Fields

// ❌ WRONG
apiKey: "={{$env.API_KEY}}"

// ✅ CORRECT
Use n8n credential system, not expressions

The transform gatekeeper

Before you add a node — or write any code — to transform data, walk this order and stop at the first that fits:

  1. The service's own node does it in its own fields: a CRM node's field slots, the Slack node's Blocks field, a Data Table insert's per-column slots. HTTP Request only when no node covers the operation.
  2. A native node for the job. Filter, IF / Switch, Summarize, Aggregate, Split Out, Merge, Compare Datasets, Remove Duplicates, Sort + Limit, Date & Time, XML / HTML / Extract From File, HTTP Request pagination, Crypto. The job-to-node table in using-n8n-mcp-skills maps jobs to nodes; their configs are in n8n-node-configuration → NATIVE_NODES.md.
  3. A short expression ({{ ... }}) inside that node's field. Property access, method chains (.map().filter().join()), a ternary, string building, Luxon date math, the helper functions below — "take A, produce B" in one expression, without intermediate variables.
    • Querying nested JSON for one field (pick, filter, sum inside an array) → $jmespath() in that same expression (rules below). When downstream needs one item per element, use Split Out / Filter / Aggregate instead.
  4. Code node, only for the closed list: loops or recursion no node expresses, state across runs, parsing no node handles, an allowlisted library, heavy all-items work (thousands of items, stated or measured), or one short Code node (~15 lines) replacing 4+ glue nodes. Give it a Why Code: note. See n8n-code-javascript.

A function body is code. When the logic needs const, if, return or several statements — an (() => { ... })() wrapped in {{ }} — it has outgrown an expression. Split it into a native node plus short expressions, or move it into a Code node with a Why Code: note. A long expression is harder to read than either, and a runtime error inside it resolves silently to null (see Debugging). The create/update hooks flag function bodies in non-Code nodes.

Why the order matters. Readability: a native node says on the canvas what it does, and a short expression stays visible in the field that uses it, instead of hiding in an upstream node someone has to open. Performance rarely decides it — below a few hundred items none of the costs matter, and the measured model lives in n8n-code-javascript.

$jmespath() — query nested JSON in one expression

{{ $jmespath($json, "customers[?country=='PL' && revenue > `100000`].name") }}    →  ["Acme"]

Verified on n8n 2.38: this one expression returns exactly what Split Out → Filter → Aggregate returns, with no extra nodes. The syntax is unforgiving, and most mistakes fail silently:

WriteNotWhat the wrong form does
$jmespath(object, "query"), object first$jmespath("query", object)throws expected two arguments (Object, string) for this function (JMESPath's own docs show search(query, data))
strings in single quotes: country=='PL'country=="PL"double quotes mean a field name → returns [], no error
numbers/booleans in backticks: revenue > `100000`revenue > 100000parse error → whole expression becomes null (see Debugging)
&& || ! ==and or =parse error → null
hyphenated keys quoted: 'customers[*].contact."first-name"' (single-quote the JS string)contact.first-nameparse error → null
over items, keep the wrapper: $jmespath($('Node').all(), "[?json.country=='PL'].json.name") or $jmespath($input.all().map(i => i.json), "[?country=='PL'].name")"[?country=='PL'].name" on .all()items are {json: …} wrappers → []
  • Results: missing path or index → null; filter with no match → []; sum() over an empty projection → 0.
  • First argument must be an object or array. A string (e.g. an HTTP Request with a text response) or undefined ($json.missingField) throws the same expected two arguments error. That one does fail the node.
  • Handy pieces: length(), sum(), max_by(arr, &field), sort_by(arr, &field), reverse(), contains(), starts_with(), keys(), to_number(); projection [*], flatten [], pipe | [0], reshape {name: name, email: contact.email}.
  • It returns a value, not items. Use it where the result feeds one field (message text, HTTP body, IF/Filter condition). When downstream needs one item per match, narrow with $jmespath in Edit Fields and follow with a single Split Out on that field.
  • Where it exists: expressions and JavaScript Code nodes (same argument order). Not in native Python Code nodes.

Built-in helper functions

n8n adds methods to values inside {{ }}. Together with a native node they replace most one-line Code nodes. They exist only in expressions, not in Code nodes — inside Code use plain JavaScript (and toFormat() instead of format()). They see only the current item's values: jobs across items (dedupe items, group and total, join two lists) belong in a node. On n8n-mcp 2.97.0+, tools_documentation({topic: "expression_helpers", depth: "full"}) lists every helper with a tested example.

NeedExpressionNote
One field from every object{{ $json.items.pluck('name') }}several names → one array per object
Sum / average / min / max{{ $json.prices.sum() }}throws on non-numbers, numeric strings included
Dedupe an array{{ $json.rows.unique('email') }}each argument is one field name; none → compares whole values (removeDuplicates is an alias)
Default for an empty value{{ $ifEmpty($json.name, 'there') }}empty = undefined, null, '', [], {}; exactly two arguments
Email or domain in text{{ $json.text.extractEmail() }}, .extractDomain()undefined when nothing matches
Hash a string{{ $json.email.hash('sha256') }}md5 by default; HMAC needs the Crypto node
Days between dates{{ $now.diffTo($json.created_at, 'days') }}receiver minus argument: positive when the argument is earlier
String to date{{ $json.created_at.toDateTime().format('yyyy-MM-dd') }}then .diffTo(), .plus(7, 'days'), .extract('month')
Split an array into batches{{ $json.ids.chunk(100) }}for b

Content truncated.

When not to use it

  • →When configuring nodes using only static UI inputs
  • →When writing native JavaScript outside of the n8n expression context

Limitations

  • →Does not execute the workflow, only validates syntax
  • →Cannot resolve issues caused by missing credentials

How it compares

It detects common pitfalls like missing quotes in node references that a standard code linter would ignore.

Compared to similar skills

n8n-expression-syntax side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
n8n-expression-syntax (this skill)67moNo flagsBeginner
customerio-advanced-troubleshooting04moCautionAdvanced
telegram-bot-builder1069moReviewIntermediate
reddit-api37moReviewIntermediate

Try saying

Example prompts that trigger this skill in your AI assistant.

More by czlonkowski

View all by czlonkowski →

n8n-workflow-patterns

czlonkowski

Proven workflow architectural patterns from real n8n workflows. Use when building new workflows, designing workflow structure, choosing workflow patterns, planning workflow architecture, or asking about webhook processing, HTTP API integration, database operations, AI agent workflows, or scheduled tasks.

16115

n8n-code-javascript

czlonkowski

Write JavaScript code in n8n Code nodes. Use when writing JavaScript in n8n, using $input/$json/$node syntax, making HTTP requests with $helpers, working with dates using DateTime, troubleshooting Code node errors, or choosing between Code node modes.

7122

n8n-code-python

czlonkowski

Write Python code in n8n Code nodes. Use when writing Python in n8n, using _input/_json/_node syntax, working with standard library, or need to understand Python limitations in n8n Code nodes.

775

n8n-mcp-tools-expert

czlonkowski

Expert guide for using n8n-mcp MCP tools effectively. Use when searching for nodes, validating configurations, accessing templates, managing workflows, or using any n8n-mcp tool. Provides tool selection guidance, parameter formats, and common patterns.

7128

n8n-node-configuration

czlonkowski

Operation-aware node configuration guidance. Use when configuring nodes, understanding property dependencies, determining required fields, choosing between get_node_essentials and get_node_info, or learning common configuration patterns by node type.

7108

n8n-validation-expert

czlonkowski

Interpret validation errors and guide fixing them. Use when encountering validation errors, validation warnings, false positives, operator structure issues, or need help understanding validation results. Also use when asking about validation profiles, error types, or the validation loop process.

697

You might also like

customerio-advanced-troubleshooting

jeremylongshore

Apply Customer.io advanced debugging techniques. Use when diagnosing complex issues, investigating delivery problems, or debugging integration failures. Trigger with phrases like "debug customer.io", "customer.io investigation", "customer.io troubleshoot", "customer.io incident".

01

telegram-bot-builder

davila7

Expert in building Telegram bots that solve real problems - from simple automation to complex AI-powered bots. Covers bot architecture, the Telegram Bot API, user experience, monetization strategies, and scaling bots to thousands of users. Use when: telegram bot, bot api, telegram automation, chat bot telegram, tg bot.

106130

reddit-api

alinaqi

Reddit API with PRAW (Python) and Snoowrap (Node.js)

334

mcporter

openclaw

Use the mcporter CLI to list, configure, auth, and call MCP servers/tools directly (HTTP or stdio), including ad-hoc servers, config edits, and CLI/type generation.

726

calcom-api

calcom

Interact with the Cal.com API v2 to manage scheduling, bookings, event types, availability, and calendars. Use this skill when building integrations that need to create or manage bookings, check availability, configure event types, or sync calendars with Cal.com's scheduling infrastructure.

216

instantly-webhooks-events

jeremylongshore

Implement Instantly webhook signature validation and event handling. Use when setting up webhook endpoints, implementing signature verification, or handling Instantly event notifications securely. Trigger with phrases like "instantly webhook", "instantly events", "instantly webhook signature", "handle instantly events", "instantly notifications".

211

Search skills

Search the agent skills registry