n8n-skills/docs/USAGE.md

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:

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

---

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