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
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