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

Dev (Local Docker)
- URL: http://localhost:5678
- Purpose: Rapid iteration and testing
- Database: Local SQLite or PostgreSQL
- Usage: Initial development and experimentation
Staging (Railway)
- Previously called "dev" (recently renamed to "staging")
- Purpose: Pre-production validation
- Database: Railway PostgreSQL
- Usage: Integration testing, acceptance tests
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

Develop in Local Docker
- Create workflow in local n8n
- Test with sample data
- Iterate quickly
Export Workflow JSON
- Settings → Export Workflow
- Save JSON file to project repo
- Version control the JSON
Deploy to Staging
- Use Railway n8n MCP to import workflow
- Run acceptance tests
- Verify integrations work
- Check error handling
Acceptance Testing
- Test happy path scenarios
- Test error scenarios
- Verify webhook responses
- Check logging and monitoring
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:

GitHub repo → Settings → Webhooks
Add webhook URL: https://n8n.railway.app/webhook/github-event
Select events: Pull requests, Issues, Push
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:

Check webhook is active in n8n
Verify webhook URL is correct
Check webhook secret/authentication
Look at n8n execution history
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

Minimize HTTP Requests
- Batch API calls when possible
- Cache responses when appropriate
- Use HTTP Request Bulk mode
Efficient Data Processing
- Filter early to reduce data volume
- Use Code nodes for bulk operations
- Avoid unnecessary transformations
Parallel Execution
- Use Split In Batches for parallel processing
- Configure concurrent execution limit
- Balance speed vs. resource usage
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:

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

If the improvement is cross-system:

Consider if it belongs in integration-workflows skill
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