feat: Add production learnings to skills and optimize triggering (v1.5.0)

Incorporate real-world n8n workflow building experience into all 7 skills:
- SplitInBatches loop semantics, cross-iteration data, nested loops
- Google Sheets/Drive integration gotchas
- pairedItem, correct node references, float precision patterns
- Batch Processing as 6th core workflow pattern
- MCP tool parameter corrections (updates vs parameters, credential format)
- $env blocking awareness, bracket notation for special chars

Optimize all skill descriptions for better triggering accuracy:
- n8n-mcp-tools-expert: triggers on any n8n MCP tool usage
- n8n-workflow-patterns: triggers on workflow creation/design
- n8n-code-javascript: triggers on Code node usage

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "n8n-mcp-skills",
       "source": "./",
       "description": "Complete bundle: 7 expert skills for building flawless n8n workflows using n8n-mcp MCP server. Includes skills for expression syntax, MCP tools usage, workflow patterns, validation, node configuration, JavaScript code, and Python code.",
-      "version": "1.4.0",
+      "version": "1.5.0",
       "author": {
         "name": "Romuald Członkowski",
         "url": "https://www.aiadvisors.pl/en"

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-mcp-skills",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Expert skills for building n8n workflows with n8n-mcp",
   "author": {
     "name": "Romuald Członkowski",

build.sh

@@ -5,7 +5,7 @@
 set -e
 
 DIST_DIR="dist"
-VERSION="1.4.0"
+VERSION="1.5.0"
 
 echo "🔨 Building n8n-skills distribution packages..."
 

dist/README.md

@@ -8,13 +8,13 @@ This folder contains distribution packages for different Claude platforms.
 
 Upload each skill separately via Settings > Capabilities > Skills (bottom of page):
 
-- `n8n-expression-syntax-v1.4.0.zip` - n8n expression syntax and common patterns
-- `n8n-mcp-tools-expert-v1.4.0.zip` - Expert guide for using n8n-mcp tools (recommended to install first)
-- `n8n-workflow-patterns-v1.4.0.zip` - 5 proven workflow architectural patterns
-- `n8n-validation-expert-v1.4.0.zip` - Validation error interpretation and fixing
-- `n8n-node-configuration-v1.4.0.zip` - Operation-aware node configuration
-- `n8n-code-javascript-v1.4.0.zip` - JavaScript in n8n Code nodes
-- `n8n-code-python-v1.4.0.zip` - Python in n8n Code nodes
+- `n8n-expression-syntax-v1.5.0.zip` - n8n expression syntax and common patterns
+- `n8n-mcp-tools-expert-v1.5.0.zip` - Expert guide for using n8n-mcp tools (recommended to install first)
+- `n8n-workflow-patterns-v1.5.0.zip` - 6 proven workflow architectural patterns
+- `n8n-validation-expert-v1.5.0.zip` - Validation error interpretation and fixing
+- `n8n-node-configuration-v1.5.0.zip` - Operation-aware node configuration
+- `n8n-code-javascript-v1.5.0.zip` - JavaScript in n8n Code nodes
+- `n8n-code-python-v1.5.0.zip` - Python in n8n Code nodes
 
 **Installation:**
 1. Go to Settings > Capabilities > Skills (bottom of page)
@@ -24,7 +24,7 @@ Upload each skill separately via Settings > Capabilities > Skills (bottom of pag
 
 ### Complete Bundle (Claude Code only)
 
-- **`n8n-mcp-skills-v1.4.0.zip`** (174 KB) - All 7 skills in one package
+- **`n8n-mcp-skills-v1.5.0.zip`** (174 KB) - All 7 skills in one package
 
 > **This bundle is NOT compatible with Claude.ai or Claude Desktop.** It uses a nested `skills/` directory structure required by Claude Code plugins. For Claude.ai/Desktop, use the individual skill zips above.
 
@@ -34,7 +34,7 @@ Upload each skill separately via Settings > Capabilities > Skills (bottom of pag
 /plugin install czlonkowski/n8n-skills
 
 # Or install from local file
-/plugin install /path/to/n8n-mcp-skills-v1.4.0.zip
+/plugin install /path/to/n8n-mcp-skills-v1.5.0.zip
 ```
 
 ## Which Package Should I Use?
@@ -51,14 +51,14 @@ Upload each skill separately via Settings > Capabilities > Skills (bottom of pag
 
 ```
 dist/
-├── n8n-code-javascript-v1.4.0.zip        (34 KB)
-├── n8n-code-python-v1.4.0.zip            (31 KB)
-├── n8n-expression-syntax-v1.4.0.zip      (11 KB)
-├── n8n-mcp-skills-v1.4.0.zip             (174 KB)  Claude Code only
-├── n8n-mcp-tools-expert-v1.4.0.zip       (19 KB)
-├── n8n-node-configuration-v1.4.0.zip     (18 KB)
-├── n8n-validation-expert-v1.4.0.zip      (19 KB)
-├── n8n-workflow-patterns-v1.4.0.zip      (37 KB)
+├── n8n-code-javascript-v1.5.0.zip        (34 KB)
+├── n8n-code-python-v1.5.0.zip            (31 KB)
+├── n8n-expression-syntax-v1.5.0.zip      (11 KB)
+├── n8n-mcp-skills-v1.5.0.zip             (174 KB)  Claude Code only
+├── n8n-mcp-tools-expert-v1.5.0.zip       (19 KB)
+├── n8n-node-configuration-v1.5.0.zip     (18 KB)
+├── n8n-validation-expert-v1.5.0.zip      (19 KB)
+├── n8n-workflow-patterns-v1.5.0.zip      (37 KB)
 └── README.md                              (this file)
 ```
 

skills/n8n-code-javascript/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: n8n-code-javascript
-description: 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.
+description: 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, choosing between Code node modes, or doing any custom data transformation in n8n. Always use this skill when a workflow needs a Code node — whether for data aggregation, filtering, API calls, format conversion, batch processing logic, or any custom JavaScript. Covers SplitInBatches loop patterns, cross-iteration data, pairedItem, and real-world production patterns.
 ---
 
 # JavaScript Code Node
@@ -613,6 +613,91 @@ return result;
 
 ---
 
+## Production Gotchas
+
+Hard-won lessons from real-world n8n workflow deployments:
+
+### SplitInBatches Loop Semantics
+
+The SplitInBatches node has two outputs — and the naming is counterintuitive:
+- `main[0]` = **done** — fires ONCE after all batches are processed
+- `main[1]` = **each batch** — fires for every batch (this is the loop body)
+
+Always add a **Limit 1** node after the done output before downstream processing, as a safety against edge cases where done fires with extra items.
+
+### Cross-Iteration Data Accumulation (CRITICAL)
+
+After a SplitInBatches loop, `$('Node Inside Loop').all()` returns **ONLY the last iteration's items**, not cumulative results. This silently drops data from all but the final batch.
+
+**Fix**: Use workflow static data to accumulate across iterations:
+
+```javascript
+// BEFORE the loop (reset accumulator):
+const staticData = $getWorkflowStaticData('global');
+staticData.results = [];
+return $input.all();
+
+// INSIDE the loop body (accumulate):
+const staticData = $getWorkflowStaticData('global');
+const results = [];
+for (const item of $input.all()) {
+  const processed = { /* ... */ };
+  results.push({ json: processed });
+  staticData.results.push(processed);
+}
+return results;
+
+// AFTER the loop (read accumulated data):
+const staticData = $getWorkflowStaticData('global');
+const allResults = staticData.results || [];
+// Now aggregate across ALL iterations
+```
+
+### pairedItem for New Output Items
+
+When creating new items that don't map 1:1 to input items, include `pairedItem` — otherwise downstream Set nodes fail with `paired_item_no_info`:
+
+```javascript
+const results = [];
+for (let i = 0; i < $input.all().length; i++) {
+  const item = $input.all()[i];
+  results.push({
+    json: { /* new data */ },
+    pairedItem: { item: i }
+  });
+}
+return results;
+```
+
+### Correct Node Reference Syntax
+
+```javascript
+// ❌ WRONG - .json directly on node reference
+const data = $('HTTP Request').json;
+
+// ✅ CORRECT - call .first() then access .json
+const data = $('HTTP Request').first().json;
+
+// ✅ Also correct - get all items
+const allData = $('HTTP Request').all();
+```
+
+### Float Precision for Price/Currency Comparison
+
+When comparing prices or currency values, floating point noise can cause false positives. Round to cents:
+
+```javascript
+// ❌ Unreliable - float comparison
+if (newPrice !== oldPrice) { /* triggers on noise */ }
+
+// ✅ Reliable - compare at cent level
+if (Math.round(newPrice * 100) !== Math.round(oldPrice * 100)) {
+  // Real price change detected
+}
+```
+
+---
+
 ## When to Use Code Node
 
 Use Code node when:

skills/n8n-code-python/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: n8n-code-python
-description: 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.
+description: 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. Use this skill when the user specifically requests Python for an n8n Code node. Note — JavaScript is recommended for 95% of use cases — only use Python when the user explicitly prefers it or the task requires Python-specific standard library capabilities (regex, hashlib, statistics).
 ---
 
 # Python Code Node (Beta)
@@ -657,6 +657,32 @@ print(f"First item: {items[0] if items else 'None'}")
 
 ---
 
+## Production Gotchas
+
+### SplitInBatches Loop Semantics
+
+The SplitInBatches node has two outputs:
+- `main[0]` = **done** — fires ONCE after all batches complete
+- `main[1]` = **each batch** — fires for every batch (the loop body)
+
+Always add a **Limit 1** node after the done output.
+
+### Correct Node Reference Syntax
+
+```python
+# ❌ WRONG
+data = _node['HTTP Request']['json']
+
+# ✅ CORRECT - call .first() then access json
+data = _node['HTTP Request'].first()['json']
+```
+
+### Cross-Iteration Data Not Available in Python
+
+`$getWorkflowStaticData('global')` may not be available in Python Beta mode. If you need to accumulate data across SplitInBatches iterations, use a JavaScript Code node for the accumulation logic instead.
+
+---
+
 ## When to Use Python vs JavaScript
 
 ### Use Python When:

skills/n8n-expression-syntax/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: n8n-expression-syntax
-description: Validate n8n expression syntax and fix common errors. Use when writing n8n expressions, using {{}} syntax, accessing $json/$node variables, troubleshooting expression errors, or working with webhook data in workflows.
+description: 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.
 ---
 
 # n8n Expression Syntax
@@ -76,6 +76,11 @@ Access environment variables:
 {{$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
@@ -214,9 +219,9 @@ Expressions **must** be wrapped in double curly braces.
 ✅ {{$json.field}}
 ```
 
-### 2. Use Quotes for Spaces
+### 2. Use Quotes for Spaces and Special Characters
 
-Field or node names with spaces require **bracket notation**:
+Field or node names with spaces, diacritics, or special characters require **bracket notation**:
 
 ```javascript
 ❌ {{$json.field name}}
@@ -224,6 +229,10 @@ Field or node names with spaces require **bracket notation**:
 
 ❌ {{$node.HTTP Request.json}}
 ✅ {{$node["HTTP Request"].json}}
+
+// Bracket notation is mandatory for keys with special characters
+✅ {{$json['Gross Price w/o shipment']}}
+✅ {{$json['Cena brutto zł']}}
 ```
 
 ### 3. Match Exact Node Names

skills/n8n-mcp-tools-expert/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: n8n-mcp-tools-expert
-description: Expert guide for using n8n-mcp MCP tools effectively. Use when searching for nodes, validating configurations, accessing templates, managing workflows, managing credentials, auditing instance security, or using any n8n-mcp tool. Provides tool selection guidance, parameter formats, and common patterns.
+description: Expert guide for using n8n-mcp MCP tools effectively. Use when searching for nodes, validating configurations, accessing templates, managing workflows, managing credentials, auditing instance security, or using any n8n-mcp tool. Provides tool selection guidance, parameter formats, and common patterns. IMPORTANT — Always consult this skill before calling any n8n-mcp tool — it prevents common mistakes like wrong nodeType formats, incorrect parameter structures, and inefficient tool usage. If the user mentions n8n, workflows, nodes, or automation and you have n8n MCP tools available, use this skill first.
 ---
 
 # n8n MCP Tools Expert
@@ -259,6 +259,51 @@ n8n_update_partial_workflow({id, operations: [...]})
 }
 ```
 
+### Mistake 7: Wrong Parameter Name for updateNode
+
+**Problem**: Using `parameters` instead of `updates`
+
+```javascript
+// WRONG
+n8n_update_partial_workflow({
+  id: "wf-123",
+  operations: [{
+    type: "updateNode",
+    nodeName: "HTTP Request",
+    parameters: {url: "..."}  // ❌ Wrong key
+  }]
+})
+
+// CORRECT
+n8n_update_partial_workflow({
+  id: "wf-123",
+  operations: [{
+    type: "updateNode",
+    nodeName: "HTTP Request",
+    updates: {url: "..."}  // ✅ Correct key
+  }]
+})
+```
+
+### Mistake 8: Wrong Credential Attachment Format
+
+**Problem**: Credentials not attaching to nodes
+
+```javascript
+// WRONG - credentials as flat object
+updates: {credentials: "myApiKey"}
+
+// CORRECT - credentials nested by type with id and name
+updates: {
+  credentials: {
+    httpHeaderAuth: {
+      id: "abc123",
+      name: "My API Key"
+    }
+  }
+}
+```
+
 ### Mistake 6: Not Using intent Parameter
 
 **Problem**: Less helpful tool responses
@@ -768,6 +813,8 @@ validate_node({nodeType: "nodes-base.webhook", config: {}, mode: "minimal"})
 ## Best Practices
 
 ### Do
+- For simple workflows (<=5 nodes), use MCP tools directly — don't over-engineer the investigation
+- Use `patchNodeField` for surgical edits to Code node content instead of replacing the entire node
 - Use `get_node({detail: "standard"})` for most use cases
 - Specify validation profile explicitly (`profile: "runtime"`)
 - Use smart parameters (`branch`, `case`) for clarity

skills/n8n-node-configuration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: n8n-node-configuration
-description: Operation-aware node configuration guidance. Use when configuring nodes, understanding property dependencies, determining required fields, choosing between get_node detail levels, or learning common configuration patterns by node type.
+description: Operation-aware node configuration guidance. Use when configuring nodes, understanding property dependencies, determining required fields, choosing between get_node detail levels, or learning common configuration patterns by node type. Always use this skill when setting up node parameters — it explains which fields are required for each operation, how displayOptions control field visibility, and when to use patchNodeField for surgical edits vs full node updates.
 ---
 
 # n8n Node Configuration
@@ -619,6 +619,31 @@ get_node({
 
 ---
 
+## Node-Specific Configuration Notes
+
+### SplitInBatches v3
+
+```javascript
+{
+  "batchSize": 100,  // Number of items per batch
+  "options": {}
+}
+```
+
+**Output wiring**:
+- `main[0]` (done) → Connect to downstream processing (add Limit 1 first)
+- `main[1]` (each batch) → Connect to loop body, then loop back to SplitInBatches input
+
+See the n8n Workflow Patterns skill for detailed loop and nested loop patterns.
+
+### Google Sheets Node
+
+**Per-item execution**: Each input item triggers a separate API call. If you have 100 items and use a Google Sheets "Append Row" node, it makes 100 API calls. To write in bulk, aggregate items in a Code node first, then use a single HTTP Request with the Sheets API.
+
+**Formula columns**: Never use `append` on sheets with formula columns — it overwrites formulas. Instead, use HTTP Request with Google Sheets API `values.update` (PUT) method and a `googleApi` credential.
+
+---
+
 ## Configuration Anti-Patterns
 
 ### ❌ Don't: Over-configure Upfront

skills/n8n-validation-expert/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: n8n-validation-expert
-description: 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.
+description: 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, the validation loop process, or auto-fix capabilities. Consult this skill whenever a validate_node or validate_workflow call returns errors or warnings — it knows which warnings are false positives and which errors need real fixes.
 ---
 
 # n8n Validation Expert

skills/n8n-workflow-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: n8n-workflow-patterns
-description: 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.
+description: 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, batch processing, or scheduled tasks. Always consult this skill when the user asks to create, build, or design an n8n workflow, automate a process, or connect services — even if they don't explicitly mention 'patterns'. Covers webhook, API, database, AI, batch processing, and scheduled automation architectures.
 ---
 
 # n8n Workflow Patterns
@@ -9,7 +9,7 @@ Proven architectural patterns for building n8n workflows.
 
 ---
 
-## The 5 Core Patterns
+## The 6 Core Patterns
 
 Based on analysis of real workflow usage:
 
@@ -33,6 +33,10 @@ Based on analysis of real workflow usage:
    - Recurring automation workflows
    - Pattern: Schedule → Fetch → Process → Deliver → Log
 
+6. **Batch Processing** (below)
+   - Process large datasets in chunks with API rate limits
+   - Pattern: Prepare → SplitInBatches → Process per batch → Accumulate → Aggregate
+
 ---
 
 ## Pattern Selection Guide
@@ -69,6 +73,12 @@ Based on analysis of real workflow usage:
 - Maintenance tasks
 - Example: "Daily: Fetch analytics → Generate report → Email team"
 
+**Batch Processing** - Use when:
+- Processing large datasets that exceed API batch limits
+- Need to accumulate results across multiple API calls
+- Nested loops (e.g., multiple categories × paginated API calls per category)
+- Example: "Fetch products for 4 markets × 1000 per API call → Aggregate all results"
+
 ---
 
 ## Common Workflow Components
@@ -176,6 +186,96 @@ Main Flow → [Success Path]
 
 ---
 
+## Batch Processing Pattern
+
+### SplitInBatches Loop
+
+The SplitInBatches node splits a large dataset into smaller chunks for processing. Understanding its outputs is critical:
+
+- `main[0]` = **done** — fires ONCE after all batches complete
+- `main[1]` = **each batch** — fires per batch (this is the loop body)
+
+```
+Prepare Items → SplitInBatches → [main[1]: Process Batch] → (loops back)
+                                  [main[0]: Done] → Limit 1 → Aggregate
+```
+
+Always add a **Limit 1** node after the done output.
+
+### Cross-Iteration Data
+
+After the loop, `$('Node Inside Loop').all()` returns **ONLY the last batch's items**. To accumulate across all iterations, use `$getWorkflowStaticData('global')` in a Code node inside the loop. See the n8n Code JavaScript skill for the full pattern.
+
+### Nested Loops
+
+When processing N categories × M items per category (where an API has a batch limit):
+
+```
+Define Categories (N items)
+  → Outer Loop (SplitInBatches, batchSize=1)
+    → Prepare category data
+    → Inner Loop (SplitInBatches, batchSize=1000)
+      → API Call → Verify → (loops back to Inner Loop via main[1])
+    → Inner done[0] → Rate Limit Delay → back to Outer Loop
+  → Outer done[0] → Limit 1 → Final Aggregate
+```
+
+**Wiring gotcha**: The inner done[0] must connect back to the OUTER loop input, not to the aggregate. The outer done[0] feeds the final aggregate.
+
+### API Pagination
+
+For APIs without multi-ID filtering, use `id_from` + date windowing for efficient pagination:
+
+```
+Schedule → Set Date Window → Fetch Page → Process
+  → IF has more? → [true] Update id_from → Fetch Page (loop)
+                  → [false] → Aggregate → Output
+```
+
+### Dry-Run / Verification Tolerance
+
+When testing with API write nodes disabled (for dry runs), downstream verification nodes receive the request body instead of the response. Make verification tolerant:
+
+```javascript
+// In verification Code node
+const body = $input.first().json;
+const looksLikeRequest = body.method && body.parameters && !body.status;
+if (looksLikeRequest) {
+  return [{ json: { status: 'SKIPPED', message: 'Upstream disabled for testing' }}];
+}
+// Normal response verification below...
+```
+
+---
+
+## Integration-Specific Gotchas
+
+### Google Sheets
+
+- **NEVER use `append`** on sheets with formula columns — it breaks formulas. Use Google Sheets API `values.update` (PUT) via HTTP Request node with a `googleApi` credential
+- **Write numbers, not strings** for formula-dependent columns — string "4.98" breaks `ADD()` formulas. Use `parseFloat()` in a Code node
+- **Per-item execution trap**: Google Sheets nodes execute once per input item. If you need a single bulk write, aggregate items into one in a Code node first
+- **UNFORMATTED_VALUE returns numbers**, not text like "N/A" — filter explicitly in Code nodes
+
+### Google Drive
+
+- **`convertToGoogleDocument: true` creates a Google Doc (text)**, NOT a Google Sheet — to upload a CSV for download, omit this option entirely
+- **CSV download link format**: `https://drive.google.com/uc?id={fileId}&export=download` — use instead of `/view` links
+
+### Bidirectional Threshold Checking
+
+When comparing values (prices, quantities, metrics), always check both directions:
+
+```javascript
+// ❌ Only catches increases
+if (diff > threshold) { flag(); }
+
+// ✅ Catches both spikes AND crashes — both are data-quality signals
+if (Math.abs(diff) > threshold) { flag(); }
+```
+
+---
+
 ## Common Gotchas
 
 ### 1. Webhook Data Structure
@@ -392,7 +492,7 @@ Use `search_templates` and `get_template` from n8n-mcp tools to find examples!
 ## Summary
 
 **Key Points**:
-1. **5 core patterns** cover 90%+ of workflow use cases
+1. **6 core patterns** cover 90%+ of workflow use cases
 2. **Webhook processing** is the most common pattern
 3. Use the **workflow creation checklist** for every workflow
 4. **Plan pattern** → **Select nodes** → **Build** → **Validate** → **Deploy**