opencode-skills-collection 4.0.53 → 4.0.54

package/bundled-skills/n8n-mcp-tools-expert/SKILL.md

@@ -3,12 +3,17 @@ 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, parameter formats, and common patterns.
 risk: critical
 source: community
+date_added: "2026-09-04"
 ---
 
 # n8n MCP Tools Expert
 
 Master guide for using n8n-mcp MCP server tools to build workflows.
 
+## Detailed Guide
+
+Read [the detailed guide](references/detailed-guide.md) before executing this skill. It retains the complete procedure and reference material. Treat its safety, prerequisites, and validation requirements as mandatory. For focused work, load the relevant sections; for end-to-end work, read the guide completely.
+
 ## When to Use
 - You are using the `n8n-mcp` toolset to discover nodes, validate configs, or manage workflows.
 - The task involves choosing the right MCP tool or understanding its expected parameters and usage pattern.
@@ -16,270 +21,6 @@ Master guide for using n8n-mcp MCP server tools to build workflows.
 
 ---
 
-## Tool Categories
-
-n8n-mcp provides tools organized into categories:
-
-1. **Node Discovery** → SEARCH_GUIDE.md
-2. **Configuration Validation** → VALIDATION_GUIDE.md
-3. **Workflow Management** → WORKFLOW_GUIDE.md
-4. **Template Library** - Search and deploy 2,700+ real workflows
-5. **Documentation & Guides** - Tool docs, AI agent guide, Code node guides
-
----
-
-## Quick Reference
-
-### Most Used Tools (by success rate)
-
-| Tool | Use When | Speed |
-|------|----------|-------|
-| `search_nodes` | Finding nodes by keyword | <20ms |
-| `get_node` | Understanding node operations (detail="standard") | <10ms |
-| `validate_node` | Checking configurations (mode="full") | <100ms |
-| `n8n_create_workflow` | Creating workflows | 100-500ms |
-| `n8n_update_partial_workflow` | Editing workflows (MOST USED!) | 50-200ms |
-| `validate_workflow` | Checking complete workflow | 100-500ms |
-| `n8n_deploy_template` | Deploy template to n8n instance | 200-500ms |
-
----
-
-## Tool Selection Guide
-
-### Finding the Right Node
-
-**Workflow**:
-```
-1. search_nodes({query: "keyword"})
-2. get_node({nodeType: "nodes-base.name"})
-3. [Optional] get_node({nodeType: "nodes-base.name", mode: "docs"})
-```
-
-**Example**:
-```javascript
-// Step 1: Search
-search_nodes({query: "slack"})
-// Returns: nodes-base.slack
-
-// Step 2: Get details
-get_node({nodeType: "nodes-base.slack"})
-// Returns: operations, properties, examples (standard detail)
-
-// Step 3: Get readable documentation
-get_node({nodeType: "nodes-base.slack", mode: "docs"})
-// Returns: markdown documentation
-```
-
-**Common pattern**: search → get_node (18s average)
-
-### Validating Configuration
-
-**Workflow**:
-```
-1. validate_node({nodeType, config: {}, mode: "minimal"}) - Check required fields
-2. validate_node({nodeType, config, profile: "runtime"}) - Full validation
-3. [Repeat] Fix errors, validate again
-```
-
-**Common pattern**: validate → fix → validate (23s thinking, 58s fixing per cycle)
-
-### Managing Workflows
-
-**Workflow**:
-```
-1. n8n_create_workflow({name, nodes, connections})
-2. n8n_validate_workflow({id})
-3. n8n_update_partial_workflow({id, operations: [...]})
-4. n8n_validate_workflow({id}) again
-5. n8n_update_partial_workflow({id, operations: [{type: "activateWorkflow"}]})
-```
-
-**Common pattern**: iterative updates (56s average between edits)
-
----
-
-## Critical: nodeType Formats
-
-**Two different formats** for different tools!
-
-### Format 1: Search/Validate Tools
-```javascript
-// Use SHORT prefix
-"nodes-base.slack"
-"nodes-base.httpRequest"
-"nodes-base.webhook"
-"nodes-langchain.agent"
-```
-
-**Tools that use this**:
-- search_nodes (returns this format)
-- get_node
-- validate_node
-- validate_workflow
-
-### Format 2: Workflow Tools
-```javascript
-// Use FULL prefix
-"n8n-nodes-base.slack"
-"n8n-nodes-base.httpRequest"
-"n8n-nodes-base.webhook"
-"@n8n/n8n-nodes-langchain.agent"
-```
-
-**Tools that use this**:
-- n8n_create_workflow
-- n8n_update_partial_workflow
-
-### Conversion
-
-```javascript
-// search_nodes returns BOTH formats
-{
-  "nodeType": "nodes-base.slack",          // For search/validate tools
-  "workflowNodeType": "n8n-nodes-base.slack"  // For workflow tools
-}
-```
-
----
-
-## Common Mistakes
-
-### Mistake 1: Wrong nodeType Format
-
-**Problem**: "Node not found" error
-
-```javascript
-// WRONG
-get_node({nodeType: "slack"})  // Missing prefix
-get_node({nodeType: "n8n-nodes-base.slack"})  // Wrong prefix
-
-// CORRECT
-get_node({nodeType: "nodes-base.slack"})
-```
-
-### Mistake 2: Using detail="full" by Default
-
-**Problem**: Huge payload, slower response, token waste
-
-```javascript
-// WRONG - Returns 3-8K tokens, use sparingly
-get_node({nodeType: "nodes-base.slack", detail: "full"})
-
-// CORRECT - Returns 1-2K tokens, covers 95% of use cases
-get_node({nodeType: "nodes-base.slack"})  // detail="standard" is default
-get_node({nodeType: "nodes-base.slack", detail: "standard"})
-```
-
-**When to use detail="full"**:
-- Debugging complex configuration issues
-- Need complete property schema with all nested options
-- Exploring advanced features
-
-**Better alternatives**:
-1. `get_node({detail: "standard"})` - for operations list (default)
-2. `get_node({mode: "docs"})` - for readable documentation
-3. `get_node({mode: "search_properties", propertyQuery: "auth"})` - for specific property
-
-### Mistake 3: Not Using Validation Profiles
-
-**Problem**: Too many false positives OR missing real errors
-
-**Profiles**:
-- `minimal` - Only required fields (fast, permissive)
-- `runtime` - Values + types (recommended for pre-deployment)
-- `ai-friendly` - Reduce false positives (for AI configuration)
-- `strict` - Maximum validation (for production)
-
-```javascript
-// WRONG - Uses default profile
-validate_node({nodeType, config})
-
-// CORRECT - Explicit profile
-validate_node({nodeType, config, profile: "runtime"})
-```
-
-### Mistake 4: Ignoring Auto-Sanitization
-
-**What happens**: ALL nodes sanitized on ANY workflow update
-
-**Auto-fixes**:
-- Binary operators (equals, contains) → removes singleValue
-- Unary operators (isEmpty, isNotEmpty) → adds singleValue: true
-- IF/Switch nodes → adds missing metadata
-
-**Cannot fix**:
-- Broken connections
-- Branch count mismatches
-- Paradoxical corrupt states
-
-```javascript
-// After ANY update, auto-sanitization runs on ALL nodes
-n8n_update_partial_workflow({id, operations: [...]})
-// → Automatically fixes operator structures
-```
-
-### Mistake 5: Not Using Smart Parameters
-
-**Problem**: Complex sourceIndex calculations for multi-output nodes
-
-**Old way** (manual):
-```javascript
-// IF node connection
-{
-  type: "addConnection",
-  source: "IF",
-  target: "Handler",
-  sourceIndex: 0  // Which output? Hard to remember!
-}
-```
-
-**New way** (smart parameters):
-```javascript
-// IF node - semantic branch names
-{
-  type: "addConnection",
-  source: "IF",
-  target: "True Handler",
-  branch: "true"  // Clear and readable!
-}
-
-{
-  type: "addConnection",
-  source: "IF",
-  target: "False Handler",
-  branch: "false"
-}
-
-// Switch node - semantic case numbers
-{
-  type: "addConnection",
-  source: "Switch",
-  target: "Handler A",
-  case: 0
-}
-```
-
-### Mistake 6: Not Using intent Parameter
-
-**Problem**: Less helpful tool responses
-
-```javascript
-// WRONG - No context for response
-n8n_update_partial_workflow({
-  id: "abc",
-  operations: [{type: "addNode", node: {...}}]
-})
-
-// CORRECT - Better AI responses
-n8n_update_partial_workflow({
-  id: "abc",
-  intent: "Add error handling for API failures",
-  operations: [{type: "addNode", node: {...}}]
-})
-```
-
----
-
 ## Tool Usage Patterns
 
 ### Pattern 1: Node Discovery (Most Common)
