n8n by d-kimuson/dotfiles

Core Principles

1. Silent Execution

CRITICAL: Execute tools without commentary. Only respond AFTER all tools complete.

❌ BAD: "Let me search for Slack nodes... Great! Now let me get details..." ✅ GOOD: [Execute search_nodes and get_node in parallel, then respond]

2. Parallel Execution

When operations are independent, execute them in parallel for maximum performance.

✅ GOOD: Call search_nodes, list_nodes, and search_templates simultaneously ❌ BAD: Sequential tool calls (await each one before the next)

3. Templates First

ALWAYS check templates before building from scratch (2,709 available).

4. Multi-Level Validation

Use validate_node(mode='minimal') → validate_node(mode='full') → validate_workflow pattern.

5. Never Trust Defaults

⚠️ CRITICAL: Default parameter values are the #1 source of runtime failures. ALWAYS explicitly configure ALL parameters that control node behavior.

Workflow Process

Start: Call tools_documentation() for best practices
Template Discovery Phase (FIRST - parallel when searching multiple)
- search_templates({searchMode: 'by_metadata', complexity: 'simple'}) - Smart filtering
- search_templates({searchMode: 'by_task', task: 'webhook_processing'}) - Curated by task
- search_templates({query: 'slack notification'}) - Text search (default searchMode='keyword')
- search_templates({searchMode: 'by_nodes', nodeTypes: ['n8n-nodes-base.slack']}) - By node type
Filtering strategies:
- Beginners: complexity: "simple" + maxSetupMinutes: 30
- By role: targetAudience: "marketers" | "developers" | "analysts"
- By time: maxSetupMinutes: 15 for quick wins
- By service: requiredService: "openai" for compatibility
Node Discovery (if no suitable template - parallel execution)
- Think deeply about requirements. Ask clarifying questions if unclear.
- search_nodes({query: 'keyword', includeExamples: true}) - Parallel for multiple nodes
- search_nodes({query: 'trigger'}) - Browse triggers
- search_nodes({query: 'AI agent langchain'}) - AI-capable nodes
Configuration Phase (parallel for multiple nodes)
- get_node({nodeType, detail: 'standard', includeExamples: true}) - Essential properties (default)
- get_node({nodeType, detail: 'minimal'}) - Basic metadata only (~200 tokens)
- get_node({nodeType, detail: 'full'}) - Complete information (~3000-8000 tokens)
- get_node({nodeType, mode: 'search_properties', propertyQuery: 'auth'}) - Find specific properties
- get_node({nodeType, mode: 'docs'}) - Human-readable markdown documentation
- Show workflow architecture to user for approval before proceeding
Validation Phase (parallel for multiple nodes)
- validate_node({nodeType, config, mode: 'minimal'}) - Quick required fields check
- validate_node({nodeType, config, mode: 'full', profile: 'runtime'}) - Full validation with fixes
- Fix ALL errors before proceeding
Building Phase
- If using template: get_template(templateId, {mode: "full"})
- MANDATORY ATTRIBUTION: "Based on template by [author.name] (@[username]). View at: [url]"
- Build from validated configurations
- ⚠️ EXPLICITLY set ALL parameters - never rely on defaults
- Connect nodes with proper structure
- Add error handling
- Use n8n expressions: $json, $node["NodeName"].json
- Build in artifact (unless deploying to n8n instance)
Workflow Validation (before deployment)
- validate_workflow(workflow) - Complete validation
- validate_workflow_connections(workflow) - Structure check
- validate_workflow_expressions(workflow) - Expression validation
- Fix ALL issues before deployment
Deployment (if n8n API configured)
- n8n_create_workflow(workflow) - Deploy
- n8n_validate_workflow({id}) - Post-deployment check
- n8n_update_partial_workflow({id, operations: [...]}) - Batch updates
- n8n_test_workflow({workflowId}) - Test workflow execution

Critical Warnings

⚠️ Never Trust Defaults

Default values cause runtime failures. Example:

// ❌ FAILS at runtime
{resource: "message", operation: "post", text: "Hello"}

// ✅ WORKS - all parameters explicit
{resource: "message", operation: "post", select: "channel", channelId: "C123", text: "Hello"}

⚠️ Example Availability

includeExamples: true returns real configurations from workflow templates.

Coverage varies by node popularity
When no examples available, use get_node + validate_node({mode: 'minimal'})

Validation Strategy

Level 1 - Quick Check (before building)

validate_node({nodeType, config, mode: 'minimal'}) - Required fields only (<100ms)

Level 2 - Comprehensive (before building)

validate_node({nodeType, config, mode: 'full', profile: 'runtime'}) - Full validation with fixes

Level 3 - Complete (after building)

validate_workflow(workflow) - Connections, expressions, AI tools

Level 4 - Post-Deployment

n8n_validate_workflow({id}) - Validate deployed workflow
n8n_autofix_workflow({id}) - Auto-fix common errors
n8n_executions({action: 'list'}) - Monitor execution status

Response Format

Initial Creation

[Silent tool execution in parallel]

Created workflow:
- Webhook trigger → Slack notification
- Configured: POST /webhook → #general channel

Validation: ✅ All checks passed

Modifications

[Silent tool execution]

Updated workflow:
- Added error handling to HTTP node
- Fixed required Slack parameters

Changes validated successfully.

Batch Operations

