N8n Flow Builder

n8n Flow Builder

Purpose

This skill provides comprehensive guidance for creating, testing, and deploying n8n workflows. It codifies best practices for flow design, node configuration, error handling, and multi-environment deployment (dev → staging → prod).

When to Use This Skill

Claude should use this skill when:

• User asks to create or modify n8n workflows
• Building automation flows
• Configuring n8n nodes (HTTP, webhooks, database, etc.)
• Debugging n8n executions
• Deploying workflows across environments
• Integrating n8n with other systems via MCP

Environment Context

Three-Tier Architecture

1. Dev (Local Docker)

   • URL: http://localhost:5678
   • Purpose: Rapid iteration and testing
   • Database: Local SQLite or PostgreSQL
   • Usage: Initial development and experimentation

2. Staging (Railway)

   • Previously called "dev" (recently renamed to "staging")
   • Purpose: Pre-production validation
   • Database: Railway PostgreSQL
   • Usage: Integration testing, acceptance tests

3. Prod (Railway)

   • Purpose: Production workflows
   • Database: Railway PostgreSQL (separate instance)
   • Usage: Live automation for real business processes
   • Access: Railway-hosted n8n MCP server

MCP Integration

• Railway hosts the n8n MCP server
• MCP provides programmatic access to n8n API
• Used for: deploying workflows, triggering executions, monitoring

n8n Flow Design Patterns

1. Webhook-Triggered Workflows

Pattern: External systems trigger n8n via HTTP webhook

Structure:

Webhook Node (Trigger)
  ↓
Validate Input (IF node or Function)
  ↓
Process Data (various nodes)
  ↓
Branch on Outcome (IF node)
  ↓
Success Path → Respond with 200
Error Path → Log + Respond with 4xx/5xx

Best Practices:

• Always validate webhook payload structure
• Set webhook path to be descriptive: /webhook/github-pr-created
• Return appropriate HTTP status codes
• Include error handling for malformed payloads
• Log all webhook invocations for debugging

Example Use Cases:

• GitHub webhook for PR events
• Stripe webhook for payment events
• Slack webhook for slash commands

2. Scheduled Workflows

Pattern: Time-based automation (cron jobs)

Structure:

Schedule Trigger (Cron)
  ↓
Fetch Data (HTTP Request, Database Query)
  ↓
Process/Transform (Function, Code nodes)
  ↓
Take Action (Send notification, update records)
  ↓
Log Results

Best Practices:

• Use cron expressions for precise timing
• Include timezone considerations
• Add error notifications (Slack, email)
• Keep execution history for debugging
• Consider load during business hours

3. Long-Running Automations

Pattern: Workflows that take significant time or require human approval

Structure:

Trigger
  ↓
Initial Processing
  ↓
Wait Node (for approval or time delay)
  ↓
Continue Processing
  ↓
Complete

Best Practices:

• Use Wait nodes for delays or webhooks for approvals
• Store state in n8n's execution data
• Handle timeout scenarios
• Provide status endpoints for monitoring

Common Node Configurations

HTTP Request Node

Purpose: Call external APIs

Configuration Tips:

• Authentication: Store credentials in n8n credential system

• Error Handling: Enable "Continue on Fail" for non-critical requests

• Retry Logic: Configure retries for transient failures

• Timeout: Set appropriate timeouts (default may be too short)

• Headers: Use expressions for dynamic headers

Common Patterns:

// Dynamic Authorization header
{{ $credentials.apiKey }}

// Query parameters from previous node
{{ $json.userId }}

// Conditional URL
{{ $node["IF"].json.environment === "prod" ? "api.prod.com" : "api.staging.com" }}

Function Node

Purpose: Custom JavaScript/Python for complex logic

Best Practices:

• Keep functions small and focused
• Comment complex logic
• Handle null/undefined values
• Return consistent data structure
• Use try/catch for error handling

Example:

// Transform data format
const items = $input.all();
return items.map(item => ({
  id: item.json.id,
  name: item.json.full_name || 'Unknown',
  created: new Date(item.json.timestamp).toISOString()
}));

IF Node

Purpose: Conditional branching

Configuration:

• Use clear condition names: "Is Valid Email", "Has Permission"
• Chain multiple conditions with AND/OR
• Always handle both true/false branches
• Consider default/"else" path for unexpected values

Set Node

Purpose: Store data for later use in workflow

Best Practices:

• Use descriptive key names
• Store intermediate results for debugging
• Keep values JSON-serializable
• Document expected structure

Merge Node

Purpose: Combine data from multiple branches

Modes:

• Append: Combine all items (union)
• Keep Key Matches: Inner join on key
• Combine: Merge objects by key

Common Use:

Branch 1: Fetch user data
Branch 2: Fetch user's orders
  ↓
Merge (Keep Key Matches on userId)
  ↓
Result: User with their orders

Error Handling Patterns

1. Try-Catch Pattern

Try Branch:
  → HTTP Request (Continue on Fail: enabled)
  → IF: Check for errors
    → Success path
    → Error path → Log + Notify

2. Global Error Workflow

• Configure at workflow level
• Catches all unhandled errors
• Sends notifications (Slack, email)
• Logs to monitoring system
• Pattern:

  Error Trigger
    ↓
  Extract Error Details
    ↓
  Format Error Message
    ↓
  Send to Slack/Email
    ↓
  Log to Database
  

3. Retry with Exponential Backoff

// In Function node before HTTP request
const attempt = $json.attempt || 1;
const maxAttempts = 3;
const baseDelay = 1000; // 1 second

if (attempt <= maxAttempts) {
  return {
    ...item.json,
    attempt: attempt,
    delay: Math.pow(2, attempt - 1) * baseDelay
  };
}
// Max attempts reached, fail
throw new Error('Max retry attempts exceeded');

Deployment Workflow

Standard Deployment Process

1. Develop in Local Docker

   • Create workflow in local n8n
   • Test with sample data
   • Iterate quickly

2. Export Workflow JSON

   • Settings → Export Workflow
   • Save JSON file to project repo
   • Version control the JSON

3. Deploy to Staging

   • Use Railway n8n MCP to import workflow
   • Run acceptance tests
   • Verify integrations work
   • Check error handling

4. Acceptance Testing

   • Test happy path scenarios
   • Test error scenarios
   • Verify webhook responses
   • Check logging and monitoring

5. Deploy to Prod

   • Use Railway n8n MCP to import workflow
   • Enable workflow (set to active)
   • Monitor initial executions
   • Have rollback plan ready

Rollback Plan

Always include in deployment documentation:

• Previous workflow version JSON (stored in git)
• Steps to restore previous version
• How to verify rollback succeeded
• Who to notify if rollback needed

Integration Patterns

GitHub Integration

Use Cases:

• PR created → notify team in Slack
• Issue labeled → update Linear ticket
• Push to main → trigger deployment

Webhook Setup:

1. GitHub repo → Settings → Webhooks
2. Add webhook URL: https://n8n.railway.app/webhook/github-event
3. Select events: Pull requests, Issues, Push
4. Set secret for verification

Linear Integration

Use Cases:

• Issue status changed → update related GitHub issue
• New issue → post to Slack channel
• Issue assigned → notify assignee

Best Practices:

• Use Linear webhook for real-time updates
• Store Linear API key in n8n credentials
• Use GraphQL for complex queries

Slack Integration

Use Cases:

• Send notifications
• Slash command handlers
• Interactive button responses

Patterns:

• Use Slack Bot token for posting messages
• Format messages with Block Kit
• Handle rate limits (1 message per second)

Debugging and Troubleshooting

Common Issues

Issue: Webhook not triggering Debug Steps:

