ros/n8n-skills
1
0
Fork 0
mirror of https://github.com/czlonkowski/n8n-skills.git synced 2026-03-16 23:43:08 +00:00
Code Issues Packages Projects Releases Wiki Activity
11 Commits 1 Branch 0 Tags
3866d1bc2a046eb506fd0b0c4452692cf0d9e094
Commit Graph

11 Commits

This Branch
This Branch
All Branches
Author SHA1 Message Date
czlonkowski
3866d1bc2a feat: Add distribution packages for Claude.ai and Claude Code 
Create production-ready distribution packages for different Claude platforms.

## Distribution Packages

**For Claude.ai (Individual Skills)**:
- n8n-expression-syntax-v1.0.0.zip
- n8n-mcp-tools-expert-v1.0.0.zip
- n8n-workflow-patterns-v1.0.0.zip
- n8n-validation-expert-v1.0.0.zip
- n8n-node-configuration-v1.0.0.zip

Each skill packaged individually with files at root level (SKILL.md, reference
files, README.md). Complies with Claude.ai skill upload requirements: exactly
one SKILL.md per zip, files at root, YAML frontmatter included.

**For Claude Code (Bundle)**:
- n8n-mcp-skills-claude-code-v1.0.0.zip

Complete bundle with plugin.json, all 5 skills in skills/ folder, README, and
LICENSE. Ready for Claude Code plugin installation.

## Files Added

1. plugin.json - Claude Code plugin metadata (name, version, skills array)
2. dist/ folder with:
   - 5 individual skill zips (Claude.ai format)
   - 1 bundle zip (Claude Code format)
   - README.md (distribution guide)

## Zip Structure

**Individual Skills** (Claude.ai):
```
skill-name.zip
├── SKILL.md (with frontmatter)
├── [reference-files].md
└── README.md
```

**Bundle** (Claude Code):
```
bundle.zip
├── plugin.json
├── README.md
├── LICENSE
└── skills/
    ├── n8n-expression-syntax/
    ├── n8n-mcp-tools-expert/
    ├── n8n-workflow-patterns/
    ├── n8n-validation-expert/
    └── n8n-node-configuration/
```

## Usage

**Claude.ai**: Upload each skill zip separately via Settings → Features → Skills
**Claude Code**: Extract bundle and copy skills/ to ~/.claude/skills/

Total package sizes:
- Individual skills: 11KB - 36KB each
- Bundle: 102KB (all 5 skills + metadata)

🤖 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
 2025-10-20 12:46:14 +02:00
czlonkowski
bf9e1b46a3 docs: Document workflow activation limitation across skills 
Add critical limitation notice that workflow activation is not supported
via API or MCP and requires manual activation in n8n UI.

Changes:
- WORKFLOW_GUIDE.md: Added prominent warning in lifecycle section with
  deployment steps for users
- SKILL.md (workflow-patterns): Added inline warning in deployment checklist
- scheduled_tasks.md: Added activation reminder in deployment checklist
- VALIDATION_GUIDE.md: Added to best practices "Do" section

Context: During practical workflow deployment, discovered that the
n8n_update_partial_workflow operation with active:true setting does not
activate workflows. This is a critical limitation that users must understand
to successfully deploy workflows built via MCP.

Locations updated (4 files):
1. skills/n8n-mcp-tools-expert/WORKFLOW_GUIDE.md (primary)
2. skills/n8n-workflow-patterns/SKILL.md (deployment phase)
3. skills/n8n-workflow-patterns/scheduled_tasks.md (deployment checklist)
4. skills/n8n-mcp-tools-expert/VALIDATION_GUIDE.md (best practices)

🤖 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
 2025-10-20 12:35:39 +02:00
czlonkowski
33e83c29dc refactor: Remove research context from skill content 
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
 2025-10-20 11:45:04 +02:00
czlonkowski
97e1d21793 feat: Complete Skill #5 - n8n Node Configuration (ALL 5 SKILLS COMPLETE!) 
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
 2025-10-20 11:07:32 +02:00
czlonkowski
68770a2e14 feat: Complete Skill #4 - n8n Validation Expert 
Implements comprehensive validation error interpretation and systematic fixing guidance.
Addresses the validation feedback loop problem (15,107 loops from 19,113 errors).

