mirror of
https://github.com/czlonkowski/n8n-skills.git
synced 2026-03-16 23:43:08 +00:00
97e1d21793
Implements operation-aware node configuration with progressive discovery. Completes the final skill in the 5-skill n8n meta-skill collection. Files created: - 4 evaluations testing dependencies, operations, conditional fields, tool selection - SKILL.md (692 lines) - Configuration workflow, progressive discovery, patterns - DEPENDENCIES.md (671 lines) - displayOptions mechanism, dependency patterns - OPERATION_PATTERNS.md (783 lines) - 20+ nodes with common configurations - README.md (380 lines) - Skill metadata with usage statistics Key features: - Operation-aware configuration (resource + operation = requirements) - Property dependencies (displayOptions show/hide rules) - Progressive discovery (essentials → dependencies → info) - Configuration workflow (identify → discover → configure → validate → iterate) - 4 common node patterns (resource/operation, HTTP, database, conditional) - Tool selection guide (get_node_essentials 91.7% success rate) - Dependency troubleshooting (field visibility, conditional requirements) - 20+ node configuration examples with gotchas Progressive discovery strategy: 1. get_node_essentials (91.7% success, 18s avg from search) 2. get_property_dependencies (when dependencies unclear) 3. get_node_info (only when necessary, full schema) Property dependency patterns: - Boolean toggle (sendBody → body) - Resource/operation cascade (different ops → different fields) - Type-specific config (string vs number conditions) - Method-specific fields (GET vs POST) Common node patterns covered: - HTTP Request (GET/POST/PUT/DELETE with auth, query, body) - Webhook (basic/auth/response, $json.body gotcha) - Slack (post/update/create channel) - Gmail (send/get with filters) - Postgres (query/insert/update with parameters) - Set (fixed values/mapping with types) - Code (per-item/all-items, no expressions!) - IF (string/number/boolean, unary vs binary) - Switch (rules with fallback) - OpenAI (chat completion with system prompt) - Schedule (daily/interval/cron with timezone) Key insights: - 91.7% configurations succeed with essentials only - Average 56 seconds between configuration edits (iterative) - 9,835 essentials calls vs fewer full schema calls - 18 seconds average from node search to essentials - Different operations = different requirements (always check!) Top 5 gotchas documented: 1. Webhook data under $json.body (not $json) 2. POST needs sendBody: true 3. Slack channel format (#name for public) 4. SQL parameterized queries (prevent injection) 5. Schedule timezone must be explicit (DST handling) displayOptions mechanism: - show: Field appears when conditions match - hide: Field disappears when conditions match - AND logic: All conditions must match - OR logic: Any value matches - Nested: Parent value controls child structure Total: ~2,526 lines across 8 files Based on analysis of 38,287 workflow updates and 9,835 essentials calls. 🎉 ALL 5 CORE SKILLS NOW COMPLETE! 🎉 Skills completed: 1. ✅ n8n Expression Syntax (1,275 lines) 2. ✅ n8n MCP Tools Expert (1,325 lines) 3. ✅ n8n Workflow Patterns (3,932 lines) 4. ✅ n8n Validation Expert (2,553 lines) 5. ✅ n8n Node Configuration (2,526 lines) Total: ~11,611 lines across 36 files + 22 evaluations All skills data-driven from 447,557 real MCP tool usage events. 🤖 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! 🚀