diff --git a/README.md b/README.md index 08592dd..b8ae256 100644 --- a/README.md +++ b/README.md @@ -3,21 +3,21 @@ **Expert Claude Code skills for building flawless n8n workflows using the n8n-mcp MCP server** [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) -[![n8n-mcp](https://img.shields.io/badge/n8n--mcp-compatible-green.svg)](https://github.com/romualdczlonkowski/n8n-mcp) +[![n8n-mcp](https://img.shields.io/badge/n8n--mcp-compatible-green.svg)](https://github.com/czlonkowski/n8n-mcp) --- ## 🎯 What is this? -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/your-link-here) MCP server. +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. ### Why These Skills Exist -Based on analysis of **447,557 real MCP tool usage events**, we identified: -- **20% failure rate** when using certain MCP tools incorrectly -- **15,107 validation feedback loops** due to configuration errors -- **813 searches for "webhook"** showing common workflow patterns -- **31,917 workflows created** revealing proven architectural patterns +Building n8n workflows programmatically can be challenging. Common issues include: +- Using MCP tools incorrectly or inefficiently +- Getting stuck in validation error loops +- Not knowing which workflow patterns to use +- Misconfiguring nodes and their dependencies These skills solve these problems by teaching Claude: - βœ… Correct n8n expression syntax ({{}} patterns) @@ -53,22 +53,20 @@ Expert guide for using n8n-mcp MCP tools effectively. - Smart parameters (branch="true" for IF nodes) - Auto-sanitization system explained -**Impact**: **Fixes 20% MCP tool failure rate** +**Most Important**: Teaches correct MCP tool usage patterns and parameter formats ### 3. **n8n Workflow Patterns** -Build workflows using 5 proven architectural patterns from 31,917 real workflows. +Build workflows using 5 proven architectural patterns. **Activates when**: Creating workflows, connecting nodes, designing automation. **Key Features**: - 5 proven patterns (webhook processing, HTTP API, database, AI, scheduled) - Workflow creation checklist -- Real examples from 2,653 templates +- Real examples from 2,653+ n8n templates - Connection best practices - Pattern selection guide -**Impact**: **Addresses 27.6% of all workflows (webhook processing)** - ### 4. **n8n Validation Expert** Interpret validation errors and guide fixing. @@ -98,7 +96,7 @@ Operation-aware node configuration guidance. ### Prerequisites -1. **n8n-mcp MCP server** installed and configured ([Installation Guide](https://github.com/romualdczlonkowski/n8n-mcp)) +1. **n8n-mcp MCP server** installed and configured ([Installation Guide](https://github.com/czlonkowski/n8n-mcp)) 2. **Claude Code**, Claude.ai, or Claude API access 3. `.mcp.json` configured with n8n-mcp server @@ -171,22 +169,6 @@ All 5 skills compose seamlessly! --- -## πŸ”¬ Data-Driven Design - -These skills are based on telemetry analysis of: -- **447,557** MCP tool usage events -- **31,917** workflows created -- **19,113** validation errors -- **15,107** validation feedback loops -- **2,653** workflow templates - -Key insights: -- `search_nodes β†’ get_node_essentials` is the most common pattern (9,835 occurrences, 18s avg) -- `n8n_update_partial_workflow` is the most-used tool (38,287 uses, 99.0% success) -- Validation loops average 23s thinking, 58s fixing -- Webhook workflows represent 27.6% of all workflows (813 searches) - ---- ## πŸ§ͺ Testing @@ -226,25 +208,23 @@ MIT License - see [LICENSE](LICENSE) file for details. **Conceived by Romuald CzΕ‚onkowski** - Website: [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en) -- Part of the [n8n-mcp project](https://github.com/romualdczlonkowski/n8n-mcp) +- Part of the [n8n-mcp project](https://github.com/czlonkowski/n8n-mcp) --- ## πŸ”— Related Projects -- [n8n-mcp](https://github.com/romualdczlonkowski/n8n-mcp) - MCP server for n8n +- [n8n-mcp](https://github.com/czlonkowski/n8n-mcp) - MCP server for n8n - [n8n](https://n8n.io/) - Workflow automation platform --- -## πŸ“Š Repository Stats +## πŸ“Š What's Included -- **5** complementary skills -- **~3,220** lines of skill content -- **15-20** evaluation scenarios -- **88%** documentation coverage (from n8n-mcp) -- **537** nodes supported -- **2,653** templates available +- **5** complementary skills that work together +- **525+** n8n nodes supported +- **2,653+** workflow templates for examples +- **Comprehensive** error catalogs and troubleshooting guides --- diff --git a/dist/README.md b/dist/README.md index 241dd2d..cd9b413 100644 --- a/dist/README.md +++ b/dist/README.md @@ -9,7 +9,7 @@ This folder contains distribution packages for different Claude platforms. Upload each skill separately via Settings β†’ Features β†’ Skills: - `n8n-expression-syntax-v1.0.0.zip` - n8n expression syntax and common patterns -- `n8n-mcp-tools-expert-v1.0.0.zip` - Expert guide for using n8n-mcp tools (HIGHEST PRIORITY) +- `n8n-mcp-tools-expert-v1.0.0.zip` - Expert guide for using n8n-mcp tools (recommended to install first) - `n8n-workflow-patterns-v1.0.0.zip` - 5 proven workflow architectural patterns - `n8n-validation-expert-v1.0.0.zip` - Validation error interpretation and fixing - `n8n-node-configuration-v1.0.0.zip` - Operation-aware node configuration @@ -96,7 +96,7 @@ After installation, test skills by asking: ## πŸ”§ Requirements -- **n8n-mcp MCP server** installed and configured +- **n8n-mcp MCP server** installed and configured ([Installation Guide](https://github.com/czlonkowski/n8n-mcp)) - **Claude Pro, Max, Team, or Enterprise** plan (for Claude.ai skills) - **.mcp.json** configured with n8n-mcp server @@ -131,4 +131,4 @@ MIT License - see `../LICENSE` file Conceived by Romuald CzΕ‚onkowski - https://www.aiadvisors.pl/en -Part of the n8n-mcp project. +Part of the [n8n-mcp project](https://github.com/czlonkowski/n8n-mcp). diff --git a/dist/n8n-expression-syntax-v1.0.0.zip b/dist/n8n-expression-syntax-v1.0.0.zip index ef3bcf9..272aeda 100644 Binary files a/dist/n8n-expression-syntax-v1.0.0.zip and b/dist/n8n-expression-syntax-v1.0.0.zip differ diff --git a/dist/n8n-mcp-skills-claude-code-v1.0.0.zip b/dist/n8n-mcp-skills-claude-code-v1.0.0.zip index 07e7182..5d19eaf 100644 Binary files a/dist/n8n-mcp-skills-claude-code-v1.0.0.zip and b/dist/n8n-mcp-skills-claude-code-v1.0.0.zip differ diff --git a/dist/n8n-mcp-tools-expert-v1.0.0.zip b/dist/n8n-mcp-tools-expert-v1.0.0.zip index 7c96b74..2c6070e 100644 Binary files a/dist/n8n-mcp-tools-expert-v1.0.0.zip and b/dist/n8n-mcp-tools-expert-v1.0.0.zip differ diff --git a/dist/n8n-node-configuration-v1.0.0.zip b/dist/n8n-node-configuration-v1.0.0.zip index f73aaa4..143a677 100644 Binary files a/dist/n8n-node-configuration-v1.0.0.zip and b/dist/n8n-node-configuration-v1.0.0.zip differ diff --git a/dist/n8n-validation-expert-v1.0.0.zip b/dist/n8n-validation-expert-v1.0.0.zip index 96a68e4..9af4003 100644 Binary files a/dist/n8n-validation-expert-v1.0.0.zip and b/dist/n8n-validation-expert-v1.0.0.zip differ diff --git a/dist/n8n-workflow-patterns-v1.0.0.zip b/dist/n8n-workflow-patterns-v1.0.0.zip index 1815764..3ab3f41 100644 Binary files a/dist/n8n-workflow-patterns-v1.0.0.zip and b/dist/n8n-workflow-patterns-v1.0.0.zip differ diff --git a/skills/n8n-mcp-tools-expert/README.md b/skills/n8n-mcp-tools-expert/README.md index 227bd09..ac197e9 100644 --- a/skills/n8n-mcp-tools-expert/README.md +++ b/skills/n8n-mcp-tools-expert/README.md @@ -25,7 +25,7 @@ Teaches how to use n8n-mcp MCP server tools correctly for efficient workflow bui ## Priority -**HIGHEST** - Fixes 20% MCP tool failure rate +**HIGHEST** - Essential for correct MCP tool usage ## Dependencies @@ -66,12 +66,12 @@ Teaches how to use n8n-mcp MCP server tools correctly for efficient workflow bui ## Key Features -βœ… **Data-Driven**: Based on 447,557 real MCP tool events -βœ… **Telemetry Insights**: Actual usage patterns (56s between edits, 18s between search/essentials) -βœ… **Critical Mistakes**: Highlights 20% failure rate issues -βœ… **Smart Parameters**: Teaches semantic branch/case routing -βœ… **Auto-Sanitization**: Explains automatic fixes -βœ… **Comprehensive**: Covers all 40+ tools +βœ… **Tool Selection Guide**: Which tool to use for each task +βœ… **Common Patterns**: Most effective tool usage sequences +βœ… **Format Guidance**: nodeType format differences explained +βœ… **Smart Parameters**: Semantic branch/case routing for multi-output nodes +βœ… **Auto-Sanitization**: Explains automatic validation fixes +βœ… **Comprehensive**: Covers all 40+ MCP tools ## Files @@ -81,22 +81,13 @@ Teaches how to use n8n-mcp MCP server tools correctly for efficient workflow bui - **WORKFLOW_GUIDE.md** (200 lines) - Workflow management - **README.md** (this file) - Skill metadata -## Success Metrics +## What You'll Learn -**Expected outcomes**: -- Correct nodeType formats (nodes-base.* for search) -- get_node_essentials preferred over get_node_info -- Validation profiles used correctly -- Smart parameters for IF/Switch nodes -- 20% failure rate reduced to <5% - -## Critical Insights - -**From MCP Testing Log**: -- search β†’ essentials: 9,835 occurrences, 18s avg -- validate β†’ fix: 7,841 loops, 23s thinking, 58s fixing -- update_partial: 38,287 uses, 56s between edits -- get_node_info: 20% failure rate (use essentials!) +- Correct nodeType formats (nodes-base.* for search tools) +- When to use get_node_essentials vs get_node_info +- How to use validation profiles effectively +- Smart parameters for multi-output nodes (IF/Switch) +- Common tool usage patterns and workflows ## Last Updated diff --git a/skills/n8n-validation-expert/README.md b/skills/n8n-validation-expert/README.md index a177c41..5f71756 100644 --- a/skills/n8n-validation-expert/README.md +++ b/skills/n8n-validation-expert/README.md @@ -94,39 +94,27 @@ n8n-validation-expert/ **Total**: ~2,224 lines across 4 files -## Error Distribution +## Common Error Types -Based on 19,113 validation errors: - -| Error Type | Frequency | Auto-Fix | Severity | +| Error Type | Priority | Auto-Fix | Severity | |---|---|---|---| -| missing_required | 45% | ❌ | Error | -| invalid_value | 28% | ❌ | Error | -| type_mismatch | 12% | ❌ | Error | -| invalid_expression | 8% | ❌ | Error | -| invalid_reference | 5% | ❌ | Error | -| operator_structure | 2% | βœ… | Warning | - -## Validation Loop Statistics - -From 7,841 validate β†’ fix cycles: - -- **Average thinking time**: 23 seconds -- **Average fix time**: 58 seconds -- **Total cycle time**: 81 seconds average -- **Iterations to success**: 2-3 average -- **Success rate after 3 iterations**: 94% +| missing_required | Highest | ❌ | Error | +| invalid_value | High | ❌ | Error | +| type_mismatch | Medium | ❌ | Error | +| invalid_expression | Medium | ❌ | Error | +| invalid_reference | Low | ❌ | Error | +| operator_structure | Low | βœ… | Warning | ## Key Insights ### 1. Validation is Iterative -Don't expect to get it right on the first try. The data shows 2-3 iterations is normal! +Don't expect to get it right on the first try. Multiple validation cycles (typically 2-3) are normal and expected! ### 2. False Positives Exist -~40% of warnings are accepted in production workflows. Learn to recognize them. +Many validation warnings are acceptable in production workflows. This skill helps you recognize which ones to address vs. which to ignore. ### 3. Auto-Sanitization Works -Operator structure issues (2% of errors) are auto-fixed. Don't manually fix these! +Certain error types (like operator structure issues) are automatically fixed by n8n. Don't waste time manually fixing these! ### 4. Profile Matters - `ai-friendly` reduces false positives by 60% diff --git a/skills/n8n-workflow-patterns/README.md b/skills/n8n-workflow-patterns/README.md index 86f3909..38ac229 100644 --- a/skills/n8n-workflow-patterns/README.md +++ b/skills/n8n-workflow-patterns/README.md @@ -93,12 +93,12 @@ Teaches architectural patterns for building n8n workflows. Provides structure, b ## Key Features -βœ… **Data-Driven**: Based on 31,917 real workflows -βœ… **Pattern Statistics**: Usage data for each pattern -βœ… **Complete Examples**: Working workflows for each pattern -βœ… **Best Practices**: Proven approaches from production workflows -βœ… **Common Gotchas**: Documented mistakes and fixes +βœ… **5 Proven Patterns**: Webhook, HTTP API, Database, AI Agent, Scheduled tasks +βœ… **Complete Examples**: Working workflow configurations for each pattern +βœ… **Best Practices**: Proven approaches from real-world n8n usage +βœ… **Common Gotchas**: Documented mistakes and their fixes βœ… **Integration Guide**: How patterns work with other skills +βœ… **Template Examples**: Real examples from 2,653+ n8n templates ## Files