mirror of
https://github.com/czlonkowski/n8n-skills.git
synced 2026-03-16 23:43:08 +00:00
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
This commit is contained in:
czlonkowski
1
.gitignore
vendored
1
.gitignore
vendored
@@ -1,2 +1 @@
|
|||||||
docs/
|
|
||||||
.mcp.json
|
.mcp.json
|
||||||
|
|||||||
251
README.md
251
README.md
@@ -1,2 +1,251 @@
|
|||||||
# n8n-skills
|
# 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)
|
||||||
|
[](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!** 🚀
|
||||||
|
|||||||
633
docs/DEVELOPMENT.md
Normal file
633
docs/DEVELOPMENT.md
Normal file
@@ -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)
|
||||||
336
docs/INSTALLATION.md
Normal file
336
docs/INSTALLATION.md
Normal file
@@ -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)
|
||||||
171
docs/MCP_TESTING_LOG.md
Normal file
171
docs/MCP_TESTING_LOG.md
Normal file
@@ -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!
|
||||||
2021
docs/SKILLS_IMPLEMENTATION_GUIDE.md
Normal file
2021
docs/SKILLS_IMPLEMENTATION_GUIDE.md
Normal file
File diff suppressed because it is too large
Load Diff
502
docs/USAGE.md
Normal file
502
docs/USAGE.md
Normal file
@@ -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)
|
||||||
Reference in New Issue
Block a user