build-workflow

name	build-workflow
description	Full 3-phase pipeline (Research → Write+Validate → Deploy+Test) for shipping an n8n workflow end-to-end. Wraps Etienne's `n8n-as-code:n8n-architect` skill for schema research + authoring, adds repo-scoped orchestration — community-template lookup, validate-push-test loop, mcpTrigger publish gate, execution inspection, Completion Report.
argument-hint	"Description of what the workflow should do"
user-invocable	true
allowed-tools	Read, Write, Edit, Grep, Glob, Bash(npx:*), Bash(grep:*), Bash(node:*), Bash(npm:*), Bash(find:*), Bash(cat:*), Bash(jq:*), Bash(mkdir:*)

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:

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); 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):

   npx n8nac pull <workflowId>
   

   Or create a new .workflow.ts file from scratch in Decorator-TS format.

2. 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:

   • Workflow names: [Trigger] Action - Target (e.g. [Webhook] Create Lead - Close CRM)
   • Node names: Verb + Object (e.g. Validate Input, Fetch Users, Send Alert)
   • File: <workflow-name>.workflow.ts in workflows/ (e.g. workflows/create-lead.workflow.ts)
   • Every workflow MUST include a sticky note documenting Purpose + Required Credentials
   • Inline node notes (visible on the canvas without opening the node) — useful for short "why this node exists" explanations:

     @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:

   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.

3. Validate locally — single source of truth:

   npx n8nac skills validate workflows/<name>.workflow.ts --strict --json
   

   Fix any errors → re-validate. Do not push with errors.

4. Push + verify in one call:

   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 run Phase 2. A workflow is only complete once an execution has been inspected (success or Class-A error reported to the user).

Step 0 — Trigger classification (automatic, runs before path selection)

1. npx n8nac test-plan <workflowId> --json
   

   Extract triggerType, testable, suggestedPayload. Reuse this result in Path A/B — do NOT call test-plan again.

2. Check the local .workflow.ts for @n8n/n8n-nodes-langchain.mcpTrigger:

   grep -l "mcpTrigger\|n8n-nodes-langchain.mcpTrigger" workflows/<name>.workflow.ts
   

   Set HAS_MCP_TRIGGER = true/false.

3. Routing:

   • HAS_MCP_TRIGGER=true → Path D (manual publish notice) added on top of A or B
   • triggerType ∈ {webhook, chat, form} → Path A
   • triggerType ∈ {schedule, manual, errorTrigger} → Path B
   • Unknown triggerType → log warning, fall back to Path B (manual UI test)

Path A — HTTP-testable triggers (webhook, chat, form)

n8nac test calls the test URL (/webhook-test/) — no activation needed.

1. Check credential presence:

   npx n8nac workflow credential-required <workflowId>
   

   • Exit 0: all present → proceed
   • Exit 1: credentials missing → inform user, do not block

2. Live test (use suggestedPayload from Step 0):

   # POST/body webhooks (default):
   npx n8nac test <workflowId> --data '<suggestedPayload>'
   
   # GET/HEAD webhooks (workflow reads $json.query):
   npx n8nac test <workflowId> --query '<suggestedPayload>'
   

   If the user provided specific test data in $ARGUMENTS, use that instead.

3. On Class A error (exit 0): inform user about missing credentials/model — do not block.

4. On Class B error (exit 1): fix workflow → re-validate → re-push (--verify) → re-test (max 3 cycles).

5. Inspect execution results:

   npx n8nac execution get <executionId> --include-data
   

   For large outputs, slice with jq:

   npx n8nac execution get <executionId> --include-data | jq '.data.resultData.runData["<nodeName>"]'
   

   Use the node-level output data in the Completion Report.

Path B — Non-HTTP triggers (schedule, manual, errorTrigger, telegram)

n8nac cannot trigger these — manual test required. Stop the auto-pipeline here and prompt the user:

1. Check credential presence (same as Path A step 1).

2. Resolve the user-facing URL via the CLI (do not string-concat):

   npx n8nac workflow present <workflowId> --json
   

