@hybridlabor-api/bdb-antigravity-skills 1.0.0

package/skills/global_legacy/n8n-workflow-patterns/SKILL.md

@@ -0,0 +1,423 @@
+---
+name: n8n-workflow-patterns
+description: "Proven architectural patterns for building n8n workflows."
+risk: unknown
+source: community
+---
+
+# n8n Workflow Patterns
+
+Proven architectural patterns for building n8n workflows.
+
+## When to Use
+- You need to choose an architectural pattern for an n8n workflow before building it.
+- The task involves webhook processing, API integration, scheduled jobs, database sync, or AI-agent workflow design.
+- You want a high-level workflow structure rather than node-by-node troubleshooting.
+
+---
+
+## The 5 Core Patterns
+
+Based on analysis of real workflow usage:
+
+1. **Webhook Processing** (Most Common)
+   - Receive HTTP requests → Process → Output
+   - Pattern: Webhook → Validate → Transform → Respond/Notify
+
+2. **[HTTP API Integration]**
+   - Fetch from REST APIs → Transform → Store/Use
+   - Pattern: Trigger → HTTP Request → Transform → Action → Error Handler
+
+3. **Database Operations**
+   - Read/Write/Sync database data
+   - Pattern: Schedule → Query → Transform → Write → Verify
+
+4. **AI Agent Workflow**
+   - AI agents with tools and memory
+   - Pattern: Trigger → AI Agent (Model + Tools + Memory) → Output
+
+5. **Scheduled Tasks**
+   - Recurring automation workflows
+   - Pattern: Schedule → Fetch → Process → Deliver → Log
+
+---
+
+## Pattern Selection Guide
+
+### When to use each pattern:
+
+**Webhook Processing** - Use when:
+- Receiving data from external systems
+- Building integrations (Slack commands, form submissions, GitHub webhooks)
+- Need instant response to events
+- Example: "Receive Stripe payment webhook → Update database → Send confirmation"
+
+**HTTP API Integration** - Use when:
+- Fetching data from external APIs
+- Synchronizing with third-party services
+- Building data pipelines
+- Example: "Fetch GitHub issues → Transform → Create Jira tickets"
+
+**Database Operations** - Use when:
+- Syncing between databases
+- Running database queries on schedule
+- ETL workflows
+- Example: "Read Postgres records → Transform → Write to MySQL"
+
+**AI Agent Workflow** - Use when:
+- Building conversational AI
+- Need AI with tool access
+- Multi-step reasoning tasks
+- Example: "Chat with AI that can search docs, query database, send emails"
+
+**Scheduled Tasks** - Use when:
+- Recurring reports or summaries
+- Periodic data fetching
+- Maintenance tasks
+- Example: "Daily: Fetch analytics → Generate report → Email team"
+
+---
+
+## Common Workflow Components
+
+All patterns share these building blocks:
+
+### 1. Triggers
+- **Webhook** - HTTP endpoint (instant)
+- **Schedule** - Cron-based timing (periodic)
+- **Manual** - Click to execute (testing)
+- **Polling** - Check for changes (intervals)
+
+### 2. Data Sources
+- **HTTP Request** - REST APIs
+- **Database nodes** - Postgres, MySQL, MongoDB
+- **Service nodes** - Slack, Google Sheets, etc.
+- **Code** - Custom JavaScript/Python
+
+### 3. Transformation
+- **Set** - Map/transform fields
+- **Code** - Complex logic
+- **IF/Switch** - Conditional routing
+- **Merge** - Combine data streams
+
+### 4. Outputs
+- **HTTP Request** - Call APIs
+- **Database** - Write data
+- **Communication** - Email, Slack, Discord
+- **Storage** - Files, cloud storage
+
+### 5. Error Handling
+- **Error Trigger** - Catch workflow errors
+- **IF** - Check for error conditions
+- **Stop and Error** - Explicit failure
+- **Continue On Fail** - Per-node setting
+
+---
+
+## Workflow Creation Checklist
+
+When building ANY workflow, follow this checklist:
+
+### Planning Phase
+- [ ] Identify the pattern (webhook, API, database, AI, scheduled)
+- [ ] List required nodes (use search_nodes)
+- [ ] Understand data flow (input → transform → output)
+- [ ] Plan error handling strategy
+
+### Implementation Phase
+- [ ] Create workflow with appropriate trigger
+- [ ] Add data source nodes
+- [ ] Configure authentication/credentials
+- [ ] Add transformation nodes (Set, Code, IF)
+- [ ] Add output/action nodes
+- [ ] Configure error handling
+
+### Validation Phase
+- [ ] Validate each node configuration (validate_node)
+- [ ] Validate complete workflow (validate_workflow)
+- [ ] Test with sample data
+- [ ] Handle edge cases (empty data, errors)
+
+### Deployment Phase
+- [ ] Review workflow settings (execution order, timeout, error handling)
+- [ ] Activate workflow using `activateWorkflow` operation
+- [ ] Monitor first executions
+- [ ] Document workflow purpose and data flow
+
+---
+
+## Data Flow Patterns
+
+### Linear Flow
+```
+Trigger → Transform → Action → End
+```
+**Use when**: Simple workflows with single path
+
+### Branching Flow
+```
+Trigger → IF → [True Path]
+             └→ [False Path]
+```
+**Use when**: Different actions based on conditions
+
+### Parallel Processing
+```
+Trigger → [Branch 1] → Merge
+       └→ [Branch 2] ↗
+```
+**Use when**: Independent operations that can run simultaneously
+
+### Loop Pattern
+```
+Trigger → Split in Batches → Process → Loop (until done)
+```
+**Use when**: Processing large datasets in chunks
+
+### Error Handler Pattern
+```
+Main Flow → [Success Path]
+         └→ [Error Trigger → Error Handler]
+```
+**Use when**: Need separate error handling workflow
+
+---
+
+## Common Gotchas
+
+### 1. Webhook Data Structure
+**Problem**: Can't access webhook payload data
+
+**Solution**: Data is nested under `$json.body`
+```javascript
+❌ {{$json.email}}
+✅ {{$json.body.email}}
+```
+See: n8n Expression Syntax skill
+
+### 2. Multiple Input Items
+**Problem**: Node processes all input items, but I only want one
+
+**Solution**: Use "Execute Once" mode or process first item only
+```javascript
+{{$json[0].field}}  // First item only
+```
+
+### 3. Authentication Issues
+**Problem**: API calls failing with 401/403
+
+**Solution**:
+- Configure credentials properly
+- Use the "Credentials" section, not parameters
+- Test credentials before workflow activation
+
+### 4. Node Execution Order
+**Problem**: Nodes executing in unexpected order
+
+**Solution**: Check workflow settings → Execution Order
+- v0: Top-to-bottom (legacy)
+- v1: Connection-based (recommended)
+
+### 5. Expression Errors
+**Problem**: Expressions showing as literal text
+
+**Solution**: Use {{}} around expressions
+- See n8n Expression Syntax skill for details
+
+---
+
+## Integration with Other Skills
+
+These skills work together with Workflow Patterns:
+
+**n8n MCP Tools Expert** - Use to:
+- Find nodes for your pattern (search_nodes)
+- Understand node operations (get_node)
+- Create workflows (n8n_create_workflow)
+- Deploy templates (n8n_deploy_template)
+- Use ai_agents_guide for AI pattern guidance
+
+**n8n Expression Syntax** - Use to:
+- Write expressions in transformation nodes
+- Access webhook data correctly ({{$json.body.field}})
+- Reference previous nodes ({{$node["Node Name"].json.field}})
+
+**n8n Node Configuration** - Use to:
+- Configure specific operations for pattern nodes
+- Understand node-specific requirements
+
+**n8n Validation Expert** - Use to:
+- Validate workflow structure
+- Fix validation errors
+- Ensure workflow correctness before deployment
+
+---
+
+## Pattern Statistics
+
+Common workflow patterns:
+
+**Most Common Triggers**:
+1. Webhook - 35%
+2. Schedule (periodic tasks) - 28%
+3. Manual (testing/admin) - 22%
+4. Service triggers (Slack, email, etc.) - 15%
+
+**Most Common Transformations**:
+1. Set (field mapping) - 68%
+2. Code (custom logic) - 42%
+3. IF (conditional routing) - 38%
+4. Switch (multi-condition) - 18%
+
+**Most Common Outputs**:
+1. HTTP Request (APIs) - 45%
+2. Slack - 32%
+3. Database writes - 28%
+4. Email - 24%
+
+**Average Workflow Complexity**:
+- Simple (3-5 nodes): 42%
+- Medium (6-10 nodes): 38%
+- Complex (11+ nodes): 20%
+
+---
+
+## Quick Start Examples
+
+### Example 1: Simple Webhook → Slack
+```
+1. Webhook (path: "form-submit", POST)
+2. Set (map form fields)
+3. Slack (post message to #notifications)
+```
+
+### Example 2: Scheduled Report
+```
+1. Schedule (daily at 9 AM)
+2. HTTP Request (fetch analytics)
+3. Code (aggregate data)
+4. Email (send formatted report)
+5. Error Trigger → Slack (notify on failure)
+```
+
+### Example 3: Database Sync
+```
+1. Schedule (every 15 minutes)
+2. Postgres (query new records)
+3. IF (check if records exist)
+4. MySQL (insert records)
+5. Postgres (update sync timestamp)
+```
+
+### Example 4: AI Assistant
+```
+1. Webhook (receive chat message)
+2. AI Agent
+   ├─ OpenAI Chat Model (ai_languageModel)
+   ├─ HTTP Request Tool (ai_tool)
+   ├─ Database Tool (ai_tool)
+   └─ Window Buffer Memory (ai_memory)
+3. Webhook Response (send AI reply)
+```
+
+### Example 5: API Integration
+```
+1. Manual Trigger (for testing)
+2. HTTP Request (GET /api/users)
+3. Split In Batches (process 100 at a time)
+4. Set (transform user data)
+5. Postgres (upsert users)
+6. Loop (back to step 3 until done)
+```
+
+---
+
+## Detailed Pattern Files
+
+For comprehensive guidance on each pattern:
+
+- **webhook_processing.md** - Webhook patterns, data structure, response handling
+- **http_api_integration** - REST APIs, authentication, pagination, retries
+- **database_operations.md** - Queries, sync, transactions, batch processing
+- **ai_agent_workflow.md** - AI agents, tools, memory, langchain nodes
+- **scheduled_tasks.md** - Cron schedules, reports, maintenance tasks
+
+---
+
+## Real Template Examples
+
+From n8n template library:
+
+**Template #2947**: Weather to Slack
+- Pattern: Scheduled Task
+- Nodes: Schedule → HTTP Request (weather API) → Set → Slack
+- Complexity: Simple (4 nodes)
+
+**Webhook Processing**: Most common pattern
+- Most common: Form submissions, payment webhooks, chat integrations
+
+**HTTP API**: Common pattern
+- Most common: Data fetching, third-party integrations
+
+**Database Operations**: Common pattern
+- Most common: ETL, data sync, backup workflows
+
+**AI Agents**: Growing in usage
+- Most common: Chatbots, content generation, data analysis
+
+Use `search_templates` and `get_template` from n8n-mcp tools to find examples!
+
+---
+
+## Best Practices
+
+### ✅ Do
+
+- Start with the simplest pattern that solves your problem
+- Plan your workflow structure before building
+- Use error handling on all workflows
+- Test with sample data before activation
+- Follow the workflow creation checklist
+- Use descriptive node names
+- Document complex workflows (notes field)
+- Monitor workflow executions after deployment
+
+### ❌ Don't
+
+- Build workflows in one shot (iterate! avg 56s between edits)
+- Skip validation before activation
+- Ignore error scenarios
+- Use complex patterns when simple ones suffice
+- Hardcode credentials in parameters
+- Forget to handle empty data cases
+- Mix multiple patterns without clear boundaries
+- Deploy without testing
+
+---
+
+## Summary
+
+**Key Points**:
+1. **5 core patterns** cover 90%+ of workflow use cases
+2. **Webhook processing** is the most common pattern
+3. Use the **workflow creation checklist** for every workflow
+4. **Plan pattern** → **Select nodes** → **Build** → **Validate** → **Deploy**
+5. Integrate with other skills for complete workflow development
+
+**Next Steps**:
+1. Identify your use case pattern
+2. Read the detailed pattern file
+3. Use n8n MCP Tools Expert to find nodes
+4. Follow the workflow creation checklist
+5. Use n8n Validation Expert to validate
+
+**Related Skills**:
+- n8n MCP Tools Expert - Find and configure nodes
+- n8n Expression Syntax - Write expressions correctly
+- n8n Validation Expert - Validate and fix errors
+- n8n Node Configuration - Configure specific operations
+
+## 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.
+- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.