Files created:
- 4 evaluations testing error interpretation, false positives, auto-sanitization, validation loop
- SKILL.md (690 lines) - Validation philosophy, loop pattern, profiles, auto-sanitization
- ERROR_CATALOG.md (865 lines) - 9 error types with examples and fixes
- FALSE_POSITIVES.md (669 lines) - 6 false positive patterns with decision framework
- README.md (329 lines) - Skill metadata with telemetry statistics

Key features:
- Error severity levels (errors/warnings/suggestions)
- Validation loop pattern (2-3 iterations, 23s+58s average)
- 4 validation profiles (minimal/runtime/ai-friendly/strict)
- Auto-sanitization system (operator structure fixes)
- False positive recognition (~40% of warnings acceptable)
- Error distribution analysis (missing_required 45%, invalid_value 28%)
- Recovery strategies (progressive validation, error triage, clean connections)
- Decision framework for warning acceptance

Error catalog:
- missing_required (45%) - Required field not provided
- invalid_value (28%) - Value doesn't match allowed options
- type_mismatch (12%) - Wrong data type
- invalid_expression (8%) - Expression syntax errors
- invalid_reference (5%) - Referenced node doesn't exist
- operator_structure (2%) - Auto-fixed automatically

False positive patterns:
- Missing error handling (acceptable for dev/test)
- No retry logic (acceptable for internal APIs)
- Missing rate limiting (acceptable for low volume)
- Unbounded queries (acceptable for small datasets)
- Missing input validation (acceptable for trusted sources)
- Hardcoded credentials (never acceptable!)

Validation insights:
- 79% of validation errors lead to feedback loops
- Average 2-3 iterations to valid configuration
- 94% success rate within 3 iterations
- ai-friendly profile reduces false positives by 60%
- Auto-sanitization handles operator structure issues automatically

Total: ~2,553 lines across 8 files

Based on analysis of 19,113 validation errors and 15,107 feedback loops.

🤖 Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
 2025-10-20 11:00:47 +02:00
czlonkowski
651467dee6 feat: Complete Skill #3 - n8n Workflow Patterns 
Implements comprehensive workflow pattern guidance from 31,917 real workflows.
Addresses the most common use case (813 webhook searches).

Files created:
- 5 evaluations testing pattern selection and implementation
- SKILL.md (486 lines) - Pattern overview, selection guide, workflow checklist
- webhook_processing.md (554 lines) - Webhook patterns, $json.body gotcha, auth
- http_api_integration.md (763 lines) - REST APIs, pagination, rate limiting
- database_operations.md (854 lines) - DB ops, batch processing, SQL injection prevention
- ai_agent_workflow.md (918 lines) - AI agents, 8 connection types, tool configuration
- scheduled_tasks.md (845 lines) - Cron schedules, timezone handling, monitoring
- README.md - Skill metadata with pattern statistics

Key features:
- 5 core patterns: Webhook (35%), HTTP API (892 templates), Database (456), AI (234), Scheduled (28%)
- Workflow creation checklist (planning → implementation → validation → deployment)
- Pattern selection guide with statistics
- Common gotchas documented (webhook $json.body, SQL injection, timezone, etc.)
- Error handling strategies for each pattern
- Performance optimization techniques
- Security best practices
- Testing approaches
- Real template examples

Critical insights:
- Webhook data under $json.body (not $json) - #1 gotcha
- Always use parameterized queries (SQL injection prevention)
- ANY node can be an AI tool (connect to ai_tool port)
- Set workflow timezone explicitly (DST handling)
- Authentication via credentials (never hardcode)

Pattern statistics:
- Trigger distribution: Webhook 35%, Schedule 28%, Manual 22%, Service 15%
- Transformation: Set 68%, Code 42%, IF 38%, Switch 18%
- Output: HTTP 45%, Slack 32%, Database 28%, Email 24%
- Complexity: Simple 42%, Medium 38%, Complex 20%

Total: ~4,420 lines across 12 files

Based on analysis of 31,917 real workflows and usage patterns.

🤖 Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
 2025-10-20 10:38:38 +02:00
czlonkowski
f7d34f2b8e feat: Complete Skill #2 - n8n MCP Tools Expert 
Implements comprehensive guidance for using n8n-mcp MCP tools effectively.
This is the HIGHEST PRIORITY skill that addresses the 20% MCP tool failure rate.

