/workflow-architect

name: workflow-architect
description: Design production-grade n8n workflows from requirements. Use this skill whenever the user wants to build, design, architect, or plan an n8n workflow or automation — including phrases like "build me a workflow", "design an automation", "create an n8n flow", "how should I structure this in n8n", or any request involving connecting services (webhooks, APIs, databases, LLMs, email, WhatsApp, Stripe, Google Sheets, etc.) through n8n. Also use when the user describes a business process and wants it automated. Always use this skill before generating n8n workflow JSON or recommending node structures — do not rely on memory of n8n node names or expression syntax.

n8n Workflow Architect

You are designing a **production n8n workflow**, not a demo. The workflow must survive real data, real failures, and real volume.

Core principles (apply every time)

1. **Real node names, not guesses.** n8n is strict about capitalization and spacing. Use `Google Sheets` not `Googlesheets`. `HTTP Request` not `HttpRequest`. `Webhook` not `webhook trigger`. If unsure, say so — don't invent.

2. **Expression syntax is `={{ $json.field }}`.** The leading `=` marks the whole field as an expression. Without it, n8n treats the value as a literal string. This is the #1 hallucination source.

3. **Every external call needs an error branch.** Wrap API calls in an `IF` or use `continueOnFail: true` + a downstream `IF` that checks `{{ $json.error }}`. Never assume third parties don't fail.

4. **Idempotency by default.** If the workflow could be retriggered (webhook, cron, polling), include a checkpoint — a MySQL/Postgres lookup on a natural key, or a `Google Sheets` row check. Reference the `mysql-checkpointing` skill for the pattern.

5. **Sub-workflows for reuse.** If logic exceeds ~8 nodes or is called from multiple places (e.g., error handling, notifications), extract into an `Execute Workflow` sub-workflow.

Workflow design process

Follow these steps in order. Skipping steps produces demo-quality output.

Step 1: Clarify the trigger

Ask (or infer) exactly ONE trigger type:

| Trigger | Use when | |---|---| | `Webhook` | External system pushes events (Stripe, Meta, custom APIs) | | `Schedule Trigger` | Recurring jobs (daily reports, hourly polls) | | `Manual Trigger` | Admin-triggered, testing | | `Form Trigger` | User-facing intake | | `Chat Trigger` | Conversational agents | | `Execute Workflow Trigger` | Called by another workflow |

Webhooks in production need: signature verification (HMAC), idempotency key extraction, and a 200 response within 3s (use `Respond to Webhook` early, process async).

Step 2: Map the happy path

Draft the node sequence as a numbered list BEFORE writing JSON. Each node gets:

• Node type (exact n8n name)
• Purpose (one sentence)
• Key config (the one or two parameters that matter)

Example:

1. Webhook (POST /stripe-events) — receives Stripe events
2. Code — verify HMAC signature against STRIPE_SIGNING_SECRET header
3. IF — branch on signature valid
4. Respond to Webhook — return 200 immediately (no payload)
5. MySQL — SELECT from processed_webhooks WHERE event_id = {{ $('Webhook').item.json.body.id }}
...

Step 3: Add error paths

For EACH external call node, answer:

• What failure modes exist? (timeout, 4xx, 5xx, rate limit, malformed response)
• What's the recovery? (retry with backoff, fallback vendor, dead-letter queue, alert)

Common patterns:

• **Retry with backoff**: `Wait` node (exponential: 2^n seconds) → loop back via `Execute Workflow` calling itself with a retry counter
• **Fallback vendor**: `IF` on error → alternative vendor node (e.g., WhatsApp fails → Twilio SMS)
• **Dead letter**: Error → `MySQL` insert into `failed_jobs` table with payload + error message

Step 4: Wire the LLM steps correctly

If using LLMs (Claude, OpenAI, Groq), reference the `chain-llm-pattern` skill for multi-step reasoning. Key rules:

• Use the **LangChain nodes** (`AI Agent`, `Basic LLM Chain`, `Information Extractor`) for structured outputs, NOT raw `HTTP Request` to the LLM API — the LangChain nodes handle JSON parsing, retries, and token accounting.
• For JSON outputs, use `Information Extractor` with an explicit schema, not "please return JSON" in a system prompt.
• Set `maxTokens` explicitly — n8n defaults can silently truncate.
• Pin an example input during development (right-click node → "Pin Data") so downstream nodes have stable schemas to build against.

Step 5: Output

Produce the workflow as valid n8n workflow JSON. Structure:

{
  "name": "Workflow Name",
  "nodes": [...],
  "connections": {...},
  "settings": { "executionOrder": "v1" }
}

Every node needs `id` (UUID), `name` (unique in workflow), `type` (exact n8n type), `typeVersion` (integer), `position` ([x, y]), and `parameters` (node-specific config).

Use `typeVersion: 1` as a safe default unless you know a newer version is required.

For connections, `main` is the default output — branching nodes (`IF`, `Switch`) have multiple output indices.

If the user asked for a description rather than importable JSON, produce a clean numbered list matching Step 2 format and offer to generate JSON.

Anti-patterns to refuse

Do NOT produce workflows that:

• Store credentials inline (always use n8n credential references: `{{ $credentials.apiKey }}`)
• Poll an API every minute when a webhook exists
• Use `Function` nodes for logic that has a purpose-built node (e.g., `Split In Batches`, `Merge`, `Item Lists`)
• Return raw LLM output to end users without validation
• Assume a list/array is always populated (always handle empty arrays)

When the user's request is vague

Don't guess — ask ONE consolidated clarifying question covering:

• Trigger source + frequency
• External services involved
• What happens on failure (silent drop? alert? retry?)
• Data destination

One question, not five. Move fast.

Reference files

• `references/node-catal