diff --git a/.gitignore b/.gitignore index 7ee1eb8..c23d465 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1 @@ -docs/ .mcp.json diff --git a/README.md b/README.md index 3f8caa7..08592dd 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,251 @@ # n8n-skills -n8n skillset for Claude Code to build flawless n8n workflows + +**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) + +--- + +## 🎯 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. + +### 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 + +1. **n8n-mcp MCP server** installed and configured ([Installation Guide](https://github.com/romualdczlonkowski/n8n-mcp)) +2. **Claude Code**, Claude.ai, or Claude API access +3. `.mcp.json` configured with n8n-mcp server + +### Claude Code + +```bash +# 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 + +1. Download individual skill folders from `skills/` +2. Zip each skill folder +3. Upload via Settings β†’ Capabilities β†’ Skills + +### API / SDK + +See [docs/INSTALLATION.md](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"** + +1. **n8n Workflow Patterns** identifies webhook processing pattern +2. **n8n MCP Tools Expert** searches for webhook and Slack nodes +3. **n8n Node Configuration** guides node setup +4. **n8n Expression Syntax** helps with data mapping +5. **n8n Validation Expert** validates the final workflow + +All 5 skills compose seamlessly! + +--- + +## πŸ“– Documentation + +- [Installation Guide](docs/INSTALLATION.md) - Detailed installation for all platforms +- [Usage Guide](docs/USAGE.md) - How to use skills effectively +- [Development Guide](docs/DEVELOPMENT.md) - Contributing and testing +- [MCP Testing Log](docs/MCP_TESTING_LOG.md) - 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_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 + +Each skill includes 3+ evaluations for quality assurance: + +```bash +# 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](docs/DEVELOPMENT.md) for guidelines. + +### Development Approach + +1. **Evaluation-First**: Write test scenarios before implementation +2. **MCP-Informed**: Test tools, document real responses +3. **Iterative**: Test against evaluations, iterate until 100% pass +4. **Concise**: Keep SKILL.md under 500 lines +5. **Real Examples**: All examples from real templates/tools + +--- + +## πŸ“ License + +MIT License - see [LICENSE](LICENSE) file for details. + +--- + +## πŸ™ Credits + +**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) + +--- + +## πŸ”— Related Projects + +- [n8n-mcp](https://github.com/romualdczlonkowski/n8n-mcp) - MCP server for n8n +- [n8n](https://n8n.io/) - Workflow automation platform + +--- + +## πŸ“Š 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!** πŸš€ diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md new file mode 100644 index 0000000..c414823 --- /dev/null +++ b/docs/DEVELOPMENT.md @@ -0,0 +1,633 @@ +# Development Guide + +Guidelines for contributing to n8n-skills and developing new skills. + +--- + +## Development Philosophy + +### 1. Evaluation-Driven Development (EDD) + +Write tests **before** writing skills! + +**Process**: +``` +1. Create 3+ evaluation scenarios +2. Test baseline (without skill) +3. Write minimal SKILL.md +4. Test against evaluations +5. Iterate until 100% pass +6. Add reference files as needed +``` + +**Why**: Ensures skills solve real problems and can be tested objectively. + +### 2. MCP-Informed Content + +All content based on **real MCP tool responses**, not assumptions. + +**Process**: +``` +1. Test MCP tools thoroughly +2. Document actual responses +3. Use real examples in skills +4. Verify all code snippets work +``` + +**See**: [MCP_TESTING_LOG.md](MCP_TESTING_LOG.md) for reference data. + +### 3. Keep Skills Concise + +**Guideline**: SKILL.md should be under 500 lines + +**Why**: Longer skills are harder to maintain and slower to load. + +**Solution**: Split complex content into reference files: +- SKILL.md: Core concepts and quick reference +- REFERENCE_*.md: Detailed information +- EXAMPLES.md: Working examples + +### 4. Real Examples Only + +**Never** invent examples. Always use: +- Real templates from n8n-mcp +- Actual MCP tool responses +- Verified node configurations + +--- + +## Repository Structure + +``` +n8n-skills/ +β”œβ”€β”€ skills/ # Skill implementations +β”‚ β”œβ”€β”€ n8n-expression-syntax/ +β”‚ β”‚ β”œβ”€β”€ SKILL.md # Main skill content (< 500 lines) +β”‚ β”‚ β”œβ”€β”€ COMMON_MISTAKES.md +β”‚ β”‚ β”œβ”€β”€ EXAMPLES.md +β”‚ β”‚ └── README.md # Skill metadata +β”‚ └── ... +β”œβ”€β”€ evaluations/ # Test scenarios +β”‚ β”œβ”€β”€ expression-syntax/ +β”‚ β”‚ β”œβ”€β”€ eval-001-*.json +β”‚ β”‚ └── ... +β”‚ └── ... +β”œβ”€β”€ docs/ # Documentation +β”‚ β”œβ”€β”€ INSTALLATION.md +β”‚ β”œβ”€β”€ USAGE.md +β”‚ β”œβ”€β”€ DEVELOPMENT.md (this file) +β”‚ └── MCP_TESTING_LOG.md # Real MCP responses +β”œβ”€β”€ README.md # Project overview +β”œβ”€β”€ LICENSE # MIT License +└── .gitignore +``` + +--- + +## Creating a New Skill + +### Step 1: Define Scope + +**Questions to answer**: +- What problem does this skill solve? +- When should it activate? +- What MCP tools will it teach? +- What are 3 key examples? + +**Document in**: `skills/[skill-name]/README.md` + +### Step 2: Create Evaluations + +**Create**: `evaluations/[skill-name]/eval-001-description.json` + +**Format**: +```json +{ + "id": "skill-001", + "skills": ["skill-name"], + "query": "User question or scenario", + "expected_behavior": [ + "Skill should identify X", + "Skill should provide Y guidance", + "Skill should reference Z content" + ], + "baseline_without_skill": { + "likely_response": "Generic answer", + "expected_quality": "Low" + }, + "with_skill_expected": { + "response_quality": "High", + "uses_skill_content": true, + "provides_correct_guidance": true + } +} +``` + +**Create at least 3 evaluations** covering: +1. Basic usage +2. Common mistake +3. Advanced scenario + +### Step 3: Test MCP Tools + +**Document tool responses** in `docs/MCP_TESTING_LOG.md`: + +```markdown +## [Your Skill Name] - MCP Testing + +### Tool: tool_name + +**Test**: +```javascript +tool_name({param: "value"}) +``` + +**Response**: +```json +{actual response} +``` + +**Key Insights**: +- Finding 1 +- Finding 2 +``` + +### Step 4: Write SKILL.md + +**Required frontmatter**: +```markdown +--- +name: Skill Name +description: When to use this skill. Use when [trigger conditions]. +--- +``` + +**Recommended structure**: +```markdown +# Skill Name + +## Quick Reference +[Table or list of most common patterns] + +## Core Concepts +[Essential knowledge] + +## Common Patterns +[Real examples with code] + +## Common Mistakes +[Errors and fixes] + +## Advanced Topics +[Link to reference files] + +## Related Skills +[Cross-references] +``` + +**Guidelines**: +- Under 500 lines for SKILL.md +- Use real examples from MCP testing +- Include quick fixes table +- Link to reference files +- Cross-reference other skills + +### Step 5: Add Reference Files + +Create as needed: +- `COMMON_MISTAKES.md` - Error catalog +- `EXAMPLES.md` - Working examples +- `PATTERNS.md` - Common patterns +- `ADVANCED.md` - Deep dive topics + +**Each file**: +- Should be focused on one topic +- Under 200 lines +- Real examples only +- Cross-linked from SKILL.md + +### Step 6: Test Against Evaluations + +**Process**: +1. Run evaluation scenarios with Claude +2. Check if expected behaviors occur +3. Document results +4. Iterate SKILL.md if needed +5. Repeat until 100% pass + +**Success criteria**: +- All evaluations pass +- Skill activates correctly +- Content is accurate +- Examples work + +### Step 7: Document Metadata + +**Create**: `skills/[skill-name]/README.md` + +```markdown +# Skill Name + +**Purpose**: One-sentence description + +**Activates on**: keyword1, keyword2, keyword3 + +**File Count**: X files, ~Y lines + +**Dependencies**: +- n8n-mcp tools: tool1, tool2 +- Other skills: skill1, skill2 + +**Coverage**: +- Topic 1 +- Topic 2 +- Topic 3 + +**Evaluations**: X scenarios (X% pass rate) + +**Last Updated**: YYYY-MM-DD +``` + +--- + +## Evaluation Guidelines + +### Good Evaluations + +**Characteristics**: +- Specific, measurable expected behavior +- Based on real user queries +- Cover common and edge cases +- Include baseline comparison + +**Example**: +```json +{ + "id": "expr-001", + "query": "Why is {{$json.email}} undefined in my webhook workflow?", + "expected_behavior": [ + "Identifies webhook data structure issue", + "Explains data is under $json.body", + "Provides corrected expression: {{$json.body.email}}", + "References webhook structure documentation" + ] +} +``` + +### Bad Evaluations + +**Avoid**: +- Vague expected behaviors +- Unrealistic scenarios +- No baseline comparison +- Too simple or too complex + +--- + +## Testing + +### Manual Testing + +``` +1. Start Claude Code +2. Load skill +3. Ask evaluation query +4. Verify expected behaviors +5. Document results +``` + +### Automated Testing + +*Coming soon: Evaluation framework* + +--- + +## MCP Tool Testing Guidelines + +### Before Writing Skills + +**Test these tools**: +```javascript +// Node discovery +search_nodes({query: "keyword"}) +list_nodes({category: "trigger"}) +get_node_essentials({nodeType: "nodes-base.webhook"}) + +// Validation +validate_node_minimal({nodeType: "nodes-base.slack", config: {}}) +validate_node_operation({nodeType: "nodes-base.slack", config: {...}, profile: "runtime"}) + +// Templates +search_templates({query: "webhook"}) +get_template({templateId: 2947, mode: "structure"}) + +// Workflow management (if API available) +n8n_create_workflow({...}) +n8n_update_partial_workflow({...}) +n8n_validate_workflow({...}) +``` + +### Document Findings + +**In MCP_TESTING_LOG.md**: +- Actual responses +- Performance (timing) +- Gotchas discovered +- Format differences +- Error messages + +### Use Real Data + +**Extract from tools**: +- Node structures +- Template examples +- Validation errors +- Property dependencies + +**Use in skills**: +- Real node configurations +- Actual error messages +- Working template IDs +- Proven patterns + +--- + +## Code Standards + +### Markdown + +**Formatting**: +```markdown +# H1 - Skill Title +## H2 - Major Sections +### H3 - Subsections + +**Bold** for emphasis +`code` for inline code +\`\`\`language for code blocks +``` + +**Code blocks**: +```javascript +// Always specify language +// Include comments +// Use real, working examples +``` + +### JSON (Evaluations) + +**Format**: +```json +{ + "id": "kebab-case-id", + "skills": ["exact-skill-name"], + "query": "Natural user question", + "expected_behavior": [ + "Specific measurable behavior" + ] +} +``` + +--- + +## Git Workflow + +### Branching + +```bash +# Feature branch +git checkout -b skill/skill-name + +# Bug fix +git checkout -b fix/issue-description +``` + +### Commits + +**Format**: +``` +type(scope): brief description + +Longer description if needed. + +Refs: #issue-number +``` + +**Types**: +- `feat`: New skill or feature +- `fix`: Bug fix +- `docs`: Documentation +- `test`: Evaluations +- `refactor`: Code improvement + +**Examples**: +``` +feat(expression-syntax): add webhook data structure guide +fix(mcp-tools): correct nodeType format examples +docs(usage): add cross-skill composition examples +test(validation): add auto-sanitization evaluation +``` + +### Pull Requests + +**Include**: +- Description of changes +- Evaluation results (if new skill) +- MCP testing performed +- Documentation updated + +**Template**: +```markdown +## Description +[What changed and why] + +## Evaluations +- [ ] eval-001: PASS +- [ ] eval-002: PASS +- [ ] eval-003: PASS + +## MCP Testing +- Tested tools: [list] +- New findings: [list] + +## Documentation +- [ ] SKILL.md updated +- [ ] README.md updated +- [ ] MCP_TESTING_LOG.md updated + +## Checklist +- [ ] SKILL.md under 500 lines +- [ ] Real examples only +- [ ] All evaluations pass +- [ ] Cross-references added +``` + +--- + +## File Naming Conventions + +### Skills + +``` +skills/skill-name/ + SKILL.md # Main content + COMMON_MISTAKES.md # Error catalog + EXAMPLES.md # Working examples + README.md # Metadata + [optional files].md # Additional references +``` + +### Evaluations + +``` +evaluations/skill-name/ + eval-001-short-description.json + eval-002-short-description.json + eval-003-short-description.json +``` + +**Naming**: `eval-NNN-kebab-case-description.json` + +--- + +## Documentation Standards + +### SKILL.md Frontmatter + +**Required**: +```yaml +--- +name: Exact Skill Name +description: When this skill activates. Use when [triggers]. Include specific keywords. +--- +``` + +### Cross-References + +**Link to**: +- Related skills +- Reference files +- MCP tool documentation +- Real templates + +**Format**: +```markdown +See [n8n MCP Tools Expert](../n8n-mcp-tools-expert/SKILL.md) +See [COMMON_MISTAKES.md](COMMON_MISTAKES.md) +See template #2947 for example +``` + +--- + +## Quality Checklist + +Before submitting a skill: + +### Content Quality +- [ ] All examples tested with real MCP tools +- [ ] No invented/fake examples +- [ ] SKILL.md under 500 lines +- [ ] Clear, actionable guidance +- [ ] Real error messages included + +### Testing +- [ ] 3+ evaluations created +- [ ] All evaluations pass +- [ ] Baseline comparison documented +- [ ] Cross-skill integration tested + +### Documentation +- [ ] Frontmatter correct +- [ ] README.md metadata complete +- [ ] MCP_TESTING_LOG.md updated +- [ ] Cross-references added +- [ ] Examples documented + +### Code Standards +- [ ] Markdown properly formatted +- [ ] Code blocks have language specified +- [ ] Consistent naming conventions +- [ ] Proper git commits + +--- + +## Common Pitfalls + +### ❌ Don't + +- Invent examples or data +- Exceed 500 lines in SKILL.md +- Skip MCP tool testing +- Write skills without evaluations +- Use generic error messages +- Assume tool behavior + +### βœ… Do + +- Test tools and document responses +- Use real templates and configurations +- Write evaluations first +- Keep skills concise +- Cross-reference related skills +- Verify all code works + +--- + +## Release Process + +### Version Numbering + +**Format**: `MAJOR.MINOR.PATCH` + +- **MAJOR**: New skills added +- **MINOR**: Skill improvements +- **PATCH**: Bug fixes, typos + +### Changelog + +Update `CHANGELOG.md`: +```markdown +## [1.1.0] - 2025-10-20 + +### Added +- New skill: n8n Expression Syntax +- 3 evaluations for expression syntax + +### Changed +- Improved MCP Tools Expert validation guidance + +### Fixed +- Corrected nodeType format in examples +``` + +--- + +## Support + +### Getting Help + +- **Issues**: https://github.com/czlonkowski/n8n-skills/issues +- **Discussions**: https://github.com/czlonkowski/n8n-skills/discussions +- **n8n-mcp**: https://github.com/romualdczlonkowski/n8n-mcp + +### Reporting Bugs + +**Include**: +- Skill name and version +- Evaluation that fails +- Expected vs actual behavior +- MCP tool versions + +--- + +## License + +All contributions must be compatible with MIT License. + +--- + +**Happy developing!** πŸš€ + +--- + +Conceived by Romuald CzΕ‚onkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en) diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md new file mode 100644 index 0000000..00ca54e --- /dev/null +++ b/docs/INSTALLATION.md @@ -0,0 +1,336 @@ +# Installation Guide + +Complete installation instructions for n8n-skills across all platforms. + +--- + +## Prerequisites + +### 1. n8n-mcp MCP Server + +You **must** have the n8n-mcp MCP server installed and configured before using these skills. + +**Install n8n-mcp**: +```bash +npm install -g n8n-mcp +``` + +**Configure MCP server** in `.mcp.json`: +```json +{ + "mcpServers": { + "n8n-mcp": { + "command": "npx", + "args": ["n8n-mcp"], + "env": { + "MCP_MODE": "stdio", + "LOG_LEVEL": "error", + "DISABLE_CONSOLE_OUTPUT": "true", + "N8N_API_URL": "https://your-n8n-instance.com", + "N8N_API_KEY": "your-api-key-here" + } + } + } +} +``` + +**Note**: `N8N_API_URL` and `N8N_API_KEY` are optional but enable workflow creation/management tools. + +### 2. Claude Access + +You need one of: +- **Claude Code** (desktop application) +- **Claude.ai** (web interface) +- **Claude API** (via SDK) + +--- + +## Installation Methods + +### Method 1: Claude Code (Recommended) + +**Step 1**: Clone the repository +```bash +git clone https://github.com/czlonkowski/n8n-skills.git +cd n8n-skills +``` + +**Step 2**: Copy skills to Claude Code skills directory + +**macOS/Linux**: +```bash +mkdir -p ~/.claude/skills +cp -r skills/* ~/.claude/skills/ +``` + +**Windows**: +```powershell +New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\skills" +Copy-Item -Recurse skills\* "$env:USERPROFILE\.claude\skills\" +``` + +**Step 3**: Verify installation +```bash +ls ~/.claude/skills/ +# Should show: n8n-expression-syntax, n8n-mcp-tools-expert, etc. +``` + +**Step 4**: Reload Claude Code +- Restart Claude Code application +- Skills will activate automatically + +--- + +### Method 2: Claude.ai (Web Interface) + +**Step 1**: Download skill folders + +Download the repository and navigate to `skills/` directory. You'll need to upload each skill individually. + +**Step 2**: Zip each skill +```bash +cd skills +zip -r n8n-expression-syntax.zip n8n-expression-syntax/ +zip -r n8n-mcp-tools-expert.zip n8n-mcp-tools-expert/ +zip -r n8n-workflow-patterns.zip n8n-workflow-patterns/ +zip -r n8n-validation-expert.zip n8n-validation-expert/ +zip -r n8n-node-configuration.zip n8n-node-configuration/ +``` + +**Step 3**: Upload to Claude.ai + +1. Go to Claude.ai +2. Navigate to **Settings** β†’ **Capabilities** β†’ **Skills** +3. Click **Upload Skill** +4. Upload each `.zip` file individually +5. Confirm each upload + +**Step 4**: Verify skills are active + +In a new conversation, type: +``` +"List my active skills" +``` + +You should see all 5 n8n skills listed. + +--- + +### Method 3: Claude API / SDK + +**Step 1**: Install via package manager + +If you're building an application with Claude SDK: + +```typescript +import Anthropic from '@anthropic-ai/sdk'; + +const client = new Anthropic({ + apiKey: process.env.ANTHROPIC_API_KEY, +}); + +// Load skills from directory +const skillsDir = './skills'; +const skills = loadSkillsFromDirectory(skillsDir); + +const response = await client.messages.create({ + model: 'claude-sonnet-4-5-20250929', + messages: [{ + role: 'user', + content: 'Build a webhook to Slack workflow' + }], + skills: skills // Pass loaded skills +}); +``` + +**Step 2**: Skill loading function + +```typescript +import fs from 'fs'; +import path from 'path'; + +function loadSkillsFromDirectory(dir: string) { + const skillDirs = fs.readdirSync(dir); + return skillDirs.map(skillName => { + const skillPath = path.join(dir, skillName, 'SKILL.md'); + const skillContent = fs.readFileSync(skillPath, 'utf-8'); + + return { + name: skillName, + content: skillContent + }; + }); +} +``` + +--- + +## Verification + +### Test Installation + +**1. Check MCP server availability** +``` +Ask Claude: "Can you search for the webhook node using n8n-mcp?" +``` + +Expected response: +``` +[Uses search_nodes tool] +Found: nodes-base.webhook (Webhook trigger node) +``` + +**2. Test skill activation** +``` +Ask Claude: "How do I access webhook data in n8n expressions?" +``` + +Expected response: +``` +[n8n Expression Syntax skill activates] +Webhook data is under $json.body... +``` + +**3. Test cross-skill composition** +``` +Ask Claude: "Build and validate a webhook to Slack workflow" +``` + +Expected: All 5 skills should activate and work together. + +--- + +## Troubleshooting + +### Skills Not Activating + +**Problem**: Skills don't activate when expected + +**Solutions**: +1. Verify skills are in correct directory: + - Claude Code: `~/.claude/skills/` + - Check each skill has `SKILL.md` with frontmatter + +2. Check SKILL.md frontmatter format: + ```markdown + --- + name: n8n Expression Syntax + description: Validate n8n expression syntax... + --- + ``` + +3. Reload Claude Code or clear cache + +### MCP Tools Not Available + +**Problem**: "n8n-mcp tools not available" + +**Solutions**: +1. Verify `.mcp.json` is in correct location +2. Check n8n-mcp is installed: `npm list -g n8n-mcp` +3. Test MCP server: `npx n8n-mcp` +4. Restart Claude Code + +### N8N API Tools Missing + +**Problem**: "n8n_create_workflow not available" + +**Solutions**: +1. Verify `N8N_API_URL` and `N8N_API_KEY` in `.mcp.json` +2. Test API access: `curl -H "X-N8N-API-KEY: your-key" https://your-n8n-instance/api/v1/workflows` +3. Skills will still work with read-only tools (search, validate, templates) + +### Permission Issues + +**Problem**: Cannot write to skills directory + +**macOS/Linux**: +```bash +sudo chown -R $USER ~/.claude +chmod -R 755 ~/.claude/skills +``` + +**Windows**: Run PowerShell as Administrator + +--- + +## Uninstallation + +### Remove All Skills + +**Claude Code**: +```bash +rm -rf ~/.claude/skills/n8n-* +``` + +**Claude.ai**: +1. Go to Settings β†’ Capabilities β†’ Skills +2. Delete each n8n skill individually + +### Remove Specific Skill + +```bash +rm -rf ~/.claude/skills/n8n-expression-syntax +``` + +--- + +## Updating + +### Update All Skills + +```bash +cd n8n-skills +git pull origin main +cp -r skills/* ~/.claude/skills/ +``` + +### Update Single Skill + +```bash +cp -r skills/n8n-expression-syntax ~/.claude/skills/ +``` + +--- + +## Advanced Configuration + +### Custom Skill Location + +If using custom skills directory: + +```bash +# Set environment variable +export CLAUDE_SKILLS_DIR="/path/to/custom/skills" + +# Copy skills +cp -r skills/* $CLAUDE_SKILLS_DIR/ +``` + +### Selective Installation + +Install only specific skills: + +```bash +# Only expression syntax and MCP tools expert +cp -r skills/n8n-expression-syntax ~/.claude/skills/ +cp -r skills/n8n-mcp-tools-expert ~/.claude/skills/ +``` + +--- + +## Next Steps + +βœ… Installation complete? Continue to [USAGE.md](USAGE.md) for usage examples. + +--- + +## Support + +- **Issues**: https://github.com/czlonkowski/n8n-skills/issues +- **Discussions**: https://github.com/czlonkowski/n8n-skills/discussions +- **n8n-mcp**: https://github.com/romualdczlonkowski/n8n-mcp + +--- + +Conceived by Romuald CzΕ‚onkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en) diff --git a/docs/MCP_TESTING_LOG.md b/docs/MCP_TESTING_LOG.md new file mode 100644 index 0000000..0b8ade3 --- /dev/null +++ b/docs/MCP_TESTING_LOG.md @@ -0,0 +1,171 @@ +# MCP Tool Testing Log +## Generated: 2025-10-20 +## Purpose: Document actual tool responses for skill content creation + +This log contains real responses from n8n-mcp tools to inform accurate skill content. + +--- + +## n8n API Status + +**Health Check Result**: +```json +{ + "status": "ok", + "apiUrl": "https://n8n-test.n8n-mcp.com", + "mcpVersion": "2.20.3", + "versionCheck": "up to date", + "responseTime": 798ms +} +``` + +βœ… **n8n API Tools Available**: All workflow creation/management tools functional + +--- + +## Database Statistics + +```json +{ + "totalNodes": 537, + "totalTemplates": 2653, + "statistics": { + "aiTools": 270, + "triggers": 108, + "versionedNodes": 141, + "nodesWithDocumentation": 470, + "documentationCoverage": "88%" + }, + "packageBreakdown": [ + {"package": "@n8n/n8n-nodes-langchain", "nodeCount": 100}, + {"package": "n8n-nodes-base", "nodeCount": 437} + ] +} +``` + +**Key Insights**: +- 537 nodes total (437 base + 100 langchain) +- 270 AI-capable tools +- 108 trigger nodes +- 88% documentation coverage +- 2,653 templates with avg 4,115 views + +--- + +## Search Tool Testing + +### search_nodes - Common Queries + +**Query: "webhook"** β†’ Returns Webhook (trigger), Respond to Webhook (transform) +- nodeType format: `nodes-base.webhook` +- workflowNodeType format: `n8n-nodes-base.webhook` +- ⚠️ **Critical**: Use different formats for different tools! + +**Query: "http"** β†’ Returns HTTP Request, HTTP Request Tool (AI), Code Tool +- Regular: `nodes-base.httpRequest` +- AI Tool: `nodes-langchain.toolHttpRequest` + +**Query: "database"** β†’ Returns Firebase, Redis Vector Store, etc. + +--- + +## Node Essentials Testing + +### Webhook Node + +**Key Properties**: +- `httpMethod`: GET, POST, PUT, DELETE, etc. (default: GET) +- `path`: Webhook URL path (e.g., "form-submit") +- `responseMode`: onReceived, lastNode, responseNode +- **CRITICAL**: Webhook data structure is `$json.body.*` not `$json.*` + +**Output Structure**: +```javascript +{ + "headers": {...}, + "params": {...}, + "query": {...}, + "body": { // ⚠️ User data is HERE! + "name": "John", + "email": "john@example.com" + } +} +``` + +--- + +## Validation Testing + +### Validation Profiles Comparison + +**Test Config**: `{resource: "channel", operation: "create"}` on Slack node + +**Result**: Missing required field "name" +- All profiles detected this error +- Fix provided: "Provide a channel name" +- Warning about rate limits (best practice) + +--- + +## Template Analysis + +**Total Templates**: 2,653 +**Popular Templates** (webhook + slack): +- #2947: Weather via Slack (1,500 views) - Webhook β†’ OpenStreetMap β†’ NWS β†’ Slack +- #4039: Download Slack Media (778 views) - SlackTrigger β†’ HTTP Request +- #5529: Jamf Patch to Slack (147 views) - Complex multi-node + +**Key Pattern**: Webhook β†’ Transform β†’ Action β†’ Notify (5-7 nodes avg) + +--- + +## Critical Findings for Skills + +### 1. Expression Syntax (Skill #1) +- βœ… Webhook data under `.body` (not root) +- βœ… Code nodes use direct access ($json), NOT expressions ({{}}) +- βœ… Node references: `$node["Node Name"].json.field` + +### 2. MCP Tools Expert (Skill #2) +- βœ… nodeType formats differ: `nodes-base.*` vs `n8n-nodes-base.*` +- βœ… get_node_essentials preferred over get_node_info (5KB vs 100KB+) +- βœ… Validation profiles: minimal/runtime/ai-friendly/strict +- βœ… Smart parameters: branch="true"/"false" for IF, case=N for Switch +- βœ… Auto-sanitization runs on ALL nodes during any update + +### 3. Workflow Patterns (Skill #3) +- βœ… 2,653 real templates available +- βœ… Template metadata includes complexity, setup time, services +- βœ… Common pattern: Trigger β†’ Process β†’ Act (5-7 nodes) +- βœ… Webhook workflows: 27.6% of all workflows + +### 4. Validation Expert (Skill #4) +- βœ… Real validation errors documented +- βœ… Auto-sanitization fixes operator structures +- βœ… Binary operators (equals, contains) vs unary (isEmpty, isNotEmpty) + +### 5. Node Configuration (Skill #5) +- βœ… Property dependencies documented (e.g., sendBody β†’ contentType) +- βœ… Operation-specific requirements vary +- βœ… 8 AI connection types supported + +--- + +## Tools Availability Summary + +**Available WITHOUT n8n API**: +- search_nodes, list_nodes, get_node_essentials βœ… +- validate_node_minimal, validate_node_operation βœ… +- validate_workflow, get_property_dependencies βœ… +- search_templates, get_template, list_tasks βœ… + +**Requires n8n API** (AVAILABLE at n8n-test.n8n-mcp.com): +- n8n_create_workflow βœ… +- n8n_update_partial_workflow βœ… +- n8n_validate_workflow (by ID) βœ… +- n8n_list_workflows, n8n_get_workflow βœ… +- n8n_trigger_webhook_workflow βœ… + +--- + +**Testing Complete**: Ready for skill implementation with real data! diff --git a/docs/SKILLS_IMPLEMENTATION_GUIDE.md b/docs/SKILLS_IMPLEMENTATION_GUIDE.md new file mode 100644 index 0000000..759d0f7 --- /dev/null +++ b/docs/SKILLS_IMPLEMENTATION_GUIDE.md @@ -0,0 +1,2021 @@ +# 🎯 COMPLETE IMPLEMENTATION GUIDE: n8n-mcp Claude Skills (Path 1) + +## Project Overview + +**Objective**: Create 5 complementary meta-skills that teach Claude how to use n8n-mcp MCP tools effectively for building n8n workflows. + +**Architecture**: +- **n8n-mcp MCP Server**: Provides data access (525 nodes, validation, templates) +- **Claude Skills**: Provides expert guidance on HOW to use MCP tools +- **Together**: Expert workflow builder with progressive disclosure + +**Repository Structure**: +``` +n8n-mcp-skills/ +β”œβ”€β”€ README.md +β”œβ”€β”€ LICENSE +β”œβ”€β”€ skills/ +β”‚ β”œβ”€β”€ n8n-expression-syntax/ +β”‚ β”œβ”€β”€ n8n-mcp-tools-expert/ +β”‚ β”œβ”€β”€ n8n-workflow-patterns/ +β”‚ β”œβ”€β”€ n8n-validation-expert/ +β”‚ └── n8n-node-configuration/ +β”œβ”€β”€ evaluations/ +β”‚ β”œβ”€β”€ expression-syntax/ +β”‚ β”œβ”€β”€ mcp-tools/ +β”‚ β”œβ”€β”€ workflow-patterns/ +β”‚ β”œβ”€β”€ validation-expert/ +β”‚ └── node-configuration/ +β”œβ”€β”€ docs/ +β”‚ └── DEVELOPMENT.md +└── package.json (for distribution metadata) +``` + +--- + +## Implementation Timeline + +**Week 1**: Expression Syntax (PoC) +**Week 2**: MCP Tools Expert + Workflow Patterns +**Week 3**: Validation Expert + Node Configuration +**Week 4**: Testing, refinement, documentation +**Week 5-6**: Distribution, plugin packaging + +--- + +# SKILL #1: n8n Expression Syntax (PoC - Week 1) + +## Priority: Foundation (Week 1) +**Purpose**: Teach correct n8n expression syntax and common patterns +**File Count**: 4 files +**Total Lines**: ~350 lines +**Complexity**: Simple (good starting point) + +## Directory Structure + +``` +skills/n8n-expression-syntax/ +β”œβ”€β”€ SKILL.md # 200 lines - main instructions +β”œβ”€β”€ COMMON_MISTAKES.md # 100 lines - error catalog +β”œβ”€β”€ EXAMPLES.md # 50 lines - working examples +└── README.md # metadata for GitHub +``` + +## File: SKILL.md + +```markdown +--- +name: n8n Expression Syntax +description: Validate n8n expression syntax and fix common errors. Use when writing n8n expressions, using {{}} syntax, accessing $json/$node variables, or troubleshooting expression errors in workflows. +--- + +# n8n Expression Syntax + +## Expression format + +All dynamic content in n8n uses double curly braces: + +``` +{{expression}} +``` + +## Core variables + +**$json** - Current node's output data +``` +{{$json.fieldName}} +{{$json['field with spaces']}} +``` + +**$node** - Other node's output data +``` +{{$node["Node Name"].json.fieldName}} +{{$node["HTTP Request"].json.data}} +``` + +**$now** - Current timestamp +``` +{{$now}} +{{$now.toFormat('yyyy-MM-dd')}} +``` + +**$env** - Environment variables +``` +{{$env.API_KEY}} +``` + +## Common patterns + +### Access nested fields +``` +βœ… {{$json.user.email}} +βœ… {{$json.data[0].name}} +βœ… {{$json['response']['items']}} +``` + +### Reference other nodes +``` +βœ… {{$node["HTTP Request"].json.data}} +βœ… {{$node["Webhook"].json.body.user_id}} +``` + +### Handle spaces in field names +``` +❌ {{$json.field name}} +βœ… {{$json['field name']}} +``` + +### Handle spaces in node names +``` +❌ {{$node.HTTP Request.json}} +βœ… {{$node["HTTP Request"].json}} +``` + +## Validation rules + +1. **Always use {{}}** - Expressions must be wrapped +2. **Use quotes for spaces** - Bracket notation for field/node names with spaces +3. **Match exact node names** - Node references are case-sensitive +4. **No nested {{}}** - Don't double-wrap expressions + +## Common mistakes + +For complete error catalog, see [COMMON_MISTAKES.md](COMMON_MISTAKES.md) + +**Quick fixes:** + +| Mistake | Fix | +|---------|-----| +| `$json.field` | `{{$json.field}}` | +| `{{$json.field name}}` | `{{$json['field name']}}` | +| `{{$node.HTTP Request}}` | `{{$node["HTTP Request"]}}` | +| `{{{$json.field}}}` | `{{$json.field}}` | + +## Examples + +For working examples, see [EXAMPLES.md](EXAMPLES.md) + +## When NOT to use expressions + +❌ Inside Code node (use JavaScript directly) +❌ In webhook paths (use static text) +❌ In credential fields (use credential system) +``` + +## File: COMMON_MISTAKES.md + +```markdown +# Common n8n Expression Mistakes + +## Missing curly braces + +**Problem**: Expression not recognized + +❌ **Wrong:** +``` +$json.email +``` + +βœ… **Correct:** +``` +{{$json.email}} +``` + +**Why it fails**: n8n treats text without {{}} as literal string + +--- + +## Spaces in field names + +**Problem**: Syntax error or undefined + +❌ **Wrong:** +``` +{{$json.first name}} +``` + +βœ… **Correct:** +``` +{{$json['first name']}} +``` + +**Why it fails**: Space breaks dot notation, must use bracket notation + +--- + +## Spaces in node names + +**Problem**: Cannot access other node's data + +❌ **Wrong:** +``` +{{$node.HTTP Request.json.data}} +``` + +βœ… **Correct:** +``` +{{$node["HTTP Request"].json.data}} +``` + +**Why it fails**: Node names are treated as strings, need quotes + +--- + +## Incorrect node reference + +**Problem**: Undefined or wrong data + +❌ **Wrong:** +``` +{{$node["http request"].json.data}} // lowercase +``` + +βœ… **Correct:** +``` +{{$node["HTTP Request"].json.data}} // exact match +``` + +**Why it fails**: Node names are case-sensitive + +--- + +## Double wrapping + +**Problem**: Literal {{}} in output + +❌ **Wrong:** +``` +{{{$json.field}}} +``` + +βœ… **Correct:** +``` +{{$json.field}} +``` + +**Why it fails**: Only one set of {{}} needed + +--- + +## Missing quotes on property access + +**Problem**: Accessing array/object incorrectly + +❌ **Wrong:** +``` +{{$json.items.0.name}} +``` + +βœ… **Correct:** +``` +{{$json.items[0].name}} +``` + +**Why it fails**: Array access requires brackets, not dots + +--- + +## Using expressions in Code node + +**Problem**: Double evaluation or errors + +❌ **Wrong (in Code node):** +```javascript +const email = '{{$json.email}}'; // Don't do this +``` + +βœ… **Correct (in Code node):** +```javascript +const email = $input.item.json.email; // Use Code node API +``` + +**Why it fails**: Code node has direct access to data, no {{}} needed +``` + +## File: EXAMPLES.md + +```markdown +# n8n Expression Examples + +## Example 1: Access webhook data + +**Workflow**: Webhook β†’ Code β†’ Slack + +**Webhook output:** +```json +{ + "body": { + "user_id": "12345", + "email": "user@example.com" + } +} +``` + +**In Slack node message field:** +``` +New user registered: {{$json.body.email}} +User ID: {{$json.body.user_id}} +``` + +--- + +## Example 2: Reference previous node + +**Workflow**: HTTP Request β†’ Set β†’ Email + +**HTTP Request output:** +```json +{ + "data": { + "items": [ + {"name": "Product 1", "price": 29.99} + ] + } +} +``` + +**In Set node, use HTTP Request data:** +``` +{{$node["HTTP Request"].json.data.items[0].name}} +{{$node["HTTP Request"].json.data.items[0].price}} +``` + +--- + +## Example 3: Format timestamp + +**Use $now for current time:** +``` +{{$now.toFormat('yyyy-MM-dd')}} // 2025-01-20 +{{$now.toFormat('HH:mm:ss')}} // 14:30:45 +{{$now.toFormat('yyyy-MM-dd HH:mm')}} // 2025-01-20 14:30 +``` + +--- + +## Example 4: Handle field with spaces + +**Data:** +```json +{ + "first name": "John", + "last name": "Doe" +} +``` + +**Expression:** +``` +Hello {{$json['first name']}} {{$json['last name']}}! +``` + +**Output:** +``` +Hello John Doe! +``` + +--- + +## Example 5: Access array elements + +**Data:** +```json +{ + "users": [ + {"email": "alice@example.com"}, + {"email": "bob@example.com"} + ] +} +``` + +**Expressions:** +``` +First user: {{$json.users[0].email}} +Second user: {{$json.users[1].email}} +Count: {{$json.users.length}} +``` +``` + +## Evaluations (3 scenarios) + +**File**: `evaluations/expression-syntax/eval-001-missing-braces.json` +```json +{ + "id": "expr-001", + "skills": ["n8n-expression-syntax"], + "query": "I'm trying to access an email field in n8n with: $json.email but it's not working. What's wrong?", + "expected_behavior": [ + "Identifies missing {{ }} brackets around expression", + "Explains that $json.email without braces is treated as literal text", + "Provides corrected expression: {{$json.email}}", + "Uses examples from SKILL.md or COMMON_MISTAKES.md" + ], + "baseline_without_skill": { + "likely_response": "May suggest general debugging, might not know n8n-specific {{ }} syntax", + "expected_quality": "Low - lacks n8n-specific knowledge" + }, + "with_skill_expected": { + "response_quality": "High - precise fix with n8n-specific guidance", + "uses_skill_content": true, + "provides_correct_syntax": true + } +} +``` + +**File**: `evaluations/expression-syntax/eval-002-space-in-field.json` +```json +{ + "id": "expr-002", + "skills": ["n8n-expression-syntax"], + "query": "My workflow has a field called 'first name' and I'm using {{$json.first name}} but getting undefined. Help!", + "expected_behavior": [ + "Identifies space in field name as the issue", + "Explains that dot notation breaks with spaces", + "Provides corrected expression using bracket notation: {{$json['first name']}}", + "References COMMON_MISTAKES.md section on spaces" + ], + "test_variations": [ + "field name with spaces", + "node name with spaces", + "nested field with spaces" + ] +} +``` + +**File**: `evaluations/expression-syntax/eval-003-node-reference.json` +```json +{ + "id": "expr-003", + "skills": ["n8n-expression-syntax"], + "query": "How do I access data from my 'HTTP Request' node in a later node?", + "expected_behavior": [ + "Provides correct $node syntax with quotes", + "Shows example: {{$node[\"HTTP Request\"].json.fieldName}}", + "Explains node name must match exactly (case-sensitive)", + "Provides multiple examples from EXAMPLES.md if relevant" + ] +} +``` + +--- + +# SKILL #2: n8n MCP Tools Expert (Week 2) + +## Priority: 1 (Highest - fixes 20% failure rate) +**Purpose**: Teach how to use n8n-mcp MCP tools effectively +**File Count**: 5 files +**Total Lines**: ~600 lines +**Complexity**: Medium + +## Directory Structure + +``` +skills/n8n-mcp-tools-expert/ +β”œβ”€β”€ SKILL.md # 350 lines - tool overview +β”œβ”€β”€ SEARCH_GUIDE.md # 150 lines - search tools +β”œβ”€β”€ VALIDATION_GUIDE.md # 100 lines - validation tools +└── WORKFLOW_GUIDE.md # 100 lines - workflow management tools +``` + +## File: SKILL.md + +```markdown +--- +name: n8n MCP Tools Expert +description: Expert guide for using n8n-mcp MCP tools effectively. Use when searching for nodes, validating configurations, accessing templates, managing workflows, or using any n8n-mcp tool. Provides tool selection guidance and parameter formats. +--- + +# n8n MCP Tools Expert + +## Tool categories + +The n8n-mcp MCP server provides 40+ tools organized into categories: + +1. **Node Discovery** β†’ [SEARCH_GUIDE.md](SEARCH_GUIDE.md) +2. **Configuration Validation** β†’ [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) +3. **Workflow Management** β†’ [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) +4. **Template Library** - templates for common patterns +5. **Documentation** - tool and node documentation + +## Quick reference + +### Most used tools (by frequency) + +| Tool | Use When | Success Rate | +|------|----------|--------------| +| `search_nodes` | Finding nodes by keyword | 99.9% | +| `get_node_essentials` | Understanding node operations | 91.7% | +| `n8n_create_workflow` | Creating new workflows | 96.8% | +| `n8n_update_partial_workflow` | Editing workflows | 99.0% | +| `n8n_validate_workflow` | Checking workflow validity | 99.7% | + +### Tool selection guide + +**Finding the right node:** +``` +1. search_nodes(query) - Start here +2. get_node_essentials(nodeType) - Get operation list +3. get_node_documentation(nodeType) - Detailed docs if needed +``` + +**Validating configuration:** +``` +1. validate_node_minimal(nodeType, {}) - Check required fields +2. validate_node_operation(nodeType, config, 'runtime') - Validate config +3. n8n_validate_workflow(workflow) - Validate complete workflow +``` + +**Managing workflows:** +``` +1. n8n_create_workflow(name, nodes, connections) - Create new +2. n8n_update_partial_workflow(id, operations) - Edit existing +3. n8n_validate_workflow(id) - Validate before deploy +``` + +## Common mistakes + +### ❌ Using get_node_info when get_node_essentials is better + +**Problem**: get_node_info returns 100KB+ of data (20% failure rate) + +**Solution**: Use get_node_essentials instead: +``` +❌ get_node_info("nodes-base.slack") // Returns massive schema +βœ… get_node_essentials("nodes-base.slack") // Returns focused data +``` + +### ❌ Wrong nodeType format + +**Problem**: Tool fails with "node not found" + +**Formats**: +- **For search tools**: `"nodes-base.slack"` (with prefix) +- **For n8n tools**: `"n8n-nodes-base.slack"` (full name) + +**Solution**: +```javascript +// Search/essentials/validation tools: +search_nodes("slack") // No prefix needed +get_node_essentials("nodes-base.slack") // Short prefix + +// List templates: +list_node_templates(["n8n-nodes-base.slack"]) // Full prefix +``` + +### ❌ Not using validation profiles + +**Problem**: Getting too many false positives or missing real errors + +**Profiles**: +- `minimal` - Only check required fields exist +- `runtime` - Check values and types (recommended) +- `ai-friendly` - Reduce false positives +- `strict` - Maximum validation + +**Solution**: +```javascript +// For configuration: +validate_node_operation(nodeType, config, 'runtime') + +// For quick check: +validate_node_minimal(nodeType, {}) +``` + +## Tool usage patterns + +See detailed guides: +- **Node Discovery**: [SEARCH_GUIDE.md](SEARCH_GUIDE.md) +- **Validation**: [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) +- **Workflow Management**: [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) + +## Self-help + +**Get tool documentation:** +``` +tools_documentation() // List all tools +tools_documentation("search_nodes", "full") // Specific tool +``` + +**Health check:** +``` +n8n_health_check() // Verify MCP server connectivity +``` +``` + +## File: SEARCH_GUIDE.md + +```markdown +# Node Discovery Tools Guide + +## Tool selection + +### search_nodes - Start here (99.9% success rate) + +**Use when**: You know what you're looking for (keyword, use case, service) + +**Example**: +```javascript +search_nodes({ + query: "slack", + mode: "OR", // Default: any word matches + limit: 20 +}) +``` + +**Returns**: List of matching nodes with types + +**Tips**: +- Use specific keywords: "slack", "http request", "database" +- Common searches: webhook, http, database, email, slack +- mode: "OR" (default) | "AND" (all words) | "FUZZY" (typo-tolerant) + +--- + +### get_node_essentials - Understand operations (91.7% success) + +**Use when**: You've found the node and need to see operations + +**Example**: +```javascript +get_node_essentials({ + nodeType: "nodes-base.slack", + includeExamples: true // Get real template configs +}) +``` + +**Returns**: +- Available operations +- Essential properties only (not full schema) +- Example configurations from templates + +**Tips**: +- Use after search_nodes to understand what a node can do +- includeExamples:true provides working configurations +- Much faster than get_node_info (4ms vs 3ms) + +--- + +### get_node_info - Full documentation (80% success) + +**Use when**: You need complete schema details + +**Warning**: +- Returns 100KB+ data +- 20% failure rate (use sparingly) +- Better alternatives exist for most cases + +**Example**: +```javascript +get_node_info({ + nodeType: "nodes-base.httpRequest" +}) +``` + +**When to use**: +- Debugging complex configuration issues +- Need full property schemas +- Exploring advanced features + +**Better alternatives**: +1. get_node_essentials - for operations list +2. get_node_documentation - for readable docs +3. search_node_properties - for specific property + +--- + +### list_nodes - Browse all nodes (99.6% success) + +**Use when**: Exploring by category or seeing all available + +**Example**: +```javascript +list_nodes({ + category: "trigger", + limit: 200 +}) +``` + +**Categories**: +- trigger - Webhook, Schedule, Manual, etc. +- transform - Code, Set, Function, etc. +- output - HTTP Request, Email, Slack, etc. + +**Tips**: +- Use limit:200 to see all nodes +- Filter by package: "n8n-nodes-base" or "@n8n/n8n-nodes-langchain" +- Filter by category for focused exploration + +--- + +## Workflow: Finding and configuring a node + +``` +Step 1: Search for node + search_nodes({query: "slack"}) + β†’ Returns: nodes-base.slack + +Step 2: Get operations + get_node_essentials({ + nodeType: "nodes-base.slack", + includeExamples: true + }) + β†’ Returns: operations list + example configs + +Step 3: Validate configuration + validate_node_operation({ + nodeType: "nodes-base.slack", + config: {resource: "channel", operation: "create"}, + profile: "runtime" + }) + β†’ Returns: validation result + +Step 4: Use in workflow + (Configuration is validated and ready) +``` + +## Common patterns from telemetry + +**Pattern**: search β†’ essentials (9,835 occurrences, 18s avg) +```javascript +// Step 1 +search_nodes({query: "webhook"}) + +// Step 2 (after ~18 seconds of reviewing results) +get_node_essentials({nodeType: "nodes-base.webhook"}) +``` + +This is the MOST COMMON discovery pattern. Follow it! +``` + +## File: VALIDATION_GUIDE.md + +```markdown +# Configuration Validation Tools Guide + +## Validation philosophy + +**Validate early, validate often** - 15,107 validation loops observed in telemetry + +## Tool selection + +### validate_node_minimal - Quick check (97.4% success) + +**Use when**: Checking what fields are required + +**Example**: +```javascript +validate_node_minimal({ + nodeType: "nodes-base.slack", + config: {} // Empty to see all required fields +}) +``` + +**Returns**: +- List of required fields +- No validation of values + +**When to use**: Planning configuration, seeing requirements + +--- + +### validate_node_operation - Full validation (varies) + +**Use when**: Validating actual configuration + +**Example**: +```javascript +validate_node_operation({ + nodeType: "nodes-base.slack", + config: { + resource: "channel", + operation: "create", + channel: "general" + }, + profile: "runtime" // Recommended +}) +``` + +**Profiles**: +- `minimal` - Required fields only +- `runtime` - Values + types (recommended) +- `ai-friendly` - Fewer false positives +- `strict` - Maximum validation + +**Returns**: +- errors: Critical issues (must fix) +- warnings: Suggestions (optional) +- suggestions: Improvements + +**Validation loop pattern** (from telemetry): +``` +1. Configure node +2. validate_node_operation (23s thinking) +3. Fix errors +4. validate_node_operation again (58s fixing) +5. Repeat until valid +``` + +--- + +### validate_workflow - Structure validation (95.5% success) + +**Use when**: Checking workflow before execution + +**Example**: +```javascript +validate_workflow({ + workflow: { + nodes: [...], + connections: {...} + }, + options: { + validateNodes: true, + validateConnections: true, + validateExpressions: true, + profile: "runtime" + } +}) +``` + +**Checks**: +- Node configurations +- Connection validity +- Expression syntax +- Workflow structure + +--- + +### n8n_validate_workflow - Complete validation (99.7% success) + +**Use when**: Final validation before deployment + +**Example**: +```javascript +n8n_validate_workflow({ + id: "workflow-id", + options: { + profile: "runtime" + } +}) +``` + +**Returns**: Comprehensive validation report + +**When to use**: After building complete workflow, before executing + +--- + +## Validation workflow (from telemetry) + +**Most common pattern** (7,841 occurrences): +``` +n8n_update_partial_workflow (make changes) + ↓ ~23 seconds +n8n_validate_workflow (check) + ↓ ~58 seconds +n8n_update_partial_workflow (fix errors) + ↓ +(repeat until valid) +``` + +**Best practice**: +1. Make changes +2. **Validate immediately** +3. Fix errors +4. **Validate again** +5. Only proceed when validation passes + +## Handling validation errors + +**Error types**: +1. **Required field missing** β†’ Add the field +2. **Invalid value** β†’ Check allowed values in essentials +3. **Type mismatch** β†’ Convert to correct type +4. **False positive** β†’ Check n8n Validation Expert skill + +**When you get errors**: +1. Read error message carefully +2. Check if it's a known false positive +3. Fix real errors +4. Validate again +5. Iterate until clean +``` + +## File: WORKFLOW_GUIDE.md + +```markdown +# Workflow Management Tools Guide + +## Creation vs Editing + +### n8n_create_workflow - New workflows (96.8% success) + +**Use when**: Starting from scratch + +**Example**: +```javascript +n8n_create_workflow({ + name: "Webhook to Slack", + nodes: [ + { + id: "webhook-1", + name: "Webhook", + type: "n8n-nodes-base.webhook", + typeVersion: 1, + position: [250, 300], + parameters: {path: "test-webhook"} + }, + { + id: "slack-1", + name: "Slack", + type: "n8n-nodes-base.slack", + typeVersion: 1, + position: [450, 300], + parameters: { + resource: "message", + operation: "post", + channel: "#general", + text: "={{$json.body.message}}" + } + } + ], + connections: { + "Webhook": { + "main": [[{"node": "Slack", "type": "main", "index": 0}]] + } + } +}) +``` + +**Returns**: Created workflow with ID + +**Tips**: +- Always include: id, name, type, typeVersion, position, parameters +- Start workflows inactive (settings.active: false) +- Validate after creation + +--- + +### n8n_update_partial_workflow - Edit existing (99.0% success) + +**Use when**: Modifying workflows (MOST COMMON - 38,287 uses) + +**Example**: +```javascript +n8n_update_partial_workflow({ + id: "workflow-id", + operations: [ + { + type: "addNode", + node: { + id: "code-1", + name: "Code", + type: "n8n-nodes-base.code", + typeVersion: 1, + position: [350, 300], + parameters: {mode: "runOnceForAllItems", code: "..."} + } + }, + { + type: "addConnection", + connection: { + sourceNode: "Webhook", + sourceOutput: "main", + sourceOutputIndex: 0, + targetNode: "Code", + targetInput: "main", + targetInputIndex: 0 + } + } + ] +}) +``` + +**Operation types**: +- addNode, removeNode, updateNode +- addConnection, removeConnection +- updateSettings, updateName +- enableNode, disableNode + +**Pattern from telemetry** (31,464 occurrences): +``` +update_partial β†’ update_partial β†’ update_partial... +Avg 56 seconds between edits (thinking time) +``` + +This shows workflow building is ITERATIVE, not one-shot! + +--- + +## Workflow retrieval + +### n8n_get_workflow - Full workflow (99.9% success) + +**Use when**: Reviewing complete workflow + +**Example**: +```javascript +n8n_get_workflow({id: "workflow-id"}) +``` + +**Returns**: Complete workflow JSON + +--- + +### n8n_get_workflow_structure - Just structure (99.9% success) + +**Use when**: Checking nodes and connections only + +**Example**: +```javascript +n8n_get_workflow_structure({id: "workflow-id"}) +``` + +**Returns**: Nodes + connections (no parameter details) + +--- + +### n8n_list_workflows - Browse workflows (100% success) + +**Use when**: Finding existing workflows + +**Example**: +```javascript +n8n_list_workflows({ + active: true, + limit: 100 +}) +``` + +--- + +## Workflow lifecycle + +``` +1. CREATE + n8n_create_workflow() β†’ Returns workflow ID + +2. VALIDATE + n8n_validate_workflow(id) β†’ Check for errors + +3. EDIT (if needed) + n8n_update_partial_workflow(id, operations) + +4. VALIDATE AGAIN + n8n_validate_workflow(id) + +5. ACTIVATE (when ready) + n8n_update_partial_workflow(id, [{ + type: "updateSettings", + settings: {active: true} + }]) + +6. MONITOR + n8n_list_executions({workflowId: id}) + n8n_get_execution({id: execution_id}) +``` + +## Common patterns from telemetry + +**Pattern 1**: Edit β†’ Validate (7,841 occurrences) +``` +n8n_update_partial_workflow + ↓ 23s +n8n_validate_workflow +``` + +**Pattern 2**: Validate β†’ Fix (7,266 occurrences) +``` +n8n_validate_workflow + ↓ 58s +n8n_update_partial_workflow (fix errors) +``` + +**Pattern 3**: Create β†’ Edit (3,906 occurrences) +``` +n8n_create_workflow + ↓ 113s +n8n_update_partial_workflow (refinements) +``` + +Follow these natural patterns! +``` + +## Evaluations (3+ scenarios) + +**File**: `evaluations/mcp-tools/eval-001-tool-selection.json` +```json +{ + "id": "mcp-001", + "skills": ["n8n-mcp-tools-expert"], + "query": "I need to find a node that can send messages to Slack. Which MCP tool should I use and how?", + "expected_behavior": [ + "Recommends search_nodes as the starting tool", + "Provides correct syntax: search_nodes({query: 'slack'})", + "Suggests following up with get_node_essentials", + "References SEARCH_GUIDE.md for tool selection" + ] +} +``` + +**File**: `evaluations/mcp-tools/eval-002-validation-workflow.json` +```json +{ + "id": "mcp-002", + "skills": ["n8n-mcp-tools-expert"], + "query": "I've created a workflow and want to make sure it's valid before deploying. Walk me through the validation process.", + "expected_behavior": [ + "Recommends n8n_validate_workflow tool", + "Explains validation profiles (runtime recommended)", + "Shows complete validation workflow from VALIDATION_GUIDE.md", + "Mentions validation loop pattern: validate β†’ fix β†’ validate again" + ] +} +``` + +**File**: `evaluations/mcp-tools/eval-003-node-type-format.json` +```json +{ + "id": "mcp-003", + "skills": ["n8n-mcp-tools-expert"], + "query": "I'm getting 'node not found' errors when calling get_node_essentials. I'm using 'slack' as the nodeType. What's wrong?", + "expected_behavior": [ + "Identifies incorrect nodeType format", + "Explains need for 'nodes-base.' prefix", + "Provides correct format: 'nodes-base.slack'", + "References nodeType format section from SKILL.md" + ] +} +``` + +--- + +# SKILL #3: n8n Workflow Patterns (Week 2-3) + +## Priority: 2 (High - addresses 813 webhook searches) +**Purpose**: Teach proven workflow architectural patterns +**File Count**: 7 files +**Total Lines**: ~800 lines +**Complexity**: Medium-High + +## Directory Structure + +``` +skills/n8n-workflow-patterns/ +β”œβ”€β”€ SKILL.md # 400 lines - overview + checklist +β”œβ”€β”€ patterns/ +β”‚ β”œβ”€β”€ webhook_processing.md # 100 lines +β”‚ β”œβ”€β”€ http_api_integration.md # 100 lines +β”‚ β”œβ”€β”€ database_operations.md # 80 lines +β”‚ β”œβ”€β”€ ai_agent_workflow.md # 80 lines +β”‚ └── scheduled_tasks.md # 80 lines +└── scripts/ + └── validate_structure.py # 100 lines (optional) +``` + +## File: SKILL.md + +```markdown +--- +name: n8n Workflow Patterns +description: Build n8n workflows using proven architectural patterns. Use when creating workflows, connecting nodes, designing automation, or when user describes a workflow goal like webhooks, APIs, databases, or scheduled tasks. +--- + +# n8n Workflow Patterns + +## Workflow creation checklist + +Copy this and track your progress: + +``` +Workflow Progress: +- [ ] Step 1: Identify pattern type +- [ ] Step 2: Search for required nodes +- [ ] Step 3: Configure node operations +- [ ] Step 4: Connect nodes properly +- [ ] Step 5: Add expressions for data mapping +- [ ] Step 6: Validate workflow structure +- [ ] Step 7: Test with sample data +``` + +## Pattern library + +Based on 31,917 real workflows, these are the most common patterns: + +### 1. Webhook Processing (27.6% of workflows) + +**Use when**: Receiving external events and taking action + +**Pattern**: Trigger β†’ Process β†’ Act + +**See**: [patterns/webhook_processing.md](patterns/webhook_processing.md) + +**Example use cases**: +- Form submissions β†’ Database +- Payment notifications β†’ Send receipt +- GitHub webhooks β†’ Slack notifications + +--- + +### 2. HTTP API Integration (755 searches) + +**Use when**: Fetching or sending data to APIs + +**Pattern**: Trigger β†’ Fetch/Send β†’ Transform β†’ Store/Notify + +**See**: [patterns/http_api_integration.md](patterns/http_api_integration.md) + +**Example use cases**: +- Fetch weather data β†’ Store in database +- Send customer data β†’ CRM system +- API polling β†’ Process updates + +--- + +### 3. Database Operations (745 searches) + +**Use when**: Reading or writing to databases + +**Pattern**: Trigger β†’ Query/Insert β†’ Process β†’ Respond + +**See**: [patterns/database_operations.md](patterns/database_operations.md) + +**Example use cases**: +- Schedule β†’ Query database β†’ Email report +- Webhook β†’ Insert record β†’ Confirm +- API β†’ Update database β†’ Notify + +--- + +### 4. AI Agent Workflows (67 searches, growing) + +**Use when**: Using AI to process or generate content + +**Pattern**: Trigger β†’ Prepare β†’ AI Process β†’ Act on result + +**See**: [patterns/ai_agent_workflow.md](patterns/ai_agent_workflow.md) + +**Example use cases**: +- Email β†’ AI categorize β†’ Route to team +- Customer message β†’ AI respond β†’ Send +- Document β†’ AI extract β†’ Store data + +--- + +### 5. Scheduled Tasks (67 searches) + +**Use when**: Running workflows on a schedule + +**Pattern**: Schedule β†’ Fetch β†’ Process β†’ Store/Notify + +**See**: [patterns/scheduled_tasks.md](patterns/scheduled_tasks.md) + +**Example use cases**: +- Daily reports +- Hourly data syncs +- Weekly cleanup tasks + +--- + +## Node connection best practices + +### Connection types + +**main** - Default data flow (most common) +```javascript +connections: { + "Webhook": { + "main": [[{ + "node": "Slack", + "type": "main", + "index": 0 + }]] + } +} +``` + +**error** - Error handling flow +```javascript +"HTTP Request": { + "error": [[{ + "node": "Error Handler", + "type": "main", + "index": 0 + }]] +} +``` + +### Connection structure + +**Single connection**: +```javascript +"Node1": { + "main": [[{"node": "Node2", "type": "main", "index": 0}]] +} +``` + +**Multiple connections (branching)**: +```javascript +"IF": { + "main": [ + [{"node": "True Branch", "type": "main", "index": 0}], // Output 0 + [{"node": "False Branch", "type": "main", "index": 0}] // Output 1 + ] +} +``` + +### Common mistakes + +❌ **Forgetting to connect nodes** +```javascript +// No connections object = nodes won't execute +``` + +❌ **Wrong node names** +```javascript +connections: { + "webhook": {...} // Lowercase - won't match "Webhook" node +} +``` + +βœ… **Correct**: +```javascript +connections: { + "Webhook": { // Exact match with node name + "main": [[{"node": "Slack", "type": "main", "index": 0}]] + } +} +``` + +## Data flow principles + +### 1. Trigger starts the flow + +Every workflow needs exactly one active trigger node: +- Webhook +- Schedule +- Manual +- Chat Trigger +- etc. + +### 2. Data flows through connections + +Each node receives: +- `$json` - Output from connected node +- `$node["Name"]` - Output from any previous node + +### 3. Transform data between nodes + +Use Code, Set, or Function nodes to: +- Reshape data +- Calculate values +- Filter/map arrays + +### 4. End with action or response + +Common ending nodes: +- HTTP Request (send to API) +- Email/Slack (notify) +- Database (store) +- Respond to Webhook (return data) + +## Pattern selection guide + +Ask yourself: + +1. **How is the workflow triggered?** + - Webhook β†’ Webhook Processing + - Time β†’ Scheduled Tasks + - Manual β†’ Any pattern + +2. **What's the main operation?** + - API call β†’ HTTP API Integration + - Database β†’ Database Operations + - AI processing β†’ AI Agent Workflow + +3. **How complex is the logic?** + - Simple (3-6 nodes) β†’ Use basic pattern + - Medium (7-15 nodes) β†’ Combine patterns + - Complex (15+ nodes) β†’ Break into sub-workflows + +## Workflow building process + +**Step 1: Choose pattern** + +Use pattern guides to understand structure + +**Step 2: Search for nodes** + +Use n8n MCP Tools Expert skill to find nodes: +```javascript +search_nodes({query: "webhook"}) +search_nodes({query: "slack"}) +``` + +**Step 3: Configure nodes** + +Use n8n Node Configuration skill for operation-aware setup + +**Step 4: Connect nodes** + +Follow connection patterns from pattern guides + +**Step 5: Add data mapping** + +Use n8n Expression Syntax skill for {{}} expressions + +**Step 6: Validate** + +Use n8n Validation Expert skill to check workflow + +**Step 7: Test** + +Create workflow and test with sample data + +## Next steps + +Choose a pattern that matches your use case and follow the detailed guide! +``` + +## File: patterns/webhook_processing.md + +```markdown +# Webhook Processing Pattern + +## Overview + +**Frequency**: 813 searches (most popular!) +**Workflows**: ~8,805 (27.6% of all workflows) +**Complexity**: Simple (5-6 nodes average) + +## Pattern structure + +``` +Webhook Trigger + ↓ +[Optional: Transform data] + ↓ +Action (API, Database, Notification) + ↓ +[Optional: Respond to webhook] +``` + +## Complete example: Form submission to Slack + +### Node 1: Webhook Trigger + +```javascript +{ + "id": "webhook-1", + "name": "Webhook", + "type": "n8n-nodes-base.webhook", + "typeVersion": 1, + "position": [250, 300], + "parameters": { + "path": "form-submit", + "httpMethod": "POST", + "responseMode": "onReceived" + } +} +``` + +**Webhook receives**: +```json +{ + "body": { + "name": "John Doe", + "email": "john@example.com", + "message": "Hello!" + } +} +``` + +### Node 2: Slack Notification + +```javascript +{ + "id": "slack-1", + "name": "Slack", + "type": "n8n-nodes-base.slack", + "typeVersion": 1, + "position": [450, 300], + "parameters": { + "resource": "message", + "operation": "post", + "channel": "#forms", + "text": "New form submission!\n\nName: {{$json.body.name}}\nEmail: {{$json.body.email}}\nMessage: {{$json.body.message}}" + } +} +``` + +### Connections + +```javascript +{ + "Webhook": { + "main": [[{ + "node": "Slack", + "type": "main", + "index": 0 + }]] + } +} +``` + +## Variations + +### With data transformation + +Add Code node between Webhook and Action: + +```javascript +{ + "id": "code-1", + "name": "Transform", + "type": "n8n-nodes-base.code", + "typeVersion": 1, + "position": [350, 300], + "parameters": { + "mode": "runOnceForAllItems", + "jsCode": "return items.map(item => ({\n json: {\n formData: item.json.body,\n timestamp: new Date().toISOString(),\n source: 'website'\n }\n}));" + } +} +``` + +### With webhook response + +Change webhook to respond after processing: + +```javascript +// Webhook node +"parameters": { + "path": "form-submit", + "responseMode": "lastNode" // Respond with last node output +} + +// Add Respond to Webhook node at end +{ + "id": "respond-1", + "name": "Respond", + "type": "n8n-nodes-base.respondToWebhook", + "position": [650, 300], + "parameters": { + "responseBody": "={{JSON.stringify({success: true, message: 'Form received'})}}", + "options": { + "responseCode": 200 + } + } +} +``` + +## Common webhook use cases + +1. **Form submissions** β†’ Store in database + Notify +2. **Payment notifications** (Stripe, PayPal) β†’ Update order + Send receipt +3. **GitHub events** β†’ Slack notifications +4. **Zapier/Make alternatives** β†’ Process external triggers +5. **Chat platforms** (Telegram, WhatsApp) β†’ AI agent responses + +## Testing webhooks + +1. Create workflow with webhook node +2. Note the webhook URL from node +3. Use Postman/curl to send test data: + +```bash +curl -X POST https://n8n.example.com/webhook/form-submit \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Test User", + "email": "test@example.com", + "message": "Test message" + }' +``` + +4. Check workflow execution in n8n + +## Best practices + +βœ… **Validate webhook data** - Check required fields exist +βœ… **Handle errors** - Add error handling for failed actions +βœ… **Respond quickly** - If response needed, process async if possible +βœ… **Log events** - Store webhook data for debugging +βœ… **Secure webhooks** - Use authentication when possible + +## Checklist for webhook workflows + +``` +- [ ] Webhook path is unique and descriptive +- [ ] HTTP method matches sender (usually POST) +- [ ] Response mode set correctly (onReceived vs lastNode) +- [ ] Data validation included (check required fields) +- [ ] Error handling configured +- [ ] Tested with sample payload +- [ ] Webhook URL documented for sender +``` +``` + +## File: patterns/http_api_integration.md + +```markdown +# HTTP API Integration Pattern + +## Overview + +**Frequency**: 755 searches +**Complexity**: Simple to Medium (5-10 nodes) + +## Pattern structure + +``` +Trigger (Webhook, Schedule, Manual) + ↓ +HTTP Request (Fetch data) + ↓ +[Optional: Transform/Filter] + ↓ +Action (Store, Process, Notify) +``` + +## Complete example: Fetch weather and send email + +### Node 1: Schedule Trigger + +```javascript +{ + "id": "schedule-1", + "name": "Schedule", + "type": "n8n-nodes-base.scheduleTrigger", + "typeVersion": 1, + "position": [250, 300], + "parameters": { + "rule": { + "interval": [{ + "field": "cronExpression", + "expression": "0 8 * * *" // Daily at 8 AM + }] + } + } +} +``` + +### Node 2: HTTP Request (Fetch Weather) + +```javascript +{ + "id": "http-1", + "name": "Get Weather", + "type": "n8n-nodes-base.httpRequest", + "typeVersion": 4.1, + "position": [450, 300], + "parameters": { + "method": "GET", + "url": "https://api.openweathermap.org/data/2.5/weather", + "authentication": "predefinedCredentialType", + "nodeCredentialType": "openWeatherMapApi", + "sendQuery": true, + "queryParameters": { + "parameters": [ + {"name": "q", "value": "London"}, + {"name": "units", "value": "metric"} + ] + } + } +} +``` + +**HTTP Request returns**: +```json +{ + "main": { + "temp": 15.5, + "feels_like": 14.2 + }, + "weather": [{ + "description": "partly cloudy" + }] +} +``` + +### Node 3: Email Notification + +```javascript +{ + "id": "email-1", + "name": "Send Email", + "type": "n8n-nodes-base.emailSend", + "typeVersion": 2, + "position": [650, 300], + "parameters": { + "fromEmail": "weather@example.com", + "toEmail": "user@example.com", + "subject": "Daily Weather Report", + "text": "Today's weather in London:\n\nTemperature: {{$json.main.temp}}Β°C\nFeels like: {{$json.main.feels_like}}Β°C\nConditions: {{$json.weather[0].description}}" + } +} +``` + +## Best practices + +βœ… **Handle rate limits** - Add delays between requests +βœ… **Parse responses** - Use Code node if needed +βœ… **Error handling** - Check for API errors +βœ… **Secure credentials** - Use n8n credential system +βœ… **Timeout settings** - Set appropriate timeouts + +## Checklist for API workflows + +``` +- [ ] API endpoint URL correct +- [ ] HTTP method correct (GET/POST/PUT/DELETE) +- [ ] Authentication configured +- [ ] Required headers included +- [ ] Query/body parameters set correctly +- [ ] Response parsing configured +- [ ] Error handling added +- [ ] Tested with actual API +``` +``` + +## Evaluations (3+ scenarios) + +**File**: `evaluations/workflow-patterns/eval-001-webhook-pattern.json` +```json +{ + "id": "pattern-001", + "skills": ["n8n-workflow-patterns", "n8n-mcp-tools-expert"], + "query": "I want to build a workflow that posts to Slack whenever someone submits a form on my website. How should I structure this?", + "expected_behavior": [ + "Identifies webhook processing pattern as correct choice", + "References patterns/webhook_processing.md", + "Provides workflow creation checklist", + "Suggests: Webhook β†’ Slack structure", + "Mentions using search_nodes to find webhook and slack nodes", + "Recommends validation after building" + ] +} +``` + +--- + +# SKILL #4: n8n Validation Expert (Week 3) + +[Similar detailed structure with SKILL.md, ERROR_CATALOG.md, FALSE_POSITIVES.md, evaluation scenarios] + +**Note**: Full implementation follows same pattern as above skills with: +- SKILL.md (validation loop workflow) +- ERROR_CATALOG.md (known errors from telemetry) +- FALSE_POSITIVES.md (Issues #304, #306, #338) +- 3+ evaluations + +--- + +# SKILL #5: n8n Node Configuration (Week 3) + +[Similar detailed structure with SKILL.md, DEPENDENCIES.md, evaluations] + +**Note**: Full implementation follows same pattern with: +- SKILL.md (operation-aware configuration process) +- DEPENDENCIES.md (property dependency rules) +- OPERATION_PATTERNS.md (common configurations) +- 3+ evaluations + +--- + +# Testing Strategy + +## Evaluation-Driven Development Process + +For EACH skill: + +1. **Create 3+ evaluations FIRST** +2. **Establish baseline** (test without skill) +3. **Write minimal SKILL.md** (under 500 lines) +4. **Test against evaluations** +5. **Iterate until 100% pass** +6. **Add reference files as needed** + +## Cross-Skill Integration Testing + +Test skills working together: + +```json +{ + "id": "integration-001", + "skills": [ + "n8n-mcp-tools-expert", + "n8n-workflow-patterns", + "n8n-node-configuration", + "n8n-expression-syntax", + "n8n-validation-expert" + ], + "query": "Build a complete webhook to Slack workflow, validate it, and explain what you did.", + "expected_behavior": [ + "Uses n8n-workflow-patterns to identify webhook pattern", + "Uses n8n-mcp-tools-expert to search for nodes", + "Uses n8n-node-configuration for Slack setup", + "Uses n8n-expression-syntax for data mapping", + "Uses n8n-validation-expert to validate result", + "All 5 skills compose automatically", + "Produces working, validated workflow" + ] +} +``` + +--- + +# Distribution Strategy + +## Claude Code Plugin Structure + +``` +n8n-mcp-skills-plugin/ +β”œβ”€β”€ plugin.json +β”œβ”€β”€ skills/ +β”‚ └── [all 5 skills] +└── README.md +``` + +**plugin.json**: +```json +{ + "name": "n8n-mcp-skills", + "version": "1.0.0", + "description": "Expert skills for building n8n workflows with n8n-mcp", + "skills": [ + "skills/n8n-expression-syntax", + "skills/n8n-mcp-tools-expert", + "skills/n8n-workflow-patterns", + "skills/n8n-validation-expert", + "skills/n8n-node-configuration" + ], + "requires": { + "mcp_servers": ["n8n-mcp"] + } +} +``` + +## GitHub Repository + +``` +n8n-mcp-skills/ +β”œβ”€β”€ README.md +β”œβ”€β”€ LICENSE (MIT) +β”œβ”€β”€ skills/ [all skills] +β”œβ”€β”€ evaluations/ [all evaluations] +β”œβ”€β”€ docs/ +β”‚ β”œβ”€β”€ INSTALLATION.md +β”‚ β”œβ”€β”€ USAGE.md +β”‚ └── DEVELOPMENT.md +└── .github/ + └── workflows/ + └── test-skills.yml +``` + +--- + +# README.md (for repository) + +```markdown +# n8n-mcp Claude Skills + +Expert Claude Skills for building n8n workflows using the n8n-mcp MCP server. + +## What are these skills? + +5 complementary skills that teach Claude how to: +- βœ… Write correct n8n expressions +- βœ… Use n8n-mcp MCP tools effectively +- βœ… Build workflows using proven patterns +- βœ… Interpret and fix validation errors +- βœ… Configure nodes with operation-aware guidance + +## Skills included + +1. **n8n Expression Syntax** - Correct {{}} syntax and common patterns +2. **n8n MCP Tools Expert** - How to use n8n-mcp tools (fixes 20% failure rate) +3. **n8n Workflow Patterns** - 5 proven patterns from 31,917 real workflows +4. **n8n Validation Expert** - Error interpretation and validation loops +5. **n8n Node Configuration** - Operation-aware configuration guidance + +## Installation + +### Claude Code + +1. Download this repository +2. Copy `skills/` directory to your Claude Code skills folder +3. Reload Claude Code + +### Claude.ai + +1. Download and zip each skill folder individually +2. Upload via Settings > Capabilities > Skills + +### API + +See [docs/INSTALLATION.md](docs/INSTALLATION.md) + +## Usage + +Once installed, skills activate automatically when relevant: + +- "How do I write n8n expressions?" β†’ Expression Syntax skill +- "Find me a Slack node" β†’ MCP Tools Expert skill +- "Build a webhook workflow" β†’ Workflow Patterns skill +- "Why is validation failing?" β†’ Validation Expert skill + +## Requirements + +- n8n-mcp MCP server installed and configured +- Claude Code, Claude.ai, or Claude API access + +## Data-driven design + +These skills are based on analysis of: +- 447,557 real MCP tool usage events +- 31,917 workflows created +- 19,113 validation errors +- 15,107 validation feedback loops + +## License + +MIT License - see LICENSE file + +## Credits + +Conceived by Romuald CzΕ‚onkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en) + +Part of the n8n-mcp project. +``` + +--- + +# COMPLETE IMPLEMENTATION CHECKLIST + +## Week 1: Expression Syntax (PoC) +- [ ] Create `skills/n8n-expression-syntax/` directory +- [ ] Write SKILL.md (200 lines) +- [ ] Write COMMON_MISTAKES.md (100 lines) +- [ ] Write EXAMPLES.md (50 lines) +- [ ] Create 3 evaluations +- [ ] Test evaluations without skill (baseline) +- [ ] Test evaluations with skill +- [ ] Iterate until 100% pass +- [ ] Document findings + +## Week 2: MCP Tools + Workflow Patterns +- [ ] Create `skills/n8n-mcp-tools-expert/` directory +- [ ] Write SKILL.md (350 lines) +- [ ] Write SEARCH_GUIDE.md (150 lines) +- [ ] Write VALIDATION_GUIDE.md (100 lines) +- [ ] Write WORKFLOW_GUIDE.md (100 lines) +- [ ] Create 3+ evaluations +- [ ] Test and iterate + +- [ ] Create `skills/n8n-workflow-patterns/` directory +- [ ] Write SKILL.md with checklist (400 lines) +- [ ] Write webhook_processing.md +- [ ] Write http_api_integration.md +- [ ] Write database_operations.md +- [ ] Write ai_agent_workflow.md +- [ ] Write scheduled_tasks.md +- [ ] Create 3+ evaluations +- [ ] Test composition with MCP Tools skill + +## Week 3: Validation + Configuration +- [ ] Create `skills/n8n-validation-expert/` +- [ ] Write SKILL.md with validation loop +- [ ] Write ERROR_CATALOG.md (known errors) +- [ ] Write FALSE_POSITIVES.md (Issues #304, #338) +- [ ] Create 3+ evaluations +- [ ] Test with all previous skills + +- [ ] Create `skills/n8n-node-configuration/` +- [ ] Write SKILL.md +- [ ] Write DEPENDENCIES.md +- [ ] Write OPERATION_PATTERNS.md +- [ ] Create 3+ evaluations + +## Week 4: Integration & Testing +- [ ] Create cross-skill integration tests +- [ ] Test all 5 skills working together +- [ ] Test with Haiku, Sonnet, Opus +- [ ] Gather feedback +- [ ] Iterate based on real usage +- [ ] Performance optimization + +## Week 5-6: Distribution +- [ ] Create plugin.json +- [ ] Package as Claude Code plugin +- [ ] Create GitHub repository +- [ ] Write comprehensive README +- [ ] Write INSTALLATION.md +- [ ] Write USAGE.md +- [ ] Write DEVELOPMENT.md +- [ ] Create demo video +- [ ] Announce to community + +--- + +**This implementation guide is complete and ready to feed into Claude Code for autonomous execution.** + +Conceived by Romuald CzΕ‚onkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en) diff --git a/docs/USAGE.md b/docs/USAGE.md new file mode 100644 index 0000000..ef10b4d --- /dev/null +++ b/docs/USAGE.md @@ -0,0 +1,502 @@ +# Usage Guide + +Learn how to use n8n-skills effectively with Claude. + +--- + +## How Skills Activate + +Skills activate **automatically** based on your query content. You don't need to manually invoke them. + +### Activation Triggers + +Each skill has specific triggers defined in its frontmatter: + +```markdown +--- +name: n8n Expression Syntax +description: Validate n8n expression syntax and fix common errors. Use when writing n8n expressions, using {{}} syntax, accessing $json/$node variables, or troubleshooting expression errors in workflows. +--- +``` + +When your query matches the description keywords, the skill activates. + +--- + +## Individual Skill Usage + +### 1. n8n Expression Syntax + +**Activates on**: expression, {{}} syntax, $json, $node, webhook data access + +**Example Queries**: +``` +"How do I write n8n expressions?" +"Why is {{$json.email}} showing undefined?" +"Access webhook data in Slack node" +"What's wrong with my $node reference?" +``` + +**What You'll Learn**: +- Correct {{}} syntax +- Webhook data structure ($json.body.*) +- Node references ($node["Node Name"].json) +- Common mistakes and fixes +- When NOT to use expressions (Code nodes) + +**Example Response**: +``` +[Skill activates] + +n8n expressions must be wrapped in double curly braces: + +βœ… Correct: {{$json.body.email}} +❌ Wrong: $json.body.email + +For webhook data, remember it's under .body: +{{$json.body.name}} // Webhook form data +{{$json.body.message}} // Webhook message + +In Code nodes, use direct access (no {{}}): +const email = $json.body.email; // Correct in Code node +``` + +--- + +### 2. n8n MCP Tools Expert + +**Activates on**: search nodes, validate, find node, MCP tools, template, workflow + +**Example Queries**: +``` +"Find me a Slack node" +"How do I search for database nodes?" +"Validate this node configuration" +"What's the difference between get_node_info and get_node_essentials?" +"Which MCP tool should I use to create workflows?" +``` + +**What You'll Learn**: +- Tool selection (which tool for which task) +- nodeType format differences +- Validation profiles (minimal/runtime/ai-friendly/strict) +- Common MCP tool mistakes +- Workflow management tools + +**Example Response**: +``` +[Skill activates] + +To find the Slack node, use search_nodes: + +search_nodes({query: "slack"}) + +This returns: +- nodeType: "nodes-base.slack" (for search/validate tools) +- workflowNodeType: "n8n-nodes-base.slack" (for workflows) + +⚠️ Important: Use different formats for different tools! + +Next, get node details: +get_node_essentials({nodeType: "nodes-base.slack"}) + +This returns focused 5KB data vs 100KB+ from get_node_info. +``` + +--- + +### 3. n8n Workflow Patterns + +**Activates on**: build workflow, webhook, pattern, architecture, workflow structure + +**Example Queries**: +``` +"Build a webhook to Slack workflow" +"What's the best pattern for API integration?" +"Create a scheduled database workflow" +"Show me webhook processing pattern" +``` + +**What You'll Learn**: +- 5 proven patterns (webhook, HTTP API, database, AI, scheduled) +- Workflow creation checklist +- Node connection best practices +- Real template examples +- Pattern selection guide + +**Example Response**: +``` +[Skill activates] + +For webhook to Slack, use the Webhook Processing pattern: + +Pattern Structure: +Webhook Trigger β†’ [Transform] β†’ Slack Notification + +Workflow Checklist: +β–‘ Search for nodes (search_nodes) +β–‘ Get node configurations (get_node_essentials) +β–‘ Create workflow structure +β–‘ Add data mappings (expressions) +β–‘ Validate workflow +β–‘ Test with sample data + +Real Example from Template #2947: +Webhook β†’ OpenStreetMap β†’ NWS β†’ Slack +(1,500 views, proven pattern) +``` + +--- + +### 4. n8n Validation Expert + +**Activates on**: validation, error, fix, debug, validate workflow + +**Example Queries**: +``` +"Why is my workflow validation failing?" +"Fix this validation error" +"Explain this validation warning" +"What does auto-sanitization do?" +``` + +**What You'll Learn**: +- Validation loop workflow +- Error interpretation +- Auto-sanitization system +- False positives handling +- Profile selection + +**Example Response**: +``` +[Skill activates] + +Validation Error: "Required field 'channel' missing" + +Fix: +validate_node_operation({ + nodeType: "nodes-base.slack", + config: { + resource: "message", + operation: "post", + channel: "#general", // Add this! + text: "Message" + }, + profile: "runtime" +}) + +Auto-sanitization will fix: +βœ… Binary operator structures (equals, contains) +βœ… Unary operator structures (isEmpty, isNotEmpty) +βœ… Missing metadata in IF/Switch nodes + +But cannot fix: +❌ Broken connections +❌ Branch count mismatches +``` + +--- + +### 5. n8n Node Configuration + +**Activates on**: configure node, property, operation, dependencies, AI workflow + +**Example Queries**: +``` +"How do I configure the HTTP Request node?" +"What properties does the Slack node need?" +"Explain property dependencies" +"Set up AI Agent workflow" +``` + +**What You'll Learn**: +- Operation-specific requirements +- Property dependencies (sendBody β†’ contentType) +- AI connection types (8 types) +- Common configuration patterns + +**Example Response**: +``` +[Skill activates] + +HTTP Request node property dependencies: + +1. Set sendBody = true + ↓ Reveals: contentType + +2. Set contentType = "json" + ↓ Reveals: specifyBody + +3. Set specifyBody = "json" + ↓ Reveals: jsonBody + +This cascade of 32 dependencies ensures you see only relevant properties! + +For AI workflows, 8 connection types: +- ai_languageModel (OpenAI, Anthropic) +- ai_tool (HTTP Request Tool, Code Tool) +- ai_memory (Window Buffer Memory) +- ai_outputParser, ai_embedding, ai_vectorStore... +``` + +--- + +## Cross-Skill Composition + +Skills work **together automatically**. Here's how: + +### Example: Complete Workflow Build + +**Your Query**: +``` +"Build and validate a webhook to Slack workflow with proper data mapping" +``` + +**What Happens** (all automatic): + +**Step 1**: n8n Workflow Patterns activates +``` +β†’ Identifies: Webhook Processing Pattern +β†’ Provides: Workflow structure +``` + +**Step 2**: n8n MCP Tools Expert activates +``` +β†’ Searches: search_nodes({query: "webhook"}) +β†’ Searches: search_nodes({query: "slack"}) +β†’ Gets details: get_node_essentials for both +``` + +**Step 3**: n8n Node Configuration activates +``` +β†’ Guides: Webhook node setup (path, httpMethod) +β†’ Guides: Slack node setup (resource, operation, channel) +``` + +**Step 4**: n8n Expression Syntax activates +``` +β†’ Provides: {{$json.body.message}} for data mapping +β†’ Warns: Webhook data is under .body! +``` + +**Step 5**: n8n Validation Expert activates +``` +β†’ Validates: Complete workflow structure +β†’ Checks: Node configurations +β†’ Reports: Any errors or warnings +``` + +**Result**: Complete, validated, working workflow! + +--- + +## Common Use Cases + +### Use Case 1: Quick Node Search + +``` +You: "Find email nodes" + +[n8n MCP Tools Expert activates] +Claude: Uses search_nodes({query: "email"}) +Returns: Gmail, Email Send, IMAP Email, etc. +``` + +### Use Case 2: Fix Expression Error + +``` +You: "My {{$json.name}} is showing undefined in webhook workflow" + +[n8n Expression Syntax activates] +Claude: Webhook data is under .body! +Fix: {{$json.body.name}} +``` + +### Use Case 3: Understand Validation Error + +``` +You: "Validation says 'binary operator cannot have singleValue'" + +[n8n Validation Expert activates] +Claude: Binary operators (equals, contains) should NOT have singleValue. +Auto-sanitization will fix this on next update. +``` + +### Use Case 4: Build AI Workflow + +``` +You: "Create an AI Agent workflow with HTTP Request tool" + +[n8n Workflow Patterns + Node Configuration activate] +Claude: AI Agent Workflow Pattern: +1. Connect language model: sourceOutput="ai_languageModel" +2. Connect tool: sourceOutput="ai_tool" +3. Connect memory: sourceOutput="ai_memory" + +[Provides complete configuration] +``` + +--- + +## Best Practices + +### 1. Be Specific + +**Good**: "Build a webhook that receives form data and posts to Slack" +**Better**: "Build a webhook to Slack workflow with form validation and error handling" + +**Why**: More specific queries activate relevant skills with better context. + +### 2. Ask Follow-Up Questions + +Skills provide deep knowledge. Don't hesitate to ask: +``` +"Explain property dependencies in HTTP Request node" +"Show me more webhook examples" +"What are validation profiles?" +``` + +### 3. Request Validation + +Always ask for validation: +``` +"Build this workflow AND validate it" +"Check if this configuration is correct" +``` + +### 4. Leverage Cross-Skill Knowledge + +``` +"Build, validate, and explain the expressions in this workflow" +β†’ Activates: Patterns + Validation + Expression Syntax +``` + +### 5. Reference Real Templates + +``` +"Show me template #2947 and explain how it works" +β†’ Uses n8n-mcp tools to fetch and analyze real templates +``` + +--- + +## Skill Limitations + +### What Skills CAN Do: +βœ… Teach n8n concepts +βœ… Guide MCP tool usage +βœ… Provide workflow patterns +βœ… Interpret validation errors +βœ… Explain configurations +βœ… Reference real templates + +### What Skills CANNOT Do: +❌ Execute workflows (use n8n for that) +❌ Access your n8n instance directly (use n8n-mcp API tools) +❌ Modify running workflows +❌ Debug runtime execution errors (only configuration errors) + +--- + +## Tool Availability + +**Always Available** (no n8n API needed): +- search_nodes, list_nodes, get_node_essentials βœ… +- validate_node_minimal, validate_node_operation βœ… +- validate_workflow, get_property_dependencies βœ… +- search_templates, get_template βœ… + +**Requires n8n API** (N8N_API_URL + N8N_API_KEY): +- n8n_create_workflow ⚠️ +- n8n_update_partial_workflow ⚠️ +- n8n_validate_workflow (by ID) ⚠️ +- n8n_list_workflows, n8n_get_workflow ⚠️ +- n8n_trigger_webhook_workflow ⚠️ + +If API tools unavailable, skills use templates and validation-only workflows. + +--- + +## Troubleshooting + +### Skill Not Activating + +**Problem**: Skill doesn't activate when expected + +**Solution**: Rephrase query to match activation keywords +``` +Instead of: "How do I use expressions?" +Try: "How do I write n8n expressions with {{}} syntax?" +``` + +### Wrong Skill Activates + +**Problem**: Different skill than expected activates + +**Solution**: This is usually fine! Skills complement each other. +If needed, be more specific: +``` +"Using n8n MCP tools, search for webhook node" +``` + +### Multiple Skills Needed + +**Problem**: Need knowledge from multiple skills + +**Solution**: Ask a comprehensive question: +``` +"Build, configure, and validate a webhook workflow with explanations" +``` + +All relevant skills will activate automatically. + +--- + +## Advanced Usage + +### Request Specific Tool Usage + +``` +"Use get_node_essentials to show me Slack node configuration" +``` + +### Ask for Real Examples + +``` +"Show me real template examples of webhook workflows" +``` + +### Request Step-by-Step + +``` +"Step by step: build a webhook to database workflow with validation at each step" +``` + +### Debug with Skills + +``` +"My workflow fails validation. Debug it using validation expert knowledge." +``` + +--- + +## Next Steps + +- **Getting Started**: Try example queries above +- **Deep Dive**: Read individual SKILL.md files in skills/ +- **Contribute**: See [DEVELOPMENT.md](DEVELOPMENT.md) + +--- + +## Support + +- **Issues**: https://github.com/czlonkowski/n8n-skills/issues +- **Discussions**: https://github.com/czlonkowski/n8n-skills/discussions + +--- + +**Ready to build amazing n8n workflows with Claude? Start asking questions!** πŸš€ + +--- + +Conceived by Romuald CzΕ‚onkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)