├── .claude-plugin ├── marketplace.json └── plugin.json ├── .gitignore ├── .mcp.json.example ├── CLAUDE.md ├── LICENSE ├── README.md ├── dist ├── README.md ├── n8n-expression-syntax-v1.0.0.zip ├── n8n-mcp-skills-v1.0.0.zip ├── n8n-mcp-tools-expert-v1.0.0.zip ├── n8n-node-configuration-v1.0.0.zip ├── n8n-validation-expert-v1.0.0.zip └── n8n-workflow-patterns-v1.0.0.zip ├── docs ├── DEVELOPMENT.md ├── INSTALLATION.md ├── MCP_TESTING_LOG.md └── USAGE.md ├── evaluations ├── code-javascript │ ├── eval-001-webhook-body-gotcha.json │ ├── eval-002-return-format-error.json │ ├── eval-003-http-request.json │ ├── eval-004-aggregation-pattern.json │ └── eval-005-expression-syntax-confusion.json ├── code-python │ ├── eval-001-module-import-error.json │ ├── eval-002-dictionary-keyerror.json │ ├── eval-003-webhook-body-gotcha.json │ ├── eval-004-return-format-error.json │ └── eval-005-standard-library-usage.json ├── expression-syntax │ ├── eval-001-missing-braces.json │ ├── eval-002-webhook-body-data.json │ ├── eval-003-code-node-confusion.json │ └── eval-004-node-reference.json ├── mcp-tools │ ├── eval-001-tool-selection.json │ ├── eval-002-nodetype-format.json │ ├── eval-003-validation-workflow.json │ ├── eval-004-essentials-vs-info.json │ └── eval-005-smart-parameters.json ├── node-configuration │ ├── eval-001-property-dependencies.json │ ├── eval-002-operation-specific-config.json │ ├── eval-003-conditional-fields.json │ └── eval-004-essentials-vs-info.json ├── validation-expert │ ├── eval-001-missing-required-field.json │ ├── eval-002-false-positive.json │ ├── eval-003-auto-sanitization.json │ └── eval-004-validation-loop.json └── workflow-patterns │ ├── eval-001-webhook-workflow.json │ ├── eval-002-http-api-workflow.json │ ├── eval-003-database-sync.json │ ├── eval-004-ai-agent.json │ └── eval-005-scheduled-report.json └── skills ├── n8n-code-javascript ├── BUILTIN_FUNCTIONS.md ├── COMMON_PATTERNS.md ├── DATA_ACCESS.md ├── ERROR_PATTERNS.md ├── README.md └── SKILL.md ├── n8n-code-python ├── COMMON_PATTERNS.md ├── DATA_ACCESS.md ├── ERROR_PATTERNS.md ├── README.md ├── SKILL.md └── STANDARD_LIBRARY.md ├── n8n-expression-syntax ├── COMMON_MISTAKES.md ├── EXAMPLES.md ├── README.md └── SKILL.md ├── n8n-mcp-tools-expert ├── README.md ├── SEARCH_GUIDE.md ├── SKILL.md ├── VALIDATION_GUIDE.md └── WORKFLOW_GUIDE.md ├── n8n-node-configuration ├── DEPENDENCIES.md ├── OPERATION_PATTERNS.md ├── README.md └── SKILL.md ├── n8n-validation-expert ├── ERROR_CATALOG.md ├── FALSE_POSITIVES.md ├── README.md └── SKILL.md └── n8n-workflow-patterns ├── README.md ├── SKILL.md ├── ai_agent_workflow.md ├── database_operations.md ├── http_api_integration.md ├── scheduled_tasks.md └── webhook_processing.md /.claude-plugin/marketplace.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "n8n-mcp-skills", 3 | "description": "Expert skills for building n8n workflows", 4 | "owner": { 5 | "name": "Romuald Członkowski", 6 | "url": "https://www.aiadvisors.pl/en" 7 | }, 8 | "plugins": [ 9 | { 10 | "name": "n8n-mcp-skills", 11 | "source": "./", 12 | "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.", 13 | "version": "1.0.0", 14 | "author": { 15 | "name": "Romuald Członkowski", 16 | "url": "https://www.aiadvisors.pl/en" 17 | }, 18 | "category": "automation", 19 | "keywords": [ 20 | "n8n", 21 | "workflow", 22 | "mcp", 23 | "automation", 24 | "validation", 25 | "expressions", 26 | "code", 27 | "javascript", 28 | "python", 29 | "skills" 30 | ], 31 | "homepage": "https://github.com/czlonkowski/n8n-skills", 32 | "repository": "https://github.com/czlonkowski/n8n-skills", 33 | "license": "MIT" 34 | } 35 | ] 36 | } 37 | -------------------------------------------------------------------------------- /.claude-plugin/plugin.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "n8n-mcp-skills", 3 | "version": "1.0.0", 4 | "description": "Expert skills for building n8n workflows with n8n-mcp", 5 | "author": { 6 | "name": "Romuald Członkowski", 7 | "url": "https://www.aiadvisors.pl/en" 8 | }, 9 | "license": "MIT", 10 | "keywords": [ 11 | "n8n", 12 | "workflow", 13 | "automation", 14 | "mcp", 15 | "validation", 16 | "expressions", 17 | "code", 18 | "javascript", 19 | "python" 20 | ], 21 | "repository": "https://github.com/czlonkowski/n8n-skills", 22 | "homepage": "https://github.com/czlonkowski/n8n-skills" 23 | } 24 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .mcp.json 2 | -------------------------------------------------------------------------------- /.mcp.json.example: -------------------------------------------------------------------------------- 1 | { 2 | "mcpServers": { 3 | "n8n-mcp": { 4 | "command": "npx", 5 | "args": ["n8n-mcp"], 6 | "env": { 7 | "MCP_MODE": "stdio", 8 | "LOG_LEVEL": "error", 9 | "DISABLE_CONSOLE_OUTPUT": "true", 10 | "N8N_API_URL": "https://your-n8n-instance.com", 11 | "N8N_API_KEY": "your-api-key-here" 12 | } 13 | } 14 | } 15 | } 16 | -------------------------------------------------------------------------------- /CLAUDE.md: -------------------------------------------------------------------------------- 1 | # CLAUDE.md 2 | 3 | This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. 4 | 5 | ## Project Overview 6 | 7 | This is the **n8n-skills** repository - a collection of Claude Code skills designed to teach AI assistants how to build flawless n8n workflows using the n8n-mcp MCP server. 8 | 9 | **Repository**: https://github.com/czlonkowski/n8n-skills 10 | 11 | **Purpose**: Create 5 complementary meta-skills that provide expert guidance on using n8n-mcp MCP tools effectively for building n8n workflows. 12 | 13 | **Architecture**: 14 | - **n8n-mcp MCP Server**: Provides data access (525 nodes, validation, templates) 15 | - **Claude Skills**: Provides expert guidance on HOW to use MCP tools 16 | - **Together**: Expert workflow builder with progressive disclosure 17 | 18 | ## Repository Structure 19 | 20 | ``` 21 | n8n-skills/ 22 | ├── README.md # Project overview 23 | ├── LICENSE # MIT License 24 | ├── skills/ # (To be created) Individual skill implementations 25 | │ ├── n8n-expression-syntax/ 26 | │ ├── n8n-mcp-tools-expert/ 27 | │ ├── n8n-workflow-patterns/ 28 | │ ├── n8n-validation-expert/ 29 | │ └── n8n-node-configuration/ 30 | ├── evaluations/ # (To be created) Test scenarios for each skill 31 | ├── docs/ # Documentation 32 | │ └── SKILLS_IMPLEMENTATION_GUIDE.md # Complete implementation guide 33 | └── .gitignore # Git ignore (excludes docs/) 34 | ``` 35 | 36 | ## Implementation Timeline 37 | 38 | - **Week 1**: n8n Expression Syntax (PoC - 4 files, ~350 lines) 39 | - **Week 2**: n8n MCP Tools Expert + n8n Workflow Patterns 40 | - **Week 3**: n8n Validation Expert + n8n Node Configuration 41 | - **Week 4**: Testing, refinement, documentation 42 | - **Week 5-6**: Distribution, plugin packaging 43 | 44 | ## Five Skills to Implement 45 | 46 | ### 1. n8n Expression Syntax 47 | **Priority**: Foundation (Week 1) 48 | - Teaches correct n8n expression syntax ({{}} patterns) 49 | - Covers common mistakes and fixes 50 | - Files: SKILL.md, COMMON_MISTAKES.md, EXAMPLES.md 51 | 52 | ### 2. n8n MCP Tools Expert 53 | **Priority**: Highest (fixes 20% failure rate) 54 | - Teaches how to use n8n-mcp MCP tools effectively 55 | - Covers node discovery, validation, workflow management 56 | - Files: SKILL.md, SEARCH_GUIDE.md, VALIDATION_GUIDE.md, WORKFLOW_GUIDE.md 57 | 58 | ### 3. n8n Workflow Patterns 59 | **Priority**: High (addresses 813 webhook searches) 60 | - Teaches proven workflow architectural patterns 61 | - 5 patterns from 31,917 real workflows 62 | - Files: SKILL.md + 5 pattern files (webhook, http, database, ai, scheduled) 63 | 64 | ### 4. n8n Validation Expert 65 | **Priority**: Medium 66 | - Interprets validation errors and guides fixing 67 | - Handles false positives and validation loops 68 | - Files: SKILL.md, ERROR_CATALOG.md, FALSE_POSITIVES.md 69 | 70 | ### 5. n8n Node Configuration 71 | **Priority**: Medium 72 | - Operation-aware node configuration guidance 73 | - Property dependencies and common patterns 74 | - Files: SKILL.md, DEPENDENCIES.md, OPERATION_PATTERNS.md 75 | 76 | ## Data-Driven Design 77 | 78 | These skills are based on telemetry analysis of: 79 | - 447,557 real MCP tool usage events 80 | - 31,917 workflows created 81 | - 19,113 validation errors 82 | - 15,107 validation feedback loops 83 | 84 | ## Skill Structure 85 | 86 | Each skill follows this format: 87 | 88 | ```markdown 89 | --- 90 | name: Skill Name 91 | description: When to use this skill. Use when [trigger conditions]. 92 | --- 93 | 94 | # Skill Name 95 | 96 | ## [Content organized in sections] 97 | ``` 98 | 99 | ## Development Approach 100 | 101 | **Evaluation-Driven Development**: 102 | 1. Create 3+ evaluations FIRST for each skill 103 | 2. Establish baseline (test without skill) 104 | 3. Write minimal SKILL.md (under 500 lines) 105 | 4. Test against evaluations 106 | 5. Iterate until 100% pass 107 | 6. Add reference files as needed 108 | 109 | ## Key Implementation Guidelines 110 | 111 | ### File Organization 112 | - Keep SKILL.md files under 500 lines 113 | - Split complex content into reference files 114 | - Use markdown with clear sections 115 | - Link between related files 116 | 117 | ### Skill Activation 118 | Skills activate automatically when queries match their description triggers: 119 | - "How do I write n8n expressions?" → n8n Expression Syntax 120 | - "Find me a Slack node" → n8n MCP Tools Expert 121 | - "Build a webhook workflow" → n8n Workflow Patterns 122 | 123 | ### Cross-Skill Integration 124 | Skills are designed to work together: 125 | - Use n8n Workflow Patterns to identify structure 126 | - Use n8n MCP Tools Expert to find nodes 127 | - Use n8n Node Configuration for setup 128 | - Use n8n Expression Syntax for data mapping 129 | - Use n8n Validation Expert to validate 130 | 131 | ## Important Patterns from Telemetry 132 | 133 | ### Most Common Tool Usage Pattern 134 | ``` 135 | search_nodes → get_node_essentials (9,835 occurrences, 18s avg) 136 | ``` 137 | 138 | ### Most Common Validation Pattern 139 | ``` 140 | n8n_update_partial_workflow → n8n_validate_workflow (7,841 occurrences) 141 | Avg 23s thinking, 58s fixing 142 | ``` 143 | 144 | ### Most Used Tool 145 | ``` 146 | n8n_update_partial_workflow (38,287 uses, 99.0% success) 147 | Avg 56 seconds between edits 148 | ``` 149 | 150 | ## Working with This Repository 151 | 152 | ### When Adding New Skills 153 | 1. Create skill directory under `skills/` 154 | 2. Follow the structure in `docs/SKILLS_IMPLEMENTATION_GUIDE.md` 155 | 3. Write SKILL.md with frontmatter 156 | 4. Add reference files as needed 157 | 5. Create 3+ evaluations in `evaluations/` 158 | 6. Test thoroughly before committing 159 | 160 | ### When Creating Evaluations 161 | Place in `evaluations/[skill-name]/eval-NNN-description.json` 162 | 163 | Format: 164 | ```json 165 | { 166 | "id": "skill-NNN", 167 | "skills": ["skill-name"], 168 | "query": "User question or scenario", 169 | "expected_behavior": [ 170 | "List of expected behaviors", 171 | "What skill should do", 172 | "What content it should reference" 173 | ] 174 | } 175 | ``` 176 | 177 | ### Git Workflow 178 | - Work on feature branches 179 | - Commit frequently with clear messages 180 | - Test skills before pushing 181 | - Keep main branch stable 182 | 183 | ## Requirements 184 | 185 | - n8n-mcp MCP server installed and configured 186 | - Claude Code, Claude.ai, or Claude API access 187 | - Understanding of n8n workflow concepts 188 | 189 | ## Distribution 190 | 191 | Final distribution will be: 192 | 1. **GitHub Repository**: Full source code and documentation 193 | 2. **Claude Code Plugin**: Packaged skills with plugin.json 194 | 3. **Individual Skill Uploads**: For Claude.ai users 195 | 196 | ## Credits 197 | 198 | Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en) 199 | 200 | Part of the n8n-mcp project. 201 | 202 | ## License 203 | 204 | MIT License - See LICENSE file for details. 205 | - Add to every commit and PR: Concieved by Romuald Członkowski - and then link to www.aiadvisors.pl/en. Don't add it in conversations -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2025 Romuald Członkowski 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # n8n-skills 2 | 3 | **Expert Claude Code skills for building flawless n8n workflows using the n8n-mcp MCP server** 4 | 5 | [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) 6 | [![n8n-mcp](https://img.shields.io/badge/n8n--mcp-compatible-green.svg)](https://github.com/czlonkowski/n8n-mcp) 7 | 8 | --- 9 | 10 | ## 🎯 What is this? 11 | 12 | This repository contains 5 complementary **Claude Code skills** that teach AI assistants how to build production-ready n8n workflows using the [n8n-mcp](https://github.com/czlonkowski/n8n-mcp) MCP server. 13 | 14 | ### Why These Skills Exist 15 | 16 | Building n8n workflows programmatically can be challenging. Common issues include: 17 | - Using MCP tools incorrectly or inefficiently 18 | - Getting stuck in validation error loops 19 | - Not knowing which workflow patterns to use 20 | - Misconfiguring nodes and their dependencies 21 | 22 | These skills solve these problems by teaching Claude: 23 | - ✅ Correct n8n expression syntax ({{}} patterns) 24 | - ✅ How to use n8n-mcp tools effectively 25 | - ✅ Proven workflow patterns from real-world usage 26 | - ✅ Validation error interpretation and fixing 27 | - ✅ Operation-aware node configuration 28 | 29 | --- 30 | 31 | ## 📚 The 7 Skills 32 | 33 | ### 1. **n8n Expression Syntax** 34 | Teaches correct n8n expression syntax and common patterns. 35 | 36 | **Activates when**: Writing expressions, using {{}} syntax, accessing $json/$node variables, troubleshooting expression errors. 37 | 38 | **Key Features**: 39 | - Core variables ($json, $node, $now, $env) 40 | - **Critical gotcha**: Webhook data is under `$json.body` 41 | - Common mistakes catalog with fixes 42 | - When NOT to use expressions (Code nodes!) 43 | 44 | ### 2. **n8n MCP Tools Expert** (HIGHEST PRIORITY) 45 | Expert guide for using n8n-mcp MCP tools effectively. 46 | 47 | **Activates when**: Searching for nodes, validating configurations, accessing templates, managing workflows. 48 | 49 | **Key Features**: 50 | - Tool selection guide (which tool for which task) 51 | - nodeType format differences (nodes-base.* vs n8n-nodes-base.*) 52 | - Validation profiles (minimal/runtime/ai-friendly/strict) 53 | - Smart parameters (branch="true" for IF nodes) 54 | - Auto-sanitization system explained 55 | 56 | **Most Important**: Teaches correct MCP tool usage patterns and parameter formats 57 | 58 | ### 3. **n8n Workflow Patterns** 59 | Build workflows using 5 proven architectural patterns. 60 | 61 | **Activates when**: Creating workflows, connecting nodes, designing automation. 62 | 63 | **Key Features**: 64 | - 5 proven patterns (webhook processing, HTTP API, database, AI, scheduled) 65 | - Workflow creation checklist 66 | - Real examples from 2,653+ n8n templates 67 | - Connection best practices 68 | - Pattern selection guide 69 | 70 | ### 4. **n8n Validation Expert** 71 | Interpret validation errors and guide fixing. 72 | 73 | **Activates when**: Validation fails, debugging workflow errors, handling false positives. 74 | 75 | **Key Features**: 76 | - Validation loop workflow 77 | - Real error catalog 78 | - Auto-sanitization behavior explained 79 | - False positives guide 80 | - Profile selection for different stages 81 | 82 | ### 5. **n8n Node Configuration** 83 | Operation-aware node configuration guidance. 84 | 85 | **Activates when**: Configuring nodes, understanding property dependencies, setting up AI workflows. 86 | 87 | **Key Features**: 88 | - Property dependency rules (e.g., sendBody → contentType) 89 | - Operation-specific requirements 90 | - AI connection types (8 types for AI Agent workflows) 91 | - Common configuration patterns 92 | 93 | ### 6. **n8n Code JavaScript** 94 | Write effective JavaScript code in n8n Code nodes. 95 | 96 | **Activates when**: Writing JavaScript in Code nodes, troubleshooting Code node errors, making HTTP requests with $helpers, working with dates. 97 | 98 | **Key Features**: 99 | - Data access patterns ($input.all(), $input.first(), $input.item) 100 | - **Critical gotcha**: Webhook data under `$json.body` 101 | - Correct return format: `[{json: {...}}]` 102 | - Built-in functions ($helpers.httpRequest(), DateTime, $jmespath()) 103 | - Top 5 error patterns with solutions (covering 62%+ of failures) 104 | - 10 production-tested patterns 105 | 106 | ### 7. **n8n Code Python** 107 | Write Python code in n8n Code nodes with proper limitations awareness. 108 | 109 | **Activates when**: Writing Python in Code nodes, need to know Python limitations, working with standard library. 110 | 111 | **Key Features**: 112 | - **Important**: Use JavaScript for 95% of use cases 113 | - Python data access (_input, _json, _node) 114 | - **Critical limitation**: No external libraries (requests, pandas, numpy) 115 | - Standard library reference (json, datetime, re, etc.) 116 | - Workarounds for missing libraries 117 | - Common Python patterns for n8n 118 | 119 | --- 120 | 121 | ## 🚀 Installation 122 | 123 | ### Prerequisites 124 | 125 | 1. **n8n-mcp MCP server** installed and configured ([Installation Guide](https://github.com/czlonkowski/n8n-mcp)) 126 | 2. **Claude Code**, Claude.ai, or Claude API access 127 | 3. `.mcp.json` configured with n8n-mcp server 128 | 129 | ### Claude Code 130 | 131 | **Method 1: Plugin Installation** (Recommended) 132 | ```bash 133 | # Install directly as a Claude Code plugin 134 | /plugin install czlonkowski/n8n-skills 135 | ``` 136 | 137 | **Method 2: Via Marketplace** 138 | ```bash 139 | # Add as marketplace, then browse and install 140 | /plugin marketplace add czlonkowski/n8n-skills 141 | 142 | # Then browse available plugins 143 | /plugin install 144 | # Select "n8n-mcp-skills" from the list 145 | ``` 146 | 147 | **Method 3: Manual Installation** 148 | ```bash 149 | # 1. Clone this repository 150 | git clone https://github.com/czlonkowski/n8n-skills.git 151 | 152 | # 2. Copy skills to your Claude Code skills directory 153 | cp -r n8n-skills/skills/* ~/.claude/skills/ 154 | 155 | # 3. Reload Claude Code 156 | # Skills will activate automatically 157 | ``` 158 | 159 | ### Claude.ai 160 | 161 | 1. Download individual skill folders from `skills/` 162 | 2. Zip each skill folder 163 | 3. Upload via Settings → Capabilities → Skills 164 | 165 | ### API / SDK 166 | 167 | See [docs/INSTALLATION.md](docs/INSTALLATION.md) for detailed instructions. 168 | 169 | --- 170 | 171 | ## 💡 Usage 172 | 173 | Skills activate **automatically** when relevant queries are detected: 174 | 175 | ``` 176 | "How do I write n8n expressions?" 177 | → Activates: n8n Expression Syntax 178 | 179 | "Find me a Slack node" 180 | → Activates: n8n MCP Tools Expert 181 | 182 | "Build a webhook workflow" 183 | → Activates: n8n Workflow Patterns 184 | 185 | "Why is validation failing?" 186 | → Activates: n8n Validation Expert 187 | 188 | "How do I configure the HTTP Request node?" 189 | → Activates: n8n Node Configuration 190 | 191 | "How do I access webhook data in a Code node?" 192 | → Activates: n8n Code JavaScript 193 | 194 | "Can I use pandas in Python Code node?" 195 | → Activates: n8n Code Python 196 | ``` 197 | 198 | ### Skills Work Together 199 | 200 | When you ask: **"Build and validate a webhook to Slack workflow"** 201 | 202 | 1. **n8n Workflow Patterns** identifies webhook processing pattern 203 | 2. **n8n MCP Tools Expert** searches for webhook and Slack nodes 204 | 3. **n8n Node Configuration** guides node setup 205 | 4. **n8n Code JavaScript** helps process webhook data with proper .body access 206 | 5. **n8n Expression Syntax** helps with data mapping in other nodes 207 | 6. **n8n Validation Expert** validates the final workflow 208 | 209 | All skills compose seamlessly! 210 | 211 | --- 212 | 213 | ## 📖 Documentation 214 | 215 | - [Installation Guide](docs/INSTALLATION.md) - Detailed installation for all platforms 216 | - [Usage Guide](docs/USAGE.md) - How to use skills effectively 217 | - [Development Guide](docs/DEVELOPMENT.md) - Contributing and testing 218 | - [MCP Testing Log](docs/MCP_TESTING_LOG.md) - Real tool responses used in skills 219 | 220 | --- 221 | 222 | 223 | ## 🧪 Testing 224 | 225 | Each skill includes 3+ evaluations for quality assurance: 226 | 227 | ```bash 228 | # Run evaluations (if testing framework available) 229 | npm test 230 | 231 | # Or manually test with Claude 232 | claude-code --skill n8n-expression-syntax "Test webhook data access" 233 | ``` 234 | 235 | --- 236 | 237 | ## 🤝 Contributing 238 | 239 | Contributions welcome! Please see [DEVELOPMENT.md](docs/DEVELOPMENT.md) for guidelines. 240 | 241 | ### Development Approach 242 | 243 | 1. **Evaluation-First**: Write test scenarios before implementation 244 | 2. **MCP-Informed**: Test tools, document real responses 245 | 3. **Iterative**: Test against evaluations, iterate until 100% pass 246 | 4. **Concise**: Keep SKILL.md under 500 lines 247 | 5. **Real Examples**: All examples from real templates/tools 248 | 249 | --- 250 | 251 | ## 📝 License 252 | 253 | MIT License - see [LICENSE](LICENSE) file for details. 254 | 255 | --- 256 | 257 | ## 🙏 Credits 258 | 259 | **Conceived by Romuald Członkowski** 260 | - Website: [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en) 261 | - Part of the [n8n-mcp project](https://github.com/czlonkowski/n8n-mcp) 262 | 263 | --- 264 | 265 | ## 🔗 Related Projects 266 | 267 | - [n8n-mcp](https://github.com/czlonkowski/n8n-mcp) - MCP server for n8n 268 | - [n8n](https://n8n.io/) - Workflow automation platform 269 | 270 | --- 271 | 272 | ## 📊 What's Included 273 | 274 | - **7** complementary skills that work together 275 | - **525+** n8n nodes supported 276 | - **2,653+** workflow templates for examples 277 | - **10** production-tested Code node patterns 278 | - **Comprehensive** error catalogs and troubleshooting guides 279 | 280 | --- 281 | 282 | **Ready to build flawless n8n workflows? Get started now!** 🚀 283 | -------------------------------------------------------------------------------- /dist/README.md: -------------------------------------------------------------------------------- 1 | # n8n-mcp Skills - Distribution Packages 2 | 3 | This folder contains distribution packages for different Claude platforms. 4 | 5 | ## 📦 Available Packages 6 | 7 | ### Complete Bundle (Recommended) 8 | 9 | - **`n8n-mcp-skills-v1.0.0.zip`** (168 KB) - All 7 skills in one package 10 | 11 | **Includes:** 12 | - Skill #1: n8n Expression Syntax 13 | - Skill #2: n8n MCP Tools Expert 14 | - Skill #3: n8n Workflow Patterns 15 | - Skill #4: n8n Validation Expert 16 | - Skill #5: n8n Node Configuration 17 | - Skill #6: n8n Code JavaScript 18 | - Skill #7: n8n Code Python 19 | 20 | **Installation:** 21 | ```bash 22 | # Claude Code plugin installation 23 | /plugin install czlonkowski/n8n-skills 24 | 25 | # Or install from local file 26 | /plugin install /path/to/n8n-mcp-skills-v1.0.0.zip 27 | ``` 28 | 29 | ### For Claude.ai Users (Individual Skills) 30 | 31 | Upload each skill separately via Settings → Capabilities → Skills (bottom of page): 32 | 33 | - `n8n-expression-syntax-v1.0.0.zip` - n8n expression syntax and common patterns 34 | - `n8n-mcp-tools-expert-v1.0.0.zip` - Expert guide for using n8n-mcp tools (recommended to install first) 35 | - `n8n-workflow-patterns-v1.0.0.zip` - 5 proven workflow architectural patterns 36 | - `n8n-validation-expert-v1.0.0.zip` - Validation error interpretation and fixing 37 | - `n8n-node-configuration-v1.0.0.zip` - Operation-aware node configuration 38 | 39 | **Installation:** 40 | 1. Go to Settings → Capabilities → Skills (bottom of page) 41 | 2. Click "Upload Skill" 42 | 3. Select one of the skill zip files above 43 | 4. Repeat for each skill you want to install 44 | 45 | **Note:** JavaScript and Python Code skills are only available in the complete bundle (not as individual skills). 46 | 47 | ## 🎯 Which Package Should I Use? 48 | 49 | | Platform | Package | What You Get | 50 | |----------|---------|--------------| 51 | | **Claude.ai** | Individual zips | 5 core skills (upload separately) | 52 | | **Claude Code** | Complete bundle (n8n-mcp-skills-v1.0.0.zip) | All 7 skills at once | 53 | | **Claude API** | Complete bundle | All 7 skills (extract skills/ folder) | 54 | 55 | **Note:** Code skills (#6 JavaScript, #7 Python) are only in the complete bundle. 56 | 57 | --- 58 | 59 | ## 📁 Files in This Directory 60 | 61 | ``` 62 | dist/ 63 | ├── n8n-mcp-skills-v1.0.0.zip (168 KB) ★ RECOMMENDED 64 | ├── n8n-expression-syntax-v1.0.0.zip (11 KB) 65 | ├── n8n-mcp-tools-expert-v1.0.0.zip (15 KB) 66 | ├── n8n-workflow-patterns-v1.0.0.zip (35 KB) 67 | ├── n8n-validation-expert-v1.0.0.zip (18 KB) 68 | ├── n8n-node-configuration-v1.0.0.zip (17 KB) 69 | └── README.md (this file) 70 | ``` 71 | 72 | --- 73 | 74 | ## 📋 What's Included in Each Package 75 | 76 | ### Individual Skill Packages (Claude.ai) 77 | 78 | Each zip contains: 79 | ``` 80 | SKILL.md # Main skill instructions with YAML frontmatter 81 | [Reference files] # Additional documentation and guides 82 | README.md # Skill metadata and statistics 83 | ``` 84 | 85 | ### Bundle Package (Claude Code) 86 | 87 | ``` 88 | .claude-plugin/ 89 | ├── plugin.json # Claude Code plugin metadata 90 | └── marketplace.json # Marketplace listing metadata 91 | README.md # Project overview and documentation 92 | LICENSE # MIT License 93 | skills/ # All 7 skills in subfolders 94 | ├── n8n-expression-syntax/ 95 | ├── n8n-mcp-tools-expert/ 96 | ├── n8n-workflow-patterns/ 97 | ├── n8n-validation-expert/ 98 | ├── n8n-node-configuration/ 99 | ├── n8n-code-javascript/ 100 | └── n8n-code-python/ 101 | ``` 102 | 103 | ## ✅ Verification 104 | 105 | After installation, test skills by asking: 106 | 107 | ``` 108 | "How do I write n8n expressions?" 109 | → Should activate: n8n Expression Syntax 110 | 111 | "Find me a Slack node" 112 | → Should activate: n8n MCP Tools Expert 113 | 114 | "Build a webhook workflow" 115 | → Should activate: n8n Workflow Patterns 116 | 117 | "How do I access webhook data in a Code node?" 118 | → Should activate: n8n Code JavaScript 119 | 120 | "Can I use pandas in Python Code node?" 121 | → Should activate: n8n Code Python 122 | ``` 123 | 124 | ## 🔧 Requirements 125 | 126 | - **n8n-mcp MCP server** installed and configured ([Installation Guide](https://github.com/czlonkowski/n8n-mcp)) 127 | - **Claude Pro, Max, Team, or Enterprise** plan (for Claude.ai skills) 128 | - **.mcp.json** configured with n8n-mcp server 129 | 130 | ## 📖 Documentation 131 | 132 | For detailed installation instructions, see: 133 | - Main README: `../README.md` 134 | - Installation Guide: `../docs/INSTALLATION.md` 135 | - Usage Guide: `../docs/USAGE.md` 136 | 137 | ## 🐛 Troubleshooting 138 | 139 | **Claude.ai Error: "Zip must contain exactly one SKILL.md file"** 140 | - Use the individual skill zips, not the bundle 141 | - Each skill must be uploaded separately 142 | 143 | **Claude Code: Skills not activating** 144 | - Verify skills are in `~/.claude/skills/` directory 145 | - Check that n8n-mcp MCP server is running 146 | - Reload Claude Code 147 | 148 | **Skills not triggering** 149 | - Skills activate based on keywords in your queries 150 | - Try more specific questions matching skill descriptions 151 | - Check that SKILL.md files have correct frontmatter 152 | 153 | ## 📝 License 154 | 155 | MIT License - see `../LICENSE` file 156 | 157 | ## 🙏 Credits 158 | 159 | Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en 160 | 161 | Part of the [n8n-mcp project](https://github.com/czlonkowski/n8n-mcp). 162 | -------------------------------------------------------------------------------- /dist/n8n-expression-syntax-v1.0.0.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/czlonkowski/n8n-skills/ec350daa6e148733ddb7d0c74b25c8dc69879b12/dist/n8n-expression-syntax-v1.0.0.zip -------------------------------------------------------------------------------- /dist/n8n-mcp-skills-v1.0.0.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/czlonkowski/n8n-skills/ec350daa6e148733ddb7d0c74b25c8dc69879b12/dist/n8n-mcp-skills-v1.0.0.zip -------------------------------------------------------------------------------- /dist/n8n-mcp-tools-expert-v1.0.0.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/czlonkowski/n8n-skills/ec350daa6e148733ddb7d0c74b25c8dc69879b12/dist/n8n-mcp-tools-expert-v1.0.0.zip -------------------------------------------------------------------------------- /dist/n8n-node-configuration-v1.0.0.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/czlonkowski/n8n-skills/ec350daa6e148733ddb7d0c74b25c8dc69879b12/dist/n8n-node-configuration-v1.0.0.zip -------------------------------------------------------------------------------- /dist/n8n-validation-expert-v1.0.0.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/czlonkowski/n8n-skills/ec350daa6e148733ddb7d0c74b25c8dc69879b12/dist/n8n-validation-expert-v1.0.0.zip -------------------------------------------------------------------------------- /dist/n8n-workflow-patterns-v1.0.0.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/czlonkowski/n8n-skills/ec350daa6e148733ddb7d0c74b25c8dc69879b12/dist/n8n-workflow-patterns-v1.0.0.zip -------------------------------------------------------------------------------- /docs/INSTALLATION.md: -------------------------------------------------------------------------------- 1 | # Installation Guide 2 | 3 | Complete installation instructions for n8n-skills across all platforms. 4 | 5 | --- 6 | 7 | ## Prerequisites 8 | 9 | ### 1. n8n-mcp MCP Server 10 | 11 | You **must** have the n8n-mcp MCP server installed and configured before using these skills. 12 | 13 | **Install n8n-mcp**: 14 | ```bash 15 | npm install -g n8n-mcp 16 | ``` 17 | 18 | **Configure MCP server** in `.mcp.json`: 19 | ```json 20 | { 21 | "mcpServers": { 22 | "n8n-mcp": { 23 | "command": "npx", 24 | "args": ["n8n-mcp"], 25 | "env": { 26 | "MCP_MODE": "stdio", 27 | "LOG_LEVEL": "error", 28 | "DISABLE_CONSOLE_OUTPUT": "true", 29 | "N8N_API_URL": "https://your-n8n-instance.com", 30 | "N8N_API_KEY": "your-api-key-here" 31 | } 32 | } 33 | } 34 | } 35 | ``` 36 | 37 | **Note**: `N8N_API_URL` and `N8N_API_KEY` are optional but enable workflow creation/management tools. 38 | 39 | ### 2. Claude Access 40 | 41 | You need one of: 42 | - **Claude Code** (desktop application) 43 | - **Claude.ai** (web interface) 44 | - **Claude API** (via SDK) 45 | 46 | --- 47 | 48 | ## Installation Methods 49 | 50 | ### Method 1: Claude Code (Recommended) 51 | 52 | **Step 1**: Clone the repository 53 | ```bash 54 | git clone https://github.com/czlonkowski/n8n-skills.git 55 | cd n8n-skills 56 | ``` 57 | 58 | **Step 2**: Copy skills to Claude Code skills directory 59 | 60 | **macOS/Linux**: 61 | ```bash 62 | mkdir -p ~/.claude/skills 63 | cp -r skills/* ~/.claude/skills/ 64 | ``` 65 | 66 | **Windows**: 67 | ```powershell 68 | New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\skills" 69 | Copy-Item -Recurse skills\* "$env:USERPROFILE\.claude\skills\" 70 | ``` 71 | 72 | **Step 3**: Verify installation 73 | ```bash 74 | ls ~/.claude/skills/ 75 | # Should show: n8n-expression-syntax, n8n-mcp-tools-expert, etc. 76 | ``` 77 | 78 | **Step 4**: Reload Claude Code 79 | - Restart Claude Code application 80 | - Skills will activate automatically 81 | 82 | --- 83 | 84 | ### Method 2: Claude.ai (Web Interface) 85 | 86 | **Step 1**: Download skill folders 87 | 88 | Download the repository and navigate to `skills/` directory. You'll need to upload each skill individually. 89 | 90 | **Step 2**: Zip each skill 91 | ```bash 92 | cd skills 93 | zip -r n8n-expression-syntax.zip n8n-expression-syntax/ 94 | zip -r n8n-mcp-tools-expert.zip n8n-mcp-tools-expert/ 95 | zip -r n8n-workflow-patterns.zip n8n-workflow-patterns/ 96 | zip -r n8n-validation-expert.zip n8n-validation-expert/ 97 | zip -r n8n-node-configuration.zip n8n-node-configuration/ 98 | ``` 99 | 100 | **Step 3**: Upload to Claude.ai 101 | 102 | 1. Go to Claude.ai 103 | 2. Navigate to **Settings** → **Capabilities** → **Skills** 104 | 3. Click **Upload Skill** 105 | 4. Upload each `.zip` file individually 106 | 5. Confirm each upload 107 | 108 | **Step 4**: Verify skills are active 109 | 110 | In a new conversation, type: 111 | ``` 112 | "List my active skills" 113 | ``` 114 | 115 | You should see all 5 n8n skills listed. 116 | 117 | --- 118 | 119 | ### Method 3: Claude API / SDK 120 | 121 | **Step 1**: Install via package manager 122 | 123 | If you're building an application with Claude SDK: 124 | 125 | ```typescript 126 | import Anthropic from '@anthropic-ai/sdk'; 127 | 128 | const client = new Anthropic({ 129 | apiKey: process.env.ANTHROPIC_API_KEY, 130 | }); 131 | 132 | // Load skills from directory 133 | const skillsDir = './skills'; 134 | const skills = loadSkillsFromDirectory(skillsDir); 135 | 136 | const response = await client.messages.create({ 137 | model: 'claude-sonnet-4-5-20250929', 138 | messages: [{ 139 | role: 'user', 140 | content: 'Build a webhook to Slack workflow' 141 | }], 142 | skills: skills // Pass loaded skills 143 | }); 144 | ``` 145 | 146 | **Step 2**: Skill loading function 147 | 148 | ```typescript 149 | import fs from 'fs'; 150 | import path from 'path'; 151 | 152 | function loadSkillsFromDirectory(dir: string) { 153 | const skillDirs = fs.readdirSync(dir); 154 | return skillDirs.map(skillName => { 155 | const skillPath = path.join(dir, skillName, 'SKILL.md'); 156 | const skillContent = fs.readFileSync(skillPath, 'utf-8'); 157 | 158 | return { 159 | name: skillName, 160 | content: skillContent 161 | }; 162 | }); 163 | } 164 | ``` 165 | 166 | --- 167 | 168 | ## Verification 169 | 170 | ### Test Installation 171 | 172 | **1. Check MCP server availability** 173 | ``` 174 | Ask Claude: "Can you search for the webhook node using n8n-mcp?" 175 | ``` 176 | 177 | Expected response: 178 | ``` 179 | [Uses search_nodes tool] 180 | Found: nodes-base.webhook (Webhook trigger node) 181 | ``` 182 | 183 | **2. Test skill activation** 184 | ``` 185 | Ask Claude: "How do I access webhook data in n8n expressions?" 186 | ``` 187 | 188 | Expected response: 189 | ``` 190 | [n8n Expression Syntax skill activates] 191 | Webhook data is under $json.body... 192 | ``` 193 | 194 | **3. Test cross-skill composition** 195 | ``` 196 | Ask Claude: "Build and validate a webhook to Slack workflow" 197 | ``` 198 | 199 | Expected: All 5 skills should activate and work together. 200 | 201 | --- 202 | 203 | ## Troubleshooting 204 | 205 | ### Skills Not Activating 206 | 207 | **Problem**: Skills don't activate when expected 208 | 209 | **Solutions**: 210 | 1. Verify skills are in correct directory: 211 | - Claude Code: `~/.claude/skills/` 212 | - Check each skill has `SKILL.md` with frontmatter 213 | 214 | 2. Check SKILL.md frontmatter format: 215 | ```markdown 216 | --- 217 | name: n8n Expression Syntax 218 | description: Validate n8n expression syntax... 219 | --- 220 | ``` 221 | 222 | 3. Reload Claude Code or clear cache 223 | 224 | ### MCP Tools Not Available 225 | 226 | **Problem**: "n8n-mcp tools not available" 227 | 228 | **Solutions**: 229 | 1. Verify `.mcp.json` is in correct location 230 | 2. Check n8n-mcp is installed: `npm list -g n8n-mcp` 231 | 3. Test MCP server: `npx n8n-mcp` 232 | 4. Restart Claude Code 233 | 234 | ### N8N API Tools Missing 235 | 236 | **Problem**: "n8n_create_workflow not available" 237 | 238 | **Solutions**: 239 | 1. Verify `N8N_API_URL` and `N8N_API_KEY` in `.mcp.json` 240 | 2. Test API access: `curl -H "X-N8N-API-KEY: your-key" https://your-n8n-instance/api/v1/workflows` 241 | 3. Skills will still work with read-only tools (search, validate, templates) 242 | 243 | ### Permission Issues 244 | 245 | **Problem**: Cannot write to skills directory 246 | 247 | **macOS/Linux**: 248 | ```bash 249 | sudo chown -R $USER ~/.claude 250 | chmod -R 755 ~/.claude/skills 251 | ``` 252 | 253 | **Windows**: Run PowerShell as Administrator 254 | 255 | --- 256 | 257 | ## Uninstallation 258 | 259 | ### Remove All Skills 260 | 261 | **Claude Code**: 262 | ```bash 263 | rm -rf ~/.claude/skills/n8n-* 264 | ``` 265 | 266 | **Claude.ai**: 267 | 1. Go to Settings → Capabilities → Skills 268 | 2. Delete each n8n skill individually 269 | 270 | ### Remove Specific Skill 271 | 272 | ```bash 273 | rm -rf ~/.claude/skills/n8n-expression-syntax 274 | ``` 275 | 276 | --- 277 | 278 | ## Updating 279 | 280 | ### Update All Skills 281 | 282 | ```bash 283 | cd n8n-skills 284 | git pull origin main 285 | cp -r skills/* ~/.claude/skills/ 286 | ``` 287 | 288 | ### Update Single Skill 289 | 290 | ```bash 291 | cp -r skills/n8n-expression-syntax ~/.claude/skills/ 292 | ``` 293 | 294 | --- 295 | 296 | ## Advanced Configuration 297 | 298 | ### Custom Skill Location 299 | 300 | If using custom skills directory: 301 | 302 | ```bash 303 | # Set environment variable 304 | export CLAUDE_SKILLS_DIR="/path/to/custom/skills" 305 | 306 | # Copy skills 307 | cp -r skills/* $CLAUDE_SKILLS_DIR/ 308 | ``` 309 | 310 | ### Selective Installation 311 | 312 | Install only specific skills: 313 | 314 | ```bash 315 | # Only expression syntax and MCP tools expert 316 | cp -r skills/n8n-expression-syntax ~/.claude/skills/ 317 | cp -r skills/n8n-mcp-tools-expert ~/.claude/skills/ 318 | ``` 319 | 320 | --- 321 | 322 | ## Next Steps 323 | 324 | ✅ Installation complete? Continue to [USAGE.md](USAGE.md) for usage examples. 325 | 326 | --- 327 | 328 | ## Support 329 | 330 | - **Issues**: https://github.com/czlonkowski/n8n-skills/issues 331 | - **Discussions**: https://github.com/czlonkowski/n8n-skills/discussions 332 | - **n8n-mcp**: https://github.com/romualdczlonkowski/n8n-mcp 333 | 334 | --- 335 | 336 | Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en) 337 | -------------------------------------------------------------------------------- /docs/MCP_TESTING_LOG.md: -------------------------------------------------------------------------------- 1 | # MCP Tool Testing Log 2 | ## Generated: 2025-10-20 3 | ## Purpose: Document actual tool responses for skill content creation 4 | 5 | This log contains real responses from n8n-mcp tools to inform accurate skill content. 6 | 7 | --- 8 | 9 | ## n8n API Status 10 | 11 | **Health Check Result**: 12 | ```json 13 | { 14 | "status": "ok", 15 | "apiUrl": "https://n8n-test.n8n-mcp.com", 16 | "mcpVersion": "2.20.3", 17 | "versionCheck": "up to date", 18 | "responseTime": 798ms 19 | } 20 | ``` 21 | 22 | ✅ **n8n API Tools Available**: All workflow creation/management tools functional 23 | 24 | --- 25 | 26 | ## Database Statistics 27 | 28 | ```json 29 | { 30 | "totalNodes": 537, 31 | "totalTemplates": 2653, 32 | "statistics": { 33 | "aiTools": 270, 34 | "triggers": 108, 35 | "versionedNodes": 141, 36 | "nodesWithDocumentation": 470, 37 | "documentationCoverage": "88%" 38 | }, 39 | "packageBreakdown": [ 40 | {"package": "@n8n/n8n-nodes-langchain", "nodeCount": 100}, 41 | {"package": "n8n-nodes-base", "nodeCount": 437} 42 | ] 43 | } 44 | ``` 45 | 46 | **Key Insights**: 47 | - 537 nodes total (437 base + 100 langchain) 48 | - 270 AI-capable tools 49 | - 108 trigger nodes 50 | - 88% documentation coverage 51 | - 2,653 templates with avg 4,115 views 52 | 53 | --- 54 | 55 | ## Search Tool Testing 56 | 57 | ### search_nodes - Common Queries 58 | 59 | **Query: "webhook"** → Returns Webhook (trigger), Respond to Webhook (transform) 60 | - nodeType format: `nodes-base.webhook` 61 | - workflowNodeType format: `n8n-nodes-base.webhook` 62 | - ⚠️ **Critical**: Use different formats for different tools! 63 | 64 | **Query: "http"** → Returns HTTP Request, HTTP Request Tool (AI), Code Tool 65 | - Regular: `nodes-base.httpRequest` 66 | - AI Tool: `nodes-langchain.toolHttpRequest` 67 | 68 | **Query: "database"** → Returns Firebase, Redis Vector Store, etc. 69 | 70 | --- 71 | 72 | ## Node Essentials Testing 73 | 74 | ### Webhook Node 75 | 76 | **Key Properties**: 77 | - `httpMethod`: GET, POST, PUT, DELETE, etc. (default: GET) 78 | - `path`: Webhook URL path (e.g., "form-submit") 79 | - `responseMode`: onReceived, lastNode, responseNode 80 | - **CRITICAL**: Webhook data structure is `$json.body.*` not `$json.*` 81 | 82 | **Output Structure**: 83 | ```javascript 84 | { 85 | "headers": {...}, 86 | "params": {...}, 87 | "query": {...}, 88 | "body": { // ⚠️ User data is HERE! 89 | "name": "John", 90 | "email": "john@example.com" 91 | } 92 | } 93 | ``` 94 | 95 | --- 96 | 97 | ## Validation Testing 98 | 99 | ### Validation Profiles Comparison 100 | 101 | **Test Config**: `{resource: "channel", operation: "create"}` on Slack node 102 | 103 | **Result**: Missing required field "name" 104 | - All profiles detected this error 105 | - Fix provided: "Provide a channel name" 106 | - Warning about rate limits (best practice) 107 | 108 | --- 109 | 110 | ## Template Analysis 111 | 112 | **Total Templates**: 2,653 113 | **Popular Templates** (webhook + slack): 114 | - #2947: Weather via Slack (1,500 views) - Webhook → OpenStreetMap → NWS → Slack 115 | - #4039: Download Slack Media (778 views) - SlackTrigger → HTTP Request 116 | - #5529: Jamf Patch to Slack (147 views) - Complex multi-node 117 | 118 | **Key Pattern**: Webhook → Transform → Action → Notify (5-7 nodes avg) 119 | 120 | --- 121 | 122 | ## Critical Findings for Skills 123 | 124 | ### 1. Expression Syntax (Skill #1) 125 | - ✅ Webhook data under `.body` (not root) 126 | - ✅ Code nodes use direct access ($json), NOT expressions ({{}}) 127 | - ✅ Node references: `$node["Node Name"].json.field` 128 | 129 | ### 2. MCP Tools Expert (Skill #2) 130 | - ✅ nodeType formats differ: `nodes-base.*` vs `n8n-nodes-base.*` 131 | - ✅ get_node_essentials preferred over get_node_info (5KB vs 100KB+) 132 | - ✅ Validation profiles: minimal/runtime/ai-friendly/strict 133 | - ✅ Smart parameters: branch="true"/"false" for IF, case=N for Switch 134 | - ✅ Auto-sanitization runs on ALL nodes during any update 135 | 136 | ### 3. Workflow Patterns (Skill #3) 137 | - ✅ 2,653 real templates available 138 | - ✅ Template metadata includes complexity, setup time, services 139 | - ✅ Common pattern: Trigger → Process → Act (5-7 nodes) 140 | - ✅ Webhook workflows: 27.6% of all workflows 141 | 142 | ### 4. Validation Expert (Skill #4) 143 | - ✅ Real validation errors documented 144 | - ✅ Auto-sanitization fixes operator structures 145 | - ✅ Binary operators (equals, contains) vs unary (isEmpty, isNotEmpty) 146 | 147 | ### 5. Node Configuration (Skill #5) 148 | - ✅ Property dependencies documented (e.g., sendBody → contentType) 149 | - ✅ Operation-specific requirements vary 150 | - ✅ 8 AI connection types supported 151 | 152 | --- 153 | 154 | ## Tools Availability Summary 155 | 156 | **Available WITHOUT n8n API**: 157 | - search_nodes, list_nodes, get_node_essentials ✅ 158 | - validate_node_minimal, validate_node_operation ✅ 159 | - validate_workflow, get_property_dependencies ✅ 160 | - search_templates, get_template, list_tasks ✅ 161 | 162 | **Requires n8n API** (AVAILABLE at n8n-test.n8n-mcp.com): 163 | - n8n_create_workflow ✅ 164 | - n8n_update_partial_workflow ✅ 165 | - n8n_validate_workflow (by ID) ✅ 166 | - n8n_list_workflows, n8n_get_workflow ✅ 167 | - n8n_trigger_webhook_workflow ✅ 168 | 169 | --- 170 | 171 | **Testing Complete**: Ready for skill implementation with real data! 172 | -------------------------------------------------------------------------------- /docs/USAGE.md: -------------------------------------------------------------------------------- 1 | # Usage Guide 2 | 3 | Learn how to use n8n-skills effectively with Claude. 4 | 5 | --- 6 | 7 | ## How Skills Activate 8 | 9 | Skills activate **automatically** based on your query content. You don't need to manually invoke them. 10 | 11 | ### Activation Triggers 12 | 13 | Each skill has specific triggers defined in its frontmatter: 14 | 15 | ```markdown 16 | --- 17 | name: n8n Expression Syntax 18 | description: Validate n8n expression syntax and fix common errors. Use when writing n8n expressions, using {{}} syntax, accessing $json/$node variables, or troubleshooting expression errors in workflows. 19 | --- 20 | ``` 21 | 22 | When your query matches the description keywords, the skill activates. 23 | 24 | --- 25 | 26 | ## Individual Skill Usage 27 | 28 | ### 1. n8n Expression Syntax 29 | 30 | **Activates on**: expression, {{}} syntax, $json, $node, webhook data access 31 | 32 | **Example Queries**: 33 | ``` 34 | "How do I write n8n expressions?" 35 | "Why is {{$json.email}} showing undefined?" 36 | "Access webhook data in Slack node" 37 | "What's wrong with my $node reference?" 38 | ``` 39 | 40 | **What You'll Learn**: 41 | - Correct {{}} syntax 42 | - Webhook data structure ($json.body.*) 43 | - Node references ($node["Node Name"].json) 44 | - Common mistakes and fixes 45 | - When NOT to use expressions (Code nodes) 46 | 47 | **Example Response**: 48 | ``` 49 | [Skill activates] 50 | 51 | n8n expressions must be wrapped in double curly braces: 52 | 53 | ✅ Correct: {{$json.body.email}} 54 | ❌ Wrong: $json.body.email 55 | 56 | For webhook data, remember it's under .body: 57 | {{$json.body.name}} // Webhook form data 58 | {{$json.body.message}} // Webhook message 59 | 60 | In Code nodes, use direct access (no {{}}): 61 | const email = $json.body.email; // Correct in Code node 62 | ``` 63 | 64 | --- 65 | 66 | ### 2. n8n MCP Tools Expert 67 | 68 | **Activates on**: search nodes, validate, find node, MCP tools, template, workflow 69 | 70 | **Example Queries**: 71 | ``` 72 | "Find me a Slack node" 73 | "How do I search for database nodes?" 74 | "Validate this node configuration" 75 | "What's the difference between get_node_info and get_node_essentials?" 76 | "Which MCP tool should I use to create workflows?" 77 | ``` 78 | 79 | **What You'll Learn**: 80 | - Tool selection (which tool for which task) 81 | - nodeType format differences 82 | - Validation profiles (minimal/runtime/ai-friendly/strict) 83 | - Common MCP tool mistakes 84 | - Workflow management tools 85 | 86 | **Example Response**: 87 | ``` 88 | [Skill activates] 89 | 90 | To find the Slack node, use search_nodes: 91 | 92 | search_nodes({query: "slack"}) 93 | 94 | This returns: 95 | - nodeType: "nodes-base.slack" (for search/validate tools) 96 | - workflowNodeType: "n8n-nodes-base.slack" (for workflows) 97 | 98 | ⚠️ Important: Use different formats for different tools! 99 | 100 | Next, get node details: 101 | get_node_essentials({nodeType: "nodes-base.slack"}) 102 | 103 | This returns focused 5KB data vs 100KB+ from get_node_info. 104 | ``` 105 | 106 | --- 107 | 108 | ### 3. n8n Workflow Patterns 109 | 110 | **Activates on**: build workflow, webhook, pattern, architecture, workflow structure 111 | 112 | **Example Queries**: 113 | ``` 114 | "Build a webhook to Slack workflow" 115 | "What's the best pattern for API integration?" 116 | "Create a scheduled database workflow" 117 | "Show me webhook processing pattern" 118 | ``` 119 | 120 | **What You'll Learn**: 121 | - 5 proven patterns (webhook, HTTP API, database, AI, scheduled) 122 | - Workflow creation checklist 123 | - Node connection best practices 124 | - Real template examples 125 | - Pattern selection guide 126 | 127 | **Example Response**: 128 | ``` 129 | [Skill activates] 130 | 131 | For webhook to Slack, use the Webhook Processing pattern: 132 | 133 | Pattern Structure: 134 | Webhook Trigger → [Transform] → Slack Notification 135 | 136 | Workflow Checklist: 137 | □ Search for nodes (search_nodes) 138 | □ Get node configurations (get_node_essentials) 139 | □ Create workflow structure 140 | □ Add data mappings (expressions) 141 | □ Validate workflow 142 | □ Test with sample data 143 | 144 | Real Example from Template #2947: 145 | Webhook → OpenStreetMap → NWS → Slack 146 | (1,500 views, proven pattern) 147 | ``` 148 | 149 | --- 150 | 151 | ### 4. n8n Validation Expert 152 | 153 | **Activates on**: validation, error, fix, debug, validate workflow 154 | 155 | **Example Queries**: 156 | ``` 157 | "Why is my workflow validation failing?" 158 | "Fix this validation error" 159 | "Explain this validation warning" 160 | "What does auto-sanitization do?" 161 | ``` 162 | 163 | **What You'll Learn**: 164 | - Validation loop workflow 165 | - Error interpretation 166 | - Auto-sanitization system 167 | - False positives handling 168 | - Profile selection 169 | 170 | **Example Response**: 171 | ``` 172 | [Skill activates] 173 | 174 | Validation Error: "Required field 'channel' missing" 175 | 176 | Fix: 177 | validate_node_operation({ 178 | nodeType: "nodes-base.slack", 179 | config: { 180 | resource: "message", 181 | operation: "post", 182 | channel: "#general", // Add this! 183 | text: "Message" 184 | }, 185 | profile: "runtime" 186 | }) 187 | 188 | Auto-sanitization will fix: 189 | ✅ Binary operator structures (equals, contains) 190 | ✅ Unary operator structures (isEmpty, isNotEmpty) 191 | ✅ Missing metadata in IF/Switch nodes 192 | 193 | But cannot fix: 194 | ❌ Broken connections 195 | ❌ Branch count mismatches 196 | ``` 197 | 198 | --- 199 | 200 | ### 5. n8n Node Configuration 201 | 202 | **Activates on**: configure node, property, operation, dependencies, AI workflow 203 | 204 | **Example Queries**: 205 | ``` 206 | "How do I configure the HTTP Request node?" 207 | "What properties does the Slack node need?" 208 | "Explain property dependencies" 209 | "Set up AI Agent workflow" 210 | ``` 211 | 212 | **What You'll Learn**: 213 | - Operation-specific requirements 214 | - Property dependencies (sendBody → contentType) 215 | - AI connection types (8 types) 216 | - Common configuration patterns 217 | 218 | **Example Response**: 219 | ``` 220 | [Skill activates] 221 | 222 | HTTP Request node property dependencies: 223 | 224 | 1. Set sendBody = true 225 | ↓ Reveals: contentType 226 | 227 | 2. Set contentType = "json" 228 | ↓ Reveals: specifyBody 229 | 230 | 3. Set specifyBody = "json" 231 | ↓ Reveals: jsonBody 232 | 233 | This cascade of 32 dependencies ensures you see only relevant properties! 234 | 235 | For AI workflows, 8 connection types: 236 | - ai_languageModel (OpenAI, Anthropic) 237 | - ai_tool (HTTP Request Tool, Code Tool) 238 | - ai_memory (Window Buffer Memory) 239 | - ai_outputParser, ai_embedding, ai_vectorStore... 240 | ``` 241 | 242 | --- 243 | 244 | ## Cross-Skill Composition 245 | 246 | Skills work **together automatically**. Here's how: 247 | 248 | ### Example: Complete Workflow Build 249 | 250 | **Your Query**: 251 | ``` 252 | "Build and validate a webhook to Slack workflow with proper data mapping" 253 | ``` 254 | 255 | **What Happens** (all automatic): 256 | 257 | **Step 1**: n8n Workflow Patterns activates 258 | ``` 259 | → Identifies: Webhook Processing Pattern 260 | → Provides: Workflow structure 261 | ``` 262 | 263 | **Step 2**: n8n MCP Tools Expert activates 264 | ``` 265 | → Searches: search_nodes({query: "webhook"}) 266 | → Searches: search_nodes({query: "slack"}) 267 | → Gets details: get_node_essentials for both 268 | ``` 269 | 270 | **Step 3**: n8n Node Configuration activates 271 | ``` 272 | → Guides: Webhook node setup (path, httpMethod) 273 | → Guides: Slack node setup (resource, operation, channel) 274 | ``` 275 | 276 | **Step 4**: n8n Expression Syntax activates 277 | ``` 278 | → Provides: {{$json.body.message}} for data mapping 279 | → Warns: Webhook data is under .body! 280 | ``` 281 | 282 | **Step 5**: n8n Validation Expert activates 283 | ``` 284 | → Validates: Complete workflow structure 285 | → Checks: Node configurations 286 | → Reports: Any errors or warnings 287 | ``` 288 | 289 | **Result**: Complete, validated, working workflow! 290 | 291 | --- 292 | 293 | ## Common Use Cases 294 | 295 | ### Use Case 1: Quick Node Search 296 | 297 | ``` 298 | You: "Find email nodes" 299 | 300 | [n8n MCP Tools Expert activates] 301 | Claude: Uses search_nodes({query: "email"}) 302 | Returns: Gmail, Email Send, IMAP Email, etc. 303 | ``` 304 | 305 | ### Use Case 2: Fix Expression Error 306 | 307 | ``` 308 | You: "My {{$json.name}} is showing undefined in webhook workflow" 309 | 310 | [n8n Expression Syntax activates] 311 | Claude: Webhook data is under .body! 312 | Fix: {{$json.body.name}} 313 | ``` 314 | 315 | ### Use Case 3: Understand Validation Error 316 | 317 | ``` 318 | You: "Validation says 'binary operator cannot have singleValue'" 319 | 320 | [n8n Validation Expert activates] 321 | Claude: Binary operators (equals, contains) should NOT have singleValue. 322 | Auto-sanitization will fix this on next update. 323 | ``` 324 | 325 | ### Use Case 4: Build AI Workflow 326 | 327 | ``` 328 | You: "Create an AI Agent workflow with HTTP Request tool" 329 | 330 | [n8n Workflow Patterns + Node Configuration activate] 331 | Claude: AI Agent Workflow Pattern: 332 | 1. Connect language model: sourceOutput="ai_languageModel" 333 | 2. Connect tool: sourceOutput="ai_tool" 334 | 3. Connect memory: sourceOutput="ai_memory" 335 | 336 | [Provides complete configuration] 337 | ``` 338 | 339 | --- 340 | 341 | ## Best Practices 342 | 343 | ### 1. Be Specific 344 | 345 | **Good**: "Build a webhook that receives form data and posts to Slack" 346 | **Better**: "Build a webhook to Slack workflow with form validation and error handling" 347 | 348 | **Why**: More specific queries activate relevant skills with better context. 349 | 350 | ### 2. Ask Follow-Up Questions 351 | 352 | Skills provide deep knowledge. Don't hesitate to ask: 353 | ``` 354 | "Explain property dependencies in HTTP Request node" 355 | "Show me more webhook examples" 356 | "What are validation profiles?" 357 | ``` 358 | 359 | ### 3. Request Validation 360 | 361 | Always ask for validation: 362 | ``` 363 | "Build this workflow AND validate it" 364 | "Check if this configuration is correct" 365 | ``` 366 | 367 | ### 4. Leverage Cross-Skill Knowledge 368 | 369 | ``` 370 | "Build, validate, and explain the expressions in this workflow" 371 | → Activates: Patterns + Validation + Expression Syntax 372 | ``` 373 | 374 | ### 5. Reference Real Templates 375 | 376 | ``` 377 | "Show me template #2947 and explain how it works" 378 | → Uses n8n-mcp tools to fetch and analyze real templates 379 | ``` 380 | 381 | --- 382 | 383 | ## Skill Limitations 384 | 385 | ### What Skills CAN Do: 386 | ✅ Teach n8n concepts 387 | ✅ Guide MCP tool usage 388 | ✅ Provide workflow patterns 389 | ✅ Interpret validation errors 390 | ✅ Explain configurations 391 | ✅ Reference real templates 392 | 393 | ### What Skills CANNOT Do: 394 | ❌ Execute workflows (use n8n for that) 395 | ❌ Access your n8n instance directly (use n8n-mcp API tools) 396 | ❌ Modify running workflows 397 | ❌ Debug runtime execution errors (only configuration errors) 398 | 399 | --- 400 | 401 | ## Tool Availability 402 | 403 | **Always Available** (no n8n API needed): 404 | - search_nodes, list_nodes, get_node_essentials ✅ 405 | - validate_node_minimal, validate_node_operation ✅ 406 | - validate_workflow, get_property_dependencies ✅ 407 | - search_templates, get_template ✅ 408 | 409 | **Requires n8n API** (N8N_API_URL + N8N_API_KEY): 410 | - n8n_create_workflow ⚠️ 411 | - n8n_update_partial_workflow ⚠️ 412 | - n8n_validate_workflow (by ID) ⚠️ 413 | - n8n_list_workflows, n8n_get_workflow ⚠️ 414 | - n8n_trigger_webhook_workflow ⚠️ 415 | 416 | If API tools unavailable, skills use templates and validation-only workflows. 417 | 418 | --- 419 | 420 | ## Troubleshooting 421 | 422 | ### Skill Not Activating 423 | 424 | **Problem**: Skill doesn't activate when expected 425 | 426 | **Solution**: Rephrase query to match activation keywords 427 | ``` 428 | Instead of: "How do I use expressions?" 429 | Try: "How do I write n8n expressions with {{}} syntax?" 430 | ``` 431 | 432 | ### Wrong Skill Activates 433 | 434 | **Problem**: Different skill than expected activates 435 | 436 | **Solution**: This is usually fine! Skills complement each other. 437 | If needed, be more specific: 438 | ``` 439 | "Using n8n MCP tools, search for webhook node" 440 | ``` 441 | 442 | ### Multiple Skills Needed 443 | 444 | **Problem**: Need knowledge from multiple skills 445 | 446 | **Solution**: Ask a comprehensive question: 447 | ``` 448 | "Build, configure, and validate a webhook workflow with explanations" 449 | ``` 450 | 451 | All relevant skills will activate automatically. 452 | 453 | --- 454 | 455 | ## Advanced Usage 456 | 457 | ### Request Specific Tool Usage 458 | 459 | ``` 460 | "Use get_node_essentials to show me Slack node configuration" 461 | ``` 462 | 463 | ### Ask for Real Examples 464 | 465 | ``` 466 | "Show me real template examples of webhook workflows" 467 | ``` 468 | 469 | ### Request Step-by-Step 470 | 471 | ``` 472 | "Step by step: build a webhook to database workflow with validation at each step" 473 | ``` 474 | 475 | ### Debug with Skills 476 | 477 | ``` 478 | "My workflow fails validation. Debug it using validation expert knowledge." 479 | ``` 480 | 481 | --- 482 | 483 | ## Next Steps 484 | 485 | - **Getting Started**: Try example queries above 486 | - **Deep Dive**: Read individual SKILL.md files in skills/ 487 | - **Contribute**: See [DEVELOPMENT.md](DEVELOPMENT.md) 488 | 489 | --- 490 | 491 | ## Support 492 | 493 | - **Issues**: https://github.com/czlonkowski/n8n-skills/issues 494 | - **Discussions**: https://github.com/czlonkowski/n8n-skills/discussions 495 | 496 | --- 497 | 498 | **Ready to build amazing n8n workflows with Claude? Start asking questions!** 🚀 499 | 500 | --- 501 | 502 | Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en) 503 | -------------------------------------------------------------------------------- /evaluations/code-javascript/eval-001-webhook-body-gotcha.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "code-js-001", 3 | "skills": ["n8n-code-javascript"], 4 | "query": "I'm getting undefined when trying to access data from my webhook in a Code node. My code is: const name = $json.name; const email = $json.email; Why isn't this working?", 5 | "expected_behavior": [ 6 | "Activate n8n-code-javascript skill", 7 | "Explain that webhook data is nested under the .body property", 8 | "Show correct syntax: $json.body.name and $json.body.email", 9 | "Reference DATA_ACCESS.md for webhook structure details", 10 | "Mention this is the #1 most common mistake", 11 | "Optionally show alternative: const webhookData = $json.body; then access webhookData.name" 12 | ], 13 | "expected_content": [ 14 | "webhook data", 15 | ".body", 16 | "$json.body.name", 17 | "DATA_ACCESS.md" 18 | ], 19 | "priority": "high", 20 | "notes": "This is the MOST common mistake. Skill must clearly explain .body nesting." 21 | } 22 | -------------------------------------------------------------------------------- /evaluations/code-javascript/eval-002-return-format-error.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "code-js-002", 3 | "skills": ["n8n-code-javascript"], 4 | "query": "My Code node is showing an error: 'Return value must be an array of objects'. My code returns: return {json: {result: 'success', data: processedData}}; What's wrong?", 5 | "expected_behavior": [ 6 | "Activate n8n-code-javascript skill", 7 | "Explain the return format must be an ARRAY of objects", 8 | "Show correct syntax: return [{json: {result: 'success', data: processedData}}];", 9 | "Note the square brackets [] wrapping the object", 10 | "Reference ERROR_PATTERNS.md #3 for detailed explanation", 11 | "Show multiple items format as well", 12 | "Emphasize this is error #3 in top 5 errors (5% of failures)" 13 | ], 14 | "expected_content": [ 15 | "array", 16 | "[{json:", 17 | "ERROR_PATTERNS.md", 18 | "square brackets" 19 | ], 20 | "priority": "high", 21 | "notes": "Return format error is 5% of all failures. Must clearly show array wrapper requirement." 22 | } 23 | -------------------------------------------------------------------------------- /evaluations/code-javascript/eval-003-http-request.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "code-js-003", 3 | "skills": ["n8n-code-javascript"], 4 | "query": "How do I make an HTTP API call from inside a JavaScript Code node in n8n? I need to call an external API with authentication.", 5 | "expected_behavior": [ 6 | "Activate n8n-code-javascript skill", 7 | "Explain $helpers.httpRequest() built-in function", 8 | "Show complete example with method, url, headers", 9 | "Include authentication example (Bearer token or API key)", 10 | "Show try-catch error handling pattern", 11 | "Reference BUILTIN_FUNCTIONS.md for complete API reference", 12 | "Mention this is async, needs await", 13 | "Show both GET and POST examples if appropriate" 14 | ], 15 | "expected_content": [ 16 | "$helpers.httpRequest", 17 | "await", 18 | "headers", 19 | "Authorization", 20 | "BUILTIN_FUNCTIONS.md", 21 | "try-catch" 22 | ], 23 | "priority": "medium", 24 | "notes": "$helpers.httpRequest() is a key built-in function that many users need to learn." 25 | } 26 | -------------------------------------------------------------------------------- /evaluations/code-javascript/eval-004-aggregation-pattern.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "code-js-004", 3 | "skills": ["n8n-code-javascript"], 4 | "query": "I need to sum up all the 'amount' values from multiple items in my Code node. How do I access all items and calculate a total?", 5 | "expected_behavior": [ 6 | "Activate n8n-code-javascript skill", 7 | "Show $input.all() to get all items", 8 | "Demonstrate reduce() function for summing", 9 | "Include null handling (item.json.amount || 0)", 10 | "Show complete return format with result", 11 | "Reference COMMON_PATTERNS.md for aggregation patterns", 12 | "Reference DATA_ACCESS.md for $input.all() details", 13 | "Emphasize 'Run Once for All Items' mode", 14 | "Optionally show additional aggregations (count, average)" 15 | ], 16 | "expected_content": [ 17 | "$input.all()", 18 | "reduce", 19 | "COMMON_PATTERNS.md", 20 | "DATA_ACCESS.md", 21 | "All Items" 22 | ], 23 | "priority": "high", 24 | "notes": "Aggregation is a very common use case. Tests understanding of $input.all() and array methods." 25 | } 26 | -------------------------------------------------------------------------------- /evaluations/code-javascript/eval-005-expression-syntax-confusion.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "code-js-005", 3 | "skills": ["n8n-code-javascript"], 4 | "query": "I'm trying to access a field in my Code node but it's not working. My code is: const userName = '{{ $json.name }}'; I'm getting the literal string instead of the value. What am I doing wrong?", 5 | "expected_behavior": [ 6 | "Activate n8n-code-javascript skill", 7 | "Explain that {{ }} expression syntax does NOT work in Code nodes", 8 | "Clarify distinction: {{ }} is for OTHER nodes (Set, IF, HTTP Request)", 9 | "Show correct JavaScript syntax: const userName = $json.name;", 10 | "Show JavaScript template literals for string interpolation: `Hello ${$json.name}`", 11 | "Reference ERROR_PATTERNS.md #2 for detailed explanation", 12 | "Emphasize this is error #2 in top 5 errors (8% of failures)", 13 | "Provide comparison table of when to use expressions vs JavaScript" 14 | ], 15 | "expected_content": [ 16 | "{{ }}", 17 | "expression syntax", 18 | "JavaScript", 19 | "$json.name", 20 | "template literals", 21 | "ERROR_PATTERNS.md", 22 | "backticks" 23 | ], 24 | "priority": "high", 25 | "notes": "Expression syntax confusion is 8% of failures. Critical to understand Code nodes use JavaScript, not expressions." 26 | } 27 | -------------------------------------------------------------------------------- /evaluations/code-python/eval-001-module-import-error.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "code-python-001", 3 | "skill": "n8n-code-python", 4 | "name": "Module Import Error - External Libraries Not Available", 5 | "description": "Tests understanding that Python Code nodes have NO external libraries", 6 | "query": "I'm writing a Python Code node to fetch data from an API. Here's my code:\n\n```python\nimport requests\n\nurl = \"https://api.example.com/users\"\nresponse = requests.get(url)\ndata = response.json()\n\nreturn [{\"json\": data}]\n```\n\nBut I'm getting a ModuleNotFoundError. What's wrong?", 7 | "expected_behavior": [ 8 | "Immediately identify this is the #1 Python Code node limitation", 9 | "Explain that NO external libraries are available (no requests, pandas, numpy)", 10 | "Recommend using JavaScript Code node instead (95% recommendation)", 11 | "Suggest alternative: Use HTTP Request node BEFORE Python Code node", 12 | "Mention urllib.request from standard library as limited workaround", 13 | "Emphasize JavaScript has $helpers.httpRequest() built-in", 14 | "Reference ERROR_PATTERNS.md Error #1" 15 | ], 16 | "expected_output_includes": [ 17 | "ModuleNotFoundError", 18 | "NO external libraries", 19 | "Use JavaScript", 20 | "HTTP Request node", 21 | "standard library only" 22 | ], 23 | "should_not_include": [ 24 | "pip install", 25 | "install requests", 26 | "add requirements.txt" 27 | ] 28 | } 29 | -------------------------------------------------------------------------------- /evaluations/code-python/eval-002-dictionary-keyerror.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "code-python-002", 3 | "skill": "n8n-code-python", 4 | "name": "Dictionary KeyError - Use .get() Instead", 5 | "description": "Tests understanding of safe dictionary access with .get()", 6 | "query": "My Python Code node is failing with this error:\n\n```\nKeyError: 'email'\n```\n\nHere's my code:\n\n```python\nitem = _input.first()[\"json\"]\n\nname = item[\"name\"]\nemail = item[\"email\"]\nage = item[\"age\"]\n\nreturn [{\n \"json\": {\n \"name\": name,\n \"email\": email,\n \"age\": age\n }\n}]\n```\n\nHow do I fix this?", 7 | "expected_behavior": [ 8 | "Identify KeyError is from direct dictionary key access", 9 | "Explain that some items may not have 'email' field", 10 | "Recommend using .get() method with default values", 11 | "Show corrected code with .get()", 12 | "Mention this is Error #3 in ERROR_PATTERNS.md", 13 | "Explain difference between item['key'] and item.get('key', default)" 14 | ], 15 | "expected_output_includes": [ 16 | "KeyError", 17 | ".get()", 18 | "default value", 19 | "item.get(\"email\", \"default\")" 20 | ], 21 | "should_not_include": [ 22 | "try/except KeyError", 23 | "if 'email' in item" 24 | ], 25 | "correct_code_pattern": "item.get(\"email\", " 26 | } 27 | -------------------------------------------------------------------------------- /evaluations/code-python/eval-003-webhook-body-gotcha.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "code-python-003", 3 | "skill": "n8n-code-python", 4 | "name": "Webhook Body Gotcha - Data Under [\"body\"]", 5 | "description": "Tests understanding that webhook data is nested under [\"body\"] key", 6 | "query": "I have a Webhook node receiving this JSON:\n\n```json\n{\n \"name\": \"Alice\",\n \"email\": \"alice@example.com\",\n \"age\": 30\n}\n```\n\nIn my Python Code node, I'm trying to access the data:\n\n```python\ndata = _input.first()[\"json\"]\n\nname = data[\"name\"] # KeyError!\nemail = data[\"email\"] # KeyError!\n\nreturn [{\"json\": {\"name\": name, \"email\": email}}]\n```\n\nBut I'm getting KeyError. The webhook is receiving data correctly. What's wrong?", 7 | "expected_behavior": [ 8 | "Immediately recognize this is the webhook .body gotcha", 9 | "Explain webhook node wraps incoming data under 'body' key", 10 | "Show the actual structure with headers, params, query, body", 11 | "Provide corrected code accessing data[\"body\"]", 12 | "Mention this is a CRITICAL gotcha highlighted in DATA_ACCESS.md", 13 | "Recommend using .get() for safe access: data.get(\"body\", {})" 14 | ], 15 | "expected_output_includes": [ 16 | "[\"body\"]", 17 | "webhook wraps", 18 | "nested under body", 19 | "data.get(\"body\", {})" 20 | ], 21 | "correct_code_pattern": "data.get(\"body\", {})", 22 | "should_emphasize": "This is the MOST COMMON webhook mistake" 23 | } 24 | -------------------------------------------------------------------------------- /evaluations/code-python/eval-004-return-format-error.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "code-python-004", 3 | "skill": "n8n-code-python", 4 | "name": "Return Format Error - Must Return Array with json Key", 5 | "description": "Tests understanding of correct return format for n8n Code nodes", 6 | "query": "My Python Code node isn't outputting any data to the next node. Here's my code:\n\n```python\nall_items = _input.all()\n\ntotal = sum(item[\"json\"].get(\"amount\", 0) for item in all_items)\naverage = total / len(all_items) if all_items else 0\n\nreturn {\n \"total\": total,\n \"count\": len(all_items),\n \"average\": average\n}\n```\n\nThe code runs without errors, but the next node receives nothing. What's wrong?", 7 | "expected_behavior": [ 8 | "Identify incorrect return format (missing array wrapper and json key)", 9 | "Explain n8n expects array of objects with 'json' key", 10 | "Show corrected code with proper format: [{\"json\": {...}}]", 11 | "Mention this is Error #5 in ERROR_PATTERNS.md", 12 | "Emphasize: MUST return array, even for single result" 13 | ], 14 | "expected_output_includes": [ 15 | "[{\"json\":", 16 | "array", 17 | "return format", 18 | "must wrap" 19 | ], 20 | "correct_code_pattern": "return [{\"json\": {", 21 | "should_not_include": [ 22 | "return {", 23 | "return total" 24 | ] 25 | } 26 | -------------------------------------------------------------------------------- /evaluations/code-python/eval-005-standard-library-usage.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "code-python-005", 3 | "skill": "n8n-code-python", 4 | "name": "Standard Library Usage - Know What's Available", 5 | "description": "Tests knowledge of available standard library modules", 6 | "query": "I need to do the following in a Python Code node:\n\n1. Parse JSON from a string\n2. Calculate SHA256 hash of some data\n3. Format the current date as ISO string\n4. Extract email addresses using regex\n\nWhat modules are available? Can I use external libraries?", 7 | "expected_behavior": [ 8 | "Emphasize NO external libraries available", 9 | "List available standard library modules for these tasks", 10 | "json module for JSON parsing", 11 | "hashlib module for SHA256", 12 | "datetime module for dates", 13 | "re module for regex", 14 | "Provide code examples for each task", 15 | "Reference STANDARD_LIBRARY.md" 16 | ], 17 | "expected_output_includes": [ 18 | "import json", 19 | "import hashlib", 20 | "import datetime", 21 | "import re", 22 | "standard library only", 23 | "NO external libraries" 24 | ], 25 | "should_not_include": [ 26 | "import requests", 27 | "import pandas", 28 | "pip install" 29 | ], 30 | "correct_modules": [ 31 | "json", 32 | "hashlib", 33 | "datetime", 34 | "re" 35 | ] 36 | } 37 | -------------------------------------------------------------------------------- /evaluations/expression-syntax/eval-001-missing-braces.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "expr-001", 3 | "skills": ["n8n-expression-syntax"], 4 | "query": "I'm trying to access an email field in my n8n Slack node using $json.email but it's showing as literal text '$json.email' in the message. What's wrong?", 5 | "expected_behavior": [ 6 | "Identifies missing curly braces around the expression", 7 | "Explains that n8n expressions must be wrapped in {{ }}", 8 | "Provides the corrected expression: {{$json.email}}", 9 | "Explains that without braces, it's treated as literal text", 10 | "References expression format documentation from SKILL.md" 11 | ], 12 | "baseline_without_skill": { 13 | "likely_response": "May suggest general JavaScript or template syntax, might not know n8n-specific {{ }} requirement", 14 | "expected_quality": "Low - lacks n8n-specific knowledge about expression syntax" 15 | }, 16 | "with_skill_expected": { 17 | "response_quality": "High - precise fix with n8n-specific guidance", 18 | "uses_skill_content": true, 19 | "provides_correct_syntax": true, 20 | "explains_why_it_failed": true 21 | } 22 | } 23 | -------------------------------------------------------------------------------- /evaluations/expression-syntax/eval-002-webhook-body-data.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "expr-002", 3 | "skills": ["n8n-expression-syntax"], 4 | "query": "My webhook workflow is showing {{$json.name}} as undefined even though I'm sending {\"name\": \"John\"} in the webhook POST request. What am I doing wrong?", 5 | "expected_behavior": [ 6 | "Identifies that webhook data is nested under .body property", 7 | "Explains the webhook node output structure", 8 | "Provides the corrected expression: {{$json.body.name}}", 9 | "Shows the complete webhook data structure with headers, params, query, and body", 10 | "Emphasizes this is a CRITICAL gotcha specific to webhook nodes" 11 | ], 12 | "baseline_without_skill": { 13 | "likely_response": "May suggest debugging or checking data format, unlikely to know webhook-specific structure", 14 | "expected_quality": "Low - would miss the webhook .body nesting" 15 | }, 16 | "with_skill_expected": { 17 | "response_quality": "High - identifies webhook-specific issue immediately", 18 | "uses_skill_content": true, 19 | "provides_correct_syntax": true, 20 | "explains_webhook_structure": true, 21 | "warns_about_common_gotcha": true 22 | } 23 | } 24 | -------------------------------------------------------------------------------- /evaluations/expression-syntax/eval-003-code-node-confusion.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "expr-003", 3 | "skills": ["n8n-expression-syntax"], 4 | "query": "I'm trying to use {{$json.email}} in my Code node to get the email address, but it's not working. The code shows the literal string '{{$json.email}}' instead of the value. How do I fix this?", 5 | "expected_behavior": [ 6 | "Identifies that Code nodes use direct JavaScript access, NOT expressions", 7 | "Explains that {{ }} syntax is NOT used inside Code nodes", 8 | "Provides the corrected Code node syntax: $json.email or $input.item.json.email", 9 | "Explains when NOT to use expressions (Code nodes, Function nodes)", 10 | "References Code node guide or documentation" 11 | ], 12 | "baseline_without_skill": { 13 | "likely_response": "May suggest template literal syntax or string interpolation, unlikely to know n8n Code node specifics", 14 | "expected_quality": "Low - would not understand Code node vs expression node difference" 15 | }, 16 | "with_skill_expected": { 17 | "response_quality": "High - immediately identifies Code node vs expression context", 18 | "uses_skill_content": true, 19 | "provides_correct_code_syntax": true, 20 | "explains_when_not_to_use_expressions": true, 21 | "clear_distinction_between_contexts": true 22 | } 23 | } 24 | -------------------------------------------------------------------------------- /evaluations/expression-syntax/eval-004-node-reference.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "expr-004", 3 | "skills": ["n8n-expression-syntax"], 4 | "query": "How do I reference data from my 'HTTP Request' node in a later Slack node? I need to access the response data.", 5 | "expected_behavior": [ 6 | "Provides correct $node syntax with quotes around node name", 7 | "Shows example: {{$node[\"HTTP Request\"].json.fieldName}}", 8 | "Explains that node names with spaces require bracket notation and quotes", 9 | "Warns that node names are case-sensitive and must match exactly", 10 | "Provides multiple examples from real workflows" 11 | ], 12 | "baseline_without_skill": { 13 | "likely_response": "May suggest generic data passing or variable references, might not know n8n $node syntax", 14 | "expected_quality": "Medium - might guess at syntax but miss specifics like quotes and case sensitivity" 15 | }, 16 | "with_skill_expected": { 17 | "response_quality": "High - precise $node syntax with proper quoting", 18 | "uses_skill_content": true, 19 | "provides_correct_syntax": true, 20 | "explains_case_sensitivity": true, 21 | "shows_multiple_examples": true 22 | } 23 | } 24 | -------------------------------------------------------------------------------- /evaluations/mcp-tools/eval-001-tool-selection.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "mcp-001", 3 | "skills": ["n8n-mcp-tools-expert"], 4 | "query": "I need to find a node that can send messages to Slack. Which n8n-mcp tool should I use and how?", 5 | "expected_behavior": [ 6 | "Recommends search_nodes as the starting tool", 7 | "Provides correct syntax: search_nodes({query: 'slack'})", 8 | "Explains the nodeType format returned (nodes-base.slack)", 9 | "Suggests following up with get_node_essentials for configuration details", 10 | "References the search → essentials workflow pattern", 11 | "Mentions the tool is <20ms fast" 12 | ], 13 | "baseline_without_skill": { 14 | "likely_response": "May suggest searching documentation or using generic search, unlikely to know specific MCP tool names and syntax", 15 | "expected_quality": "Low - would not know n8n-mcp specific tools" 16 | }, 17 | "with_skill_expected": { 18 | "response_quality": "High - precise tool recommendation with syntax", 19 | "uses_skill_content": true, 20 | "provides_correct_tool": true, 21 | "shows_proper_workflow": true, 22 | "explains_nodeType_format": true 23 | } 24 | } 25 | -------------------------------------------------------------------------------- /evaluations/mcp-tools/eval-002-nodetype-format.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "mcp-002", 3 | "skills": ["n8n-mcp-tools-expert"], 4 | "query": "I'm getting 'node not found' errors when calling get_node_essentials. I'm using 'slack' as the nodeType. What's wrong?", 5 | "expected_behavior": [ 6 | "Identifies incorrect nodeType format", 7 | "Explains need for prefix: 'nodes-base.slack' not just 'slack'", 8 | "Distinguishes between nodeType (nodes-base.*) and workflowNodeType (n8n-nodes-base.*)", 9 | "Provides correct syntax: get_node_essentials({nodeType: 'nodes-base.slack'})", 10 | "References nodeType format documentation from SKILL.md", 11 | "Warns about common format confusion" 12 | ], 13 | "baseline_without_skill": { 14 | "likely_response": "May suggest checking spelling or tool availability, unlikely to know specific prefix requirements", 15 | "expected_quality": "Low - would not understand nodeType format nuances" 16 | }, 17 | "with_skill_expected": { 18 | "response_quality": "High - immediately identifies format issue", 19 | "uses_skill_content": true, 20 | "provides_correct_format": true, 21 | "explains_prefix_difference": true, 22 | "gives_working_example": true 23 | } 24 | } 25 | -------------------------------------------------------------------------------- /evaluations/mcp-tools/eval-003-validation-workflow.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "mcp-003", 3 | "skills": ["n8n-mcp-tools-expert"], 4 | "query": "I've created a Slack node configuration and want to make sure it's valid before deploying. Walk me through the validation process using n8n-mcp tools.", 5 | "expected_behavior": [ 6 | "Recommends validate_node_operation tool", 7 | "Explains validation profiles (minimal, runtime, ai-friendly, strict)", 8 | "Recommends 'runtime' profile for pre-deployment", 9 | "Shows complete validation syntax with all parameters", 10 | "Explains validation loop pattern (validate → fix → validate again)", 11 | "References VALIDATION_GUIDE.md", 12 | "Mentions 23s avg thinking time, 58s avg fixing time from telemetry" 13 | ], 14 | "baseline_without_skill": { 15 | "likely_response": "May suggest testing the workflow or checking documentation, unlikely to know validation tools and profiles", 16 | "expected_quality": "Medium - might guess at validation but miss profile options" 17 | }, 18 | "with_skill_expected": { 19 | "response_quality": "High - complete validation workflow with profiles", 20 | "uses_skill_content": true, 21 | "recommends_correct_profile": true, 22 | "shows_validation_loop": true, 23 | "explains_error_handling": true 24 | } 25 | } 26 | -------------------------------------------------------------------------------- /evaluations/mcp-tools/eval-004-essentials-vs-info.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "mcp-004", 3 | "skills": ["n8n-mcp-tools-expert"], 4 | "query": "Should I use get_node_info or get_node_essentials to understand how to configure a node? What's the difference?", 5 | "expected_behavior": [ 6 | "Strongly recommends get_node_essentials for most cases", 7 | "Explains size difference (5KB vs 100KB+)", 8 | "Explains success rate difference (91.7% vs 80%)", 9 | "Lists when to use get_node_info (debugging complex issues, need full schema)", 10 | "Provides performance comparison (<10ms vs slower)", 11 | "References the 20% failure rate for get_node_info", 12 | "Shows examples of both tool calls" 13 | ], 14 | "baseline_without_skill": { 15 | "likely_response": "May assume more data is better, unlikely to know performance and reliability differences", 16 | "expected_quality": "Low - would not understand the critical difference" 17 | }, 18 | "with_skill_expected": { 19 | "response_quality": "High - clear recommendation with data-driven reasoning", 20 | "uses_skill_content": true, 21 | "recommends_essentials": true, 22 | "explains_trade_offs": true, 23 | "provides_both_examples": true 24 | } 25 | } 26 | -------------------------------------------------------------------------------- /evaluations/mcp-tools/eval-005-smart-parameters.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "mcp-005", 3 | "skills": ["n8n-mcp-tools-expert"], 4 | "query": "I'm using n8n_update_partial_workflow to connect an IF node to two different handlers. How do I specify which branch (true or false) each connection should use?", 5 | "expected_behavior": [ 6 | "Explains smart parameters for multi-output nodes", 7 | "Shows branch parameter: branch='true' or branch='false'", 8 | "Provides complete example with addConnection operation", 9 | "Explains this is simpler than using sourceIndex manually", 10 | "Mentions Switch nodes use case=N parameter", 11 | "References WORKFLOW_GUIDE.md for more details", 12 | "Shows both true and false branch connections" 13 | ], 14 | "baseline_without_skill": { 15 | "likely_response": "May suggest using output indices without knowing semantic parameters exist", 16 | "expected_quality": "Medium - might work but miss the easier smart parameter approach" 17 | }, 18 | "with_skill_expected": { 19 | "response_quality": "High - teaches smart parameters for cleaner code", 20 | "uses_skill_content": true, 21 | "shows_branch_parameter": true, 22 | "provides_working_example": true, 23 | "mentions_switch_equivalent": true 24 | } 25 | } 26 | -------------------------------------------------------------------------------- /evaluations/node-configuration/eval-001-property-dependencies.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "node-config-001", 3 | "skills": ["n8n-node-configuration"], 4 | "query": "I'm configuring an HTTP Request node with method=POST. What other fields become required or visible when I set this?", 5 | "expected_behavior": [ 6 | "Explains property dependencies (displayOptions)", 7 | "Identifies that sendBody becomes visible for POST", 8 | "Explains that body becomes required when sendBody=true", 9 | "Suggests using get_property_dependencies to see all dependencies", 10 | "Provides guidance on checking conditional requirements", 11 | "May reference DEPENDENCIES.md for detailed dependency rules" 12 | ] 13 | } 14 | -------------------------------------------------------------------------------- /evaluations/node-configuration/eval-002-operation-specific-config.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "node-config-002", 3 | "skills": ["n8n-node-configuration"], 4 | "query": "How do I configure a Slack node to post a message? What fields are required for this specific operation?", 5 | "expected_behavior": [ 6 | "Identifies need to set resource='message' and operation='post'", 7 | "Explains operation-specific required fields (channel, text)", 8 | "Suggests using get_node_essentials with operation context", 9 | "Provides example configuration for this operation", 10 | "May reference OPERATION_PATTERNS.md for Slack patterns", 11 | "Explains that different operations have different requirements" 12 | ] 13 | } 14 | -------------------------------------------------------------------------------- /evaluations/node-configuration/eval-003-conditional-fields.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "node-config-003", 3 | "skills": ["n8n-node-configuration"], 4 | "query": "My IF node configuration is valid with operation='equals', but when I change to operation='isEmpty', validation fails. Why?", 5 | "expected_behavior": [ 6 | "Explains that isEmpty is a unary operator (single value)", 7 | "Identifies that value2 is not needed for unary operators", 8 | "Explains singleValue property dependency", 9 | "Mentions auto-sanitization will fix operator structure", 10 | "Suggests using get_property_dependencies to understand operator rules", 11 | "May reference DEPENDENCIES.md for operator-specific dependencies" 12 | ] 13 | } 14 | -------------------------------------------------------------------------------- /evaluations/node-configuration/eval-004-essentials-vs-info.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "node-config-004", 3 | "skills": ["n8n-node-configuration"], 4 | "query": "Should I use get_node_essentials or get_node_info when configuring a new node? What's the difference?", 5 | "expected_behavior": [ 6 | "Recommends get_node_essentials for configuration (91.7% success rate)", 7 | "Explains essentials provides required fields and options", 8 | "Explains get_node_info provides full schema (use when essentials insufficient)", 9 | "Suggests starting with essentials, escalate to info if needed", 10 | "May provide telemetry insight (essentials used 9,835 times)", 11 | "References progressive disclosure approach" 12 | ] 13 | } 14 | -------------------------------------------------------------------------------- /evaluations/validation-expert/eval-001-missing-required-field.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "validation-001", 3 | "skills": ["n8n-validation-expert"], 4 | "query": "I'm getting a validation error: 'Missing required field: channel'. What does this mean and how do I fix it?", 5 | "expected_behavior": [ 6 | "Identifies this as a 'missing_required' error type", 7 | "Explains that the node configuration is incomplete", 8 | "Provides guidance on finding what value to provide", 9 | "Suggests using get_node_essentials to see required fields", 10 | "Explains where to add the missing field in the node configuration", 11 | "May reference ERROR_CATALOG.md for details" 12 | ] 13 | } 14 | -------------------------------------------------------------------------------- /evaluations/validation-expert/eval-002-false-positive.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "validation-002", 3 | "skills": ["n8n-validation-expert"], 4 | "query": "Validation is warning me about 'best_practice' issues like error handling and retries. Do I need to fix these?", 5 | "expected_behavior": [ 6 | "Identifies these as warnings, not errors", 7 | "Explains difference between errors (must fix) and warnings (should fix)", 8 | "Discusses when warnings can be acceptable (false positives)", 9 | "References FALSE_POSITIVES.md", 10 | "Suggests using 'ai-friendly' validation profile to reduce false positives", 11 | "Explains that warnings don't prevent workflow activation", 12 | "Provides guidance on when to address warnings vs when to accept them" 13 | ] 14 | } 15 | -------------------------------------------------------------------------------- /evaluations/validation-expert/eval-003-auto-sanitization.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "validation-003", 3 | "skills": ["n8n-validation-expert"], 4 | "query": "I'm getting an error about 'Binary operator cannot have singleValue property'. What does this mean?", 5 | "expected_behavior": [ 6 | "Identifies this as an operator structure issue", 7 | "Explains auto-sanitization system", 8 | "States that this error will be automatically fixed on next workflow update", 9 | "Explains binary vs unary operator distinction", 10 | "References the auto-sanitization section", 11 | "Suggests that user doesn't need to manually fix this", 12 | "May suggest running n8n_update_partial_workflow or validate_workflow to trigger auto-fix" 13 | ] 14 | } 15 | -------------------------------------------------------------------------------- /evaluations/validation-expert/eval-004-validation-loop.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "validation-004", 3 | "skills": ["n8n-validation-expert"], 4 | "query": "I fixed one validation error but now I'm getting a different one. How do I systematically fix all validation errors?", 5 | "expected_behavior": [ 6 | "Explains the validation loop pattern", 7 | "References telemetry data (7,841 validate → fix cycles, avg 23s thinking + 58s fixing)", 8 | "Provides step-by-step process: validate → read errors → fix → validate again", 9 | "Emphasizes iterative approach", 10 | "Suggests fixing errors one at a time", 11 | "May recommend validate_node_operation for individual nodes", 12 | "Explains that this is normal workflow (not a problem)" 13 | ] 14 | } 15 | -------------------------------------------------------------------------------- /evaluations/workflow-patterns/eval-001-webhook-workflow.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "pattern-001", 3 | "skills": ["n8n-workflow-patterns"], 4 | "query": "I need to build a workflow that receives webhook data and sends it to Slack. What's the best way to structure this?", 5 | "expected_behavior": [ 6 | "Identifies this as a Webhook Processing pattern", 7 | "References the webhook_processing.md pattern file", 8 | "Explains the basic structure: Webhook → Transform → Output", 9 | "Mentions data is nested under $json.body for webhook payloads", 10 | "Suggests validation and error handling", 11 | "May reference real template examples", 12 | "Provides checklist: trigger, validation, transformation, output, error handling" 13 | ] 14 | } 15 | -------------------------------------------------------------------------------- /evaluations/workflow-patterns/eval-002-http-api-workflow.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "pattern-002", 3 | "skills": ["n8n-workflow-patterns"], 4 | "query": "I want to fetch data from a REST API, transform it, and store it in my database. How should I structure this workflow?", 5 | "expected_behavior": [ 6 | "Identifies this as an HTTP API Integration pattern", 7 | "References the http_api_integration.md pattern file", 8 | "Explains the structure: Trigger → HTTP Request → Transform → Database → Error Handler", 9 | "Discusses authentication handling (credentials)", 10 | "Mentions pagination for large datasets", 11 | "Suggests retry logic for API failures", 12 | "Provides guidance on response parsing and data mapping" 13 | ] 14 | } 15 | -------------------------------------------------------------------------------- /evaluations/workflow-patterns/eval-003-database-sync.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "pattern-003", 3 | "skills": ["n8n-workflow-patterns"], 4 | "query": "How do I build a workflow that syncs data between two databases? I need to read from Postgres and write to MySQL.", 5 | "expected_behavior": [ 6 | "Identifies this as a Database Operations pattern", 7 | "References the database_operations.md pattern file", 8 | "Explains the structure: Schedule/Trigger → Read DB → Transform → Write DB → Error Handler", 9 | "Discusses batch processing for large datasets", 10 | "Mentions transaction handling and rollback considerations", 11 | "Suggests incremental sync strategies (last_modified timestamps)", 12 | "Warns about connection pooling and performance", 13 | "Provides guidance on data type mapping between databases" 14 | ] 15 | } 16 | -------------------------------------------------------------------------------- /evaluations/workflow-patterns/eval-004-ai-agent.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "pattern-004", 3 | "skills": ["n8n-workflow-patterns"], 4 | "query": "I want to build an AI agent that can use tools to answer questions. What's the recommended workflow pattern?", 5 | "expected_behavior": [ 6 | "Identifies this as an AI Agent Workflow pattern", 7 | "References the ai_agent_workflow.md pattern file", 8 | "Explains the structure: Trigger → AI Agent (with Language Model + Tools + Memory)", 9 | "Discusses the 8 AI connection types (ai_languageModel, ai_tool, ai_memory, etc.)", 10 | "Mentions that ANY node can be an AI tool (connected via ai_tool port)", 11 | "Suggests memory integration for conversation context", 12 | "Provides guidance on tool configuration and result handling", 13 | "May mention langchain package nodes" 14 | ] 15 | } 16 | -------------------------------------------------------------------------------- /evaluations/workflow-patterns/eval-005-scheduled-report.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "pattern-005", 3 | "skills": ["n8n-workflow-patterns"], 4 | "query": "I need to generate a daily report that fetches analytics data and emails it to my team. What's the best workflow structure?", 5 | "expected_behavior": [ 6 | "Identifies this as a Scheduled Tasks pattern", 7 | "References the scheduled_tasks.md pattern file", 8 | "Explains the structure: Schedule Trigger → Fetch Data → Transform/Aggregate → Format Report → Send Email", 9 | "Discusses cron expression configuration", 10 | "Mentions timezone considerations", 11 | "Suggests error handling and failure notifications", 12 | "Provides guidance on data aggregation and report formatting", 13 | "May suggest using templates for consistent report structure" 14 | ] 15 | } 16 | -------------------------------------------------------------------------------- /skills/n8n-code-javascript/README.md: -------------------------------------------------------------------------------- 1 | # n8n Code JavaScript 2 | 3 | Expert guidance for writing JavaScript code in n8n Code nodes. 4 | 5 | --- 6 | 7 | ## Purpose 8 | 9 | Teaches how to write effective JavaScript in n8n Code nodes, avoid common errors, and use built-in functions effectively. 10 | 11 | --- 12 | 13 | ## Activates On 14 | 15 | **Trigger keywords**: 16 | - "javascript code node" 17 | - "write javascript in n8n" 18 | - "code node javascript" 19 | - "$input syntax" 20 | - "$json syntax" 21 | - "$helpers.httpRequest" 22 | - "DateTime luxon" 23 | - "code node error" 24 | - "webhook data code" 25 | - "return format code node" 26 | 27 | **Common scenarios**: 28 | - Writing JavaScript code in Code nodes 29 | - Troubleshooting Code node errors 30 | - Making HTTP requests from code 31 | - Working with dates and times 32 | - Accessing webhook data 33 | - Choosing between All Items and Each Item mode 34 | 35 | --- 36 | 37 | ## What You'll Learn 38 | 39 | ### Quick Start 40 | - Mode selection (All Items vs Each Item) 41 | - Data access patterns ($input.all(), $input.first(), $input.item) 42 | - Correct return format: `[{json: {...}}]` 43 | - Webhook data structure (.body nesting) 44 | - Built-in functions overview 45 | 46 | ### Data Access Mastery 47 | - $input.all() - Batch operations (most common) 48 | - $input.first() - Single item operations 49 | - $input.item - Each Item mode processing 50 | - $node - Reference other workflow nodes 51 | - **Critical gotcha**: Webhook data under `.body` 52 | 53 | ### Common Patterns (Production-Tested) 54 | 1. Multi-source Data Aggregation 55 | 2. Regex Filtering & Pattern Matching 56 | 3. Markdown Parsing & Structured Extraction 57 | 4. JSON Comparison & Validation 58 | 5. CRM Data Transformation 59 | 6. Release Information Processing 60 | 7. Array Transformation with Context 61 | 8. Slack Block Kit Formatting 62 | 9. Top N Filtering & Ranking 63 | 10. String Aggregation & Reporting 64 | 65 | ### Error Prevention 66 | Top 5 errors to avoid: 67 | 1. **Empty code / missing return** (38% of failures) 68 | 2. **Expression syntax confusion** (using `{{}}` in code) 69 | 3. **Incorrect return format** (missing array wrapper or json property) 70 | 4. **Unmatched brackets** (string escaping issues) 71 | 5. **Missing null checks** (crashes on undefined) 72 | 73 | ### Built-in Functions 74 | - **$helpers.httpRequest()** - Make HTTP requests 75 | - **DateTime (Luxon)** - Advanced date/time operations 76 | - **$jmespath()** - Query JSON structures 77 | - **$getWorkflowStaticData()** - Persistent storage 78 | - Standard JavaScript globals (Math, JSON, console) 79 | - Available Node.js modules (crypto, Buffer, URL) 80 | 81 | --- 82 | 83 | ## File Structure 84 | 85 | ``` 86 | n8n-code-javascript/ 87 | ├── SKILL.md (500 lines) 88 | │ Overview, quick start, mode selection, best practices 89 | │ - Mode selection guide (All Items vs Each Item) 90 | │ - Data access patterns overview 91 | │ - Return format requirements 92 | │ - Critical webhook gotcha 93 | │ - Error prevention overview 94 | │ - Quick reference checklist 95 | │ 96 | ├── DATA_ACCESS.md (400 lines) 97 | │ Complete data access patterns 98 | │ - $input.all() - Most common (26% usage) 99 | │ - $input.first() - Very common (25% usage) 100 | │ - $input.item - Each Item mode (19% usage) 101 | │ - $node - Reference other nodes 102 | │ - Webhook data structure (.body nesting) 103 | │ - Choosing the right pattern 104 | │ - Common mistakes to avoid 105 | │ 106 | ├── COMMON_PATTERNS.md (600 lines) 107 | │ 10 production-tested patterns 108 | │ - Pattern 1: Multi-source Aggregation 109 | │ - Pattern 2: Regex Filtering 110 | │ - Pattern 3: Markdown Parsing 111 | │ - Pattern 4: JSON Comparison 112 | │ - Pattern 5: CRM Transformation 113 | │ - Pattern 6: Release Processing 114 | │ - Pattern 7: Array Transformation 115 | │ - Pattern 8: Slack Block Kit 116 | │ - Pattern 9: Top N Filtering 117 | │ - Pattern 10: String Aggregation 118 | │ - Pattern selection guide 119 | │ 120 | ├── ERROR_PATTERNS.md (450 lines) 121 | │ Top 5 errors with solutions 122 | │ - Error #1: Empty Code / Missing Return (38%) 123 | │ - Error #2: Expression Syntax Confusion (8%) 124 | │ - Error #3: Incorrect Return Wrapper (5%) 125 | │ - Error #4: Unmatched Brackets (6%) 126 | │ - Error #5: Missing Null Checks 127 | │ - Error prevention checklist 128 | │ - Quick error reference 129 | │ - Debugging tips 130 | │ 131 | ├── BUILTIN_FUNCTIONS.md (450 lines) 132 | │ Complete built-in function reference 133 | │ - $helpers.httpRequest() API reference 134 | │ - DateTime (Luxon) complete guide 135 | │ - $jmespath() JSON querying 136 | │ - $getWorkflowStaticData() persistent storage 137 | │ - Standard JavaScript globals 138 | │ - Available Node.js modules 139 | │ - What's NOT available 140 | │ 141 | └── README.md (this file) 142 | Skill metadata and overview 143 | ``` 144 | 145 | **Total**: ~2,400 lines across 6 files 146 | 147 | --- 148 | 149 | ## Coverage 150 | 151 | ### Mode Selection 152 | - **Run Once for All Items** - Recommended for 95% of use cases 153 | - **Run Once for Each Item** - Specialized cases only 154 | - Decision guide and performance implications 155 | 156 | ### Data Access 157 | - Most common patterns with usage statistics 158 | - Webhook data structure (critical .body gotcha) 159 | - Safe access patterns with null checks 160 | - When to use which pattern 161 | 162 | ### Error Prevention 163 | - Top 5 errors covering 62%+ of all failures 164 | - Clear wrong vs right examples 165 | - Error prevention checklist 166 | - Debugging tips and console.log usage 167 | 168 | ### Production Patterns 169 | - 10 patterns from real workflows 170 | - Complete working examples 171 | - Use cases and key techniques 172 | - Pattern selection guide 173 | 174 | ### Built-in Functions 175 | - Complete $helpers.httpRequest() reference 176 | - DateTime/Luxon operations (formatting, parsing, arithmetic) 177 | - $jmespath() for JSON queries 178 | - Persistent storage with $getWorkflowStaticData() 179 | - Standard JavaScript and Node.js modules 180 | 181 | --- 182 | 183 | ## Critical Gotchas Highlighted 184 | 185 | ### #1: Webhook Data Structure 186 | **MOST COMMON MISTAKE**: Webhook data is under `.body` 187 | 188 | ```javascript 189 | // ❌ WRONG 190 | const name = $json.name; 191 | 192 | // ✅ CORRECT 193 | const name = $json.body.name; 194 | ``` 195 | 196 | ### #2: Return Format 197 | **CRITICAL**: Must return array with json property 198 | 199 | ```javascript 200 | // ❌ WRONG 201 | return {json: {result: 'success'}}; 202 | 203 | // ✅ CORRECT 204 | return [{json: {result: 'success'}}]; 205 | ``` 206 | 207 | ### #3: Expression Syntax 208 | **Don't use `{{}}` in Code nodes** 209 | 210 | ```javascript 211 | // ❌ WRONG 212 | const value = "{{ $json.field }}"; 213 | 214 | // ✅ CORRECT 215 | const value = $json.field; 216 | ``` 217 | 218 | --- 219 | 220 | ## Integration with Other Skills 221 | 222 | ### n8n Expression Syntax 223 | - **Distinction**: Expressions use `{{}}` in OTHER nodes 224 | - **Code nodes**: Use JavaScript directly (no `{{}}`) 225 | - **When to use each**: Code vs expressions decision guide 226 | 227 | ### n8n MCP Tools Expert 228 | - Find Code node: `search_nodes({query: "code"})` 229 | - Get configuration: `get_node_essentials("nodes-base.code")` 230 | - Validate code: `validate_node_operation()` 231 | 232 | ### n8n Node Configuration 233 | - Mode selection (All Items vs Each Item) 234 | - Language selection (JavaScript vs Python) 235 | - Understanding property dependencies 236 | 237 | ### n8n Workflow Patterns 238 | - Code nodes in transformation step 239 | - Webhook → Code → API pattern 240 | - Error handling in workflows 241 | 242 | ### n8n Validation Expert 243 | - Validate Code node configuration 244 | - Handle validation errors 245 | - Auto-fix common issues 246 | 247 | --- 248 | 249 | ## When to Use Code Node 250 | 251 | **Use Code node when:** 252 | - ✅ Complex transformations requiring multiple steps 253 | - ✅ Custom calculations or business logic 254 | - ✅ Recursive operations 255 | - ✅ API response parsing with complex structure 256 | - ✅ Multi-step conditionals 257 | - ✅ Data aggregation across items 258 | 259 | **Consider other nodes when:** 260 | - ❌ Simple field mapping → Use **Set** node 261 | - ❌ Basic filtering → Use **Filter** node 262 | - ❌ Simple conditionals → Use **IF** or **Switch** node 263 | - ❌ HTTP requests only → Use **HTTP Request** node 264 | 265 | **Code node excels at**: Complex logic that would require chaining many simple nodes 266 | 267 | --- 268 | 269 | ## Success Metrics 270 | 271 | **Before this skill**: 272 | - Users confused by mode selection 273 | - Frequent return format errors 274 | - Expression syntax mistakes 275 | - Webhook data access failures 276 | - Missing null check crashes 277 | 278 | **After this skill**: 279 | - Clear mode selection guidance 280 | - Understanding of return format 281 | - JavaScript vs expression distinction 282 | - Correct webhook data access 283 | - Safe null-handling patterns 284 | - Production-ready code patterns 285 | 286 | --- 287 | 288 | ## Quick Reference 289 | 290 | ### Essential Rules 291 | 1. Choose "All Items" mode (recommended) 292 | 2. Access data: `$input.all()`, `$input.first()`, `$input.item` 293 | 3. **MUST return**: `[{json: {...}}]` format 294 | 4. **Webhook data**: Under `.body` property 295 | 5. **No `{{}}` syntax**: Use JavaScript directly 296 | 297 | ### Most Common Patterns 298 | - Batch processing → $input.all() + map/filter 299 | - Single item → $input.first() 300 | - Aggregation → reduce() 301 | - HTTP requests → $helpers.httpRequest() 302 | - Date handling → DateTime (Luxon) 303 | 304 | ### Error Prevention 305 | - Always return data 306 | - Check for null/undefined 307 | - Use try-catch for risky operations 308 | - Test with empty input 309 | - Use console.log() for debugging 310 | 311 | --- 312 | 313 | ## Related Documentation 314 | 315 | - **n8n Code Node Guide**: https://docs.n8n.io/code/code-node/ 316 | - **Built-in Methods Reference**: https://docs.n8n.io/code-examples/methods-variables-reference/ 317 | - **Luxon Documentation**: https://moment.github.io/luxon/ 318 | 319 | --- 320 | 321 | ## Evaluations 322 | 323 | **5 test scenarios** covering: 324 | 1. Webhook body gotcha (most common mistake) 325 | 2. Return format error (missing array wrapper) 326 | 3. HTTP request with $helpers.httpRequest() 327 | 4. Aggregation pattern with $input.all() 328 | 5. Expression syntax confusion (using `{{}}`) 329 | 330 | Each evaluation tests skill activation, correct guidance, and reference to appropriate documentation files. 331 | 332 | --- 333 | 334 | ## Version History 335 | 336 | - **v1.0** (2025-01-20): Initial implementation 337 | - SKILL.md with comprehensive overview 338 | - DATA_ACCESS.md covering all access patterns 339 | - COMMON_PATTERNS.md with 10 production patterns 340 | - ERROR_PATTERNS.md covering top 5 errors 341 | - BUILTIN_FUNCTIONS.md complete reference 342 | - 5 evaluation scenarios 343 | 344 | --- 345 | 346 | ## Author 347 | 348 | Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en) 349 | 350 | Part of the n8n-skills collection. 351 | -------------------------------------------------------------------------------- /skills/n8n-code-python/README.md: -------------------------------------------------------------------------------- 1 | # n8n Code Python Skill 2 | 3 | Expert guidance for writing Python code in n8n Code nodes. 4 | 5 | --- 6 | 7 | ## ⚠️ Important: JavaScript First 8 | 9 | **Use JavaScript for 95% of use cases.** 10 | 11 | Python in n8n has **NO external libraries** (no requests, pandas, numpy). 12 | 13 | **When to use Python**: 14 | - You have complex Python-specific logic 15 | - You need Python's standard library features 16 | - You're more comfortable with Python than JavaScript 17 | 18 | **When to use JavaScript** (recommended): 19 | - HTTP requests ($helpers.httpRequest available) 20 | - Date/time operations (Luxon library included) 21 | - Most data transformations 22 | - When in doubt 23 | 24 | --- 25 | 26 | ## What This Skill Teaches 27 | 28 | ### Core Concepts 29 | 30 | 1. **Critical Limitation**: No external libraries 31 | 2. **Data Access**: `_input.all()`, `_input.first()`, `_input.item` 32 | 3. **Webhook Gotcha**: Data is under `_json["body"]` 33 | 4. **Return Format**: Must return `[{"json": {...}}]` 34 | 5. **Standard Library**: json, datetime, re, base64, hashlib, etc. 35 | 36 | ### Top 5 Error Prevention 37 | 38 | This skill emphasizes **error prevention**: 39 | 40 | 1. **ModuleNotFoundError** (trying to import external libraries) 41 | 2. **Empty code / missing return** 42 | 3. **KeyError** (dictionary access without .get()) 43 | 4. **IndexError** (list access without bounds checking) 44 | 5. **Incorrect return format** 45 | 46 | These 5 errors are the most common in Python Code nodes. 47 | 48 | --- 49 | 50 | ## Skill Activation 51 | 52 | This skill activates when you: 53 | - Write Python in Code nodes 54 | - Ask about Python limitations 55 | - Need to know available standard library 56 | - Troubleshoot Python Code node errors 57 | - Work with Python data structures 58 | 59 | **Example queries**: 60 | - "Can I use pandas in Python Code node?" 61 | - "How do I access webhook data in Python?" 62 | - "What Python libraries are available?" 63 | - "Write Python code to process JSON" 64 | - "Why is requests module not found?" 65 | 66 | --- 67 | 68 | ## File Structure 69 | 70 | ### SKILL.md (719 lines) 71 | **Quick start** and overview 72 | - When to use Python vs JavaScript 73 | - Critical limitation (no external libraries) 74 | - Mode selection (All Items vs Each Item) 75 | - Data access overview 76 | - Return format requirements 77 | - Standard library overview 78 | 79 | ### DATA_ACCESS.md (703 lines) 80 | **Complete data access patterns** 81 | - `_input.all()` - Process all items 82 | - `_input.first()` - Get first item 83 | - `_input.item` - Current item (Each Item mode) 84 | - `_node["Name"]` - Reference other nodes 85 | - Webhook body structure (critical gotcha!) 86 | - Pattern selection guide 87 | 88 | ### STANDARD_LIBRARY.md (850 lines) 89 | **Available Python modules** 90 | - json - JSON parsing 91 | - datetime - Date/time operations 92 | - re - Regular expressions 93 | - base64 - Encoding/decoding 94 | - hashlib - Hashing 95 | - urllib.parse - URL operations 96 | - math, random, statistics 97 | - What's NOT available (requests, pandas, numpy) 98 | - Workarounds for missing libraries 99 | 100 | ### COMMON_PATTERNS.md (895 lines) 101 | **10 production-tested patterns** 102 | 1. Multi-source data aggregation 103 | 2. Regex-based filtering 104 | 3. Markdown to structured data 105 | 4. JSON object comparison 106 | 5. CRM data transformation 107 | 6. Release notes processing 108 | 7. Array transformation 109 | 8. Dictionary lookup 110 | 9. Top N filtering 111 | 10. String aggregation 112 | 113 | ### ERROR_PATTERNS.md (730 lines) 114 | **Top 5 errors with solutions** 115 | 1. ModuleNotFoundError (external libraries) 116 | 2. Empty code / missing return 117 | 3. KeyError (dictionary access) 118 | 4. IndexError (list access) 119 | 5. Incorrect return format 120 | - Error prevention checklist 121 | - Quick fix reference 122 | - Testing patterns 123 | 124 | --- 125 | 126 | ## Integration with Other Skills 127 | 128 | This skill works with: 129 | 130 | ### n8n Expression Syntax 131 | - Python uses code syntax, not {{}} expressions 132 | - Data access patterns differ ($ vs _) 133 | 134 | ### n8n MCP Tools Expert 135 | - Use MCP tools to validate Code node configurations 136 | - Check node setup with `get_node_essentials` 137 | 138 | ### n8n Workflow Patterns 139 | - Code nodes fit into larger workflow patterns 140 | - Often used after HTTP Request or Webhook nodes 141 | 142 | ### n8n Code JavaScript 143 | - Compare Python vs JavaScript approaches 144 | - Understand when to use which language 145 | - JavaScript recommended for 95% of cases 146 | 147 | ### n8n Node Configuration 148 | - Configure Code node mode (All Items vs Each Item) 149 | - Set up proper connections 150 | 151 | --- 152 | 153 | ## Success Metrics 154 | 155 | After using this skill, you should be able to: 156 | 157 | - [ ] **Know the limitation**: Python has NO external libraries 158 | - [ ] **Choose language**: JavaScript for 95% of cases, Python when needed 159 | - [ ] **Access data**: Use `_input.all()`, `_input.first()`, `_input.item` 160 | - [ ] **Handle webhooks**: Access data via `_json["body"]` 161 | - [ ] **Return properly**: Always return `[{"json": {...}}]` 162 | - [ ] **Avoid KeyError**: Use `.get()` for dictionary access 163 | - [ ] **Use standard library**: Know what's available (json, datetime, re, etc.) 164 | - [ ] **Prevent errors**: Avoid top 5 common errors 165 | - [ ] **Choose alternatives**: Use n8n nodes when libraries needed 166 | - [ ] **Write production code**: Use proven patterns 167 | 168 | --- 169 | 170 | ## Quick Reference 171 | 172 | ### Data Access 173 | ```python 174 | all_items = _input.all() 175 | first_item = _input.first() 176 | current_item = _input.item # Each Item mode only 177 | other_node = _node["NodeName"] 178 | ``` 179 | 180 | ### Webhook Data 181 | ```python 182 | webhook = _input.first()["json"] 183 | body = webhook.get("body", {}) 184 | name = body.get("name") 185 | ``` 186 | 187 | ### Safe Dictionary Access 188 | ```python 189 | # ✅ Use .get() with defaults 190 | value = data.get("field", "default") 191 | 192 | # ❌ Risky - may raise KeyError 193 | value = data["field"] 194 | ``` 195 | 196 | ### Return Format 197 | ```python 198 | # ✅ Correct format 199 | return [{"json": {"result": "success"}}] 200 | 201 | # ❌ Wrong - plain dict 202 | return {"result": "success"} 203 | ``` 204 | 205 | ### Standard Library 206 | ```python 207 | # ✅ Available 208 | import json 209 | import datetime 210 | import re 211 | import base64 212 | import hashlib 213 | 214 | # ❌ NOT available 215 | import requests # ModuleNotFoundError! 216 | import pandas # ModuleNotFoundError! 217 | import numpy # ModuleNotFoundError! 218 | ``` 219 | 220 | --- 221 | 222 | ## Common Use Cases 223 | 224 | ### Use Case 1: Process Webhook Data 225 | ```python 226 | webhook = _input.first()["json"] 227 | body = webhook.get("body", {}) 228 | 229 | return [{ 230 | "json": { 231 | "name": body.get("name"), 232 | "email": body.get("email"), 233 | "processed": True 234 | } 235 | }] 236 | ``` 237 | 238 | ### Use Case 2: Filter and Transform 239 | ```python 240 | all_items = _input.all() 241 | 242 | active = [ 243 | {"json": {**item["json"], "filtered": True}} 244 | for item in all_items 245 | if item["json"].get("status") == "active" 246 | ] 247 | 248 | return active 249 | ``` 250 | 251 | ### Use Case 3: Aggregate Statistics 252 | ```python 253 | import statistics 254 | 255 | all_items = _input.all() 256 | amounts = [item["json"].get("amount", 0) for item in all_items] 257 | 258 | return [{ 259 | "json": { 260 | "total": sum(amounts), 261 | "average": statistics.mean(amounts) if amounts else 0, 262 | "count": len(amounts) 263 | } 264 | }] 265 | ``` 266 | 267 | ### Use Case 4: Parse JSON String 268 | ```python 269 | import json 270 | 271 | data = _input.first()["json"]["body"] 272 | json_string = data.get("payload", "{}") 273 | 274 | try: 275 | parsed = json.loads(json_string) 276 | return [{"json": parsed}] 277 | except json.JSONDecodeError: 278 | return [{"json": {"error": "Invalid JSON"}}] 279 | ``` 280 | 281 | --- 282 | 283 | ## Limitations and Workarounds 284 | 285 | ### Limitation 1: No HTTP Requests Library 286 | **Problem**: No `requests` library 287 | **Workaround**: Use HTTP Request node or JavaScript 288 | 289 | ### Limitation 2: No Data Analysis Library 290 | **Problem**: No `pandas` or `numpy` 291 | **Workaround**: Use list comprehensions and standard library 292 | 293 | ### Limitation 3: No Database Drivers 294 | **Problem**: No `psycopg2`, `pymongo`, etc. 295 | **Workaround**: Use n8n database nodes (Postgres, MySQL, MongoDB) 296 | 297 | ### Limitation 4: No Web Scraping 298 | **Problem**: No `beautifulsoup4` or `selenium` 299 | **Workaround**: Use HTML Extract node 300 | 301 | --- 302 | 303 | ## Best Practices 304 | 305 | 1. **Use JavaScript for most cases** (95% recommendation) 306 | 2. **Use .get() for dictionaries** (avoid KeyError) 307 | 3. **Check lengths before indexing** (avoid IndexError) 308 | 4. **Always return proper format**: `[{"json": {...}}]` 309 | 5. **Access webhook data via ["body"]** 310 | 6. **Use standard library only** (no external imports) 311 | 7. **Handle empty input** (check `if items:`) 312 | 8. **Test both modes** (All Items and Each Item) 313 | 314 | --- 315 | 316 | ## When Python is the Right Choice 317 | 318 | Use Python when: 319 | - Complex text processing (re module) 320 | - Mathematical calculations (math, statistics) 321 | - Date/time manipulation (datetime) 322 | - Cryptographic operations (hashlib) 323 | - You have existing Python logic to reuse 324 | - Team is more comfortable with Python 325 | 326 | Use JavaScript instead when: 327 | - Making HTTP requests 328 | - Working with dates (Luxon included) 329 | - Most data transformations 330 | - When in doubt 331 | 332 | --- 333 | 334 | ## Learning Path 335 | 336 | **Beginner**: 337 | 1. Read SKILL.md - Understand the limitation 338 | 2. Try DATA_ACCESS.md examples - Learn `_input` patterns 339 | 3. Practice safe dictionary access with `.get()` 340 | 341 | **Intermediate**: 342 | 4. Study STANDARD_LIBRARY.md - Know what's available 343 | 5. Try COMMON_PATTERNS.md examples - Use proven patterns 344 | 6. Learn ERROR_PATTERNS.md - Avoid common mistakes 345 | 346 | **Advanced**: 347 | 7. Combine multiple patterns 348 | 8. Use standard library effectively 349 | 9. Know when to switch to JavaScript 350 | 10. Write production-ready code 351 | 352 | --- 353 | 354 | ## Support 355 | 356 | **Questions?** 357 | - Check ERROR_PATTERNS.md for common issues 358 | - Review COMMON_PATTERNS.md for examples 359 | - Consider using JavaScript instead 360 | 361 | **Related Skills**: 362 | - n8n Code JavaScript - Alternative (recommended for 95% of cases) 363 | - n8n Expression Syntax - For {{}} expressions in other nodes 364 | - n8n Workflow Patterns - Bigger picture workflow design 365 | 366 | --- 367 | 368 | ## Version 369 | 370 | **Version**: 1.0.0 371 | **Status**: Production Ready 372 | **Compatibility**: n8n Code node (Python mode) 373 | 374 | --- 375 | 376 | ## Credits 377 | 378 | Part of the n8n-skills project. 379 | 380 | **Conceived by Romuald Członkowski** 381 | - Website: [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en) 382 | - Part of [n8n-mcp project](https://github.com/czlonkowski/n8n-mcp) 383 | 384 | --- 385 | 386 | **Remember**: JavaScript is recommended for 95% of use cases. Use Python only when you specifically need Python's standard library features. 387 | -------------------------------------------------------------------------------- /skills/n8n-expression-syntax/COMMON_MISTAKES.md: -------------------------------------------------------------------------------- 1 | # Common n8n Expression Mistakes 2 | 3 | Complete catalog of expression errors with explanations and fixes. 4 | 5 | --- 6 | 7 | ## 1. Missing Curly Braces 8 | 9 | **Problem**: Expression not recognized, shows as literal text 10 | 11 | ❌ **Wrong**: 12 | ``` 13 | $json.email 14 | ``` 15 | 16 | ✅ **Correct**: 17 | ``` 18 | {{$json.email}} 19 | ``` 20 | 21 | **Why it fails**: n8n treats text without {{ }} as a literal string. Expressions must be wrapped to be evaluated. 22 | 23 | **How to identify**: Field shows exact text like "$json.email" instead of actual value. 24 | 25 | --- 26 | 27 | ## 2. Webhook Body Access 28 | 29 | **Problem**: Undefined values when accessing webhook data 30 | 31 | ❌ **Wrong**: 32 | ``` 33 | {{$json.name}} 34 | {{$json.email}} 35 | {{$json.message}} 36 | ``` 37 | 38 | ✅ **Correct**: 39 | ``` 40 | {{$json.body.name}} 41 | {{$json.body.email}} 42 | {{$json.body.message}} 43 | ``` 44 | 45 | **Why it fails**: Webhook node wraps incoming data under `.body` property. The root `$json` contains headers, params, query, and body. 46 | 47 | **Webhook structure**: 48 | ```javascript 49 | { 50 | "headers": {...}, 51 | "params": {...}, 52 | "query": {...}, 53 | "body": { // User data is HERE! 54 | "name": "John", 55 | "email": "john@example.com" 56 | } 57 | } 58 | ``` 59 | 60 | **How to identify**: Webhook workflow shows "undefined" for fields that are definitely being sent. 61 | 62 | --- 63 | 64 | ## 3. Spaces in Field Names 65 | 66 | **Problem**: Syntax error or undefined value 67 | 68 | ❌ **Wrong**: 69 | ``` 70 | {{$json.first name}} 71 | {{$json.user data.email}} 72 | ``` 73 | 74 | ✅ **Correct**: 75 | ``` 76 | {{$json['first name']}} 77 | {{$json['user data'].email}} 78 | ``` 79 | 80 | **Why it fails**: Spaces break dot notation. JavaScript interprets space as end of property name. 81 | 82 | **How to identify**: Error message about unexpected token, or undefined when field exists. 83 | 84 | --- 85 | 86 | ## 4. Spaces in Node Names 87 | 88 | **Problem**: Cannot access other node's data 89 | 90 | ❌ **Wrong**: 91 | ``` 92 | {{$node.HTTP Request.json.data}} 93 | {{$node.Respond to Webhook.json}} 94 | ``` 95 | 96 | ✅ **Correct**: 97 | ``` 98 | {{$node["HTTP Request"].json.data}} 99 | {{$node["Respond to Webhook"].json}} 100 | ``` 101 | 102 | **Why it fails**: Node names are treated as object property names and need quotes when they contain spaces. 103 | 104 | **How to identify**: Error like "Cannot read property 'Request' of undefined" 105 | 106 | --- 107 | 108 | ## 5. Incorrect Node Reference Case 109 | 110 | **Problem**: Undefined or wrong data returned 111 | 112 | ❌ **Wrong**: 113 | ``` 114 | {{$node["http request"].json.data}} // lowercase 115 | {{$node["Http Request"].json.data}} // wrong capitalization 116 | ``` 117 | 118 | ✅ **Correct**: 119 | ``` 120 | {{$node["HTTP Request"].json.data}} // exact match 121 | ``` 122 | 123 | **Why it fails**: Node names are **case-sensitive**. Must match exactly as shown in workflow. 124 | 125 | **How to identify**: Undefined value even though node exists and has data. 126 | 127 | --- 128 | 129 | ## 6. Double Wrapping 130 | 131 | **Problem**: Literal {{ }} appears in output 132 | 133 | ❌ **Wrong**: 134 | ``` 135 | {{{$json.field}}} 136 | ``` 137 | 138 | ✅ **Correct**: 139 | ``` 140 | {{$json.field}} 141 | ``` 142 | 143 | **Why it fails**: Only one set of {{ }} is needed. Extra braces are treated as literal characters. 144 | 145 | **How to identify**: Output shows "{{value}}" instead of just "value". 146 | 147 | --- 148 | 149 | ## 7. Array Access with Dots 150 | 151 | **Problem**: Syntax error or undefined 152 | 153 | ❌ **Wrong**: 154 | ``` 155 | {{$json.items.0.name}} 156 | {{$json.users.1.email}} 157 | ``` 158 | 159 | ✅ **Correct**: 160 | ``` 161 | {{$json.items[0].name}} 162 | {{$json.users[1].email}} 163 | ``` 164 | 165 | **Why it fails**: Array indices require brackets, not dots. Number after dot is invalid JavaScript. 166 | 167 | **How to identify**: Syntax error or "Cannot read property '0' of undefined" 168 | 169 | --- 170 | 171 | ## 8. Using Expressions in Code Nodes 172 | 173 | **Problem**: Literal string instead of value, or errors 174 | 175 | ❌ **Wrong (in Code node)**: 176 | ```javascript 177 | const email = '{{$json.email}}'; 178 | const name = '={{$json.body.name}}'; 179 | ``` 180 | 181 | ✅ **Correct (in Code node)**: 182 | ```javascript 183 | const email = $json.email; 184 | const name = $json.body.name; 185 | 186 | // Or using Code node API 187 | const email = $input.item.json.email; 188 | const allItems = $input.all(); 189 | ``` 190 | 191 | **Why it fails**: Code nodes have **direct access** to data. The {{ }} syntax is for expression fields in other nodes, not for JavaScript code. 192 | 193 | **How to identify**: Literal string "{{$json.email}}" appears in Code node output instead of actual value. 194 | 195 | --- 196 | 197 | ## 9. Missing Quotes in $node Reference 198 | 199 | **Problem**: Syntax error 200 | 201 | ❌ **Wrong**: 202 | ``` 203 | {{$node[HTTP Request].json.data}} 204 | ``` 205 | 206 | ✅ **Correct**: 207 | ``` 208 | {{$node["HTTP Request"].json.data}} 209 | ``` 210 | 211 | **Why it fails**: Node names must be quoted strings inside brackets. 212 | 213 | **How to identify**: Syntax error "Unexpected identifier" 214 | 215 | --- 216 | 217 | ## 10. Incorrect Property Path 218 | 219 | **Problem**: Undefined value 220 | 221 | ❌ **Wrong**: 222 | ``` 223 | {{$json.data.items.name}} // items is an array 224 | {{$json.user.email}} // user doesn't exist, it's userData 225 | ``` 226 | 227 | ✅ **Correct**: 228 | ``` 229 | {{$json.data.items[0].name}} // access array element 230 | {{$json.userData.email}} // correct property name 231 | ``` 232 | 233 | **Why it fails**: Wrong path to data. Arrays need index, property names must be exact. 234 | 235 | **How to identify**: Check actual data structure using expression editor preview. 236 | 237 | --- 238 | 239 | ## 11. Using = Prefix Outside JSON 240 | 241 | **Problem**: Literal "=" appears in output 242 | 243 | ❌ **Wrong (in text field)**: 244 | ``` 245 | Email: ={{$json.email}} 246 | ``` 247 | 248 | ✅ **Correct (in text field)**: 249 | ``` 250 | Email: {{$json.email}} 251 | ``` 252 | 253 | **Note**: The `=` prefix is **only** needed in JSON mode or when you want to set entire field value to expression result: 254 | 255 | ```javascript 256 | // JSON mode (set property to expression) 257 | { 258 | "email": "={{$json.body.email}}" 259 | } 260 | 261 | // Text mode (no = needed) 262 | Hello {{$json.body.name}}! 263 | ``` 264 | 265 | **Why it fails**: The `=` is parsed as literal text in non-JSON contexts. 266 | 267 | **How to identify**: Output shows "=john@example.com" instead of "john@example.com" 268 | 269 | --- 270 | 271 | ## 12. Expressions in Webhook Path 272 | 273 | **Problem**: Path doesn't update, validation error 274 | 275 | ❌ **Wrong**: 276 | ``` 277 | path: "{{$json.user_id}}/webhook" 278 | path: "users/={{$env.TENANT_ID}}" 279 | ``` 280 | 281 | ✅ **Correct**: 282 | ``` 283 | path: "my-webhook" // Static paths only 284 | path: "user-webhook/:userId" // Use dynamic URL parameters instead 285 | ``` 286 | 287 | **Why it fails**: Webhook paths must be static. Use dynamic URL parameters (`:paramName`) instead of expressions. 288 | 289 | **How to identify**: Webhook path doesn't change or validation warns about invalid path. 290 | 291 | --- 292 | 293 | ## 13. Forgetting .json in $node Reference 294 | 295 | **Problem**: Undefined or wrong data 296 | 297 | ❌ **Wrong**: 298 | ``` 299 | {{$node["HTTP Request"].data}} // Missing .json 300 | {{$node["Webhook"].body.email}} // Missing .json 301 | ``` 302 | 303 | ✅ **Correct**: 304 | ``` 305 | {{$node["HTTP Request"].json.data}} 306 | {{$node["Webhook"].json.body.email}} 307 | ``` 308 | 309 | **Why it fails**: Node data is always under `.json` property (or `.binary` for binary data). 310 | 311 | **How to identify**: Undefined value when you know the node has data. 312 | 313 | --- 314 | 315 | ## 14. String Concatenation Confusion 316 | 317 | **Problem**: Attempting JavaScript template literals 318 | 319 | ❌ **Wrong**: 320 | ``` 321 | `Hello ${$json.name}!` // Template literal syntax 322 | "Hello " + $json.name + "!" // String concatenation 323 | ``` 324 | 325 | ✅ **Correct**: 326 | ``` 327 | Hello {{$json.name}}! // n8n expressions auto-concatenate 328 | ``` 329 | 330 | **Why it fails**: n8n expressions don't use JavaScript template literal syntax. Adjacent text and expressions are automatically concatenated. 331 | 332 | **How to identify**: Literal backticks or + symbols appear in output. 333 | 334 | --- 335 | 336 | ## 15. Empty Expression Brackets 337 | 338 | **Problem**: Literal {{}} in output 339 | 340 | ❌ **Wrong**: 341 | ``` 342 | {{}} 343 | {{ }} 344 | ``` 345 | 346 | ✅ **Correct**: 347 | ``` 348 | {{$json.field}} // Include expression content 349 | ``` 350 | 351 | **Why it fails**: Empty expression brackets have nothing to evaluate. 352 | 353 | **How to identify**: Literal "{{ }}" text appears in output. 354 | 355 | --- 356 | 357 | ## Quick Reference Table 358 | 359 | | Error | Symptom | Fix | 360 | |-------|---------|-----| 361 | | No {{ }} | Literal text | Add {{ }} | 362 | | Webhook data | Undefined | Add `.body` | 363 | | Space in field | Syntax error | Use `['field name']` | 364 | | Space in node | Undefined | Use `["Node Name"]` | 365 | | Wrong case | Undefined | Match exact case | 366 | | Double {{ }} | Literal braces | Remove extra {{ }} | 367 | | .0 array | Syntax error | Use [0] | 368 | | {{ }} in Code | Literal string | Remove {{ }} | 369 | | No quotes in $node | Syntax error | Add quotes | 370 | | Wrong path | Undefined | Check data structure | 371 | | = in text | Literal = | Remove = prefix | 372 | | Dynamic path | Doesn't work | Use static path | 373 | | Missing .json | Undefined | Add .json | 374 | | Template literals | Literal text | Use {{ }} | 375 | | Empty {{ }} | Literal braces | Add expression | 376 | 377 | --- 378 | 379 | ## Debugging Process 380 | 381 | When expression doesn't work: 382 | 383 | 1. **Check braces**: Is it wrapped in {{ }}? 384 | 2. **Check data source**: Is it webhook data? Add `.body` 385 | 3. **Check spaces**: Field or node name has spaces? Use brackets 386 | 4. **Check case**: Does node name match exactly? 387 | 5. **Check path**: Is the property path correct? 388 | 6. **Use expression editor**: Preview shows actual result 389 | 7. **Check context**: Is it a Code node? Remove {{ }} 390 | 391 | --- 392 | 393 | **Related**: See [EXAMPLES.md](EXAMPLES.md) for working examples of correct syntax. 394 | -------------------------------------------------------------------------------- /skills/n8n-expression-syntax/EXAMPLES.md: -------------------------------------------------------------------------------- 1 | # n8n Expression Examples 2 | 3 | Real working examples from n8n workflows. 4 | 5 | --- 6 | 7 | ## Example 1: Webhook Form Submission 8 | 9 | **Scenario**: Form submission webhook posts to Slack 10 | 11 | **Workflow**: Webhook → Slack 12 | 13 | **Webhook Input** (POST): 14 | ```json 15 | { 16 | "name": "John Doe", 17 | "email": "john@example.com", 18 | "company": "Acme Corp", 19 | "message": "Interested in your product" 20 | } 21 | ``` 22 | 23 | **Webhook Node Output**: 24 | ```json 25 | { 26 | "headers": {"content-type": "application/json"}, 27 | "params": {}, 28 | "query": {}, 29 | "body": { 30 | "name": "John Doe", 31 | "email": "john@example.com", 32 | "company": "Acme Corp", 33 | "message": "Interested in your product" 34 | } 35 | } 36 | ``` 37 | 38 | **In Slack Node** (text field): 39 | ``` 40 | New form submission! 📝 41 | 42 | Name: {{$json.body.name}} 43 | Email: {{$json.body.email}} 44 | Company: {{$json.body.company}} 45 | Message: {{$json.body.message}} 46 | ``` 47 | 48 | **Output**: 49 | ``` 50 | New form submission! 📝 51 | 52 | Name: John Doe 53 | Email: john@example.com 54 | Company: Acme Corp 55 | Message: Interested in your product 56 | ``` 57 | 58 | --- 59 | 60 | ## Example 2: HTTP API to Database 61 | 62 | **Scenario**: Fetch user data from API and insert into database 63 | 64 | **Workflow**: Schedule → HTTP Request → Postgres 65 | 66 | **HTTP Request Returns**: 67 | ```json 68 | { 69 | "data": { 70 | "users": [ 71 | { 72 | "id": 123, 73 | "name": "Alice Smith", 74 | "email": "alice@example.com", 75 | "role": "admin" 76 | } 77 | ] 78 | } 79 | } 80 | ``` 81 | 82 | **In Postgres Node** (INSERT statement): 83 | ```sql 84 | INSERT INTO users (user_id, name, email, role, synced_at) 85 | VALUES ( 86 | {{$json.data.users[0].id}}, 87 | '{{$json.data.users[0].name}}', 88 | '{{$json.data.users[0].email}}', 89 | '{{$json.data.users[0].role}}', 90 | '{{$now.toFormat('yyyy-MM-dd HH:mm:ss')}}' 91 | ) 92 | ``` 93 | 94 | **Result**: User inserted with current timestamp 95 | 96 | --- 97 | 98 | ## Example 3: Multi-Node Data Flow 99 | 100 | **Scenario**: Webhook → HTTP Request → Email 101 | 102 | **Workflow Structure**: 103 | 1. Webhook receives order ID 104 | 2. HTTP Request fetches order details 105 | 3. Email sends confirmation 106 | 107 | ### Node 1: Webhook 108 | 109 | **Receives**: 110 | ```json 111 | { 112 | "body": { 113 | "order_id": "ORD-12345" 114 | } 115 | } 116 | ``` 117 | 118 | ### Node 2: HTTP Request 119 | 120 | **URL field**: 121 | ``` 122 | https://api.example.com/orders/{{$json.body.order_id}} 123 | ``` 124 | 125 | **Returns**: 126 | ```json 127 | { 128 | "order": { 129 | "id": "ORD-12345", 130 | "customer": "Bob Jones", 131 | "total": 99.99, 132 | "items": ["Widget", "Gadget"] 133 | } 134 | } 135 | ``` 136 | 137 | ### Node 3: Email 138 | 139 | **Subject**: 140 | ``` 141 | Order {{$node["Webhook"].json.body.order_id}} Confirmed 142 | ``` 143 | 144 | **Body**: 145 | ``` 146 | Dear {{$node["HTTP Request"].json.order.customer}}, 147 | 148 | Your order {{$node["Webhook"].json.body.order_id}} has been confirmed! 149 | 150 | Total: ${{$node["HTTP Request"].json.order.total}} 151 | Items: {{$node["HTTP Request"].json.order.items.join(', ')}} 152 | 153 | Thank you for your purchase! 154 | ``` 155 | 156 | **Email Result**: 157 | ``` 158 | Subject: Order ORD-12345 Confirmed 159 | 160 | Dear Bob Jones, 161 | 162 | Your order ORD-12345 has been confirmed! 163 | 164 | Total: $99.99 165 | Items: Widget, Gadget 166 | 167 | Thank you for your purchase! 168 | ``` 169 | 170 | --- 171 | 172 | ## Example 4: Date Formatting 173 | 174 | **Scenario**: Various date format outputs 175 | 176 | **Current Time**: 2025-10-20 14:30:45 177 | 178 | ### ISO Format 179 | ```javascript 180 | {{$now.toISO()}} 181 | ``` 182 | **Output**: `2025-10-20T14:30:45.000Z` 183 | 184 | ### Custom Date Format 185 | ```javascript 186 | {{$now.toFormat('yyyy-MM-dd')}} 187 | ``` 188 | **Output**: `2025-10-20` 189 | 190 | ### Time Only 191 | ```javascript 192 | {{$now.toFormat('HH:mm:ss')}} 193 | ``` 194 | **Output**: `14:30:45` 195 | 196 | ### Full Readable Format 197 | ```javascript 198 | {{$now.toFormat('MMMM dd, yyyy')}} 199 | ``` 200 | **Output**: `October 20, 2025` 201 | 202 | ### Date Math - Future 203 | ```javascript 204 | {{$now.plus({days: 7}).toFormat('yyyy-MM-dd')}} 205 | ``` 206 | **Output**: `2025-10-27` 207 | 208 | ### Date Math - Past 209 | ```javascript 210 | {{$now.minus({hours: 24}).toFormat('yyyy-MM-dd HH:mm')}} 211 | ``` 212 | **Output**: `2025-10-19 14:30` 213 | 214 | --- 215 | 216 | ## Example 5: Array Operations 217 | 218 | **Data**: 219 | ```json 220 | { 221 | "users": [ 222 | {"name": "Alice", "email": "alice@example.com"}, 223 | {"name": "Bob", "email": "bob@example.com"}, 224 | {"name": "Charlie", "email": "charlie@example.com"} 225 | ] 226 | } 227 | ``` 228 | 229 | ### First User 230 | ```javascript 231 | {{$json.users[0].name}} 232 | ``` 233 | **Output**: `Alice` 234 | 235 | ### Last User 236 | ```javascript 237 | {{$json.users[$json.users.length - 1].name}} 238 | ``` 239 | **Output**: `Charlie` 240 | 241 | ### All Emails (Join) 242 | ```javascript 243 | {{$json.users.map(u => u.email).join(', ')}} 244 | ``` 245 | **Output**: `alice@example.com, bob@example.com, charlie@example.com` 246 | 247 | ### Array Length 248 | ```javascript 249 | {{$json.users.length}} 250 | ``` 251 | **Output**: `3` 252 | 253 | --- 254 | 255 | ## Example 6: Conditional Logic 256 | 257 | **Data**: 258 | ```json 259 | { 260 | "order": { 261 | "status": "completed", 262 | "total": 150 263 | } 264 | } 265 | ``` 266 | 267 | ### Ternary Operator 268 | ```javascript 269 | {{$json.order.status === 'completed' ? 'Order Complete ✓' : 'Pending...'}} 270 | ``` 271 | **Output**: `Order Complete ✓` 272 | 273 | ### Default Values 274 | ```javascript 275 | {{$json.order.notes || 'No notes provided'}} 276 | ``` 277 | **Output**: `No notes provided` (if notes field doesn't exist) 278 | 279 | ### Multiple Conditions 280 | ```javascript 281 | {{$json.order.total > 100 ? 'Premium Customer' : 'Standard Customer'}} 282 | ``` 283 | **Output**: `Premium Customer` 284 | 285 | --- 286 | 287 | ## Example 7: String Manipulation 288 | 289 | **Data**: 290 | ```json 291 | { 292 | "user": { 293 | "email": "JOHN@EXAMPLE.COM", 294 | "message": " Hello World " 295 | } 296 | } 297 | ``` 298 | 299 | ### Lowercase 300 | ```javascript 301 | {{$json.user.email.toLowerCase()}} 302 | ``` 303 | **Output**: `john@example.com` 304 | 305 | ### Uppercase 306 | ```javascript 307 | {{$json.user.message.toUpperCase()}} 308 | ``` 309 | **Output**: ` HELLO WORLD ` 310 | 311 | ### Trim 312 | ```javascript 313 | {{$json.user.message.trim()}} 314 | ``` 315 | **Output**: `Hello World` 316 | 317 | ### Substring 318 | ```javascript 319 | {{$json.user.email.substring(0, 4)}} 320 | ``` 321 | **Output**: `JOHN` 322 | 323 | ### Replace 324 | ```javascript 325 | {{$json.user.message.replace('World', 'n8n')}} 326 | ``` 327 | **Output**: ` Hello n8n ` 328 | 329 | --- 330 | 331 | ## Example 8: Fields with Spaces 332 | 333 | **Data**: 334 | ```json 335 | { 336 | "user data": { 337 | "first name": "Jane", 338 | "last name": "Doe", 339 | "phone number": "+1234567890" 340 | } 341 | } 342 | ``` 343 | 344 | ### Bracket Notation 345 | ```javascript 346 | {{$json['user data']['first name']}} 347 | ``` 348 | **Output**: `Jane` 349 | 350 | ### Combined 351 | ```javascript 352 | {{$json['user data']['first name']}} {{$json['user data']['last name']}} 353 | ``` 354 | **Output**: `Jane Doe` 355 | 356 | ### Nested Spaces 357 | ```javascript 358 | Contact: {{$json['user data']['phone number']}} 359 | ``` 360 | **Output**: `Contact: +1234567890` 361 | 362 | --- 363 | 364 | ## Example 9: Code Node (Direct Access) 365 | 366 | **Code Node**: Transform webhook data 367 | 368 | **Input** (from Webhook node): 369 | ```json 370 | { 371 | "body": { 372 | "items": ["apple", "banana", "cherry"] 373 | } 374 | } 375 | ``` 376 | 377 | **Code** (JavaScript): 378 | ```javascript 379 | // ✅ Direct access (no {{ }}) 380 | const items = $json.body.items; 381 | 382 | // Transform to uppercase 383 | const uppercased = items.map(item => item.toUpperCase()); 384 | 385 | // Return in n8n format 386 | return [{ 387 | json: { 388 | original: items, 389 | transformed: uppercased, 390 | count: items.length 391 | } 392 | }]; 393 | ``` 394 | 395 | **Output**: 396 | ```json 397 | { 398 | "original": ["apple", "banana", "cherry"], 399 | "transformed": ["APPLE", "BANANA", "CHERRY"], 400 | "count": 3 401 | } 402 | ``` 403 | 404 | --- 405 | 406 | ## Example 10: Environment Variables 407 | 408 | **Setup**: Environment variable `API_KEY=secret123` 409 | 410 | ### In HTTP Request (Headers) 411 | ```javascript 412 | Authorization: Bearer {{$env.API_KEY}} 413 | ``` 414 | **Result**: `Authorization: Bearer secret123` 415 | 416 | ### In URL 417 | ```javascript 418 | https://api.example.com/data?key={{$env.API_KEY}} 419 | ``` 420 | **Result**: `https://api.example.com/data?key=secret123` 421 | 422 | --- 423 | 424 | ## Template from Real Workflow 425 | 426 | **Based on n8n template #2947** (Weather to Slack) 427 | 428 | ### Workflow Structure 429 | Webhook → OpenStreetMap API → Weather API → Slack 430 | 431 | ### Webhook Slash Command 432 | **Input**: `/weather London` 433 | 434 | **Webhook receives**: 435 | ```json 436 | { 437 | "body": { 438 | "text": "London" 439 | } 440 | } 441 | ``` 442 | 443 | ### OpenStreetMap API 444 | **URL**: 445 | ``` 446 | https://nominatim.openstreetmap.org/search?q={{$json.body.text}}&format=json 447 | ``` 448 | 449 | ### Weather API (NWS) 450 | **URL**: 451 | ``` 452 | https://api.weather.gov/points/{{$node["OpenStreetMap"].json[0].lat}},{{$node["OpenStreetMap"].json[0].lon}} 453 | ``` 454 | 455 | ### Slack Message 456 | ``` 457 | Weather for {{$json.body.text}}: 458 | 459 | Temperature: {{$node["Weather API"].json.properties.temperature.value}}°C 460 | Conditions: {{$node["Weather API"].json.properties.shortForecast}} 461 | ``` 462 | 463 | --- 464 | 465 | ## Summary 466 | 467 | **Key Patterns**: 468 | 1. Webhook data is under `.body` 469 | 2. Use `{{}}` for expressions (except Code nodes) 470 | 3. Reference other nodes with `$node["Node Name"].json` 471 | 4. Use brackets for field names with spaces 472 | 5. Node names are case-sensitive 473 | 474 | **Most Common Uses**: 475 | - `{{$json.body.field}}` - Webhook data 476 | - `{{$node["Name"].json.field}}` - Other node data 477 | - `{{$now.toFormat('yyyy-MM-dd')}}` - Timestamps 478 | - `{{$json.array[0].field}}` - Array access 479 | - `{{$json.field || 'default'}}` - Default values 480 | 481 | --- 482 | 483 | **Related**: See [COMMON_MISTAKES.md](COMMON_MISTAKES.md) for error examples and fixes. 484 | -------------------------------------------------------------------------------- /skills/n8n-expression-syntax/README.md: -------------------------------------------------------------------------------- 1 | # n8n Expression Syntax 2 | 3 | Expert guide for writing correct n8n expressions in workflows. 4 | 5 | --- 6 | 7 | ## Purpose 8 | 9 | Teaches correct n8n expression syntax ({{ }} patterns) and fixes common mistakes, especially the critical webhook data structure gotcha. 10 | 11 | ## Activates On 12 | 13 | - expression 14 | - {{}} syntax 15 | - $json, $node, $now, $env 16 | - webhook data 17 | - troubleshoot expression error 18 | - undefined in workflow 19 | 20 | ## File Count 21 | 22 | 4 files, ~450 lines total 23 | 24 | ## Dependencies 25 | 26 | **n8n-mcp tools**: 27 | - None directly (syntax knowledge skill) 28 | - Works with n8n-mcp validation tools 29 | 30 | **Related skills**: 31 | - n8n Workflow Patterns (uses expressions in examples) 32 | - n8n MCP Tools Expert (validates expressions) 33 | - n8n Node Configuration (when expressions are needed) 34 | 35 | ## Coverage 36 | 37 | ### Core Topics 38 | - Expression format ({{ }}) 39 | - Core variables ($json, $node, $now, $env) 40 | - **Webhook data structure** ($json.body.*) 41 | - When NOT to use expressions (Code nodes) 42 | 43 | ### Common Patterns 44 | - Accessing nested fields 45 | - Referencing other nodes 46 | - Array and object access 47 | - Date/time formatting 48 | - String manipulation 49 | 50 | ### Error Prevention 51 | - 15 common mistakes with fixes 52 | - Quick reference table 53 | - Debugging process 54 | 55 | ## Evaluations 56 | 57 | 4 scenarios (100% coverage expected): 58 | 1. **eval-001**: Missing curly braces 59 | 2. **eval-002**: Webhook body data access (critical!) 60 | 3. **eval-003**: Code node vs expression confusion 61 | 4. **eval-004**: Node reference syntax 62 | 63 | ## Key Features 64 | 65 | ✅ **Critical Gotcha Highlighted**: Webhook data under `.body` 66 | ✅ **Real Examples**: From MCP testing and real templates 67 | ✅ **Quick Fixes Table**: Fast reference for common errors 68 | ✅ **Code vs Expression**: Clear distinction 69 | ✅ **Comprehensive**: Covers 95% of expression use cases 70 | 71 | ## Files 72 | 73 | - **SKILL.md** (285 lines) - Main content with all essential knowledge 74 | - **COMMON_MISTAKES.md** (380 lines) - Complete error catalog with 15 common mistakes 75 | - **EXAMPLES.md** (450 lines) - 10 real working examples 76 | - **README.md** (this file) - Skill metadata 77 | 78 | ## Success Metrics 79 | 80 | **Expected outcomes**: 81 | - Users correctly wrap expressions in {{ }} 82 | - Zero webhook `.body` access errors 83 | - No expressions used in Code nodes 84 | - Correct $node reference syntax 85 | 86 | ## Last Updated 87 | 88 | 2025-10-20 89 | 90 | --- 91 | 92 | **Part of**: n8n-skills repository 93 | **Conceived by**: Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en) 94 | -------------------------------------------------------------------------------- /skills/n8n-expression-syntax/SKILL.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: n8n-expression-syntax 3 | 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. 4 | --- 5 | 6 | # n8n Expression Syntax 7 | 8 | Expert guide for writing correct n8n expressions in workflows. 9 | 10 | --- 11 | 12 | ## Expression Format 13 | 14 | All dynamic content in n8n uses **double curly braces**: 15 | 16 | ``` 17 | {{expression}} 18 | ``` 19 | 20 | **Examples**: 21 | ``` 22 | ✅ {{$json.email}} 23 | ✅ {{$json.body.name}} 24 | ✅ {{$node["HTTP Request"].json.data}} 25 | ❌ $json.email (no braces - treated as literal text) 26 | ❌ {$json.email} (single braces - invalid) 27 | ``` 28 | 29 | --- 30 | 31 | ## Core Variables 32 | 33 | ### $json - Current Node Output 34 | 35 | Access data from the current node: 36 | 37 | ```javascript 38 | {{$json.fieldName}} 39 | {{$json['field with spaces']}} 40 | {{$json.nested.property}} 41 | {{$json.items[0].name}} 42 | ``` 43 | 44 | ### $node - Reference Other Nodes 45 | 46 | Access data from any previous node: 47 | 48 | ```javascript 49 | {{$node["Node Name"].json.fieldName}} 50 | {{$node["HTTP Request"].json.data}} 51 | {{$node["Webhook"].json.body.email}} 52 | ``` 53 | 54 | **Important**: 55 | - Node names **must** be in quotes 56 | - Node names are **case-sensitive** 57 | - Must match exact node name from workflow 58 | 59 | ### $now - Current Timestamp 60 | 61 | Access current date/time: 62 | 63 | ```javascript 64 | {{$now}} 65 | {{$now.toFormat('yyyy-MM-dd')}} 66 | {{$now.toFormat('HH:mm:ss')}} 67 | {{$now.plus({days: 7})}} 68 | ``` 69 | 70 | ### $env - Environment Variables 71 | 72 | Access environment variables: 73 | 74 | ```javascript 75 | {{$env.API_KEY}} 76 | {{$env.DATABASE_URL}} 77 | ``` 78 | 79 | --- 80 | 81 | ## 🚨 CRITICAL: Webhook Data Structure 82 | 83 | **Most Common Mistake**: Webhook data is **NOT** at the root! 84 | 85 | ### Webhook Node Output Structure 86 | 87 | ```javascript 88 | { 89 | "headers": {...}, 90 | "params": {...}, 91 | "query": {...}, 92 | "body": { // ⚠️ USER DATA IS HERE! 93 | "name": "John", 94 | "email": "john@example.com", 95 | "message": "Hello" 96 | } 97 | } 98 | ``` 99 | 100 | ### Correct Webhook Data Access 101 | 102 | ```javascript 103 | ❌ WRONG: {{$json.name}} 104 | ❌ WRONG: {{$json.email}} 105 | 106 | ✅ CORRECT: {{$json.body.name}} 107 | ✅ CORRECT: {{$json.body.email}} 108 | ✅ CORRECT: {{$json.body.message}} 109 | ``` 110 | 111 | **Why**: Webhook node wraps incoming data under `.body` property to preserve headers, params, and query parameters. 112 | 113 | --- 114 | 115 | ## Common Patterns 116 | 117 | ### Access Nested Fields 118 | 119 | ```javascript 120 | // Simple nesting 121 | {{$json.user.email}} 122 | 123 | // Array access 124 | {{$json.data[0].name}} 125 | {{$json.items[0].id}} 126 | 127 | // Bracket notation for spaces 128 | {{$json['field name']}} 129 | {{$json['user data']['first name']}} 130 | ``` 131 | 132 | ### Reference Other Nodes 133 | 134 | ```javascript 135 | // Node without spaces 136 | {{$node["Set"].json.value}} 137 | 138 | // Node with spaces (common!) 139 | {{$node["HTTP Request"].json.data}} 140 | {{$node["Respond to Webhook"].json.message}} 141 | 142 | // Webhook node 143 | {{$node["Webhook"].json.body.email}} 144 | ``` 145 | 146 | ### Combine Variables 147 | 148 | ```javascript 149 | // Concatenation (automatic) 150 | Hello {{$json.body.name}}! 151 | 152 | // In URLs 153 | https://api.example.com/users/{{$json.body.user_id}} 154 | 155 | // In object properties 156 | { 157 | "name": "={{$json.body.name}}", 158 | "email": "={{$json.body.email}}" 159 | } 160 | ``` 161 | 162 | --- 163 | 164 | ## When NOT to Use Expressions 165 | 166 | ### ❌ Code Nodes 167 | 168 | Code nodes use **direct JavaScript access**, NOT expressions! 169 | 170 | ```javascript 171 | // ❌ WRONG in Code node 172 | const email = '={{$json.email}}'; 173 | const name = '{{$json.body.name}}'; 174 | 175 | // ✅ CORRECT in Code node 176 | const email = $json.email; 177 | const name = $json.body.name; 178 | 179 | // Or using Code node API 180 | const email = $input.item.json.email; 181 | const allItems = $input.all(); 182 | ``` 183 | 184 | ### ❌ Webhook Paths 185 | 186 | ```javascript 187 | // ❌ WRONG 188 | path: "{{$json.user_id}}/webhook" 189 | 190 | // ✅ CORRECT 191 | path: "user-webhook" // Static paths only 192 | ``` 193 | 194 | ### ❌ Credential Fields 195 | 196 | ```javascript 197 | // ❌ WRONG 198 | apiKey: "={{$env.API_KEY}}" 199 | 200 | // ✅ CORRECT 201 | Use n8n credential system, not expressions 202 | ``` 203 | 204 | --- 205 | 206 | ## Validation Rules 207 | 208 | ### 1. Always Use {{}} 209 | 210 | Expressions **must** be wrapped in double curly braces. 211 | 212 | ```javascript 213 | ❌ $json.field 214 | ✅ {{$json.field}} 215 | ``` 216 | 217 | ### 2. Use Quotes for Spaces 218 | 219 | Field or node names with spaces require **bracket notation**: 220 | 221 | ```javascript 222 | ❌ {{$json.field name}} 223 | ✅ {{$json['field name']}} 224 | 225 | ❌ {{$node.HTTP Request.json}} 226 | ✅ {{$node["HTTP Request"].json}} 227 | ``` 228 | 229 | ### 3. Match Exact Node Names 230 | 231 | Node references are **case-sensitive**: 232 | 233 | ```javascript 234 | ❌ {{$node["http request"].json}} // lowercase 235 | ❌ {{$node["Http Request"].json}} // wrong case 236 | ✅ {{$node["HTTP Request"].json}} // exact match 237 | ``` 238 | 239 | ### 4. No Nested {{}} 240 | 241 | Don't double-wrap expressions: 242 | 243 | ```javascript 244 | ❌ {{{$json.field}}} 245 | ✅ {{$json.field}} 246 | ``` 247 | 248 | --- 249 | 250 | ## Common Mistakes 251 | 252 | For complete error catalog with fixes, see [COMMON_MISTAKES.md](COMMON_MISTAKES.md) 253 | 254 | ### Quick Fixes 255 | 256 | | Mistake | Fix | 257 | |---------|-----| 258 | | `$json.field` | `{{$json.field}}` | 259 | | `{{$json.field name}}` | `{{$json['field name']}}` | 260 | | `{{$node.HTTP Request}}` | `{{$node["HTTP Request"]}}` | 261 | | `{{{$json.field}}}` | `{{$json.field}}` | 262 | | `{{$json.name}}` (webhook) | `{{$json.body.name}}` | 263 | | `'={{$json.email}}'` (Code node) | `$json.email` | 264 | 265 | --- 266 | 267 | ## Working Examples 268 | 269 | For real workflow examples, see [EXAMPLES.md](EXAMPLES.md) 270 | 271 | ### Example 1: Webhook to Slack 272 | 273 | **Webhook receives**: 274 | ```json 275 | { 276 | "body": { 277 | "name": "John Doe", 278 | "email": "john@example.com", 279 | "message": "Hello!" 280 | } 281 | } 282 | ``` 283 | 284 | **In Slack node text field**: 285 | ``` 286 | New form submission! 287 | 288 | Name: {{$json.body.name}} 289 | Email: {{$json.body.email}} 290 | Message: {{$json.body.message}} 291 | ``` 292 | 293 | ### Example 2: HTTP Request to Email 294 | 295 | **HTTP Request returns**: 296 | ```json 297 | { 298 | "data": { 299 | "items": [ 300 | {"name": "Product 1", "price": 29.99} 301 | ] 302 | } 303 | } 304 | ``` 305 | 306 | **In Email node** (reference HTTP Request): 307 | ``` 308 | Product: {{$node["HTTP Request"].json.data.items[0].name}} 309 | Price: ${{$node["HTTP Request"].json.data.items[0].price}} 310 | ``` 311 | 312 | ### Example 3: Format Timestamp 313 | 314 | ```javascript 315 | // Current date 316 | {{$now.toFormat('yyyy-MM-dd')}} 317 | // Result: 2025-10-20 318 | 319 | // Time 320 | {{$now.toFormat('HH:mm:ss')}} 321 | // Result: 14:30:45 322 | 323 | // Full datetime 324 | {{$now.toFormat('yyyy-MM-dd HH:mm')}} 325 | // Result: 2025-10-20 14:30 326 | ``` 327 | 328 | --- 329 | 330 | ## Data Type Handling 331 | 332 | ### Arrays 333 | 334 | ```javascript 335 | // First item 336 | {{$json.users[0].email}} 337 | 338 | // Array length 339 | {{$json.users.length}} 340 | 341 | // Last item 342 | {{$json.users[$json.users.length - 1].name}} 343 | ``` 344 | 345 | ### Objects 346 | 347 | ```javascript 348 | // Dot notation (no spaces) 349 | {{$json.user.email}} 350 | 351 | // Bracket notation (with spaces or dynamic) 352 | {{$json['user data'].email}} 353 | ``` 354 | 355 | ### Strings 356 | 357 | ```javascript 358 | // Concatenation (automatic) 359 | Hello {{$json.name}}! 360 | 361 | // String methods 362 | {{$json.email.toLowerCase()}} 363 | {{$json.name.toUpperCase()}} 364 | ``` 365 | 366 | ### Numbers 367 | 368 | ```javascript 369 | // Direct use 370 | {{$json.price}} 371 | 372 | // Math operations 373 | {{$json.price * 1.1}} // Add 10% 374 | {{$json.quantity + 5}} 375 | ``` 376 | 377 | --- 378 | 379 | ## Advanced Patterns 380 | 381 | ### Conditional Content 382 | 383 | ```javascript 384 | // Ternary operator 385 | {{$json.status === 'active' ? 'Active User' : 'Inactive User'}} 386 | 387 | // Default values 388 | {{$json.email || 'no-email@example.com'}} 389 | ``` 390 | 391 | ### Date Manipulation 392 | 393 | ```javascript 394 | // Add days 395 | {{$now.plus({days: 7}).toFormat('yyyy-MM-dd')}} 396 | 397 | // Subtract hours 398 | {{$now.minus({hours: 24}).toISO()}} 399 | 400 | // Set specific date 401 | {{DateTime.fromISO('2025-12-25').toFormat('MMMM dd, yyyy')}} 402 | ``` 403 | 404 | ### String Manipulation 405 | 406 | ```javascript 407 | // Substring 408 | {{$json.email.substring(0, 5)}} 409 | 410 | // Replace 411 | {{$json.message.replace('old', 'new')}} 412 | 413 | // Split and join 414 | {{$json.tags.split(',').join(', ')}} 415 | ``` 416 | 417 | --- 418 | 419 | ## Debugging Expressions 420 | 421 | ### Test in Expression Editor 422 | 423 | 1. Click field with expression 424 | 2. Open expression editor (click "fx" icon) 425 | 3. See live preview of result 426 | 4. Check for errors highlighted in red 427 | 428 | ### Common Error Messages 429 | 430 | **"Cannot read property 'X' of undefined"** 431 | → Parent object doesn't exist 432 | → Check your data path 433 | 434 | **"X is not a function"** 435 | → Trying to call method on non-function 436 | → Check variable type 437 | 438 | **Expression shows as literal text** 439 | → Missing {{ }} 440 | → Add curly braces 441 | 442 | --- 443 | 444 | ## Expression Helpers 445 | 446 | ### Available Methods 447 | 448 | **String**: 449 | - `.toLowerCase()`, `.toUpperCase()` 450 | - `.trim()`, `.replace()`, `.substring()` 451 | - `.split()`, `.includes()` 452 | 453 | **Array**: 454 | - `.length`, `.map()`, `.filter()` 455 | - `.find()`, `.join()`, `.slice()` 456 | 457 | **DateTime** (Luxon): 458 | - `.toFormat()`, `.toISO()`, `.toLocal()` 459 | - `.plus()`, `.minus()`, `.set()` 460 | 461 | **Number**: 462 | - `.toFixed()`, `.toString()` 463 | - Math operations: `+`, `-`, `*`, `/`, `%` 464 | 465 | --- 466 | 467 | ## Best Practices 468 | 469 | ### ✅ Do 470 | 471 | - Always use {{ }} for dynamic content 472 | - Use bracket notation for field names with spaces 473 | - Reference webhook data from `.body` 474 | - Use $node for data from other nodes 475 | - Test expressions in expression editor 476 | 477 | ### ❌ Don't 478 | 479 | - Don't use expressions in Code nodes 480 | - Don't forget quotes around node names with spaces 481 | - Don't double-wrap with extra {{ }} 482 | - Don't assume webhook data is at root (it's under .body!) 483 | - Don't use expressions in webhook paths or credentials 484 | 485 | --- 486 | 487 | ## Related Skills 488 | 489 | - **n8n MCP Tools Expert**: Learn how to validate expressions using MCP tools 490 | - **n8n Workflow Patterns**: See expressions in real workflow examples 491 | - **n8n Node Configuration**: Understand when expressions are needed 492 | 493 | --- 494 | 495 | ## Summary 496 | 497 | **Essential Rules**: 498 | 1. Wrap expressions in {{ }} 499 | 2. Webhook data is under `.body` 500 | 3. No {{ }} in Code nodes 501 | 4. Quote node names with spaces 502 | 5. Node names are case-sensitive 503 | 504 | **Most Common Mistakes**: 505 | - Missing {{ }} → Add braces 506 | - `{{$json.name}}` in webhooks → Use `{{$json.body.name}}` 507 | - `{{$json.email}}` in Code → Use `$json.email` 508 | - `{{$node.HTTP Request}}` → Use `{{$node["HTTP Request"]}}` 509 | 510 | For more details, see: 511 | - [COMMON_MISTAKES.md](COMMON_MISTAKES.md) - Complete error catalog 512 | - [EXAMPLES.md](EXAMPLES.md) - Real workflow examples 513 | 514 | --- 515 | 516 | **Need Help?** Reference the n8n expression documentation or use n8n-mcp validation tools to check your expressions. 517 | -------------------------------------------------------------------------------- /skills/n8n-mcp-tools-expert/README.md: -------------------------------------------------------------------------------- 1 | # n8n MCP Tools Expert 2 | 3 | Expert guide for using n8n-mcp MCP tools effectively. 4 | 5 | --- 6 | 7 | ## Purpose 8 | 9 | Teaches how to use n8n-mcp MCP server tools correctly for efficient workflow building. 10 | 11 | ## Activates On 12 | 13 | - search nodes 14 | - find node 15 | - validate 16 | - MCP tools 17 | - template 18 | - workflow 19 | - n8n-mcp 20 | - tool selection 21 | 22 | ## File Count 23 | 24 | 5 files, ~1,150 lines total 25 | 26 | ## Priority 27 | 28 | **HIGHEST** - Essential for correct MCP tool usage 29 | 30 | ## Dependencies 31 | 32 | **n8n-mcp tools**: All of them! (40+ tools) 33 | 34 | **Related skills**: 35 | - n8n Expression Syntax (write expressions for workflows) 36 | - n8n Workflow Patterns (use tools to build patterns) 37 | - n8n Validation Expert (interpret validation results) 38 | - n8n Node Configuration (configure nodes found with tools) 39 | 40 | ## Coverage 41 | 42 | ### Core Topics 43 | - Tool selection guide (which tool for which task) 44 | - nodeType format differences (nodes-base.* vs n8n-nodes-base.*) 45 | - Validation profiles (minimal/runtime/ai-friendly/strict) 46 | - Smart parameters (branch, case for multi-output nodes) 47 | - Auto-sanitization system 48 | - Workflow management (15 operation types) 49 | - AI connection types (8 types) 50 | 51 | ### Tool Categories 52 | - Node Discovery (search, list, essentials, info) 53 | - Configuration Validation (minimal, operation, workflow) 54 | - Workflow Management (create, update, validate) 55 | - Template Library (search, get) 56 | - Documentation (tools, database stats) 57 | 58 | ## Evaluations 59 | 60 | 5 scenarios (100% coverage expected): 61 | 1. **eval-001**: Tool selection (search_nodes) 62 | 2. **eval-002**: nodeType format (nodes-base.* prefix) 63 | 3. **eval-003**: Validation workflow (profiles) 64 | 4. **eval-004**: essentials vs info (5KB vs 100KB) 65 | 5. **eval-005**: Smart parameters (branch, case) 66 | 67 | ## Key Features 68 | 69 | ✅ **Tool Selection Guide**: Which tool to use for each task 70 | ✅ **Common Patterns**: Most effective tool usage sequences 71 | ✅ **Format Guidance**: nodeType format differences explained 72 | ✅ **Smart Parameters**: Semantic branch/case routing for multi-output nodes 73 | ✅ **Auto-Sanitization**: Explains automatic validation fixes 74 | ✅ **Comprehensive**: Covers all 40+ MCP tools 75 | 76 | ## Files 77 | 78 | - **SKILL.md** (480 lines) - Core tool usage guide 79 | - **SEARCH_GUIDE.md** (220 lines) - Node discovery tools 80 | - **VALIDATION_GUIDE.md** (250 lines) - Validation tools and profiles 81 | - **WORKFLOW_GUIDE.md** (200 lines) - Workflow management 82 | - **README.md** (this file) - Skill metadata 83 | 84 | ## What You'll Learn 85 | 86 | - Correct nodeType formats (nodes-base.* for search tools) 87 | - When to use get_node_essentials vs get_node_info 88 | - How to use validation profiles effectively 89 | - Smart parameters for multi-output nodes (IF/Switch) 90 | - Common tool usage patterns and workflows 91 | 92 | ## Last Updated 93 | 94 | 2025-10-20 95 | 96 | --- 97 | 98 | **Part of**: n8n-skills repository 99 | **Conceived by**: Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en) 100 | -------------------------------------------------------------------------------- /skills/n8n-mcp-tools-expert/SEARCH_GUIDE.md: -------------------------------------------------------------------------------- 1 | # Node Discovery Tools Guide 2 | 3 | Complete guide for finding and understanding n8n nodes. 4 | 5 | --- 6 | 7 | ## search_nodes (START HERE!) 8 | 9 | **Success Rate**: 99.9% | **Speed**: <20ms 10 | 11 | **Use when**: You know what you're looking for (keyword, service, use case) 12 | 13 | **Syntax**: 14 | ```javascript 15 | search_nodes({ 16 | query: "slack", // Required: search keywords 17 | mode: "OR", // Optional: OR (default), AND, FUZZY 18 | limit: 20 // Optional: max results (default 20, max 100) 19 | }) 20 | ``` 21 | 22 | **Returns**: 23 | ```javascript 24 | { 25 | "query": "slack", 26 | "results": [ 27 | { 28 | "nodeType": "nodes-base.slack", // For search/validate tools 29 | "workflowNodeType": "n8n-nodes-base.slack", // For workflow tools 30 | "displayName": "Slack", 31 | "description": "Consume Slack API", 32 | "category": "output", 33 | "relevance": "high" 34 | } 35 | ] 36 | } 37 | ``` 38 | 39 | **Tips**: 40 | - Common searches: webhook, http, database, email, slack, google, ai 41 | - OR mode (default): matches any word 42 | - AND mode: requires all words 43 | - FUZZY mode: typo-tolerant (finds "slak" → Slack) 44 | 45 | --- 46 | 47 | ## get_node_essentials (RECOMMENDED!) 48 | 49 | **Success Rate**: 91.7% | **Speed**: <10ms | **Size**: ~5KB 50 | 51 | **Use when**: You've found the node and need configuration details 52 | 53 | **Syntax**: 54 | ```javascript 55 | get_node_essentials({ 56 | nodeType: "nodes-base.slack", // Required: SHORT prefix format 57 | includeExamples: true // Optional: get real template configs 58 | }) 59 | ``` 60 | 61 | **Returns**: 62 | - Available operations and resources 63 | - Essential properties (10-20 most common) 64 | - Metadata (isAITool, isTrigger, hasCredentials) 65 | - Real examples from templates (if includeExamples: true) 66 | 67 | **Why use this**: 68 | - 5KB vs 100KB+ (get_node_info) 69 | - 91.7% success vs 80% 70 | - <10ms vs slower 71 | - Focused data (no information overload) 72 | 73 | --- 74 | 75 | ## get_node_info (USE SPARINGLY!) 76 | 77 | **Success Rate**: 80% ⚠️ | **Size**: 100KB+ 78 | 79 | **Use when**: 80 | - Debugging complex configuration 81 | - Need complete property schema 82 | - Exploring advanced features 83 | 84 | **Syntax**: 85 | ```javascript 86 | get_node_info({ 87 | nodeType: "nodes-base.httpRequest" 88 | }) 89 | ``` 90 | 91 | **Warning**: 20% failure rate! Use get_node_essentials instead for most cases. 92 | 93 | **Better alternatives**: 94 | 1. get_node_essentials - operations list 95 | 2. get_node_documentation - readable docs 96 | 3. search_node_properties - specific property 97 | 98 | --- 99 | 100 | ## list_nodes (BROWSE BY CATEGORY) 101 | 102 | **Success Rate**: 99.6% | **Speed**: <20ms 103 | 104 | **Use when**: Exploring by category or listing all nodes 105 | 106 | **Syntax**: 107 | ```javascript 108 | list_nodes({ 109 | category: "trigger", // Optional: filter by category 110 | package: "n8n-nodes-base", // Optional: filter by package 111 | limit: 200 // Optional: default 50 112 | }) 113 | ``` 114 | 115 | **Categories**: 116 | - `trigger` - Webhook, Schedule, Manual, etc. (108 total) 117 | - `transform` - Code, Set, Function, etc. 118 | - `output` - HTTP Request, Email, Slack, etc. 119 | - `input` - Read data sources 120 | - `AI` - AI-capable nodes (270 total) 121 | 122 | **Packages**: 123 | - `n8n-nodes-base` - Core nodes (437 total) 124 | - `@n8n/n8n-nodes-langchain` - AI nodes (100 total) 125 | 126 | --- 127 | 128 | ## search_node_properties (FIND SPECIFIC FIELDS) 129 | 130 | **Use when**: Looking for specific property in a node 131 | 132 | **Syntax**: 133 | ```javascript 134 | search_node_properties({ 135 | nodeType: "nodes-base.httpRequest", 136 | query: "auth" // Find authentication properties 137 | }) 138 | ``` 139 | 140 | **Returns**: Property paths and descriptions matching query 141 | 142 | **Common searches**: auth, header, body, json, url, method 143 | 144 | --- 145 | 146 | ## get_node_documentation (READABLE DOCS) 147 | 148 | **Coverage**: 88% of nodes (470/537) 149 | 150 | **Use when**: Need human-readable documentation with examples 151 | 152 | **Syntax**: 153 | ```javascript 154 | get_node_documentation({ 155 | nodeType: "nodes-base.slack" 156 | }) 157 | ``` 158 | 159 | **Returns**: Formatted docs with: 160 | - Usage examples 161 | - Authentication guide 162 | - Common patterns 163 | - Best practices 164 | 165 | **Note**: Better than raw schema for learning! 166 | 167 | --- 168 | 169 | ## Common Workflow: Finding & Configuring 170 | 171 | ``` 172 | Step 1: Search 173 | search_nodes({query: "slack"}) 174 | → Returns: nodes-base.slack 175 | 176 | Step 2: Get Operations (18s avg thinking time) 177 | get_node_essentials({ 178 | nodeType: "nodes-base.slack", 179 | includeExamples: true 180 | }) 181 | → Returns: operations list + example configs 182 | 183 | Step 3: Validate Config 184 | validate_node_operation({ 185 | nodeType: "nodes-base.slack", 186 | config: {resource: "channel", operation: "create"}, 187 | profile: "runtime" 188 | }) 189 | → Returns: validation result 190 | 191 | Step 4: Use in Workflow 192 | (Configuration ready!) 193 | ``` 194 | 195 | **Most common pattern**: search → essentials (18s average) 196 | 197 | --- 198 | 199 | ## Quick Comparison 200 | 201 | | Tool | When to Use | Success | Speed | Size | 202 | |------|-------------|---------|-------|------| 203 | | search_nodes | Find by keyword | 99.9% | <20ms | Small | 204 | | get_node_essentials | Get config | 91.7% | <10ms | 5KB | 205 | | get_node_info | Full schema | 80% ⚠️ | Slow | 100KB+ | 206 | | list_nodes | Browse category | 99.6% | <20ms | Small | 207 | | get_node_documentation | Learn usage | N/A | Fast | Medium | 208 | 209 | **Best Practice**: search → essentials → validate 210 | 211 | --- 212 | 213 | ## nodeType Format (CRITICAL!) 214 | 215 | **Search/Validate Tools** (SHORT prefix): 216 | ```javascript 217 | "nodes-base.slack" 218 | "nodes-base.httpRequest" 219 | "nodes-langchain.agent" 220 | ``` 221 | 222 | **Workflow Tools** (FULL prefix): 223 | ```javascript 224 | "n8n-nodes-base.slack" 225 | "n8n-nodes-base.httpRequest" 226 | "@n8n/n8n-nodes-langchain.agent" 227 | ``` 228 | 229 | **Conversion**: search_nodes returns BOTH formats: 230 | ```javascript 231 | { 232 | "nodeType": "nodes-base.slack", // Use with essentials 233 | "workflowNodeType": "n8n-nodes-base.slack" // Use with create_workflow 234 | } 235 | ``` 236 | 237 | --- 238 | 239 | ## Related 240 | 241 | - [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) - Validate node configs 242 | - [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) - Use nodes in workflows 243 | -------------------------------------------------------------------------------- /skills/n8n-mcp-tools-expert/VALIDATION_GUIDE.md: -------------------------------------------------------------------------------- 1 | # Configuration Validation Tools Guide 2 | 3 | Complete guide for validating node configurations and workflows. 4 | 5 | --- 6 | 7 | ## Validation Philosophy 8 | 9 | **Validate early, validate often** 10 | 11 | Validation is typically iterative with validate → fix cycles 12 | 13 | --- 14 | 15 | ## validate_node_minimal (QUICK CHECK) 16 | 17 | **Success Rate**: 97.4% | **Speed**: <100ms 18 | 19 | **Use when**: Checking what fields are required 20 | 21 | **Syntax**: 22 | ```javascript 23 | validate_node_minimal({ 24 | nodeType: "nodes-base.slack", 25 | config: {} // Empty to see all required fields 26 | }) 27 | ``` 28 | 29 | **Returns**: 30 | ```javascript 31 | { 32 | "valid": true, // Usually true (most nodes have no strict requirements) 33 | "missingRequiredFields": [] 34 | } 35 | ``` 36 | 37 | **When to use**: Planning configuration, seeing basic requirements 38 | 39 | --- 40 | 41 | ## validate_node_operation (FULL VALIDATION) 42 | 43 | **Success Rate**: Varies | **Speed**: <100ms 44 | 45 | **Use when**: Validating actual configuration before deployment 46 | 47 | **Syntax**: 48 | ```javascript 49 | validate_node_operation({ 50 | nodeType: "nodes-base.slack", 51 | config: { 52 | resource: "channel", 53 | operation: "create", 54 | channel: "general" 55 | }, 56 | profile: "runtime" // Recommended! 57 | }) 58 | ``` 59 | 60 | ### Validation Profiles 61 | 62 | Choose based on your stage: 63 | 64 | **minimal** - Only required fields 65 | - Fastest 66 | - Most permissive 67 | - Use: Quick checks during editing 68 | 69 | **runtime** - Values + types (**RECOMMENDED**) 70 | - Balanced validation 71 | - Catches real errors 72 | - Use: Pre-deployment validation 73 | 74 | **ai-friendly** - Reduce false positives 75 | - For AI-generated configs 76 | - Tolerates minor issues 77 | - Use: When AI configures nodes 78 | 79 | **strict** - Maximum validation 80 | - Strictest rules 81 | - May have false positives 82 | - Use: Production deployment 83 | 84 | ### Returns 85 | 86 | ```javascript 87 | { 88 | "valid": false, 89 | "errors": [ 90 | { 91 | "type": "missing_required", 92 | "property": "name", 93 | "message": "Channel name is required", 94 | "fix": "Provide a channel name (lowercase, no spaces, 1-80 characters)" 95 | } 96 | ], 97 | "warnings": [ 98 | { 99 | "type": "best_practice", 100 | "property": "errorHandling", 101 | "message": "Slack API can have rate limits", 102 | "suggestion": "Add onError: 'continueRegularOutput' with retryOnFail" 103 | } 104 | ], 105 | "suggestions": [], 106 | "summary": { 107 | "hasErrors": true, 108 | "errorCount": 1, 109 | "warningCount": 1 110 | } 111 | } 112 | ``` 113 | 114 | ### Error Types 115 | 116 | - `missing_required` - Must fix 117 | - `invalid_value` - Must fix 118 | - `type_mismatch` - Must fix 119 | - `best_practice` - Should fix (warning) 120 | - `suggestion` - Optional improvement 121 | 122 | --- 123 | 124 | ## validate_workflow (STRUCTURE VALIDATION) 125 | 126 | **Success Rate**: 95.5% | **Speed**: 100-500ms 127 | 128 | **Use when**: Checking complete workflow before execution 129 | 130 | **Syntax**: 131 | ```javascript 132 | validate_workflow({ 133 | workflow: { 134 | nodes: [...], // Array of nodes 135 | connections: {...} // Connections object 136 | }, 137 | options: { 138 | validateNodes: true, // Default: true 139 | validateConnections: true, // Default: true 140 | validateExpressions: true, // Default: true 141 | profile: "runtime" // For node validation 142 | } 143 | }) 144 | ``` 145 | 146 | **Validates**: 147 | - Node configurations 148 | - Connection validity (no broken references) 149 | - Expression syntax ({{ }} patterns) 150 | - Workflow structure (triggers, flow) 151 | - AI connections (8 types) 152 | 153 | **Returns**: Comprehensive validation report with errors, warnings, suggestions 154 | 155 | --- 156 | 157 | ## Validation Loop Pattern 158 | 159 | **Typical cycle**: 23s thinking, 58s fixing 160 | 161 | ``` 162 | 1. Configure node 163 | ↓ 164 | 2. validate_node_operation (23s thinking about errors) 165 | ↓ 166 | 3. Fix errors 167 | ↓ 168 | 4. validate_node_operation again (58s fixing) 169 | ↓ 170 | 5. Repeat until valid 171 | ``` 172 | 173 | **Example**: 174 | ```javascript 175 | // Iteration 1 176 | let config = { 177 | resource: "channel", 178 | operation: "create" 179 | }; 180 | 181 | const result1 = validate_node_operation({ 182 | nodeType: "nodes-base.slack", 183 | config, 184 | profile: "runtime" 185 | }); 186 | // → Error: Missing "name" 187 | 188 | // Iteration 2 (~58s later) 189 | config.name = "general"; 190 | 191 | const result2 = validate_node_operation({ 192 | nodeType: "nodes-base.slack", 193 | config, 194 | profile: "runtime" 195 | }); 196 | // → Valid! 197 | ``` 198 | 199 | --- 200 | 201 | ## Auto-Sanitization System 202 | 203 | **When it runs**: On ANY workflow update (create or update_partial) 204 | 205 | **What it fixes** (automatically on ALL nodes): 206 | 1. Binary operators (equals, contains, greaterThan) → removes `singleValue` 207 | 2. Unary operators (isEmpty, isNotEmpty, true, false) → adds `singleValue: true` 208 | 3. Invalid operator structures → corrects to proper format 209 | 4. IF v2.2+ nodes → adds complete `conditions.options` metadata 210 | 5. Switch v3.2+ nodes → adds complete `conditions.options` for all rules 211 | 212 | **What it CANNOT fix**: 213 | - Broken connections (references to non-existent nodes) 214 | - Branch count mismatches (3 Switch rules but only 2 outputs) 215 | - Paradoxical corrupt states (API returns corrupt, rejects updates) 216 | 217 | **Example**: 218 | ```javascript 219 | // Before auto-sanitization 220 | { 221 | "type": "boolean", 222 | "operation": "equals", 223 | "singleValue": true // ❌ Binary operators shouldn't have this 224 | } 225 | 226 | // After auto-sanitization (automatic!) 227 | { 228 | "type": "boolean", 229 | "operation": "equals" 230 | // singleValue removed automatically 231 | } 232 | ``` 233 | 234 | **Recovery tools**: 235 | - `cleanStaleConnections` operation - removes broken connections 236 | - `n8n_autofix_workflow` - preview/apply fixes 237 | 238 | --- 239 | 240 | ## Binary vs Unary Operators 241 | 242 | **Binary operators** (compare two values): 243 | - equals, notEquals, contains, notContains 244 | - greaterThan, lessThan, startsWith, endsWith 245 | - **Must NOT have** `singleValue: true` 246 | 247 | **Unary operators** (check single value): 248 | - isEmpty, isNotEmpty, true, false 249 | - **Must have** `singleValue: true` 250 | 251 | **Auto-sanitization fixes these automatically!** 252 | 253 | --- 254 | 255 | ## Handling Validation Errors 256 | 257 | ### Process 258 | 259 | ``` 260 | 1. Read error message carefully 261 | 2. Check if it's a known false positive 262 | 3. Fix real errors 263 | 4. Validate again 264 | 5. Iterate until clean 265 | ``` 266 | 267 | ### Common Errors 268 | 269 | **"Required field missing"** 270 | → Add the field with appropriate value 271 | 272 | **"Invalid value"** 273 | → Check allowed values in essentials/documentation 274 | 275 | **"Type mismatch"** 276 | → Convert to correct type (string/number/boolean) 277 | 278 | **"Cannot have singleValue"** 279 | → Auto-sanitization will fix on next update 280 | 281 | **"Missing operator metadata"** 282 | → Auto-sanitization will fix on next update 283 | 284 | ### False Positives 285 | 286 | Some validation warnings may be acceptable: 287 | - Optional best practices 288 | - Node-specific edge cases 289 | - Profile-dependent issues 290 | 291 | Use **ai-friendly** profile to reduce false positives. 292 | 293 | --- 294 | 295 | ## Best Practices 296 | 297 | ### ✅ Do 298 | 299 | - Use **runtime** profile for pre-deployment 300 | - Validate after every configuration change 301 | - Fix errors immediately (avg 58s) 302 | - Iterate validation loop 303 | - Trust auto-sanitization for operator issues 304 | - Use minimal profile for quick checks 305 | - Complete workflow activation manually in n8n UI (API/MCP cannot activate workflows) 306 | 307 | ### ❌ Don't 308 | 309 | - Skip validation before deployment 310 | - Ignore error messages 311 | - Use strict profile during development (too many warnings) 312 | - Assume validation passed (check result) 313 | - Try to manually fix auto-sanitization issues 314 | 315 | --- 316 | 317 | ## Example: Complete Validation Workflow 318 | 319 | ```javascript 320 | // Step 1: Get node requirements 321 | validate_node_minimal({ 322 | nodeType: "nodes-base.slack", 323 | config: {} 324 | }); 325 | // → Know what's required 326 | 327 | // Step 2: Configure node 328 | const config = { 329 | resource: "message", 330 | operation: "post", 331 | channel: "#general", 332 | text: "Hello!" 333 | }; 334 | 335 | // Step 3: Validate configuration 336 | const result = validate_node_operation({ 337 | nodeType: "nodes-base.slack", 338 | config, 339 | profile: "runtime" 340 | }); 341 | 342 | // Step 4: Check result 343 | if (result.valid) { 344 | console.log("✅ Configuration valid!"); 345 | } else { 346 | console.log("❌ Errors:", result.errors); 347 | // Fix and validate again 348 | } 349 | 350 | // Step 5: Validate in workflow context 351 | validate_workflow({ 352 | workflow: { 353 | nodes: [{...config as node...}], 354 | connections: {...} 355 | } 356 | }); 357 | ``` 358 | 359 | --- 360 | 361 | ## Summary 362 | 363 | **Key Points**: 364 | 1. Use **runtime** profile (balanced validation) 365 | 2. Validation loop: validate → fix (58s) → validate again 366 | 3. Auto-sanitization fixes operator structures automatically 367 | 4. Binary operators ≠ singleValue, Unary operators = singleValue: true 368 | 5. Iterate until validation passes 369 | 370 | **Tool Selection**: 371 | - **validate_node_minimal**: Quick check 372 | - **validate_node_operation**: Full config validation (**use this!**) 373 | - **validate_workflow**: Complete workflow check 374 | 375 | **Related**: 376 | - [SEARCH_GUIDE.md](SEARCH_GUIDE.md) - Find nodes 377 | - [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) - Build workflows 378 | -------------------------------------------------------------------------------- /skills/n8n-mcp-tools-expert/WORKFLOW_GUIDE.md: -------------------------------------------------------------------------------- 1 | # Workflow Management Tools Guide 2 | 3 | Complete guide for creating, updating, and managing n8n workflows. 4 | 5 | --- 6 | 7 | ## Tool Availability 8 | 9 | **⚠️ Requires n8n API**: All tools in this guide need `N8N_API_URL` and `N8N_API_KEY` configured. 10 | 11 | If unavailable, use template examples and validation-only workflows. 12 | 13 | --- 14 | 15 | ## n8n_create_workflow 16 | 17 | **Success Rate**: 96.8% | **Speed**: 100-500ms 18 | 19 | **Use when**: Creating new workflows from scratch 20 | 21 | **Syntax**: 22 | ```javascript 23 | n8n_create_workflow({ 24 | name: "Webhook to Slack", // Required 25 | nodes: [...], // Required: array of nodes 26 | connections: {...}, // Required: connections object 27 | settings: {...} // Optional: workflow settings 28 | }) 29 | ``` 30 | 31 | **Returns**: Created workflow with ID 32 | 33 | **Example**: 34 | ```javascript 35 | n8n_create_workflow({ 36 | name: "Webhook to Slack", 37 | nodes: [ 38 | { 39 | id: "webhook-1", 40 | name: "Webhook", 41 | type: "n8n-nodes-base.webhook", // Full prefix! 42 | typeVersion: 1, 43 | position: [250, 300], 44 | parameters: { 45 | path: "slack-notify", 46 | httpMethod: "POST" 47 | } 48 | }, 49 | { 50 | id: "slack-1", 51 | name: "Slack", 52 | type: "n8n-nodes-base.slack", 53 | typeVersion: 1, 54 | position: [450, 300], 55 | parameters: { 56 | resource: "message", 57 | operation: "post", 58 | channel: "#general", 59 | text: "={{$json.body.message}}" 60 | } 61 | } 62 | ], 63 | connections: { 64 | "Webhook": { 65 | "main": [[{node: "Slack", type: "main", index: 0}]] 66 | } 67 | } 68 | }) 69 | ``` 70 | 71 | **Notes**: 72 | - Workflows created **inactive** (must activate separately) 73 | - Auto-sanitization runs on creation 74 | - Validate before creating for best results 75 | 76 | --- 77 | 78 | ## n8n_update_partial_workflow (MOST USED!) 79 | 80 | **Success Rate**: 99.0% | **Speed**: 50-200ms | **Uses**: 38,287 (most used tool!) 81 | 82 | **Use when**: Making incremental changes to workflows 83 | 84 | **Common pattern**: 56s average between edits (iterative building!) 85 | 86 | ### 15 Operation Types 87 | 88 | **Node Operations** (6 types): 89 | 1. `addNode` - Add new node 90 | 2. `removeNode` - Remove node by ID or name 91 | 3. `updateNode` - Update node properties 92 | 4. `moveNode` - Change position 93 | 5. `enableNode` - Enable disabled node 94 | 6. `disableNode` - Disable active node 95 | 96 | **Connection Operations** (5 types): 97 | 7. `addConnection` - Connect nodes 98 | 8. `removeConnection` - Remove connection 99 | 9. `rewireConnection` - Change target 100 | 10. `cleanStaleConnections` - Auto-remove broken connections 101 | 11. `replaceConnections` - Replace entire connections object 102 | 103 | **Metadata Operations** (4 types): 104 | 12. `updateSettings` - Workflow settings 105 | 13. `updateName` - Rename workflow 106 | 14. `addTag` - Add tag 107 | 15. `removeTag` - Remove tag 108 | 109 | ### Smart Parameters (NEW!) 110 | 111 | **IF nodes** - Use semantic branch names: 112 | ```javascript 113 | { 114 | type: "addConnection", 115 | source: "IF", 116 | target: "True Handler", 117 | branch: "true" // Instead of sourceIndex: 0 118 | } 119 | 120 | { 121 | type: "addConnection", 122 | source: "IF", 123 | target: "False Handler", 124 | branch: "false" // Instead of sourceIndex: 1 125 | } 126 | ``` 127 | 128 | **Switch nodes** - Use semantic case numbers: 129 | ```javascript 130 | { 131 | type: "addConnection", 132 | source: "Switch", 133 | target: "Handler A", 134 | case: 0 135 | } 136 | 137 | { 138 | type: "addConnection", 139 | source: "Switch", 140 | target: "Handler B", 141 | case: 1 142 | } 143 | ``` 144 | 145 | ### AI Connection Types (8 types) 146 | 147 | **Full support** for AI workflows: 148 | 149 | ```javascript 150 | // Language Model 151 | { 152 | type: "addConnection", 153 | source: "OpenAI Chat Model", 154 | target: "AI Agent", 155 | sourceOutput: "ai_languageModel" 156 | } 157 | 158 | // Tool 159 | { 160 | type: "addConnection", 161 | source: "HTTP Request Tool", 162 | target: "AI Agent", 163 | sourceOutput: "ai_tool" 164 | } 165 | 166 | // Memory 167 | { 168 | type: "addConnection", 169 | source: "Window Buffer Memory", 170 | target: "AI Agent", 171 | sourceOutput: "ai_memory" 172 | } 173 | 174 | // All 8 types: 175 | // - ai_languageModel 176 | // - ai_tool 177 | // - ai_memory 178 | // - ai_outputParser 179 | // - ai_embedding 180 | // - ai_vectorStore 181 | // - ai_document 182 | // - ai_textSplitter 183 | ``` 184 | 185 | ### Example Usage 186 | 187 | ```javascript 188 | n8n_update_partial_workflow({ 189 | id: "workflow-id", 190 | operations: [ 191 | // Add node 192 | { 193 | type: "addNode", 194 | node: { 195 | name: "Transform", 196 | type: "n8n-nodes-base.set", 197 | position: [400, 300], 198 | parameters: {} 199 | } 200 | }, 201 | // Connect it (smart parameter) 202 | { 203 | type: "addConnection", 204 | source: "IF", 205 | target: "Transform", 206 | branch: "true" // Clear and semantic! 207 | } 208 | ] 209 | }) 210 | ``` 211 | 212 | ### Cleanup & Recovery 213 | 214 | **cleanStaleConnections** - Remove broken connections: 215 | ```javascript 216 | { 217 | type: "cleanStaleConnections" 218 | } 219 | ``` 220 | 221 | **Best-effort mode** - Apply what works: 222 | ```javascript 223 | n8n_update_partial_workflow({ 224 | id: "workflow-id", 225 | operations: [...], 226 | continueOnError: true // Don't fail if some operations fail 227 | }) 228 | ``` 229 | 230 | --- 231 | 232 | ## n8n_validate_workflow (by ID) 233 | 234 | **Success Rate**: 99.7% | **Speed**: Network-dependent 235 | 236 | **Use when**: Validating workflow stored in n8n 237 | 238 | **Syntax**: 239 | ```javascript 240 | n8n_validate_workflow({ 241 | id: "workflow-id", 242 | options: { 243 | validateNodes: true, 244 | validateConnections: true, 245 | validateExpressions: true, 246 | profile: "runtime" 247 | } 248 | }) 249 | ``` 250 | 251 | **Returns**: Same as validate_workflow (from validation guide) 252 | 253 | --- 254 | 255 | ## Workflow Lifecycle 256 | 257 | **Standard pattern**: 258 | ``` 259 | 1. CREATE 260 | n8n_create_workflow({...}) 261 | → Returns workflow ID 262 | 263 | 2. VALIDATE 264 | n8n_validate_workflow({id}) 265 | → Check for errors 266 | 267 | 3. EDIT (iterative! 56s avg between edits) 268 | n8n_update_partial_workflow({id, operations: [...]}) 269 | → Make changes 270 | 271 | 4. VALIDATE AGAIN 272 | n8n_validate_workflow({id}) 273 | → Verify changes 274 | 275 | 5. ACTIVATE (when ready) 276 | ⚠️ **IMPORTANT LIMITATION**: Workflow activation is NOT supported via API or MCP. 277 | Users must activate workflows manually in the n8n UI. 278 | 279 | The following operation will NOT activate the workflow: 280 | n8n_update_partial_workflow({id, operations: [{ 281 | type: "updateSettings", 282 | settings: {active: true} 283 | }]}) 284 | 285 | **Manual activation required**: Navigate to workflow in n8n UI and toggle activation. 286 | 287 | 6. MONITOR 288 | n8n_list_executions({workflowId: id}) 289 | n8n_get_execution({id: execution_id}) 290 | ``` 291 | 292 | **Deployment Note**: After creating and validating workflows via MCP, inform users they must: 293 | 1. Open the workflow in n8n UI (provide workflow ID) 294 | 2. Review the workflow configuration 295 | 3. Manually activate the workflow using the activation toggle 296 | 297 | --- 298 | 299 | ## Common Patterns from Telemetry 300 | 301 | ### Pattern 1: Edit → Validate (7,841 occurrences) 302 | 303 | ```javascript 304 | // Edit 305 | n8n_update_partial_workflow({...}) 306 | // ↓ 23s (thinking about what to validate) 307 | // Validate 308 | n8n_validate_workflow({id}) 309 | ``` 310 | 311 | ### Pattern 2: Validate → Fix (7,266 occurrences) 312 | 313 | ```javascript 314 | // Validate 315 | n8n_validate_workflow({id}) 316 | // ↓ 58s (fixing errors) 317 | // Fix 318 | n8n_update_partial_workflow({...}) 319 | ``` 320 | 321 | ### Pattern 3: Iterative Building (31,464 occurrences) 322 | 323 | ```javascript 324 | update → update → update → ... (56s avg between edits) 325 | ``` 326 | 327 | **This shows**: Workflows are built **iteratively**, not in one shot! 328 | 329 | --- 330 | 331 | ## Retrieval Tools 332 | 333 | ### n8n_get_workflow 334 | ```javascript 335 | n8n_get_workflow({id: "workflow-id"}) 336 | // Returns: Complete workflow JSON 337 | ``` 338 | 339 | ### n8n_get_workflow_structure 340 | ```javascript 341 | n8n_get_workflow_structure({id: "workflow-id"}) 342 | // Returns: Nodes + connections only (no parameters) 343 | ``` 344 | 345 | ### n8n_get_workflow_minimal 346 | ```javascript 347 | n8n_get_workflow_minimal({id: "workflow-id"}) 348 | // Returns: ID, name, active, tags only (fast!) 349 | ``` 350 | 351 | ### n8n_list_workflows 352 | ```javascript 353 | n8n_list_workflows({ 354 | active: true, // Optional: filter by status 355 | limit: 100, // Optional: max results 356 | tags: ["production"] // Optional: filter by tags 357 | }) 358 | ``` 359 | 360 | --- 361 | 362 | ## Best Practices 363 | 364 | ### ✅ Do 365 | 366 | - Build workflows **iteratively** (avg 56s between edits) 367 | - Use **smart parameters** (branch, case) for clarity 368 | - Validate **after** significant changes 369 | - Use **atomic mode** (default) for critical updates 370 | - Specify **sourceOutput** for AI connections 371 | - Clean stale connections after node renames/deletions 372 | 373 | ### ❌ Don't 374 | 375 | - Try to build workflows in one shot 376 | - Use sourceIndex when branch/case available 377 | - Skip validation before activation 378 | - Forget to test workflows after creation 379 | - Ignore auto-sanitization behavior 380 | 381 | --- 382 | 383 | ## Summary 384 | 385 | **Most Important**: 386 | 1. **n8n_update_partial_workflow** is most-used tool (38,287 uses, 99.0% success) 387 | 2. Workflows built **iteratively** (56s avg between edits) 388 | 3. Use **smart parameters** (branch="true", case=0) for clarity 389 | 4. **AI connections** supported (8 types with sourceOutput) 390 | 5. **Auto-sanitization** runs on all operations 391 | 6. Validate frequently (7,841 edit → validate patterns) 392 | 393 | **Related**: 394 | - [SEARCH_GUIDE.md](SEARCH_GUIDE.md) - Find nodes to add 395 | - [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) - Validate workflows 396 | -------------------------------------------------------------------------------- /skills/n8n-node-configuration/README.md: -------------------------------------------------------------------------------- 1 | # n8n Node Configuration 2 | 3 | Expert guidance for operation-aware node configuration with property dependencies. 4 | 5 | ## Overview 6 | 7 | **Skill Name**: n8n Node Configuration 8 | **Priority**: Medium 9 | **Purpose**: Teach operation-aware configuration with progressive discovery and dependency awareness 10 | 11 | ## The Problem This Solves 12 | 13 | Node configuration patterns: 14 | 15 | - get_node_essentials is the primary discovery tool (18s avg from search → essentials) 16 | - 91.7% success rate with essentials-based configuration 17 | - 56 seconds average between configuration edits 18 | 19 | **Key insight**: Most configurations only need essentials, not full schema! 20 | 21 | ## What This Skill Teaches 22 | 23 | ### Core Concepts 24 | 25 | 1. **Operation-Aware Configuration** 26 | - Resource + operation determine required fields 27 | - Different operations = different requirements 28 | - Always check requirements when changing operation 29 | 30 | 2. **Property Dependencies** 31 | - Fields appear/disappear based on other field values 32 | - displayOptions control visibility 33 | - Conditional required fields 34 | - Understanding dependency chains 35 | 36 | 3. **Progressive Discovery** 37 | - Start with get_node_essentials (91.7% success) 38 | - Escalate to get_property_dependencies if needed 39 | - Use get_node_info only when necessary 40 | - Right tool for right job 41 | 42 | 4. **Configuration Workflow** 43 | - Identify → Discover → Configure → Validate → Iterate 44 | - Average 2-3 validation cycles 45 | - Read errors for dependency hints 46 | - 56 seconds between edits average 47 | 48 | 5. **Common Patterns** 49 | - Resource/operation nodes (Slack, Sheets) 50 | - HTTP-based nodes (HTTP Request, Webhook) 51 | - Database nodes (Postgres, MySQL) 52 | - Conditional logic nodes (IF, Switch) 53 | 54 | ## File Structure 55 | 56 | ``` 57 | n8n-node-configuration/ 58 | ├── SKILL.md (692 lines) 59 | │ Main configuration guide 60 | │ - Configuration philosophy (progressive disclosure) 61 | │ - Core concepts (operation-aware, dependencies) 62 | │ - Configuration workflow (8-step process) 63 | │ - get_node_essentials vs get_node_info 64 | │ - Property dependencies deep dive 65 | │ - Common node patterns (4 categories) 66 | │ - Operation-specific examples 67 | │ - Conditional requirements 68 | │ - Anti-patterns and best practices 69 | │ 70 | ├── DEPENDENCIES.md (671 lines) 71 | │ Property dependencies reference 72 | │ - displayOptions mechanism 73 | │ - show vs hide rules 74 | │ - Multiple conditions (AND logic) 75 | │ - Multiple values (OR logic) 76 | │ - 4 common dependency patterns 77 | │ - Using get_property_dependencies 78 | │ - Complex dependency examples 79 | │ - Nested dependencies 80 | │ - Auto-sanitization interaction 81 | │ - Troubleshooting guide 82 | │ - Advanced patterns 83 | │ 84 | ├── OPERATION_PATTERNS.md (783 lines) 85 | │ Common configurations by node type 86 | │ - HTTP Request (GET/POST/PUT/DELETE) 87 | │ - Webhook (basic/auth/response) 88 | │ - Slack (post/update/create) 89 | │ - Gmail (send/get) 90 | │ - Postgres (query/insert/update) 91 | │ - Set (values/mapping) 92 | │ - Code (per-item/all-items) 93 | │ - IF (string/number/boolean) 94 | │ - Switch (rules/fallback) 95 | │ - OpenAI (chat completion) 96 | │ - Schedule (daily/interval/cron) 97 | │ - Gotchas and tips for each 98 | │ 99 | └── README.md (this file) 100 | Skill metadata and statistics 101 | ``` 102 | 103 | **Total**: ~2,146 lines across 4 files + 4 evaluations 104 | 105 | ## Usage Statistics 106 | 107 | Configuration metrics: 108 | 109 | | Metric | Value | Insight | 110 | |---|---|---| 111 | | get_node_essentials | Primary tool | Most popular discovery pattern | 112 | | Success rate (essentials) | 91.7% | Essentials sufficient for most | 113 | | Avg time search→essentials | 18 seconds | Fast discovery workflow | 114 | | Avg time between edits | 56 seconds | Iterative configuration | 115 | 116 | ## Tool Usage Pattern 117 | 118 | **Most common discovery pattern**: 119 | ``` 120 | search_nodes → get_node_essentials (18s average) 121 | ``` 122 | 123 | **Configuration cycle**: 124 | ``` 125 | get_node_essentials → configure → validate → iterate (56s avg per edit) 126 | ``` 127 | 128 | ## Key Insights 129 | 130 | ### 1. Progressive Disclosure Works 131 | 132 | **91.7% success rate** with get_node_essentials proves most configurations don't need full schema. 133 | 134 | **Strategy**: 135 | 1. Start with essentials 136 | 2. Escalate to dependencies if stuck 137 | 3. Use full schema only when necessary 138 | 139 | ### 2. Operations Determine Requirements 140 | 141 | **Same node, different operation = different requirements** 142 | 143 | Example: Slack message 144 | - `operation="post"` → needs channel + text 145 | - `operation="update"` → needs messageId + text (different!) 146 | 147 | ### 3. Dependencies Control Visibility 148 | 149 | **Fields appear/disappear based on other values** 150 | 151 | Example: HTTP Request 152 | - `method="GET"` → body hidden 153 | - `method="POST"` + `sendBody=true` → body required 154 | 155 | ### 4. Configuration is Iterative 156 | 157 | **Average 56 seconds between edits** shows configuration is iterative, not one-shot. 158 | 159 | **Normal workflow**: 160 | 1. Configure minimal 161 | 2. Validate → error 162 | 3. Add missing field 163 | 4. Validate → error 164 | 5. Adjust value 165 | 6. Validate → valid ✅ 166 | 167 | ### 5. Common Gotchas Exist 168 | 169 | **Top 5 gotchas** from patterns: 170 | 1. Webhook data under `$json.body` (not `$json`) 171 | 2. POST needs `sendBody: true` 172 | 3. Slack channel format (`#name`) 173 | 4. SQL parameterized queries (injection prevention) 174 | 5. Timezone must be explicit (schedule nodes) 175 | 176 | ## Usage Examples 177 | 178 | ### Example 1: Basic Configuration Flow 179 | 180 | ```javascript 181 | // Step 1: Get essentials 182 | const info = get_node_essentials({ 183 | nodeType: "nodes-base.slack" 184 | }); 185 | 186 | // Step 2: Configure for operation 187 | { 188 | "resource": "message", 189 | "operation": "post", 190 | "channel": "#general", 191 | "text": "Hello!" 192 | } 193 | 194 | // Step 3: Validate 195 | validate_node_operation({...}); 196 | // ✅ Valid! 197 | ``` 198 | 199 | ### Example 2: Handling Dependencies 200 | 201 | ```javascript 202 | // Step 1: Configure HTTP POST 203 | { 204 | "method": "POST", 205 | "url": "https://api.example.com/create" 206 | } 207 | 208 | // Step 2: Validate → Error: "sendBody required" 209 | // Step 3: Check dependencies 210 | get_property_dependencies({ 211 | nodeType: "nodes-base.httpRequest" 212 | }); 213 | // Shows: body visible when sendBody=true 214 | 215 | // Step 4: Fix 216 | { 217 | "method": "POST", 218 | "url": "https://api.example.com/create", 219 | "sendBody": true, 220 | "body": { 221 | "contentType": "json", 222 | "content": {...} 223 | } 224 | } 225 | // ✅ Valid! 226 | ``` 227 | 228 | ### Example 3: Operation Change 229 | 230 | ```javascript 231 | // Initial config (post operation) 232 | { 233 | "resource": "message", 234 | "operation": "post", 235 | "channel": "#general", 236 | "text": "Hello" 237 | } 238 | 239 | // Change operation 240 | { 241 | "resource": "message", 242 | "operation": "update", // Changed! 243 | // Need to check new requirements 244 | } 245 | 246 | // Get essentials for update operation 247 | get_node_essentials({nodeType: "nodes-base.slack"}); 248 | // Shows: messageId required, channel optional 249 | 250 | // Correct config 251 | { 252 | "resource": "message", 253 | "operation": "update", 254 | "messageId": "1234567890.123456", 255 | "text": "Updated" 256 | } 257 | ``` 258 | 259 | ## When This Skill Activates 260 | 261 | **Trigger phrases**: 262 | - "how to configure" 263 | - "what fields are required" 264 | - "property dependencies" 265 | - "get_node_essentials vs get_node_info" 266 | - "operation-specific" 267 | - "field not visible" 268 | 269 | **Common scenarios**: 270 | - Configuring new nodes 271 | - Understanding required fields 272 | - Field appears/disappears unexpectedly 273 | - Choosing between discovery tools 274 | - Switching operations 275 | - Learning common patterns 276 | 277 | ## Integration with Other Skills 278 | 279 | ### Works With: 280 | - **n8n MCP Tools Expert** - How to call discovery tools correctly 281 | - **n8n Validation Expert** - Interpret missing_required errors 282 | - **n8n Expression Syntax** - Configure expression fields 283 | - **n8n Workflow Patterns** - Apply patterns with proper node config 284 | 285 | ### Complementary: 286 | - Use MCP Tools Expert to learn tool selection 287 | - Use Validation Expert to fix configuration errors 288 | - Use Expression Syntax for dynamic field values 289 | - Use Workflow Patterns to understand node relationships 290 | 291 | ## Testing 292 | 293 | **Evaluations**: 4 test scenarios 294 | 295 | 1. **eval-001-property-dependencies.json** 296 | - Tests understanding of displayOptions 297 | - Guides to get_property_dependencies 298 | - Explains conditional requirements 299 | 300 | 2. **eval-002-operation-specific-config.json** 301 | - Tests operation-aware configuration 302 | - Identifies resource + operation pattern 303 | - References OPERATION_PATTERNS.md 304 | 305 | 3. **eval-003-conditional-fields.json** 306 | - Tests unary vs binary operators 307 | - Explains singleValue dependency 308 | - Mentions auto-sanitization 309 | 310 | 4. **eval-004-essentials-vs-info.json** 311 | - Tests tool selection knowledge 312 | - Explains progressive disclosure 313 | - Provides success rate statistics 314 | 315 | ## Success Metrics 316 | 317 | **Before this skill**: 318 | - Using get_node_info for everything (slow, overwhelming) 319 | - Not understanding property dependencies 320 | - Confused when fields appear/disappear 321 | - Not aware of operation-specific requirements 322 | - Trial and error configuration 323 | 324 | **After this skill**: 325 | - Start with get_node_essentials (91.7% success) 326 | - Understand displayOptions mechanism 327 | - Predict field visibility based on dependencies 328 | - Check requirements when changing operations 329 | - Systematic configuration approach 330 | - Know common patterns by node type 331 | 332 | ## Coverage 333 | 334 | **Node types covered**: Top 20 most-used nodes 335 | 336 | | Category | Nodes | Coverage | 337 | |---|---|---| 338 | | HTTP/API | HTTP Request, Webhook | Complete | 339 | | Communication | Slack, Gmail | Common operations | 340 | | Database | Postgres, MySQL | CRUD operations | 341 | | Transform | Set, Code | All modes | 342 | | Conditional | IF, Switch | All operator types | 343 | | AI | OpenAI | Chat completion | 344 | | Schedule | Schedule Trigger | All modes | 345 | 346 | ## Related Documentation 347 | 348 | - **n8n-mcp MCP Server**: Provides discovery tools 349 | - **n8n Node API**: get_node_essentials, get_property_dependencies, get_node_info 350 | - **n8n Schema**: displayOptions mechanism, property definitions 351 | 352 | ## Version History 353 | 354 | - **v1.0** (2025-10-20): Initial implementation 355 | - SKILL.md with configuration workflow 356 | - DEPENDENCIES.md with displayOptions deep dive 357 | - OPERATION_PATTERNS.md with 20+ node patterns 358 | - 4 evaluation scenarios 359 | 360 | ## Author 361 | 362 | Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en) 363 | 364 | Part of the n8n-skills meta-skill collection. 365 | -------------------------------------------------------------------------------- /skills/n8n-validation-expert/README.md: -------------------------------------------------------------------------------- 1 | # n8n Validation Expert 2 | 3 | Expert guidance for interpreting and fixing n8n validation errors. 4 | 5 | ## Overview 6 | 7 | **Skill Name**: n8n Validation Expert 8 | **Priority**: Medium 9 | **Purpose**: Interpret validation errors and guide systematic fixing through the validation loop 10 | 11 | ## The Problem This Solves 12 | 13 | Validation errors are common: 14 | 15 | - Validation often requires iteration (79% lead to feedback loops) 16 | - **7,841 validate → fix cycles** (avg 23s thinking + 58s fixing) 17 | - **2-3 iterations** average to achieve valid configuration 18 | 19 | **Key insight**: Validation is an iterative process, not a one-shot fix! 20 | 21 | ## What This Skill Teaches 22 | 23 | ### Core Concepts 24 | 25 | 1. **Error Severity Levels** 26 | - Errors (must fix) - Block execution 27 | - Warnings (should fix) - Don't block but indicate issues 28 | - Suggestions (optional) - Nice-to-have improvements 29 | 30 | 2. **The Validation Loop** 31 | - Configure → Validate → Read errors → Fix → Validate again 32 | - Average 2-3 iterations to success 33 | - 23 seconds thinking + 58 seconds fixing per cycle 34 | 35 | 3. **Validation Profiles** 36 | - `minimal` - Quick checks, most permissive 37 | - `runtime` - Recommended for most use cases 38 | - `ai-friendly` - Reduces false positives for AI workflows 39 | - `strict` - Maximum safety, many warnings 40 | 41 | 4. **Auto-Sanitization System** 42 | - Automatically fixes operator structure issues 43 | - Runs on every workflow save 44 | - Fixes binary/unary operator problems 45 | - Adds IF/Switch metadata 46 | 47 | 5. **False Positives** 48 | - Not all warnings need fixing 49 | - 40% of warnings are acceptable in context 50 | - Use `ai-friendly` profile to reduce by 60% 51 | - Document accepted warnings 52 | 53 | ## File Structure 54 | 55 | ``` 56 | n8n-validation-expert/ 57 | ├── SKILL.md (690 lines) 58 | │ Core validation concepts and workflow 59 | │ - Validation philosophy 60 | │ - Error severity levels 61 | │ - The validation loop pattern 62 | │ - Validation profiles 63 | │ - Common error types 64 | │ - Auto-sanitization system 65 | │ - Workflow validation 66 | │ - Recovery strategies 67 | │ - Best practices 68 | │ 69 | ├── ERROR_CATALOG.md (865 lines) 70 | │ Complete error reference with examples 71 | │ - 9 error types with real examples 72 | │ - missing_required (45% of errors) 73 | │ - invalid_value (28%) 74 | │ - type_mismatch (12%) 75 | │ - invalid_expression (8%) 76 | │ - invalid_reference (5%) 77 | │ - operator_structure (2%, auto-fixed) 78 | │ - Recovery patterns 79 | │ - Summary with frequencies 80 | │ 81 | ├── FALSE_POSITIVES.md (669 lines) 82 | │ When warnings are acceptable 83 | │ - Philosophy of warning acceptance 84 | │ - 6 common false positive types 85 | │ - When acceptable vs when to fix 86 | │ - Validation profile strategies 87 | │ - Decision framework 88 | │ - Documentation template 89 | │ - Known n8n issues (#304, #306, #338) 90 | │ 91 | └── README.md (this file) 92 | Skill metadata and statistics 93 | ``` 94 | 95 | **Total**: ~2,224 lines across 4 files 96 | 97 | ## Common Error Types 98 | 99 | | Error Type | Priority | Auto-Fix | Severity | 100 | |---|---|---|---| 101 | | missing_required | Highest | ❌ | Error | 102 | | invalid_value | High | ❌ | Error | 103 | | type_mismatch | Medium | ❌ | Error | 104 | | invalid_expression | Medium | ❌ | Error | 105 | | invalid_reference | Low | ❌ | Error | 106 | | operator_structure | Low | ✅ | Warning | 107 | 108 | ## Key Insights 109 | 110 | ### 1. Validation is Iterative 111 | Don't expect to get it right on the first try. Multiple validation cycles (typically 2-3) are normal and expected! 112 | 113 | ### 2. False Positives Exist 114 | Many validation warnings are acceptable in production workflows. This skill helps you recognize which ones to address vs. which to ignore. 115 | 116 | ### 3. Auto-Sanitization Works 117 | Certain error types (like operator structure issues) are automatically fixed by n8n. Don't waste time manually fixing these! 118 | 119 | ### 4. Profile Matters 120 | - `ai-friendly` reduces false positives by 60% 121 | - `runtime` is the sweet spot for most use cases 122 | - `strict` has value pre-production but is noisy 123 | 124 | ### 5. Error Messages Help 125 | Validation errors include fix guidance - read them carefully! 126 | 127 | ## Usage Examples 128 | 129 | ### Example 1: Basic Validation Loop 130 | 131 | ```javascript 132 | // Iteration 1 133 | let config = { 134 | resource: "channel", 135 | operation: "create" 136 | }; 137 | 138 | const result1 = validate_node_operation({ 139 | nodeType: "nodes-base.slack", 140 | config, 141 | profile: "runtime" 142 | }); 143 | // → Error: Missing "name" 144 | 145 | // Iteration 2 146 | config.name = "general"; 147 | const result2 = validate_node_operation({...}); 148 | // → Valid! ✅ 149 | ``` 150 | 151 | ### Example 2: Handling False Positives 152 | 153 | ```javascript 154 | // Run validation 155 | const result = validate_node_operation({ 156 | nodeType: "nodes-base.slack", 157 | config, 158 | profile: "runtime" 159 | }); 160 | 161 | // Fix errors (must fix) 162 | if (!result.valid) { 163 | result.errors.forEach(error => { 164 | console.log(`MUST FIX: ${error.message}`); 165 | }); 166 | } 167 | 168 | // Review warnings (context-dependent) 169 | result.warnings.forEach(warning => { 170 | if (warning.type === 'best_practice' && isDevWorkflow) { 171 | console.log(`ACCEPTABLE: ${warning.message}`); 172 | } else { 173 | console.log(`SHOULD FIX: ${warning.message}`); 174 | } 175 | }); 176 | ``` 177 | 178 | ### Example 3: Using Auto-Fix 179 | 180 | ```javascript 181 | // Check what can be auto-fixed 182 | const preview = n8n_autofix_workflow({ 183 | id: "workflow-id", 184 | applyFixes: false // Preview mode 185 | }); 186 | 187 | console.log(`Can auto-fix: ${preview.fixCount} issues`); 188 | 189 | // Apply fixes 190 | if (preview.fixCount > 0) { 191 | n8n_autofix_workflow({ 192 | id: "workflow-id", 193 | applyFixes: true 194 | }); 195 | } 196 | ``` 197 | 198 | ## When This Skill Activates 199 | 200 | **Trigger phrases**: 201 | - "validation error" 202 | - "validation failing" 203 | - "what does this error mean" 204 | - "false positive" 205 | - "validation loop" 206 | - "operator structure" 207 | - "validation profile" 208 | 209 | **Common scenarios**: 210 | - Encountering validation errors 211 | - Stuck in validation feedback loops 212 | - Wondering if warnings need fixing 213 | - Choosing the right validation profile 214 | - Understanding auto-sanitization 215 | 216 | ## Integration with Other Skills 217 | 218 | ### Works With: 219 | - **n8n MCP Tools Expert** - How to use validation tools correctly 220 | - **n8n Expression Syntax** - Fix invalid_expression errors 221 | - **n8n Node Configuration** - Understand required fields 222 | - **n8n Workflow Patterns** - Validate pattern implementations 223 | 224 | ### Complementary: 225 | - Use MCP Tools Expert to call validation tools 226 | - Use Expression Syntax to fix expression errors 227 | - Use Node Configuration to understand dependencies 228 | - Use Workflow Patterns to validate structure 229 | 230 | ## Testing 231 | 232 | **Evaluations**: 4 test scenarios 233 | 234 | 1. **eval-001-missing-required-field.json** 235 | - Tests error interpretation 236 | - Guides to get_node_essentials 237 | - References ERROR_CATALOG.md 238 | 239 | 2. **eval-002-false-positive.json** 240 | - Tests warning vs error distinction 241 | - Explains false positives 242 | - References FALSE_POSITIVES.md 243 | - Suggests ai-friendly profile 244 | 245 | 3. **eval-003-auto-sanitization.json** 246 | - Tests auto-sanitization understanding 247 | - Explains operator structure fixes 248 | - Advises trusting auto-fix 249 | 250 | 4. **eval-004-validation-loop.json** 251 | - Tests iterative validation process 252 | - Explains 2-3 iteration pattern 253 | - Provides systematic approach 254 | 255 | ## Success Metrics 256 | 257 | **Before this skill**: 258 | - Users confused by validation errors 259 | - Multiple failed attempts to fix 260 | - Frustration with "validation loops" 261 | - Fixing issues that auto-fix handles 262 | - Fixing all warnings unnecessarily 263 | 264 | **After this skill**: 265 | - Systematic error resolution 266 | - Understanding of iteration process 267 | - Recognition of false positives 268 | - Trust in auto-sanitization 269 | - Context-aware warning handling 270 | - 94% success within 3 iterations 271 | 272 | ## Related Documentation 273 | 274 | - **n8n-mcp MCP Server**: Provides validation tools 275 | - **n8n Validation API**: validate_node_operation, validate_workflow, n8n_autofix_workflow 276 | - **n8n Issues**: #304 (IF metadata), #306 (Switch branches), #338 (credentials) 277 | 278 | ## Version History 279 | 280 | - **v1.0** (2025-10-20): Initial implementation 281 | - SKILL.md with core concepts 282 | - ERROR_CATALOG.md with 9 error types 283 | - FALSE_POSITIVES.md with 6 false positive patterns 284 | - 4 evaluation scenarios 285 | 286 | ## Author 287 | 288 | Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en) 289 | 290 | Part of the n8n-skills meta-skill collection. 291 | -------------------------------------------------------------------------------- /skills/n8n-workflow-patterns/README.md: -------------------------------------------------------------------------------- 1 | # n8n Workflow Patterns 2 | 3 | Proven architectural patterns for building n8n workflows. 4 | 5 | --- 6 | 7 | ## Purpose 8 | 9 | Teaches architectural patterns for building n8n workflows. Provides structure, best practices, and proven approaches for common use cases. 10 | 11 | ## Activates On 12 | 13 | - build workflow 14 | - workflow pattern 15 | - workflow architecture 16 | - workflow structure 17 | - webhook processing 18 | - http api 19 | - api integration 20 | - database sync 21 | - ai agent 22 | - chatbot 23 | - scheduled task 24 | - automation pattern 25 | 26 | ## File Count 27 | 28 | 7 files, ~3,700 lines total 29 | 30 | ## Priority 31 | 32 | **HIGH** - Addresses 813 webhook searches (most common use case) 33 | 34 | ## Dependencies 35 | 36 | **n8n-mcp tools**: 37 | - search_nodes (find nodes for patterns) 38 | - get_node_essentials (understand node operations) 39 | - search_templates (find example workflows) 40 | 41 | **Related skills**: 42 | - n8n MCP Tools Expert (find and configure nodes) 43 | - n8n Expression Syntax (write expressions in patterns) 44 | - n8n Node Configuration (configure pattern nodes) 45 | - n8n Validation Expert (validate pattern implementations) 46 | 47 | ## Coverage 48 | 49 | ### The 5 Core Patterns 50 | 51 | 1. **Webhook Processing** (Most Common - 813 searches) 52 | - Receive HTTP requests → Process → Respond 53 | - Critical gotcha: Data under $json.body 54 | - Authentication, validation, error handling 55 | 56 | 2. **HTTP API Integration** (892 templates) 57 | - Fetch from REST APIs → Transform → Store/Use 58 | - Authentication methods, pagination, rate limiting 59 | - Error handling and retries 60 | 61 | 3. **Database Operations** (456 templates) 62 | - Read/Write/Sync database data 63 | - Batch processing, transactions, performance 64 | - Security: parameterized queries, read-only access 65 | 66 | 4. **AI Agent Workflow** (234 templates, 270 AI nodes) 67 | - AI agents with tool access and memory 68 | - 8 AI connection types 69 | - ANY node can be an AI tool 70 | 71 | 5. **Scheduled Tasks** (28% of all workflows) 72 | - Recurring automation workflows 73 | - Cron schedules, timezone handling 74 | - Monitoring and error handling 75 | 76 | ### Cross-Cutting Concerns 77 | 78 | - Data flow patterns (linear, branching, parallel, loops) 79 | - Error handling strategies 80 | - Performance optimization 81 | - Security best practices 82 | - Testing approaches 83 | - Monitoring and logging 84 | 85 | ## Evaluations 86 | 87 | 5 scenarios (100% coverage expected): 88 | 1. **eval-001**: Webhook workflow structure 89 | 2. **eval-002**: HTTP API integration pattern 90 | 3. **eval-003**: Database sync pattern 91 | 4. **eval-004**: AI agent workflow with tools 92 | 5. **eval-005**: Scheduled report generation 93 | 94 | ## Key Features 95 | 96 | ✅ **5 Proven Patterns**: Webhook, HTTP API, Database, AI Agent, Scheduled tasks 97 | ✅ **Complete Examples**: Working workflow configurations for each pattern 98 | ✅ **Best Practices**: Proven approaches from real-world n8n usage 99 | ✅ **Common Gotchas**: Documented mistakes and their fixes 100 | ✅ **Integration Guide**: How patterns work with other skills 101 | ✅ **Template Examples**: Real examples from 2,653+ n8n templates 102 | 103 | ## Files 104 | 105 | - **SKILL.md** (486 lines) - Pattern overview, selection guide, checklist 106 | - **webhook_processing.md** (554 lines) - Webhook patterns, data structure, auth 107 | - **http_api_integration.md** (763 lines) - REST APIs, pagination, rate limiting 108 | - **database_operations.md** (854 lines) - DB operations, batch processing, security 109 | - **ai_agent_workflow.md** (918 lines) - AI agents, tools, memory, 8 connection types 110 | - **scheduled_tasks.md** (845 lines) - Cron schedules, timezone, monitoring 111 | - **README.md** (this file) - Skill metadata 112 | 113 | ## Success Metrics 114 | 115 | **Expected outcomes**: 116 | - Users select appropriate pattern for their use case 117 | - Workflows follow proven structural patterns 118 | - Common gotchas avoided (webhook $json.body, SQL injection, etc.) 119 | - Proper error handling implemented 120 | - Security best practices followed 121 | 122 | ## Pattern Selection Stats 123 | 124 | Common workflow composition: 125 | 126 | **Trigger Distribution**: 127 | - Webhook: 35% (most common) 128 | - Schedule: 28% 129 | - Manual: 22% 130 | - Service triggers: 15% 131 | 132 | **Transformation Nodes**: 133 | - Set: 68% 134 | - Code: 42% 135 | - IF: 38% 136 | - Switch: 18% 137 | 138 | **Output Channels**: 139 | - HTTP Request: 45% 140 | - Slack: 32% 141 | - Database: 28% 142 | - Email: 24% 143 | 144 | **Complexity**: 145 | - Simple (3-5 nodes): 42% 146 | - Medium (6-10 nodes): 38% 147 | - Complex (11+ nodes): 20% 148 | 149 | ## Critical Insights 150 | 151 | **Webhook Processing**: 152 | - 813 searches (most common use case!) 153 | - #1 gotcha: Data under $json.body (not $json directly) 154 | - Must choose response mode: onReceived vs lastNode 155 | 156 | **API Integration**: 157 | - Authentication via credentials (never hardcode!) 158 | - Pagination essential for large datasets 159 | - Rate limiting prevents API bans 160 | - continueOnFail: true for error handling 161 | 162 | **Database Operations**: 163 | - Always use parameterized queries (SQL injection prevention) 164 | - Batch processing for large datasets 165 | - Read-only access for AI tools 166 | - Transaction handling for multi-step operations 167 | 168 | **AI Agents**: 169 | - 8 AI connection types (ai_languageModel, ai_tool, ai_memory, etc.) 170 | - ANY node can be an AI tool (connect to ai_tool port) 171 | - Memory essential for conversations (Window Buffer recommended) 172 | - Tool descriptions critical (AI uses them to decide when to call) 173 | 174 | **Scheduled Tasks**: 175 | - Set workflow timezone explicitly (DST handling) 176 | - Prevent overlapping executions (use locks) 177 | - Error Trigger workflow for alerts 178 | - Batch processing for large data 179 | 180 | ## Workflow Creation Checklist 181 | 182 | Every pattern follows this checklist: 183 | 184 | ### Planning Phase 185 | - [ ] Identify the pattern (webhook, API, database, AI, scheduled) 186 | - [ ] List required nodes (use search_nodes) 187 | - [ ] Understand data flow (input → transform → output) 188 | - [ ] Plan error handling strategy 189 | 190 | ### Implementation Phase 191 | - [ ] Create workflow with appropriate trigger 192 | - [ ] Add data source nodes 193 | - [ ] Configure authentication/credentials 194 | - [ ] Add transformation nodes (Set, Code, IF) 195 | - [ ] Add output/action nodes 196 | - [ ] Configure error handling 197 | 198 | ### Validation Phase 199 | - [ ] Validate each node configuration 200 | - [ ] Validate complete workflow 201 | - [ ] Test with sample data 202 | - [ ] Handle edge cases 203 | 204 | ### Deployment Phase 205 | - [ ] Review workflow settings 206 | - [ ] Activate workflow 207 | - [ ] Monitor first executions 208 | - [ ] Document workflow 209 | 210 | ## Real Template Examples 211 | 212 | **Weather to Slack** (Template #2947): 213 | ``` 214 | Schedule (daily 8 AM) → HTTP Request (weather) → Set → Slack 215 | ``` 216 | 217 | **Webhook Processing**: 1,085 templates 218 | **HTTP API Integration**: 892 templates 219 | **Database Operations**: 456 templates 220 | **AI Workflows**: 234 templates 221 | 222 | Use `search_templates` to find examples for your use case! 223 | 224 | ## Integration with Other Skills 225 | 226 | **Pattern Selection** (this skill): 227 | 1. Identify use case 228 | 2. Select appropriate pattern 229 | 3. Follow pattern structure 230 | 231 | **Node Discovery** (n8n MCP Tools Expert): 232 | 4. Find nodes for pattern (search_nodes) 233 | 5. Understand node operations (get_node_essentials) 234 | 235 | **Implementation** (n8n Expression Syntax + Node Configuration): 236 | 6. Write expressions ({{$json.body.field}}) 237 | 7. Configure nodes properly 238 | 239 | **Validation** (n8n Validation Expert): 240 | 8. Validate workflow structure 241 | 9. Fix validation errors 242 | 243 | ## Last Updated 244 | 245 | 2025-10-20 246 | 247 | --- 248 | 249 | **Part of**: n8n-skills repository 250 | **Conceived by**: Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en) 251 | -------------------------------------------------------------------------------- /skills/n8n-workflow-patterns/SKILL.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: n8n-workflow-patterns 3 | 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. 4 | --- 5 | 6 | # n8n Workflow Patterns 7 | 8 | Proven architectural patterns for building n8n workflows. 9 | 10 | --- 11 | 12 | ## The 5 Core Patterns 13 | 14 | Based on analysis of real workflow usage: 15 | 16 | 1. **[Webhook Processing](webhook_processing.md)** (Most Common) 17 | - Receive HTTP requests → Process → Output 18 | - Pattern: Webhook → Validate → Transform → Respond/Notify 19 | 20 | 2. **[HTTP API Integration](http_api_integration.md)** 21 | - Fetch from REST APIs → Transform → Store/Use 22 | - Pattern: Trigger → HTTP Request → Transform → Action → Error Handler 23 | 24 | 3. **[Database Operations](database_operations.md)** 25 | - Read/Write/Sync database data 26 | - Pattern: Schedule → Query → Transform → Write → Verify 27 | 28 | 4. **[AI Agent Workflow](ai_agent_workflow.md)** 29 | - AI agents with tools and memory 30 | - Pattern: Trigger → AI Agent (Model + Tools + Memory) → Output 31 | 32 | 5. **[Scheduled Tasks](scheduled_tasks.md)** 33 | - Recurring automation workflows 34 | - Pattern: Schedule → Fetch → Process → Deliver → Log 35 | 36 | --- 37 | 38 | ## Pattern Selection Guide 39 | 40 | ### When to use each pattern: 41 | 42 | **Webhook Processing** - Use when: 43 | - Receiving data from external systems 44 | - Building integrations (Slack commands, form submissions, GitHub webhooks) 45 | - Need instant response to events 46 | - Example: "Receive Stripe payment webhook → Update database → Send confirmation" 47 | 48 | **HTTP API Integration** - Use when: 49 | - Fetching data from external APIs 50 | - Synchronizing with third-party services 51 | - Building data pipelines 52 | - Example: "Fetch GitHub issues → Transform → Create Jira tickets" 53 | 54 | **Database Operations** - Use when: 55 | - Syncing between databases 56 | - Running database queries on schedule 57 | - ETL workflows 58 | - Example: "Read Postgres records → Transform → Write to MySQL" 59 | 60 | **AI Agent Workflow** - Use when: 61 | - Building conversational AI 62 | - Need AI with tool access 63 | - Multi-step reasoning tasks 64 | - Example: "Chat with AI that can search docs, query database, send emails" 65 | 66 | **Scheduled Tasks** - Use when: 67 | - Recurring reports or summaries 68 | - Periodic data fetching 69 | - Maintenance tasks 70 | - Example: "Daily: Fetch analytics → Generate report → Email team" 71 | 72 | --- 73 | 74 | ## Common Workflow Components 75 | 76 | All patterns share these building blocks: 77 | 78 | ### 1. Triggers 79 | - **Webhook** - HTTP endpoint (instant) 80 | - **Schedule** - Cron-based timing (periodic) 81 | - **Manual** - Click to execute (testing) 82 | - **Polling** - Check for changes (intervals) 83 | 84 | ### 2. Data Sources 85 | - **HTTP Request** - REST APIs 86 | - **Database nodes** - Postgres, MySQL, MongoDB 87 | - **Service nodes** - Slack, Google Sheets, etc. 88 | - **Code** - Custom JavaScript/Python 89 | 90 | ### 3. Transformation 91 | - **Set** - Map/transform fields 92 | - **Code** - Complex logic 93 | - **IF/Switch** - Conditional routing 94 | - **Merge** - Combine data streams 95 | 96 | ### 4. Outputs 97 | - **HTTP Request** - Call APIs 98 | - **Database** - Write data 99 | - **Communication** - Email, Slack, Discord 100 | - **Storage** - Files, cloud storage 101 | 102 | ### 5. Error Handling 103 | - **Error Trigger** - Catch workflow errors 104 | - **IF** - Check for error conditions 105 | - **Stop and Error** - Explicit failure 106 | - **Continue On Fail** - Per-node setting 107 | 108 | --- 109 | 110 | ## Workflow Creation Checklist 111 | 112 | When building ANY workflow, follow this checklist: 113 | 114 | ### Planning Phase 115 | - [ ] Identify the pattern (webhook, API, database, AI, scheduled) 116 | - [ ] List required nodes (use search_nodes) 117 | - [ ] Understand data flow (input → transform → output) 118 | - [ ] Plan error handling strategy 119 | 120 | ### Implementation Phase 121 | - [ ] Create workflow with appropriate trigger 122 | - [ ] Add data source nodes 123 | - [ ] Configure authentication/credentials 124 | - [ ] Add transformation nodes (Set, Code, IF) 125 | - [ ] Add output/action nodes 126 | - [ ] Configure error handling 127 | 128 | ### Validation Phase 129 | - [ ] Validate each node configuration (validate_node_operation) 130 | - [ ] Validate complete workflow (validate_workflow) 131 | - [ ] Test with sample data 132 | - [ ] Handle edge cases (empty data, errors) 133 | 134 | ### Deployment Phase 135 | - [ ] Review workflow settings (execution order, timeout, error handling) 136 | - [ ] Activate workflow ⚠️ **Manual activation required in n8n UI** (API/MCP cannot activate) 137 | - [ ] Monitor first executions 138 | - [ ] Document workflow purpose and data flow 139 | 140 | --- 141 | 142 | ## Data Flow Patterns 143 | 144 | ### Linear Flow 145 | ``` 146 | Trigger → Transform → Action → End 147 | ``` 148 | **Use when**: Simple workflows with single path 149 | 150 | ### Branching Flow 151 | ``` 152 | Trigger → IF → [True Path] 153 | └→ [False Path] 154 | ``` 155 | **Use when**: Different actions based on conditions 156 | 157 | ### Parallel Processing 158 | ``` 159 | Trigger → [Branch 1] → Merge 160 | └→ [Branch 2] ↗ 161 | ``` 162 | **Use when**: Independent operations that can run simultaneously 163 | 164 | ### Loop Pattern 165 | ``` 166 | Trigger → Split in Batches → Process → Loop (until done) 167 | ``` 168 | **Use when**: Processing large datasets in chunks 169 | 170 | ### Error Handler Pattern 171 | ``` 172 | Main Flow → [Success Path] 173 | └→ [Error Trigger → Error Handler] 174 | ``` 175 | **Use when**: Need separate error handling workflow 176 | 177 | --- 178 | 179 | ## Common Gotchas 180 | 181 | ### 1. Webhook Data Structure 182 | **Problem**: Can't access webhook payload data 183 | 184 | **Solution**: Data is nested under `$json.body` 185 | ```javascript 186 | ❌ {{$json.email}} 187 | ✅ {{$json.body.email}} 188 | ``` 189 | See: n8n Expression Syntax skill 190 | 191 | ### 2. Multiple Input Items 192 | **Problem**: Node processes all input items, but I only want one 193 | 194 | **Solution**: Use "Execute Once" mode or process first item only 195 | ```javascript 196 | {{$json[0].field}} // First item only 197 | ``` 198 | 199 | ### 3. Authentication Issues 200 | **Problem**: API calls failing with 401/403 201 | 202 | **Solution**: 203 | - Configure credentials properly 204 | - Use the "Credentials" section, not parameters 205 | - Test credentials before workflow activation 206 | 207 | ### 4. Node Execution Order 208 | **Problem**: Nodes executing in unexpected order 209 | 210 | **Solution**: Check workflow settings → Execution Order 211 | - v0: Top-to-bottom (legacy) 212 | - v1: Connection-based (recommended) 213 | 214 | ### 5. Expression Errors 215 | **Problem**: Expressions showing as literal text 216 | 217 | **Solution**: Use {{}} around expressions 218 | - See n8n Expression Syntax skill for details 219 | 220 | --- 221 | 222 | ## Integration with Other Skills 223 | 224 | These skills work together with Workflow Patterns: 225 | 226 | **n8n MCP Tools Expert** - Use to: 227 | - Find nodes for your pattern (search_nodes) 228 | - Understand node operations (get_node_essentials) 229 | - Create workflows (n8n_create_workflow) 230 | 231 | **n8n Expression Syntax** - Use to: 232 | - Write expressions in transformation nodes 233 | - Access webhook data correctly ({{$json.body.field}}) 234 | - Reference previous nodes ({{$node["Node Name"].json.field}}) 235 | 236 | **n8n Node Configuration** - Use to: 237 | - Configure specific operations for pattern nodes 238 | - Understand node-specific requirements 239 | 240 | **n8n Validation Expert** - Use to: 241 | - Validate workflow structure 242 | - Fix validation errors 243 | - Ensure workflow correctness before deployment 244 | 245 | --- 246 | 247 | ## Pattern Statistics 248 | 249 | Common workflow patterns: 250 | 251 | **Most Common Triggers**: 252 | 1. Webhook - 35% 253 | 2. Schedule (periodic tasks) - 28% 254 | 3. Manual (testing/admin) - 22% 255 | 4. Service triggers (Slack, email, etc.) - 15% 256 | 257 | **Most Common Transformations**: 258 | 1. Set (field mapping) - 68% 259 | 2. Code (custom logic) - 42% 260 | 3. IF (conditional routing) - 38% 261 | 4. Switch (multi-condition) - 18% 262 | 263 | **Most Common Outputs**: 264 | 1. HTTP Request (APIs) - 45% 265 | 2. Slack - 32% 266 | 3. Database writes - 28% 267 | 4. Email - 24% 268 | 269 | **Average Workflow Complexity**: 270 | - Simple (3-5 nodes): 42% 271 | - Medium (6-10 nodes): 38% 272 | - Complex (11+ nodes): 20% 273 | 274 | --- 275 | 276 | ## Quick Start Examples 277 | 278 | ### Example 1: Simple Webhook → Slack 279 | ``` 280 | 1. Webhook (path: "form-submit", POST) 281 | 2. Set (map form fields) 282 | 3. Slack (post message to #notifications) 283 | ``` 284 | 285 | ### Example 2: Scheduled Report 286 | ``` 287 | 1. Schedule (daily at 9 AM) 288 | 2. HTTP Request (fetch analytics) 289 | 3. Code (aggregate data) 290 | 4. Email (send formatted report) 291 | 5. Error Trigger → Slack (notify on failure) 292 | ``` 293 | 294 | ### Example 3: Database Sync 295 | ``` 296 | 1. Schedule (every 15 minutes) 297 | 2. Postgres (query new records) 298 | 3. IF (check if records exist) 299 | 4. MySQL (insert records) 300 | 5. Postgres (update sync timestamp) 301 | ``` 302 | 303 | ### Example 4: AI Assistant 304 | ``` 305 | 1. Webhook (receive chat message) 306 | 2. AI Agent 307 | ├─ OpenAI Chat Model (ai_languageModel) 308 | ├─ HTTP Request Tool (ai_tool) 309 | ├─ Database Tool (ai_tool) 310 | └─ Window Buffer Memory (ai_memory) 311 | 3. Webhook Response (send AI reply) 312 | ``` 313 | 314 | ### Example 5: API Integration 315 | ``` 316 | 1. Manual Trigger (for testing) 317 | 2. HTTP Request (GET /api/users) 318 | 3. Split In Batches (process 100 at a time) 319 | 4. Set (transform user data) 320 | 5. Postgres (upsert users) 321 | 6. Loop (back to step 3 until done) 322 | ``` 323 | 324 | --- 325 | 326 | ## Detailed Pattern Files 327 | 328 | For comprehensive guidance on each pattern: 329 | 330 | - **[webhook_processing.md](webhook_processing.md)** - Webhook patterns, data structure, response handling 331 | - **[http_api_integration.md](http_api_integration.md)** - REST APIs, authentication, pagination, retries 332 | - **[database_operations.md](database_operations.md)** - Queries, sync, transactions, batch processing 333 | - **[ai_agent_workflow.md](ai_agent_workflow.md)** - AI agents, tools, memory, langchain nodes 334 | - **[scheduled_tasks.md](scheduled_tasks.md)** - Cron schedules, reports, maintenance tasks 335 | 336 | --- 337 | 338 | ## Real Template Examples 339 | 340 | From n8n template library: 341 | 342 | **Template #2947**: Weather to Slack 343 | - Pattern: Scheduled Task 344 | - Nodes: Schedule → HTTP Request (weather API) → Set → Slack 345 | - Complexity: Simple (4 nodes) 346 | 347 | **Webhook Processing**: Most common pattern 348 | - Most common: Form submissions, payment webhooks, chat integrations 349 | 350 | **HTTP API**: Common pattern 351 | - Most common: Data fetching, third-party integrations 352 | 353 | **Database Operations**: Common pattern 354 | - Most common: ETL, data sync, backup workflows 355 | 356 | **AI Agents**: Growing in usage 357 | - Most common: Chatbots, content generation, data analysis 358 | 359 | Use `search_templates` and `get_template` from n8n-mcp tools to find examples! 360 | 361 | --- 362 | 363 | ## Best Practices 364 | 365 | ### ✅ Do 366 | 367 | - Start with the simplest pattern that solves your problem 368 | - Plan your workflow structure before building 369 | - Use error handling on all workflows 370 | - Test with sample data before activation 371 | - Follow the workflow creation checklist 372 | - Use descriptive node names 373 | - Document complex workflows (notes field) 374 | - Monitor workflow executions after deployment 375 | 376 | ### ❌ Don't 377 | 378 | - Build workflows in one shot (iterate! avg 56s between edits) 379 | - Skip validation before activation 380 | - Ignore error scenarios 381 | - Use complex patterns when simple ones suffice 382 | - Hardcode credentials in parameters 383 | - Forget to handle empty data cases 384 | - Mix multiple patterns without clear boundaries 385 | - Deploy without testing 386 | 387 | --- 388 | 389 | ## Summary 390 | 391 | **Key Points**: 392 | 1. **5 core patterns** cover 90%+ of workflow use cases 393 | 2. **Webhook processing** is the most common pattern 394 | 3. Use the **workflow creation checklist** for every workflow 395 | 4. **Plan pattern** → **Select nodes** → **Build** → **Validate** → **Deploy** 396 | 5. Integrate with other skills for complete workflow development 397 | 398 | **Next Steps**: 399 | 1. Identify your use case pattern 400 | 2. Read the detailed pattern file 401 | 3. Use n8n MCP Tools Expert to find nodes 402 | 4. Follow the workflow creation checklist 403 | 5. Use n8n Validation Expert to validate 404 | 405 | **Related Skills**: 406 | - n8n MCP Tools Expert - Find and configure nodes 407 | - n8n Expression Syntax - Write expressions correctly 408 | - n8n Validation Expert - Validate and fix errors 409 | - n8n Node Configuration - Configure specific operations 410 | --------------------------------------------------------------------------------