@@ -367,34 +108,6 @@ await n8n_update_partial_workflow({
 
 ---
 
-## Detailed Guides
-
-### Node Discovery Tools
-See SEARCH_GUIDE.md for:
-- search_nodes
-- get_node with detail levels (minimal, standard, full)
-- get_node modes (info, docs, search_properties, versions)
-
-### Validation Tools
-See VALIDATION_GUIDE.md for:
-- Validation profiles explained
-- validate_node with modes (minimal, full)
-- validate_workflow complete structure
-- Auto-sanitization system
-- Handling validation errors
-
-### Workflow Management
-See WORKFLOW_GUIDE.md for:
-- n8n_create_workflow
-- n8n_update_partial_workflow (17 operation types!)
-- Smart parameters (branch, case)
-- AI connection types (8 types)
-- Workflow activation (activateWorkflow/deactivateWorkflow)
-- n8n_deploy_template
-- n8n_workflow_versions
-
----
-
 ## Template Usage
 
 ### Search Templates
@@ -455,199 +168,6 @@ n8n_deploy_template({
 
 ---
 
-## Self-Help Tools
-
-### Get Tool Documentation
-
-```javascript
-// Overview of all tools
-tools_documentation()
-
-// Specific tool details
-tools_documentation({
-  topic: "search_nodes",
-  depth: "full"
-})
-
-// Code node guides
-tools_documentation({topic: "javascript_code_node_guide", depth: "full"})
-tools_documentation({topic: "python_code_node_guide", depth: "full"})
-```
-
-### AI Agent Guide
-
-```javascript
-// Comprehensive AI workflow guide
-ai_agents_guide()
-// Returns: Architecture, connections, tools, validation, best practices
-```
-
-### Health Check
-
-```javascript
-// Quick health check
-n8n_health_check()
-
-// Detailed diagnostics
-n8n_health_check({mode: "diagnostic"})
-// → Returns: status, env vars, tool status, API connectivity
-```
-
----
-
-## Tool Availability
-
-**Always Available** (no n8n API needed):
-- search_nodes, get_node
-- validate_node, validate_workflow
-- search_templates, get_template
-- tools_documentation, ai_agents_guide
-
-**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_test_workflow
-- n8n_executions
-- n8n_deploy_template
-- n8n_workflow_versions
-- n8n_autofix_workflow
-
-If API tools unavailable, use templates and validation-only workflows.
-
----
-
-## Unified Tool Reference
-
-### get_node (Unified Node Information)
-
-**Detail Levels** (mode="info", default):
-- `minimal` (~200 tokens) - Basic metadata only
-- `standard` (~1-2K tokens) - Essential properties + operations (RECOMMENDED)
-- `full` (~3-8K tokens) - Complete schema (use sparingly)
-
-**Operation Modes**:
-- `info` (default) - Node schema with detail level
-- `docs` - Readable markdown documentation
-- `search_properties` - Find specific properties (use with propertyQuery)
-- `versions` - List all versions with breaking changes
-- `compare` - Compare two versions
-- `breaking` - Show only breaking changes
-- `migrations` - Show auto-migratable changes
-
-```javascript
-// Standard (recommended)
-get_node({nodeType: "nodes-base.httpRequest"})
-
-// Get documentation
-get_node({nodeType: "nodes-base.webhook", mode: "docs"})
-
-// Search for properties
-get_node({nodeType: "nodes-base.httpRequest", mode: "search_properties", propertyQuery: "auth"})
-
-// Check versions
-get_node({nodeType: "nodes-base.executeWorkflow", mode: "versions"})
-```
-
-### validate_node (Unified Validation)
-
-**Modes**:
-- `full` (default) - Comprehensive validation with errors/warnings/suggestions
-- `minimal` - Quick required fields check only
-
-**Profiles** (for mode="full"):
-- `minimal` - Very lenient
-- `runtime` - Standard (default, recommended)
-- `ai-friendly` - Balanced for AI workflows
-- `strict` - Most thorough (production)
-
-```javascript
-// Full validation with runtime profile
-validate_node({nodeType: "nodes-base.slack", config: {...}, profile: "runtime"})
-
-// Quick required fields check
-validate_node({nodeType: "nodes-base.webhook", config: {}, mode: "minimal"})
-```
-
----
-
-## Performance Characteristics
-
-| Tool | Response Time | Payload Size |
-|------|---------------|--------------|
-| search_nodes | <20ms | Small |
-| get_node (standard) | <10ms | ~1-2KB |
-| get_node (full) | <100ms | 3-8KB |
-| validate_node (minimal) | <50ms | Small |
-| validate_node (full) | <100ms | Medium |
-| validate_workflow | 100-500ms | Medium |
-| n8n_create_workflow | 100-500ms | Medium |
-| n8n_update_partial_workflow | 50-200ms | Small |
-| n8n_deploy_template | 200-500ms | Medium |
-
----
-
-## Best Practices
-
-### Do
-- Use `get_node({detail: "standard"})` for most use cases
-- Specify validation profile explicitly (`profile: "runtime"`)
-- Use smart parameters (`branch`, `case`) for clarity
-- Include `intent` parameter in workflow updates
-- Follow search → get_node → validate workflow
-- Iterate workflows (avg 56s between edits)
-- Validate after every significant change
-- Use `includeExamples: true` for real configs
-- Use `n8n_deploy_template` for quick starts
-
-### Don't
-- Use `detail: "full"` unless necessary (wastes tokens)
-- Forget nodeType prefix (`nodes-base.*`)
-- Skip validation profiles
-- Try to build workflows in one shot (iterate!)
-- Ignore auto-sanitization behavior
-- Use full prefix (`n8n-nodes-base.*`) with search/validate tools
-- Forget to activate workflows after building
-
----
-
-## Summary
-
-**Most Important**:
-1. Use **get_node** with `detail: "standard"` (default) - covers 95% of use cases
-2. nodeType formats differ: `nodes-base.*` (search/validate) vs `n8n-nodes-base.*` (workflows)
-3. Specify **validation profiles** (`runtime` recommended)
-4. Use **smart parameters** (`branch="true"`, `case=0`)
-5. Include **intent parameter** in workflow updates
-6. **Auto-sanitization** runs on ALL nodes during updates
-7. Workflows can be **activated via API** (`activateWorkflow` operation)
-8. Workflows are built **iteratively** (56s avg between edits)
-
-**Common Workflow**:
-1. search_nodes → find node
-2. get_node → understand config
-3. validate_node → check config
-4. n8n_create_workflow → build
-5. n8n_validate_workflow → verify
-6. n8n_update_partial_workflow → iterate
-7. activateWorkflow → go live!
-
-For details, see:
-- SEARCH_GUIDE.md - Node discovery
-- VALIDATION_GUIDE.md - Configuration validation
-- WORKFLOW_GUIDE.md - Workflow management
-
----
-
-**Related Skills**:
-- n8n Expression Syntax - Write expressions in workflow fields
-- n8n Workflow Patterns - Architectural patterns from templates
-- n8n Validation Expert - Interpret validation errors
-- n8n Node Configuration - Operation-specific requirements
-- n8n Code JavaScript - Write JavaScript in Code nodes
-- n8n Code Python - Write Python in Code nodes
-
 ## Limitations
 - Use this skill only when the task clearly matches the scope described above.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.