33e83c29dc
Cleaned up all skills to remove research/telemetry context that was used during design but is not needed at runtime when AI agents use the skills. ## Changes Made ### Pattern 1: Research Framing Removed - "From analysis of X workflows/events" → Removed - "From telemetry analysis:" → Replaced with operational context - "Based on X real workflows" → Simplified to general statements ### Pattern 2: Popularity Metrics Removed - "**Popularity**: Second most common (892 templates)" → Removed entirely - "813 searches", "456 templates", etc. → Removed ### Pattern 3: Frequency Percentages Converted - "**Frequency**: 45% of errors" → "Most common error" - "**Frequency**: 28%" → "Second most common" - "**Frequency**: 12%" → "Common error" - Percentages in tables → Priority levels (Highest/High/Medium/Low) ### Pattern 4: Operational Guidance Kept - ✅ Success rates (91.7%) - helps tool selection - ✅ Average times (18s, 56s) - sets expectations - ✅ Relative priority (most common, typical) - guides decisions - ✅ Iteration counts (2-3 cycles) - manages expectations ## Files Modified (19 files across 4 skills) **Skill #2: MCP Tools Expert (5 files)** - Removed telemetry occurrence counts - Kept success rates and average times **Skill #3: Workflow Patterns (7 files)** - Removed all popularity metrics from pattern files - Removed "From analysis of 31,917 workflows" - Removed template counts **Skill #4: Validation Expert (4 files)** - Converted frequency % to priority levels - Removed "From analysis of 19,113 errors" - Removed telemetry loop counts (kept iteration guidance) **Skill #5: Node Configuration (3 files)** - Removed workflow update counts - Removed essentials call counts - Kept success rates and timing guidance ## Result Skills now provide clean, focused runtime guidance without research justification. Content is more actionable for AI agents using the skills. All technical guidance, examples, patterns, and operational metrics preserved. Only removed: research methodology, data source attribution, and statistical justification for design decisions. 🤖 Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
n8n-skills
Expert Claude Code skills for building flawless n8n workflows using the n8n-mcp MCP server
🎯 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 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
These skills solve these problems by teaching Claude:
- ✅ Correct n8n expression syntax ({{}} patterns)
- ✅ How to use n8n-mcp tools effectively
- ✅ Proven workflow patterns from real-world usage
- ✅ Validation error interpretation and fixing
- ✅ Operation-aware node configuration
📚 The 5 Skills
1. n8n Expression Syntax
Teaches correct n8n expression syntax and common patterns.
Activates when: Writing expressions, using {{}} syntax, accessing $json/$node variables, troubleshooting expression errors.
Key Features:
- Core variables ($json, $node, $now, $env)
- Critical gotcha: Webhook data is under
$json.body - Common mistakes catalog with fixes
- When NOT to use expressions (Code nodes!)
2. n8n MCP Tools Expert (HIGHEST PRIORITY)
Expert guide for using n8n-mcp MCP tools effectively.
Activates when: Searching for nodes, validating configurations, accessing templates, managing workflows.
Key Features:
- Tool selection guide (which tool for which task)
- nodeType format differences (nodes-base.* vs n8n-nodes-base.*)
- Validation profiles (minimal/runtime/ai-friendly/strict)
- Smart parameters (branch="true" for IF nodes)
- Auto-sanitization system explained
Impact: Fixes 20% MCP tool failure rate
3. n8n Workflow Patterns
Build workflows using 5 proven architectural patterns from 31,917 real workflows.
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
- 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.
Activates when: Validation fails, debugging workflow errors, handling false positives.
Key Features:
- Validation loop workflow
- Real error catalog
- Auto-sanitization behavior explained
- False positives guide
- Profile selection for different stages
5. n8n Node Configuration
Operation-aware node configuration guidance.
Activates when: Configuring nodes, understanding property dependencies, setting up AI workflows.
Key Features:
- Property dependency rules (e.g., sendBody → contentType)
- Operation-specific requirements
- AI connection types (8 types for AI Agent workflows)
- Common configuration patterns
🚀 Installation
Prerequisites
- n8n-mcp MCP server installed and configured (Installation Guide)
- Claude Code, Claude.ai, or Claude API access
.mcp.jsonconfigured with n8n-mcp server
Claude Code
# 1. Clone this repository
git clone https://github.com/czlonkowski/n8n-skills.git
# 2. Copy skills to your Claude Code skills directory
cp -r n8n-skills/skills/* ~/.claude/skills/
# 3. Reload Claude Code
# Skills will activate automatically
Claude.ai
- Download individual skill folders from
skills/ - Zip each skill folder
- Upload via Settings → Capabilities → Skills
API / SDK
See docs/INSTALLATION.md for detailed instructions.
💡 Usage
Skills activate automatically when relevant queries are detected:
"How do I write n8n expressions?"
→ Activates: n8n Expression Syntax
"Find me a Slack node"
→ Activates: n8n MCP Tools Expert
"Build a webhook workflow"
→ Activates: n8n Workflow Patterns
"Why is validation failing?"
→ Activates: n8n Validation Expert
"How do I configure the HTTP Request node?"
→ Activates: n8n Node Configuration
Skills Work Together
When you ask: "Build and validate a webhook to Slack workflow"
- n8n Workflow Patterns identifies webhook processing pattern
- n8n MCP Tools Expert searches for webhook and Slack nodes
- n8n Node Configuration guides node setup
- n8n Expression Syntax helps with data mapping
- n8n Validation Expert validates the final workflow
All 5 skills compose seamlessly!
📖 Documentation
- Installation Guide - Detailed installation for all platforms
- Usage Guide - How to use skills effectively
- Development Guide - Contributing and testing
- MCP Testing Log - Real tool responses used in skills
🔬 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_essentialsis the most common pattern (9,835 occurrences, 18s avg)n8n_update_partial_workflowis 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
Each skill includes 3+ evaluations for quality assurance:
# Run evaluations (if testing framework available)
npm test
# Or manually test with Claude
claude-code --skill n8n-expression-syntax "Test webhook data access"
🤝 Contributing
Contributions welcome! Please see DEVELOPMENT.md for guidelines.
Development Approach
- Evaluation-First: Write test scenarios before implementation
- MCP-Informed: Test tools, document real responses
- Iterative: Test against evaluations, iterate until 100% pass
- Concise: Keep SKILL.md under 500 lines
- Real Examples: All examples from real templates/tools
📝 License
MIT License - see LICENSE file for details.
🙏 Credits
Conceived by Romuald Członkowski
- Website: www.aiadvisors.pl/en
- Part of the n8n-mcp project
🔗 Related Projects
📊 Repository Stats
- 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
Ready to build flawless n8n workflows? Get started now! 🚀