mirror of
https://github.com/czlonkowski/n8n-skills.git
synced 2026-03-16 23:43:08 +00:00
4077036b23
Implements comprehensive Python Code node guidance with critical focus on "NO external libraries" limitation. ## Skill #7 - n8n Code Python **Critical Message**: Use JavaScript for 95% of use cases. Python in n8n has NO external libraries (no requests, pandas, numpy). ### Files Created **Core Skill Files (6 files, 4,205 lines total)**: 1. **SKILL.md** (748 lines) - When to use Python vs JavaScript (95% JavaScript recommendation) - Critical limitation: NO external libraries - Mode selection (All Items vs Each Item) - Data access overview (_input, _json, _node) - Return format requirements - Standard library overview 2. **DATA_ACCESS.md** (702 lines) - _input.all() - Process all items - _input.first() - Get first item - _input.item - Current item (Each Item mode only) - _node["Name"] - Reference other nodes - Webhook body structure (data under ["body"]) - Pattern selection guide - Python vs JavaScript comparison 3. **STANDARD_LIBRARY.md** (974 lines) - Complete reference for available modules - json - JSON parsing and generation - datetime - Date/time operations - re - Regular expressions - base64 - Encoding/decoding - hashlib - Hashing (MD5, SHA256) - urllib.parse - URL operations - math, random, statistics - What's NOT available (requests, pandas, numpy, etc.) - Workarounds for missing libraries 4. **COMMON_PATTERNS.md** (794 lines) - 10 production-tested Python patterns - Multi-source data aggregation - Regex-based filtering - Markdown to structured data - JSON object comparison - CRM data transformation - Release notes processing - Array transformation - Dictionary lookup - Top N filtering - String aggregation - Python vs JavaScript pattern comparison 5. **ERROR_PATTERNS.md** (601 lines) - Top 5 Python-specific errors with solutions - Error #1: ModuleNotFoundError (THE critical Python error) - Error #2: Empty code / missing return - Error #3: KeyError (use .get() instead) - Error #4: IndexError (check bounds first) - Error #5: Incorrect return format - Error prevention checklist - Quick fix reference table - Testing patterns 6. **README.md** (386 lines) - Skill metadata and activation triggers - "JavaScript First" recommendation prominent - What this skill teaches - File structure overview - Integration with other skills - Success metrics checklist - Quick reference guide - Common use cases - Limitations and workarounds - Best practices **Evaluations (5 scenarios)**: 1. **eval-001-module-import-error.json** - Tests understanding of external library limitation - Scenario: ModuleNotFoundError with requests - Expected: Recommend JavaScript or HTTP Request node 2. **eval-002-dictionary-keyerror.json** - Tests safe dictionary access with .get() - Scenario: KeyError when accessing missing field - Expected: Use .get() with default values 3. **eval-003-webhook-body-gotcha.json** - Tests webhook data under ["body"] understanding - Scenario: KeyError when accessing webhook data directly - Expected: Access via data.get("body", {}) 4. **eval-004-return-format-error.json** - Tests proper return format requirement - Scenario: Returning plain dict instead of array - Expected: Return [{"json": {...}}] 5. **eval-005-standard-library-usage.json** - Tests knowledge of available modules - Scenario: What modules for JSON, hashing, dates, regex - Expected: json, hashlib, datetime, re (standard library only) ### Key Features **Critical Limitations Emphasized**: - NO external libraries (no requests, pandas, numpy) - JavaScript recommended for 95% of use cases - Only standard library available - ModuleNotFoundError is #1 Python error **Python-Specific Syntax**: - Underscore prefix: _input, _json, _node (vs $ in JavaScript) - Dictionary access: _json["body"]["field"] (vs dot notation) - Safe access: .get() method with defaults **Complete Standard Library Coverage**: - 15+ modules documented with examples - json, datetime, re, base64, hashlib, urllib.parse - math, random, statistics, collections - Clear list of what's NOT available - Workarounds for missing functionality **Production Patterns**: - 10 tested patterns adapted from JavaScript - Python-specific implementations - List comprehensions and dictionary operations - Standard library usage examples **Error Prevention Focus**: - Top 5 errors cover majority of failures - ModuleNotFoundError prominently featured - Safe dictionary access (.get()) - Proper return format emphasized - Error prevention checklist ### Integration Works seamlessly with: - **n8n Code JavaScript**: Compare approaches, know when to use which - **n8n Expression Syntax**: Different from {{}} expressions - **n8n MCP Tools Expert**: Validate Code node configurations - **n8n Workflow Patterns**: Code nodes in larger workflows - **n8n Node Configuration**: Configure mode and connections ### Statistics - **6 skill files**: 4,205 lines total - **5 evaluations**: Cover critical Python scenarios - **10 patterns**: Production-tested Python code - **15+ modules**: Standard library coverage - **5 top errors**: Prevention and solutions ### Design Principles 1. **JavaScript First**: 95% recommendation throughout 2. **Critical Limitation**: NO external libraries emphasized everywhere 3. **Safe Patterns**: .get() for dicts, bounds checking for lists 4. **Proper Format**: [{"json": {...}}] return format 5. **Standard Library**: Complete reference with examples 6. **Error Prevention**: Top 5 errors with solutions ### Recommendation **Use JavaScript Code node for 95% of use cases.** Use Python only when: - Complex Python-specific logic required - Python standard library features needed - Team more comfortable with Python than JavaScript For HTTP requests, date operations, and most transformations → Use JavaScript. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> 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
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)
- ✅ How to use n8n-mcp tools effectively
- ✅ Proven workflow patterns from real-world usage
- ✅ Validation error interpretation and fixing
- ✅ Operation-aware node configuration
📚 The 7 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
Most Important: Teaches correct MCP tool usage patterns and parameter formats
3. n8n Workflow Patterns
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+ n8n templates
- Connection best practices
- Pattern selection guide
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
6. n8n Code JavaScript
Write effective JavaScript code in n8n Code nodes.
Activates when: Writing JavaScript in Code nodes, troubleshooting Code node errors, making HTTP requests with $helpers, working with dates.
Key Features:
- Data access patterns ($input.all(), $input.first(), $input.item)
- Critical gotcha: Webhook data under
$json.body - Correct return format:
[{json: {...}}] - Built-in functions ($helpers.httpRequest(), DateTime, $jmespath())
- Top 5 error patterns with solutions (covering 62%+ of failures)
- 10 production-tested patterns
7. n8n Code Python
Write Python code in n8n Code nodes with proper limitations awareness.
Activates when: Writing Python in Code nodes, need to know Python limitations, working with standard library.
Key Features:
- Important: Use JavaScript for 95% of use cases
- Python data access (_input, _json, _node)
- Critical limitation: No external libraries (requests, pandas, numpy)
- Standard library reference (json, datetime, re, etc.)
- Workarounds for missing libraries
- Common Python patterns for n8n
🚀 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
Method 1: Plugin Installation (Recommended)
# Install directly as a Claude Code plugin
/plugin install czlonkowski/n8n-skills
Method 2: Via Marketplace
# Add as marketplace, then browse and install
/plugin marketplace add czlonkowski/n8n-skills
# Then browse available plugins
/plugin install
# Select "n8n-mcp-skills" from the list
Method 3: Manual Installation
# 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
"How do I access webhook data in a Code node?"
→ Activates: n8n Code JavaScript
"Can I use pandas in Python Code node?"
→ Activates: n8n Code Python
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 Code JavaScript helps process webhook data with proper .body access
- n8n Expression Syntax helps with data mapping in other nodes
- n8n Validation Expert validates the final workflow
All 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
🧪 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
📊 What's Included
- 7 complementary skills that work together
- 525+ n8n nodes supported
- 2,653+ workflow templates for examples
- 10 production-tested Code node patterns
- Comprehensive error catalogs and troubleshooting guides
Ready to build flawless n8n workflows? Get started now! 🚀