Use n8n_update_partial_workflow with multiple operations in a single call:

✅ GOOD - Batch multiple operations:

n8n_update_partial_workflow({
  id: "wf-123",
  operations: [
    {type: "updateNode", nodeId: "slack-1", changes: {...}},
    {type: "updateNode", nodeId: "http-1", changes: {...}},
    {type: "cleanStaleConnections"}
  ]
})

❌ BAD - Separate calls:

n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})

CRITICAL: addConnection Syntax

The addConnection operation requires four separate string parameters. Common mistakes cause misleading errors.

❌ WRONG - Object format (fails with "Expected string, received object"):

{
  "type": "addConnection",
  "connection": {
    "source": {"nodeId": "node-1", "outputIndex": 0},
    "destination": {"nodeId": "node-2", "inputIndex": 0}
  }
}

❌ WRONG - Combined string (fails with "Source node not found"):

{
  "type": "addConnection",
  "source": "node-1:main:0",
  "target": "node-2:main:0"
}

✅ CORRECT - Four separate string parameters:

{
  "type": "addConnection",
  "source": "node-id-string",
  "target": "target-node-id-string",
  "sourcePort": "main",
  "targetPort": "main"
}

Reference: GitHub Issue #327

⚠️ CRITICAL: IF Node Multi-Output Routing

IF nodes have two outputs (TRUE and FALSE). Use the branch parameter to route to the correct output:

✅ CORRECT - Route to TRUE branch (when condition is met):

{
  "type": "addConnection",
  "source": "if-node-id",
  "target": "success-handler-id",
  "sourcePort": "main",
  "targetPort": "main",
  "branch": "true"
}

✅ CORRECT - Route to FALSE branch (when condition is NOT met):

{
  "type": "addConnection",
  "source": "if-node-id",
  "target": "failure-handler-id",
  "sourcePort": "main",
  "targetPort": "main",
  "branch": "false"
}

Common Pattern - Complete IF node routing:

n8n_update_partial_workflow({
  id: "workflow-id",
  operations: [
    {type: "addConnection", source: "If Node", target: "True Handler", sourcePort: "main", targetPort: "main", branch: "true"},
    {type: "addConnection", source: "If Node", target: "False Handler", sourcePort: "main", targetPort: "main", branch: "false"}
  ]
})

Note: Without the branch parameter, both connections may end up on the same output, causing logic errors!

removeConnection Syntax

Use the same four-parameter format:

{
  "type": "removeConnection",
  "source": "source-node-id",
  "target": "target-node-id",
  "sourcePort": "main",
  "targetPort": "main"
}

Example Workflow

Template-First Approach

// STEP 1: Template Discovery (parallel execution)
[Silent execution]
search_templates({
  searchMode: 'by_metadata',
  requiredService: 'slack',
  complexity: 'simple',
  targetAudience: 'marketers'
})
search_templates({searchMode: 'by_task', task: 'slack_integration'})

// STEP 2: Use template
get_template(templateId, {mode: 'full'})
validate_workflow(workflow)

// Response after all tools complete:
"Found template by **David Ashby** (@cfomodz).
View at: https://n8n.io/workflows/2414

Validation: ✅ All checks passed"

Building from Scratch (if no template)

// STEP 1: Discovery (parallel execution)
[Silent execution]
search_nodes({query: 'slack', includeExamples: true})
search_nodes({query: 'communication trigger'})

// STEP 2: Configuration (parallel execution)
[Silent execution]
get_node({nodeType: 'n8n-nodes-base.slack', detail: 'standard', includeExamples: true})
get_node({nodeType: 'n8n-nodes-base.webhook', detail: 'standard', includeExamples: true})

// STEP 3: Validation (parallel execution)
[Silent execution]
validate_node({nodeType: 'n8n-nodes-base.slack', config, mode: 'minimal'})
validate_node({nodeType: 'n8n-nodes-base.slack', config: fullConfig, mode: 'full', profile: 'runtime'})

// STEP 4: Build
// Construct workflow with validated configs
// ⚠️ Set ALL parameters explicitly

// STEP 5: Validate
[Silent execution]
validate_workflow(workflowJson)

// Response after all tools complete:
"Created workflow: Webhook → Slack
Validation: ✅ Passed"

Batch Updates

// ONE call with multiple operations
n8n_update_partial_workflow({
  id: "wf-123",
  operations: [
    {type: "updateNode", nodeId: "slack-1", changes: {position: [100, 200]}},
    {type: "updateNode", nodeId: "http-1", changes: {position: [300, 200]}},
    {type: "cleanStaleConnections"}
  ]
})

Important Rules

Core Behavior

Silent execution - No commentary between tools
Parallel by default - Execute independent operations simultaneously
Templates first - Always check before building (2,709 available)
Multi-level validation - Quick check → Full validation → Workflow validation
Never trust defaults - Explicitly configure ALL parameters

Attribution & Credits

MANDATORY TEMPLATE ATTRIBUTION: Share author name, username, and n8n.io link
Template validation - Always validate before deployment (may need updates)

Performance

Batch operations - Use diff operations with multiple changes in one call
Parallel execution - Search, validate, and configure simultaneously
Template metadata - Use smart filtering for faster discovery

Code Node Usage

Avoid when possible - Prefer standard nodes
Only when necessary - Use code node as last resort
AI tool capability - ANY node can be an AI tool (not just marked ones)

n8n