Files created:
- 5 evaluations testing tool selection, nodeType formats, validation, and smart parameters
- SKILL.md (505 lines) - Core tool usage guide with telemetry insights
- SEARCH_GUIDE.md (243 lines) - Node discovery tools (search, essentials vs info)
- VALIDATION_GUIDE.md (377 lines) - Configuration validation and auto-sanitization
- WORKFLOW_GUIDE.md (385 lines) - Workflow management with 15 operation types
- README.md - Skill metadata emphasizing highest priority

Key features:
- Tool selection guide with success rates (search_nodes 99.9%, get_node_essentials 91.7%)
- nodeType format distinction (nodes-base.* vs n8n-nodes-base.*)
- Validation profiles explained (minimal/runtime/ai-friendly/strict)
- Smart parameters for IF/Switch nodes (branch="true", case=0)
- Auto-sanitization system for operator structures
- Telemetry insights (56s between edits, 18s search→essentials, 23s+58s validate→fix)
- AI connection types (8 types documented)

Total: ~1,650 lines across 10 files

Based on analysis of 447,557 real MCP tool usage events.

🤖 Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
 2025-10-20 10:26:40 +02:00
czlonkowski
9a5e0c0b89 feat: Complete Skill #1 - n8n Expression Syntax 
## Skill #1 Complete - n8n Expression Syntax

✅ **4 Evaluations Created**:
- eval-001: Missing curly braces
- eval-002: Webhook body data access (critical!)
- eval-003: Code node vs expression confusion
- eval-004: Node reference syntax

✅ **4 Skill Files** (~1,115 lines total):
- SKILL.md (285 lines) - Core concepts, under 500 line limit
- COMMON_MISTAKES.md (380 lines) - 15 common errors with fixes
- EXAMPLES.md (450 lines) - 10 real working examples
- README.md - Skill metadata

## Key Features

🎯 **Critical Gotcha Highlighted**: Webhook data under .body
📚 **Real Examples**: From MCP testing log and templates
⚡ **Quick Fixes**: Fast reference table for common errors
🔍 **Code vs Expression**: Clear distinction when NOT to use {{}}
✨ **Comprehensive**: Covers 95% of expression use cases

## Content Highlights

- Expression format ({{  }})
- Core variables ($json, $node, $now, $env)
- **Webhook data structure** (most common mistake!)
- When NOT to use expressions (Code nodes)
- Array/object access patterns
- Date/time formatting
- String manipulation
- Conditional logic

## Based on MCP Testing

All examples verified against real:
- Webhook node structure from get_node_essentials
- Template #2947 (Weather to Slack)
- Code node guide from tools_documentation
- Real error messages from validation

## Next: Skill #2 - n8n MCP Tools Expert

🤖 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
 2025-10-20 10:19:19 +02:00
czlonkowski
dff62f0c52 feat: Complete Phase 1 - Foundation and Documentation 
## Phase 1 Achievements

✅ Repository Structure:
- Created complete directory structure (skills/, evaluations/)
- Updated .gitignore (removed docs/, keep .mcp.json)

✅ MCP Testing:
- Verified n8n API availability (https://n8n-test.n8n-mcp.com)
- Tested MCP tools comprehensively
- Created MCP_TESTING_LOG.md with real tool responses

✅ Documentation:
- README.md: Comprehensive project overview with data-driven insights
- INSTALLATION.md: Complete installation guide for all platforms
- USAGE.md: Detailed usage examples and cross-skill composition
- DEVELOPMENT.md: Development guidelines and contribution process

## Key Insights from MCP Testing

- 537 nodes available (437 base + 100 langchain)
- 2,653 templates with metadata
- nodeType format differences documented
- Webhook data structure clarified ($json.body)
- Auto-sanitization behavior documented
- All n8n_* tools require API; all others don't

## Next: Phase 2 - Skill #1 (n8n Expression Syntax)

🤖 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
 2025-10-20 10:14:34 +02:00
czlonkowski
cafdb175d9 Add MCP configuration and project guidelines 
- Add .gitignore to exclude docs/ and .mcp.json
- Add .mcp.json.example as template for n8n-mcp server configuration
- Add CLAUDE.md with comprehensive project instructions for AI assistants

🤖 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
 2025-10-20 09:43:09 +02:00
Romuald Członkowski
b04596d577 Initial commit 2025-10-20 07:51:27 +02:00