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