build-workflow

Build Workflow (Full Pipeline)

Take a natural-language description and ship it as a verified live execution on n8n. All three phases are mandatory. The skill is only complete after a successful execution has been inspected and reported.

Companion plugin required. This skill leans on n8n-as-code:n8n-architect (from the n8nac-marketplace plugin by Etienne Lescot) for schema research, authoring rules, and n8n best practices — installing n8n-autopilot without the companion plugin will work but you will miss the shared knowledge base. Install both:

```bash

claude plugin marketplace add EtienneLescot/n8n-as-code

claude plugin install n8n-as-code@n8nac-marketplace

```

Tools — all CLI

n8n-autopilot drives everything through the CLI (npx n8nac …) — use the table below. Since n8nac 2.4 a working MCP server exists (n8nac mcp, plus the read-only native-mcp assist against the instance's own MCP endpoint — see [docs/MCP.md](../../docs/MCP.md)); it complements research and execution inspection but does NOT replace the CLI pipeline here: authoring stays .workflow.ts + push, and live tests stay n8nac test (binary/file payloads NEVER go through MCP).

| Command | Role | |---------|------| | npx n8nac skills examples search "<q>" / info <id> / download <id> | Community-template lookup (7000+ from n8nworkflows.xyz) — always Step 0 | | npx n8nac skills search "<q>" / node-info <name> --json / node-schema <name> --json | Node discovery + exact TypeScript defs from local schemas | | npx n8nac skills related "<q>" / guides "<q>" | Alternative nodes + tutorials | | npx n8nac skills validate <file> --strict --json | Local workflow validation | | npx n8nac push <file> --verify | Deploy + remote-state verification in one call | | npx n8nac test-plan <id> --json | Infer triggerType + suggestedPayload before testing | | npx n8nac test <id> --data '...' | HTTP-trigger live test (webhook/chat/form) | | npx n8nac execution get <execId> --include-data | Inspect execution output | | npx n8nac find <q> --json --remote | Search existing remote workflows | | npx n8nac workflow present <id> --json | Resolve the user-facing n8n URL — never string-concat <host>/workflow/<id> | | npx n8nac workflow credential-required <id> | Check credential readiness (exit 0 = all present, exit 1 = missing) |

Limits: n8nac test cannot fire schedule/manual/errorTrigger workflows (user runs "Execute Workflow" in the n8n UI). n8nac cannot publish drafts (mcpTrigger workflows need manual UI publish).

Input

$ARGUMENTS = natural-language description of the workflow. Extract:

• Trigger type: webhook, schedule, error, manual, chat, telegram
• Action: what the workflow does
• Target: which service/API is involved
• AI components: agent, model, memory, tools?
• Test data: what input should the live test use?

If $ARGUMENTS is empty, ask the user before proceeding.

Pipeline

Phase 0 — Research

Goal: Know exact node types, parameter names, and SDK patterns before writing code. Delegate schema-research details to the companion n8n-architect skill — it owns Schema-First Research, Workflow Authoring Rules, AI/LangChain rules, Common Mistakes.

Step 0 — Community-template lookup (MANDATORY before any node-by-node work):

npx n8nac skills examples search "<2-3 keywords from the description>" --json

Inspect top hits with npx n8nac skills examples info <id>. If a template matches the requested workflow by ≥70 % (same trigger family + same target service + comparable transformations), download it as the starting point:

npx n8nac skills examples download <id>

Then jump to Phase 1 step 1 with the downloaded file as the seed and only run Steps 1–2 below for nodes you add or change. Adapting an existing template is cheaper, less hallucination-prone, and lands on a community-proven pattern.

Step 1 — Node discovery (CLI-only):

npx n8nac skills search "<service>" --json     # find candidate nodes
npx n8nac skills node-info <type> --json       # exact parameters, credential keys, typeVersion
npx n8nac skills related "<service>" --json    # alternatives + nearest docs

For AI agents/memory/vector stores also check npx n8nac skills guides "<topic>".

Step 2 — Code-Node specifics (only if the workflow uses Code nodes):

• Skill n8n-code-javascript covers $input / $json / $node / $helpers.httpRequest() / DateTime (Luxon) / top mistakes
• Skill n8n-code-python covers _input / _json / standard library only

Step 3 — Find similar existing workflows (optional):

npx n8nac find <query> --json --remote

Gate: Do not proceed to Phase 1 without verified parameter names for every node. Never guess — wrong keys are silently ignored by n8n at runtime.

Missing schema? If npx n8nac skills node-info <type> returns empty or not-found for a community node:

1. Look up the npm package name in docs/COMMUNITY_NODES.md (Package column)

2. Run Stage 3 extraction immediately (see /n8n-autopilot:pull-schemas skill) for that package

3. Rebuild schemas/_index.json

4. Then re-run skills node-info — or read the cached schema directly from schemas/nodes/

A missing schema is always recoverable via Stage 3.

Phase 1 — Write + Validate

1. Pull the closest existing workflow as starting point (optional, only if Step 0 / Step 3 surfaced a useful one):

``bash npx n8nac pull <workflowId> ` Or create a new .workflow.ts` file from scratch in Decorator-TS format.

1. Write workflows/<name>.workflow.ts using Decorator-TS format. The companion n8n-architect skill documents the full authoring rules — these conventions are repo-specific additions on top:
2. Workflow names: [Trigger] Action - Target (e.g. [Webhook] Create Lead - Close CRM)
3. Node names: Verb + Object (e.g. Validate Input, Fetch Users, Send Alert)
4. File: <workflow-name>.workflow.ts in workflows/ (e.g. workflows/create-lead.workflow.ts)
5. Every workflow MUST include a sticky note documenting Purpose + Required Credentials
6. Inline node notes (visible on the canvas without opening the node) — useful for short "why this node exists" explanations:

``typescript @node({ name: 'Filter Inactive Users', type: 'n8n-nodes-base.filter', notes: 'Removes users with status != active before CRM sync', notesInFlow: true, // shows the note on the canvas position: [500, 300] }) ` notesInFlow: true without notes` has no effect.

• Every webhook-triggered workflow MUST include a Respond to Webhook node — a webhook without a response will hang and time out for the caller.

> mcpTrigger rule: If the workflow uses @n8n/n8n-nodes-langchain.mcpTrigger, > always set availableInMCP: true explicitly in the @workflow settings block: > ``typescript > settings: { > executionOrder: "v1", > callerPolicy: "any", > availableInMCP: true, // required — prevents n8n API bug #25987 from resetting to false > } > ` > The PreToolUse hook (ensure-mcp-trigger-setting.sh) auto-fixes false → true` and warns > when the field is missing entirely, but setting it explicitly here is the canonical source of truth.

1. Validate locally — single source of truth:

``bash npx n8nac skills validate workflows/<name>.workflow.ts --strict --json `` Fix any errors → re-validate. Do not push with errors.

1. Push + verify in one call:

``bash npx n8nac push workflows/<name>.workflow.ts --verify ` --verify` fetches the workflow from n8n after push and validates it against the local schema. On mismatch: re-push. On success: proceed to Phase 2.

Gate: Local validation passes + push succeeds + verify passes. Fix and retry if needed.

Phase 2 — Execute + Test (MANDATORY)

**After every successful push, ALWAYS r