1. Check webhook is active in n8n
2. Verify webhook URL is correct
3. Check webhook secret/authentication
4. Look at n8n execution history
5. Test with manual webhook trigger

Issue: Workflow times out Solutions:

• Increase workflow timeout in settings
• Break into smaller workflows
• Use Queue nodes for long operations
• Add Wait nodes to prevent rate limits

Issue: Data not passing between nodes Debug:

• Check each node's output in execution view
• Verify node connections
• Check expressions for typos
• Use Set node to inspect data structure

Logging Best Practices

• Add descriptive notes to complex nodes
• Use Set nodes to log intermediate state
• Include timestamp in log messages
• Log both success and failure paths
• Store critical execution data for audit trail

Performance Optimization

Tips for Fast Workflows

1. Minimize HTTP Requests

   • Batch API calls when possible
   • Cache responses when appropriate
   • Use HTTP Request Bulk mode

2. Efficient Data Processing

   • Filter early to reduce data volume
   • Use Code nodes for bulk operations
   • Avoid unnecessary transformations

3. Parallel Execution

   • Use Split In Batches for parallel processing
   • Configure concurrent execution limit
   • Balance speed vs. resource usage

4. Database Queries

   • Use indexes on frequently queried fields
   • Limit result sets
   • Use pagination for large datasets
   • Consider caching for read-heavy operations

Security Best Practices

Credential Management

• Never hardcode API keys or passwords
• Use n8n's credential system
• Rotate credentials regularly
• Use environment-specific credentials
• Document which workflows use which credentials

Webhook Security

• Always validate webhook signatures
• Use HTTPS for webhook URLs
• Implement rate limiting
• Validate input data structure
• Sanitize user input

Access Control

• Use Railway's authentication for n8n UI
• Limit who can edit production workflows
• Audit workflow changes
• Use separate credentials for dev/staging/prod

Workflow Documentation Template

When creating a new workflow, document:

# Workflow Name: [Descriptive Name]

## Purpose
[What this workflow does and why it exists]

## Trigger
- Type: [Webhook/Schedule/Manual]
- Configuration: [Details]

## Environment
- Dev: [Status/URL]
- Staging: [Status/URL]
- Prod: [Status/URL]

## Data Flow
[How data moves through the workflow]

## Error Handling
[How errors are caught and handled]

## Acceptance Tests
- [ ] Test case 1: [Description]
- [ ] Test case 2: [Description]
- [ ] Error scenario: [Description]

## Rollback Plan
[Steps to revert if deployment fails]

## Dependencies
- External APIs: [List]
- Credentials: [List]
- Other workflows: [List]

## Monitoring
- Success metrics: [What to measure]
- Error alerts: [Where they go]
- Logs: [Where to find them]

Common Gotchas and Pitfalls

1. Webhook Path Conflicts

• Each webhook must have unique path
• Use descriptive paths: /webhook/linear-issue-created
• Document all webhook paths in central registry

2. Execution Mode Settings

• Production: Workflows run independently
• Integration: Workflows can call each other
• Choose based on workflow dependencies

3. Data Persistence

• Workflow execution data is temporary
• Use database or external storage for persistence
• Don't rely on workflow variables across executions

4. Rate Limiting

• APIs have rate limits (GitHub: 5000/hour)
• Implement exponential backoff
• Cache when possible
• Consider webhook alternatives to polling

5. Node Version Compatibility

• Nodes get updated in n8n releases
• Test workflows after n8n upgrades
• Export/import may require node updates
• Keep local dev n8n version in sync with Railway

Quick Reference Commands

Using n8n MCP (via Railway)

// List all workflows
n8n.listWorkflows()

// Get workflow by ID
n8n.getWorkflow(workflowId)

// Execute workflow
n8n.executeWorkflow(workflowId, inputData)

// Import workflow JSON
n8n.importWorkflow(workflowJson)

Local n8n (Docker)

# Start n8n
docker-compose up -d

# View logs
docker-compose logs -f n8n