3. Display to user (prominent), using the URL from step 2:

   ⚠️  MANUAL TEST REQUIRED — non-HTTP trigger
   
   Open n8n UI:  <url from workflow present>
   Click:        "Execute Workflow" button (top right)
   Then report back: execution-id (visible in the executions panel)
   

4. Once the user reports an execution-id, inspect results:

   npx n8nac execution get <executionId> --include-data
   

   Check status, node outputs, error messages.

5. On error: fix workflow → re-validate → re-push (--verify) → ask user to re-execute in UI (max 3 cycles).

Path C — Activate for production (optional)

After successful test, if the user wants the workflow active (cron starts running, webhook becomes available on the production URL):

npx n8nac workflow activate <workflowId>

Activation failure = broken workflow (hard rule). If activate does not report active=true, the workflow has node issues — n8n refuses activation exactly then. NEVER ask the user to activate in the UI. Diagnose (most common: an external-service node without a credentials: block in @node({...}); then missing required params / broken expression), fix, re-validate, re-push (--verify), re-activate. Cross-check with a known-good trivial workflow to rule out the instance. This is a Class B error → normal fix loop (max 3 cycles).

Note: activate is NOT the same as publish for the new Two-Phase model — see Path D for mcpTrigger workflows.

Path D — Manual Publish required (when HAS_MCP_TRIGGER=true)

n8nac cannot publish drafts. After a successful push of an mcpTrigger workflow:

1. Resolve URL: npx n8nac workflow present <workflowId> --json
2. Display to user (prominent), using that URL:

⚠️  MANUAL PUBLISH REQUIRED — mcpTrigger detected

The MCP endpoint will return 404 until the workflow is published.

Open n8n UI:  <url from workflow present>
Click:        "Publish" button
Confirm in the Completion Report once done.

Reminder: npx n8nac push writes a new draft. The previously-published version stays live, but its MCP endpoint may diverge from the new draft. Each push to an mcpTrigger workflow requires a fresh UI publish.

Gate: Execution status is success or Class A error reported to user. Maximum 3 fix cycles.

Completion Report

## Workflow deployed and verified

**Name:** [Workflow Name]
**ID:** [n8n workflow ID]
**URL:** [from `npx n8nac workflow present <id> --json`]
**Location:** workflows/<name>.workflow.ts
**trigger_type:** [webhook | schedule | manual | mcpTrigger | ...]
**test_path_used:** [Path A (auto) / Path B (manual UI) / Path D-extended]

**Live test result:**
- execution_id: [ID]
- execution_status: [success / error-class-A / error-class-B]
- Nodes executed: [list with status per node]
- output_sample: [key fields from last node, via `n8nac execution get --include-data`]

**MCP Access:** (only when mcpTrigger is present)
- mcp_endpoint: [URL]
- manually_published: yes / no — user confirmation required

**Files created:**
- workflows/<name>.workflow.ts

Error Recovery

Phase	Error	Action
0	npx n8nac skills node-info returns empty for a community node	Run Stage 3 (npm extraction, see /n8n-autopilot:pull-schemas) → rebuild index → read from schemas/nodes/
0	Schema-research stuck on parameter ambiguity	Defer to n8n-as-code:n8n-architect skill — it has authoritative rules for resource/operation discriminators
1	Local validation fails	Fix code → re-validate
1	Push fails (conflict)	npx n8nac list → npx n8nac resolve <id> → retry
1	Push fails (archived)	Workflow is archived → read-only. Do not iterate — inform user: unarchive in n8n UI or create a new workflow
1	Verify fails (remote mismatch)	Re-push → re-verify
2A	Class A error (exit 0)	Report missing credentials to user — do not iterate
2A	Class B error (exit 1)	Fix workflow → re-validate → re-push (--verify) → re-test (max 3 cycles)
2B	Manual UI execution fails	npx n8nac execution get <id> --include-data for error details → fix → re-push → ask user to re-execute