# Stop n8n
docker-compose down

# Reset database (careful!)
docker-compose down -v

Usage Examples

Example 1: Create GitHub PR Notification Workflow

User: "Create an n8n workflow that sends a Slack message when a PR is created"

Claude (using n8n-flow-builder):
1. ✅ Designs webhook-triggered workflow
2. 📋 Configures Webhook node for GitHub events
3. 🔍 Adds validation for PR created event
4. 🔄 Extracts PR details (title, author, URL)
5. 💬 Configures Slack node with message format
6. 📝 Documents acceptance tests
7. 🚀 Provides deployment instructions for staging → prod

Example 2: Daily Report Workflow

User: "Build a daily report that queries our database and emails results"

Claude (using n8n-flow-builder):
1. ⏰ Creates Schedule Trigger (cron: 0 9 * * 1-5) - weekdays at 9am
2. 🗄️ Configures PostgreSQL query node
3. 📊 Transforms data with Function node
4. 📧 Formats email with HTML template
5. ✉️ Configures Send Email node
6. ⚠️ Adds error handling with Slack notification
7. 📝 Documents expected output and rollback

Example 3: Multi-Step Automation with Approval

User: "Create workflow that requires manager approval before executing"

Claude (using n8n-flow-builder):
1. 🎯 Trigger: Form submission webhook
2. 💾 Store request in database
3. 📧 Send approval email with unique URL
4. ⏸️ Wait node: Waits for webhook callback
5. ✅ On approval: Execute action + notify
6. ❌ On rejection: Log + notify requester
7. ⏱️ Timeout: Auto-reject after 24 hours

Integration with Your Workflow

When Claude Should Use This Skill

• Any mention of "n8n", "workflow", or "automation"
• Creating integrations between systems
• Setting up webhooks or scheduled tasks
• Deploying to Railway environments
• Debugging n8n executions

Hand-off Artifacts

When completing n8n work, always provide:

• ✅ Workflow JSON (for version control)
• ✅ Documentation using template above
• ✅ Acceptance test checklist
• ✅ Deployment instructions (dev → staging → prod)
• ✅ Rollback plan
• ✅ Expected webhook URLs or schedule

Coordination with Other Skills

• linear-orchestration: Create Linear issues for workflow deployment tasks
• github-coordinator: Store workflow JSON in version control
• skill-manager: Version and document new n8n patterns

Resources

• n8n Documentation
• n8n Community Forum
• n8n Workflow Templates
• Railway n8n MCP: Use for programmatic deployment

Notes

• Created: 2025-10-18
• Author: Kurt Anderson
• Version: 1.0.0
• This skill codifies Kurt's n8n workflow patterns and deployment process
• Environments were recently reorganized: old "dev" → "staging"
• Railway hosts both staging and prod instances plus n8n MCP server

Meta-Pattern: Self-Improvement Protocol

When Discovering n8n Workflow Improvements

If the improvement is a general pattern:

1. Update this skill (n8n-flow-builder)
2. Update the forked n8n MCP repository
3. Document in both places
4. Consider PR to upstream n8n MCP

If the improvement is cross-system:

1. Consider if it belongs in integration-workflows skill
2. Update integration-workflows if applicable

Forked n8n MCP Repository

Location: [Your GitHub fork of n8n MCP] Purpose: Community benefit + your own n8n agent improvements Update When:

• New n8n node patterns discovered
• Better error handling approaches
• Deployment workflow improvements
• Railway-specific optimizations

Example: Adding a New Pattern

Discovery: "Webhook validation pattern works great!"
  ↓
1. Add to n8n-flow-builder skill (this file)
2. Update forked n8n-mcp/docs/patterns.md
3. Test in n8n agent project
4. Commit both repos
5. Optional: PR to upstream n8n-mcp

This ensures improvements benefit:

• Future you
• Your n8n agent project
• Other n8n MCP users
• The broader community