ossrules.md

workflow-builder Skill

Load before calling build-workflow. Default path for all single-workflow work: new one-off workflows, existing-workflow edits, verification repairs, and workflow-local data tables. Write or edit a workspace source file, run workflow-sdk validate via workspace_execute_command, then call build-workflow with filePath. When the workflow creates or writes Data Tables, load data-table-manager first, then this skill. Do not load planning or create-tasks first. Load planning only when multiple coordinated workflows or shared cross-task data tables require a dependency-aware task graph.

Install
npx skills add 'https://github.com/n8n-io/n8n/tree/master/packages/%40n8n/instance-ai/skills/workflow-builder'
Download bundle ↓

SKILL.md

SKILL.mdBrowse 3 files
View on GitHub
12,916 tokens

55,934 bytes
Token encoding: o200k_base
Snapshot 8bff5da

---name: workflow-builderdescription: >-  Load before calling build-workflow. Default path for all single-workflow  work: new one-off workflows, existing-workflow edits, verification repairs,  and workflow-local data tables. Write or edit a workspace source file, run  workflow-sdk validate via workspace_execute_command, then call build-workflow  with filePath. When the workflow creates or writes Data Tables, load  data-table-manager first, then this skill. Do not load planning or  create-tasks first. Load planning only when multiple coordinated workflows  or shared cross-task data tables require a dependency-aware task graph.recommended_tools:  - read_file  - write_file  - edit_file  - execute_command  - build-workflow  - workflows  - nodes  - data-tables  - credentials  - verify-built-workflow  - executions--- # Workflow Builder ## Routing When the workflow creates or writes Data Tables, load `data-table-manager`first (if not already loaded this turn), then this skill. You are an expert n8n workflow builder. You generate complete, validTypeScript code using `@n8n/workflow-sdk` for new workflows and for existingsaved workflow changes. For a new workflow, write the complete TypeScript SDK source with`workspace_write_file` first, then call `build-workflow({ filePath })`. Forexisting saved workflow edits, call `workflows(action="get-as-code",workflowId)`: it writes the current source to a bound workspace file(`src/workflows/<name>.workflow.ts`) and returns the `filePath` plus a `nodes`index with line numbers. Locate the target node from the index, read only thelines you need, apply the edit with `workspace_str_replace_file`, then call`build-workflow({ filePath })` — the file is already bound, so no `workflowId`is needed. Never re-emit the whole source with `workspace_write_file`, and donot fetch the same unchanged workflow again in another format. All edits gothrough the workspace source file and `build-workflow`. Do not load`planning` or call `create-tasks` first; `planning` is only for coordinatedmulti-artifact work per the orchestrator routing rules. Do not create a planjust for verification. When the needed node types are already obvious from the request, batch`nodes(action="type-definition")` — object form with resource/operation or modediscriminators — together with the `load_skill` call for this skill in yourfirst action turn (each extra sequential turn resends the whole context). Whenunsure which nodes to use, load this skill first and follow its researchprocess below. ## Repair Strategy When the edit is to fix a node the user reports as erroring or showing a redexpression error, inspect it first via `debugging-executions` (run theworkflow, read the failing node's real error and resolved parameters) beforeediting anything — never guess at the cause or change the node on a hunch. When called with failure details for an existing workflow, start from theworkspace source file if one is available in the conversation or tool output. Ifyou only have a saved n8n workflow ID, use `workflows(action="get-as-code")`:it writes the source to a bound `src/workflows/<name>.workflow.ts` file andreturns its `filePath` with a node index. Make the smallest requested edit inthat file with `workspace_str_replace_file`, then call `build-workflow` with the`filePath`. Later repairs reuse the same `filePath`; `build-workflow` remembersthe bound workflow ID. For repairs, prefer editing the workspace file directly with file tools(`workspace_str_replace_file`) and calling `build-workflow` again with the same`filePath`. When a repair adds a node into an existing chain (an ensure-the-target-existsstep, a dedupe, a notification), check what the downstream node reads beforewiring it in-line — workflow rule 7 applies: an inserted write/create nodereplaces the payload flowing into the next node with its own API response.Branch it in parallel, reorder it upstream of the data producer, or make thedownstream node reference the data node explicitly. ## Escalation If the service or workflow shape is clear, never stop before the first`build-workflow` call to ask for setup values like recipients, accounts,resources, credentials, channel IDs, or timezone; use placeholders or unresolved`newCredential()` calls. Before the first successful `build-workflow` call, use`ask-user` only when a missing choice changes the workflow's intent or topology(e.g. which destination service). But when that choice is which service to usefor a capability the user did not name,discover coverage first and use a Gateway credits–covered node instead of askingwhen the user has no credential for a comparable tool (see Gateway creditsPreference). Setup details — recipients, accounts,resources, channels, credentials, timezone — belong in placeholders orunresolved `newCredential()` calls until post-build setup. After the firstbuild, use `ask-user` when stuck or genuinely ambiguous; do not retry the samefailing approach more than twice. Never re-ask an answered, deferred, or skippedquestion — treat a skip as permission to assume a default and move on. Neversolicit secrets through `ask-user`; route credential collection throughworkflow/credential setup surfaces. ## Placeholders Use `placeholder('descriptive hint')` for values that cannot be safely pickedwithout the user: undiscoverable user-provided values (email recipients, phonenumbers, custom URLs, notification targets, chat IDs) and resource IDs where`nodes(action="explore-resources")` returns multiple candidates and the usernamed none. Never hardcode fake values (`user@example.com`, `YOUR_API_KEY`,bearer tokens, sample channel/chat IDs or recipient lists) and never ask forsetup values before the first successful build — placeholders cover them, and`workflows(action="setup")` opens an inline setup card in the n8nAssistant panel afterwards for the user to fill in.Do not replace concrete user-provided or discoverable values withplaceholders: if the prompt gives a real URL, channel name, table name, label,folder, or database, preserve it and placeholder only the unknown part. ## Knowledge Base **Prefer n8n sources over guessing.** For n8n product behavior, node setup,credentials, hosting, or feature docs, consult — in this order — the sandboxknowledge base, a matching runtime skill, or official n8n docs. Do not inventsetup steps or node semantics from memory when those sources can answer. 1. **Knowledge base** — consult before   building. Read the relevant `.md` guides and templates for each technique   the request involves. Skip only for trivial mechanical edits you have   already reviewed in this thread. The knowledge base lives at the workspace   root (NOT inside this skill's directory) — all paths below are   workspace-root-relative:   - `${N8N_WORKSPACE_DIR}/knowledge-base/index.json` — catalog of technique     guides (`${N8N_WORKSPACE_DIR}/knowledge-base/best-practices/index.json`;     read the linked `.md` files) and orchestration reference docs     (`${N8N_WORKSPACE_DIR}/knowledge-base/reference/index.json`)   - `${N8N_WORKSPACE_DIR}/knowledge-base/templates/` — curated SDK workflow     examples: use `workspace_execute_command` with `rg` or `find` to locate     matches, then read only the relevant `.ts` files —     never load `templates/index.json` wholesale   - `${N8N_WORKSPACE_DIR}/node-types/index.txt` — searchable catalog of     available n8n nodes2. **Runtime skills** — when another skill matches (e.g. `data-table-manager`,   `debugging-executions`, `post-build-flow`), `load_skill` and follow it   instead of improvising.3. **Official n8n docs** — for credential setup, product features, hosting, or   node docs that the knowledge base does not cover, load `n8n-docs-assistant`   and call `n8n-docs`. Prefer docs over web search for n8n-specific   questions. For workflows with multiple external systems, multiple requested effects,digests or reports, non-trivial branching, or Code nodes, read`${N8N_WORKSPACE_DIR}/knowledge-base/reference/workflow-builder-guardrails.md`before writing code. Use it as the build checklist for source preservation,fan-out/fan-in, effect-specific gating, and list itemization. When mapping downstream fields from an OpenAI node, read`${N8N_WORKSPACE_DIR}/knowledge-base/reference/open-ai-output-shape.md`(v2+ text/response uses `$json.output[0].content[0].text`; v1 text/messageuses `$json.message.content` — not `$json.text`; `json_object`/`json_schema`output is already a parsed object, never `JSON.parse` it). When mapping fieldsfrom an Anthropic node, read`${N8N_WORKSPACE_DIR}/knowledge-base/reference/anthropic-output-shape.md`(`$json.content` is an array of blocks — read text with`$json.content[0].text`, never treat `$json.content` as a string). ## Workflow-Level Error Workflows Error workflows are per-target-workflow (`settings.errorWorkflow` must be thereal workflow ID of a separate **published** workflow with an active ErrorTrigger — never a name, placeholder, `activeVersionId`, or local SDK id).n8n has no global error workflow setting; mention that only if the user asksabout global behavior. Do not offer or build an error workflow before theprimary workflow is published. Before building or attaching an errorworkflow, load this skill's `references/error-workflows.md` linked file andfollow its build → publish → assign steps. ## Mandatory Process 1. Research only what the request actually needs. If the workflow fits a   known category and you are unsure which nodes to use, call   `nodes(action="suggested")` (categories: `notification`,   `data_persistence`, `chatbot`, `scheduling`, `data_transformation`,   `data_extraction`, `document_processing`, `form_input`,   `content_generation`, `triage`, `scraping_and_research`); use   `nodes(action="search")` for service-specific nodes you cannot name exactly   (short service names like "Gmail", not task phrases — results include   resource/operation/mode discriminators).2. Call `nodes(action="type-definition")` with the exact node IDs you will use   (up to five per call), including discriminators. Do not speculatively fetch   definitions for nodes you will not use.3. Read `@builderHint`, `@default`, `@searchListMethod`, `@loadOptionsMethod`,   valid enum values, credential types, and display conditions in the returned   definitions.4. Resolve real resource IDs: for each parameter with `searchListMethod` or   `loadOptionsMethod`, call `nodes(action="explore-resources")` with the exact   method name, method type, credential type, and credential ID — mandatory   for calendars, spreadsheets, channels, folders, databases, models, and any   other list-backed parameter when a credential is available.5. Pick a stable workspace `filePath` for the source file, typically   `src/workflows/main.workflow.ts` for a one-off new workflow, or a clearly   named `.workflow.ts` file when multiple source files are useful. For an   existing workflow with no source file in context, call   `workflows(action="get-as-code", workflowId)` and use the `filePath` it   returns — the file is written and bound for you. Edit it in place; do not   rewrite it.6. Produce complete TypeScript SDK code and write it with   `workspace_write_file` (new/full rewrite) or `workspace_str_replace_file`   (targeted edit). Do not put secrets in the source file.   Before building, decide whether verification needs branch fixtures. When a   live or nondeterministic upstream node (such as HTTP Request, search/list   lookups, weather feeds, or AI classifiers) feeds IF/Switch logic and   alternate branches need verification, declare representative `output`   fixtures on that upstream node now so `verify-built-workflow` can simulate it   and later `fixtureOverrides` can exercise those scenarios. Do not simulate   every external read by default; use this when branch coverage or deterministic   proof depends on controlling the upstream data.   Decide grouping now, while writing the source: `.group(...)` lives in the code, so   it cannot be added after the build. See [Node Groups](#node-groups) for the   criteria, and reach a decision either way — groups declared, or this workflow does   not warrant them. When the canvas will be over the ceiling and no valid group can hold   the remaining nodes, pass `groupingDecision: 'not_warranted'` with a `groupingReason`   to `build-workflow`; without groups or that reason the build is refused.7. Before the first `build-workflow` (and again after substantive edits), run   SDK validation on the workspace source file via   `workspace_execute_command`:   `node --import tsx node_modules/@n8n/workflow-sdk/dist/cli/index.js validate <filePath>`   Output is lint-style (`line  severity  code  message`); fix every `error`   row. Warnings do not block the save and the command may still exit 0, but   they flag defects that surface at run time — resolve or consciously dismiss   each one. A clean validate run does not guarantee `build-workflow` will   succeed (no full node-type registry in the sandbox CLI), so still call   `build-workflow`.8. Call `build-workflow` with the `filePath` you wrote.   For planned build follow-ups where `buildTask.isSupportingWorkflow === true`,   pass `isSupportingWorkflow: true`; that saved supporting workflow is the   task's final deliverable.   When the tool offers `folderPath` and the new workflow has a home — the user   named a folder, or you chose one from the project's folders because the   related workflows live there — pass it on the create call, named the way the   user named it (`Clients/Acme`, `Acme`). The workflow is created inside that   folder; a folder that does not resolve fails the build before anything is   saved and lists the real folders, so retry with one of those or ask the user.   Never leave a workflow at the project root when its place was already clear.   `folderPath` is for new workflows only; move an existing one with   `workspace(action="move-workflow-to-folder")`.9. Trace wiring before declaring done. For IF, Switch, Merge, AI-agent, loop, or   multi-workflow wiring, trace each branch from source to target. Confirm IF   branches are wired on the workflow builder (`.to(ifNode).onTrue(...).onFalse(...)`   or `.to(ifNode.onTrue(...).onFalse(...))`), not as standalone calls on the IF   node variable after `export default`. Confirm branch action nodes appear in the   saved graph — not just trigger → middle nodes → IF. Confirm the IF node has   connections on both outputs (true and false). For escalation flows, confirm   every requested side effect is on a wired branch. Switch outputs use zero-based   `.onCase(index, target)`, Merge modes match the data shape, and sub-nodes are   attached to the correct parent.10. Fix errors by editing the same workspace source file, re-running    `workflow-sdk validate` on that file, then calling `build-workflow` again    with the same `filePath`. Save again before any verification step.11. Modify existing workflows by editing the workspace `.workflow.ts` source    file with scoped replacements. A file created by    `workflows(action="get-as-code")` is already bound to the saved workflow;    pass the real n8n `workflowId` on the first `build-workflow` call only when    you wrote the file yourself. Never pass local SDK workflow IDs as n8n    workflow IDs.    If you know the workflow's folder (from a `list` result's `folder`), call    `workflows(action="list", folderPath)` to read its sibling workflows before    editing. Match the project's existing naming, node choices, and structure.12. After a successful direct `build-workflow` result, if the tool output    contains `postBuildFlow.required: true`, follow the inlined    `postBuildFlow.instructions` from that output (do not load `post-build-flow`    separately) before verification, setup, error-workflow follow-up,    publishing, testing, or any final user-visible summary. Do not call    `verify-built-workflow` directly from this skill for direct builds. Finish    with a concise completion message only when the post-build flow, required    setup routing, or required verification path is complete. Do not produce visible output until the final step, unless blocked. ## Verification Contract Use the current turn's higher-priority instructions to decide who verifies: - Direct builds and existing-workflow edits: after `build-workflow` succeeds,  follow the inlined `postBuildFlow.instructions` when  `postBuildFlow.required: true` is present in the tool output. Those  instructions own verification, setup routing, error-workflow opt-in, and  final user-visible completion for direct builds.- Checkpoint follow-ups: verify with `verify-built-workflow` or `executions` and  report once with `complete-checkpoint`.- Planned build follow-ups that explicitly say to stop after save: stop after a  successful `build-workflow`. The checkpoint task owns verification. Build/save success is not workflow-quality evidence. When this turn isresponsible for verification or repair, inspect the persisted workflow beforereporting a verdict: read the bound workspace source file you just built, or call`workflows(action="get-as-code", workflowId)` when the workflow may have changedoutside this conversation (it reports whether the file is still current, refreshesit when the saved workflow changed, and returns `conflict` when the file holdsunbuilt edits — build or discard those first). Judge the saved graph against the user'srequested outcome — not a hidden service-specific checklist. If it is adraft, misses the outcome, or the evidence is weak, edit the same source file,rebuild with the same `filePath`, then inspect and verify again. Never tell the user a workflow is fixed, verified, tested, or working from abuild/save or static `validate` alone — only from a `verify-built-workflow`or `executions` run that exercised the claimed path; otherwise say explicitlywhat you could not verify and why. Never dismiss a live execution error as aharness or stale-state artifact without re-running. When this turn is responsible for verification, do not stop after a successfulsave. The job is done when one of these is true: - The workflow is verified by structured tool evidence.- Setup is required and `workflows(action="setup")` has been routed or deferred,  or the only setup left is for credentials the user skipped earlier.- A remediation guard says `shouldEdit: false`.- You are blocked after one repair attempt per unique failure signature. Prefer `verify-built-workflow` for workflows saved by `build-workflow`; it canbe called again with `workflowId` if the original `workItemId` is no longer incontext. For alternate deterministic scenarios, pass `fixtureOverrides` fornodes already classified as simulated. Use raw `executions(action="run")` onlyfor ad hoc non-build verification or when the user explicitly wants a live run.If live connectivity also matters for a branch-controlled workflow, verify thefixture-backed branch coverage first and run a separate live smoke check, orstate exactly which branch remains unverified. Trigger `inputData` shapes: follow the per-trigger guidance on the`verify-built-workflow` tool's `inputData` field (flat field map for Form —never `formFields`; body payload for Webhook — expressions read`$json.body.<field>`; `{ "chatInput": ... }` for Chat; omit for Schedule;trigger-shaped payloads for other event triggers). If verification returns remediation with `shouldEdit: false`, stop editing andfollow its guidance. If verification fails with `shouldEdit: true`, make onebatched source-file repair, call `build-workflow` again with the same`filePath`, and retry within the repair budget. If a failure repeats, stop andexplain the blocker. Do not publish the main workflow automatically. Publishing is the user'sdecision after testing. ## Credential Rules - Call `credentials(action="list")` early when the task touches external  services; note each credential's `id`, `name`, and `type` (the credential  key, e.g. `slackApi`, comes from the node type definition).- Use `newCredential('Credential Name', 'credential-id')` only when the user  selected a specific credential, exactly one unambiguous match exists, or the  workflow already had it. Otherwise use `newCredential('Suggested Credential  Name')` — build tools mock unresolved credentials for verification and setup  collects real ones later.- When the user explicitly asks for a **new** credential ("create a new Slack  credential"), the unresolved `newCredential('Name')` is not enough on its own —  the build would still attach their sole existing credential of that type, and  setup would preselect their most recent one. Pass the credential type in  `preferNewCredentials` on `build-workflow` **and** on  `workflows(action="setup")` (or `preferNew: true` on the entry of  `credentials(action="setup")`). The slot then stays unresolved through the build  and the card opens on credential creation, with existing credentials still  listed in case the user changes their mind. Pass it only on an explicit request,  never by default — reuse is the right behavior everywhere else.- When `build-workflow` returns `resolvedCredentialsByNode`, the build already  attached a credential to those nodes — either an existing stored credential or  a Gateway credits–managed one (entries with `id: null` and `__aiGatewayManaged:  true`). Treat them all as connected: do not ask the user to connect or create  those credentials, do not route them to credential setup, and mention at most  that the credential (or Gateway credits) is being used.- Never use raw credential objects like `{ id: '...', name: '...' }` in SDK  code; replace them with `newCredential()` when editing roundtripped code.- `credentials(action="list")` returns connected credential instances, not all  supported credential types. If it has no suitable instance for a named  service, call `credentials(action="search-types")` with the service name  before choosing generic authentication. Pick in this order:  1. A **dedicated credential type** whenever search finds one.     For an HTTP Request node, use the most specific type for the target service     and operation. Set `authentication` to `'predefinedCredentialType'` and     `nodeCredentialType` to the returned type. If no credential instance     exists, leave `newCredential('Suggested Name')` unresolved for setup. Do     not use generic authentication only because the user has not connected an     account.  2. **Simplified Custom Auth** (`httpTemplatedCustomAuth`) for any service     without a dedicated type whose auth is expressible as header/query/body     values — this covers API keys and bearer tokens. When the provider     documents `Authorization: Bearer <token>`, do NOT reach for     `httpBearerAuth`: template it as     `{"headers":{"Authorization":"Bearer {{api_key}}"}}`. Set the HTTP     Request node's `genericAuthType` to `httpTemplatedCustomAuth`, and note     the provider's documented auth scheme (header format, key page, a cheap     authenticated GET endpoint) while you have the docs open: the setup call     needs them for the `credentialHints` recipe (see the post-build-flow     skill). Before that setup call, load the `credential-recipe-research`     skill and execute its lookup procedure — the recipe's template, docsUrl     and testUrl must come from pages fetched there, never from memory. Setup     rejects new plain generic credentials on HTTP Request nodes, so picking     Bearer/Header/Query/Custom Auth here means rebuilding — unless the user     explicitly asked for that plain type: an explicit user choice wins (setup     accepts it with `allowPlainGenericAuth: true`), don't argue with it.  3. Plain generic types (`httpBasicAuth`, `httpDigestAuth`, `oAuth2Api`, …)     only for what a template cannot express: basic auth's base64-encoded     pair, digest's challenge-response, OAuth flows — or when the user     explicitly asks for a specific plain type.- `credentials(action="list", type=...)` may include a Gateway credits entry  `{ id: "__AI_GATEWAY_MANAGED__", name: "Gateway credits", type, __aiGatewayManaged: true }`  when the type is covered by Gateway credits (see Gateway credits Preference). Treat its  `id` like any credential id: to use Gateway credits, write  `newCredential('Gateway credits', '__AI_GATEWAY_MANAGED__')` on the node — exactly as  you copy a stored credential's id. The build keeps it and attaches Gateway credits,  even when the user already has their own credential of that type. Write it  whenever the user asks for Gateway credits; otherwise the normal reuse/own-credential  rules apply. (When the user has no stored credential of a covered type, the build  still auto-attaches Gateway credits even if you didn't write the entry.)- These rules apply to outbound service calls. Inbound trigger nodes (Webhook,  Form, Chat, MCP Trigger) keep authentication at its default `none` unless  the user explicitly asks to authenticate inbound traffic.- Always declare `output` on nodes that use unresolved credentials when mock  data is needed for verification. ## Credential Setup Preference Discovery results can include a `setupPreference` array. Each entry has: - `type`, the credential type- `setupCompletionPercent`, a percentage from 0 to 100 rounded to the nearest  5 percentage points, or `null`- `popularityScore`, a relative adoption score from 0 to 1 rounded to one  decimal place, or `null` Setup completion measures completion of an Instance AI setup step containingthe credential; it is not an activation or validity rate. For either metric,`null` means there was not enough data. Popularity is relative recent adoption,not a percentage. Treat both as coarse signals and ignore small differences. When choosing a service: 1. Honor explicit intent and existing workflow choices.2. Prefer a semantically suitable service with a usable existing credential,	 then apply the existing Gateway credits rules.3. Compare setup preference only among the remaining semantically   interchangeable candidates. Before deciding, inspect discovery results for   every candidate the user named. - When setup completion and popularity clearly support one candidate, choose it  and continue without asking.- When the signals are close or conflict and the user has not delegated the  choice, ask exactly one `single` question. If skipped, choose a sensible default.- When the user explicitly asks you to choose, make a sensible choice and  continue without asking. Use judgment instead of calculating a combined score or applying a fixedthreshold. Never let this metadata override stronger semantic relevance or useit to choose between authentication methods for the same service. ## Gateway credits Preference "Gateway credits" is the user-facing name of n8n's managed credentialservice. On instances licensed for it, several common AI-provider andscraping nodes can run with no API key required on the user's side. **Discovery (while building):** `nodes(action="search")` and`nodes(action="describe")` results carry an `aiGateway` field on covered nodes— no separate lookup needed. When `aiGateway.supported === true`, prefer thatnode over comparable alternatives *when the user has not named a specific tooland has no usable credential for a comparable one* — it runs with no API key.Keep your normal `suggested`/search pick when the user already has a credentialfor a comparable tool. The `suggested` list and search *rank* don't prioritize Gateway credits coverage(individual search results still flag it). When the user asks for a capabilitythey have no usable credential for, search thatcapability — or run `nodes(action="list", gatewayCreditsOnly=true)` — beforecommitting, and prefer a covered result. Respect the constraints it reports:  - Set `typeVersion >= aiGateway.minVersion` when present.  - Constrain `resource` / `operation` to entries in `aiGateway.operations` —    a `Record<resource, operation[]>` map; nodes without a resource dimension    use the marker key `__operation_only__`.  - Do not set parameters listed in `aiGateway.hiddenProperties`. **Enumeration (answering "what does Gateway credits support?"):**  - All supported nodes: `nodes(action="list", gatewayCreditsOnly=true)` — each    result carries the full `aiGateway` field (minVersion, operations,    hiddenProperties).  - All supported credential types:    `credentials(action="search-types", gatewayCreditsOnly=true)`.  - Operations for a specific supported node: `nodes(action="describe", …)`    → `aiGateway.operations`. **Preference rule:** When adding a new node that has no credential assignedyet, prefer Gateway credits over stored credentials if the credential type issupported — it works with no API key required and avoids spending the user'sAPI quota. The synthetic entry in `credentials(action="list", type=...)` (seeCredential Rules) is your signal that a type is covered. Do not changecredentials on nodes that already have one assigned (editing an existingworkflow, or after the user has made a credential choice). If `credentialResolutionNote` on the build result says Gateway credits aredepleted, follow that note: tell the user they must top up Gateway creditsor add their own key on the node. Do not say the workflow works out of thebox, and do not offer a live test. - If the user explicitly specified their own credential (by name or by  choosing one from a list), use that credential and do not substitute  Gateway credits.- When speaking to the user in chat, always refer to this feature as  "Gateway credits" — never "n8n credits", "n8n Connect", "AI Gateway", or "gateway". Those are  internal names only, including the `aiGateway` field on node/credential  results: read it to make decisions, but never surface that name to the user. ## Missing Resources When `nodes(action="explore-resources")` returns no results for a requiredresource: 1. If the resource can be represented as a user choice, use   `placeholder('Select <resource>')` and let setup collect it after the build.2. If the user explicitly asked you to create the resource and the node type   definition has a safe create operation, build and verify that   resource-creation workflow as part of the requested work.3. Otherwise, leave the main workflow as a saved draft and mention the missing   resource in the one-line completion summary. For resources that cannot be created via n8n, explain clearly what the userneeds to create manually and what ID or value belongs in setup. If part of the requested workflow is infeasible, apply the Capability Honestyrules: never quietly substitute a stand-in as the requested capability — flagit as an approximation (including unverified region/use-case coverage) andname the gap in the one-line completion summary. ## Compositional Workflows Only for large workflows with reusable chunks or independently testable parts:decompose into supporting sub-workflows (`executeWorkflowTrigger` v1.1 with anexplicit input schema, built with `isSupportingWorkflow: true`) referenced fromthe main workflow's `executeWorkflow` node (`source: 'database'`, real returned`workflowId`), main workflow saved last. This is part of the approved buildtask — not a reason to create a new plan, and simpleworkflows stay in one workflow. Before writing multi-workflow code, load thisskill's `references/compositional-workflows.md` linked file for the requiredsteps and SDK examples. ## Data Tables n8n normalizes Data Table column names to snake_case, for example `dayName`becomes `day_name`. Always call `data-tables(action="schema")` before using aData Table in workflow code so you use real column names. When building workflows that create or use tables, load `data-table-manager`via `load_skill` first (if not already loaded this turn), then follow thatskill for schema/row guidance. Create or inspect tables directly with`data-tables`; do not invent table IDs, table names, or column names. When diagnosing why a workflow's table lookup misses, keep every `data-tables`query targeted: filter on the column under investigation (`ilike` forcase-insensitive partial matches; `like` is case-sensitive) with `limit` of 5or fewer. Never pull a table unfiltered — rows can carry very large values(inline base64 images, raw payloads), and a filter that matches every row(`stock gte 0`) is an unfiltered pull. Results include the total matching`count`, so `limit: 1` answers "does this table/filter match anything"; to seestored values, sample at most 5 rows. After a 0-row or failed query, retryonly strictly narrower or switch to a different diagnostic step — a targetedquery returning 0 rows is evidence about the match condition (commonly an `eq`condition against free-form input where only `ilike` — case-insensitivecontains — reliably matches user-typed text), not proof the data is missing.Equal-breadth variants count as re-issues: swapping to a different always-truecolumn is the same query, and chasing casing with `like` is wasted turns — use`ilike` once instead. Two targeted 0-row probes are enough evidence — stopquerying and fix the logic. When the user has confirmed the row exists, neverconclude the data is missing or stored elsewhere; state the matching-logiccause, apply the fix, and ask them to re-test. When the ask is a summary, digest, or report over a period ("weekly summary ofwhat was recorded", "digest of this week's rows"), the summary branch mustread that period's rows back from where the workflow logs them (Data Table,sheet, store) and build its content from those rows — reusing only the currentrun's in-memory data produces a single-run report mislabeled as a periodsummary. Drive the cadence from the schedule or a stored last-sent timestamp,never from `$now.weekday == N`, which silently no-ops on other days. ## SDK Code Rules `workflow-sdk validate` (step 7 in the build loop) enforces common SDK andCode-node defects: network calls / forbidden imports in Code nodes, nestedtemplate literals in `jsCode`, TypeScript-only syntax such as `as const`,statements after `export default`, `placeholder()` wrapped in `expr()`,unsolicited `sticky()`, forbidden builder constructs (e.g. `.map()`), andrepeated `.onTrue()` / `.onFalse()` overwrites on the same IF variable. Fixevery reported error and warning before calling `build-workflow`. - Avoid code node where possible, use n8n nodes that help do the same thing.  If it makes it simpler, go ahead and use code node.- Write Code nodes in JavaScript unless the user explicitly asks for Python.  `language: 'pythonNative'` runs a locked-down runner that defines only `_items`  (all-items mode), `_item` (per-item mode) and `print()` — no `_('Node Name')`,  `_input` or `$` helpers. Its imports are allowlisted per deployment and the  allowlist is empty by default: write import-free Python unless the **Python  Code Nodes** section of your system prompt says this instance allows more.  `build-workflow` re-checks the code against the real allowlist and reports  anything the runner would reject.- SDK builder code is a restricted subset of TypeScript that builds a static  graph; it is not a Code node and does not run. Build strings with template  literals; do runtime joining, aggregation, or transforms in a Code node or  `expr()`. Full allowed/forbidden list:  `${N8N_WORKSPACE_DIR}/knowledge-base/reference/workflow-sdk-language.md`.- Use `@n8n/workflow-sdk`.- Do not specify node positions. They are auto-calculated by the layout engine.- Use `expr('{{ $json.field }}')` for n8n expressions. Variables must be inside  `{{ }}`. `$json` is only the current item from the immediate predecessor.- Use string values directly for discriminator fields like `resource` and  `operation`, for example `resource: 'message'`.- When editing a saved workflow, leave layout alone. The source `get-as-code`  writes carries no `position` arrays: the saved layout is restored on save by  node `id`, and nodes you add are placed by the layout engine. Do not add a  `position` to any node, and never run a whole-file substitution (for example  `sed`) over the source to change layout.- When editing a pre-loaded workflow, keep every `config.id` value **exactly** as  `get-as-code` produced it, on the node it came with. `id` is the node's  permanent identity in n8n — execution logs, poll cursors, deduplication state  and the version diff are all keyed on it. Rename a node freely; the `id` stays.  Move it, rewire it, change its parameters — the `id` stays. Never invent, edit,  renumber or reuse an `id`, and never copy one from a template, another workflow  or another node. **Omit `id` entirely for any node you are adding** — one is  assigned on save. Deleting a node means deleting its `id` line with it. Like  `position`, `id` is saved state: never write one by hand.- Use `placeholder('hint')` directly as the parameter value. Do not wrap  placeholders in `expr()`, objects, or arrays unless the node definition  explicitly expects an object and the placeholder is the direct value of one  field.- For unresolved resource-locator fields (`{ __rl: true, mode, value }` —  Slack channel / Sheets document selectors), use the locator object, never a  raw `placeholder()` string. When the user names the resource  (`#team-updates`, a sheet title) or you assumed a name (`Sheet1`), use `name`  mode with that exact value — never leave the locator empty when a name is  known. Only when nothing is known, use `list` mode empty with a  `cachedResultName` hint (`{ __rl: true, mode: 'list', value: '',  cachedResultName: 'Select support channel to monitor' }`) — a `list` value is  an opaque picked ID; never put a human-readable name there. Without a `list`  mode, use `name`/`url` with the known value, or `id` only with a concrete ID  (never empty or placeholder).- For single-execution nodes that receive many items but should run once, set  `executeOnce: true`.- Whenever a node declares mock `output` for verification, include every field  later referenced by `$json` expressions, including optional trigger fields  used in filters (for example Slack `subtype`, `bot_id`, `text`, `user`, `ts`,  `channel`). Missing optional fields make expression-path validation fail.- Match real cardinality in mock `output`. When a node's real response is a  collection (HTTP list endpoints, search results, a top-level array such as  Binance klines or a bare array of IDs), declare at least two items so  single-item assumptions like `$input.first()` break during verification  instead of on the user's first run. A single-item mock hides array-vs-single  bugs.- Match the real payload SHAPE in webhook trigger mocks. When a third-party  platform calls the webhook (voice agents, payment providers, messaging  platforms), that platform's documented envelope fixes the shape — mock it  faithfully instead of inventing a flattened body. Tool-call style webhooks  from AI/voice platforms nest arguments in an OpenAI-compatible envelope  (`body.message.toolCalls[0].function.arguments`), not at the body root and  not under `call.arguments`. Coding against an invented flat mock  self-verifies green, then every field parses empty on the first real call.- SDK node `output` mocks are raw `$json` objects. Do not wrap mock items in  n8n runtime item envelopes like `{ json: { ... } }` unless downstream  expressions intentionally read `$json.json.*`. Correct:  `output: [{ orderId: 'ord_123', total: 42 }]`; wrong:  `output: [{ json: { orderId: 'ord_123', total: 42 } }]`.  Code node `jsCode` may still return runtime items like `[{ json: { ... } }]`;  this rule applies to SDK `node({ output: [...] })` mocks. Use this import shape unless the task needs fewer symbols: ```tsimport {  workflow,  node,  trigger,  placeholder,  newCredential,  ifElse,  switchCase,  merge,  splitInBatches,  nextBatch,  languageModel,  memory,  tool,  outputParser,  embedding,  embeddings,  vectorStore,  retriever,  documentLoader,  textSplitter,  fromAi,  nodeJson,  expr,} from '@n8n/workflow-sdk';``` ## Node Groups {{GROUPING_GUIDANCE_PLACEHOLDER}} Declare a group with `.group(name, members, { description })` on the workflow builder; membersare the node handles. Before you emit a `.group(...)`, read`${N8N_WORKSPACE_DIR}/knowledge-base/reference/node-groups.md` — it carries the rules that makea group valid and the contract for editing an existing workflow's groups. Do not restate thoserules from memory: an invalid group is dropped from the saved workflow with a warning, so thesource has to be fixed rather than re-emitted. ## Workflow Rules Follow these rules strictly when generating workflows: 1. Always use `newCredential()` for authentication. Never use placeholder   strings, fake API keys, hardcoded auth values, invented credential IDs, or   raw `mock-*` IDs.2. Zero items end the branch — downstream nodes do not run. Trust this default;   do not add `alwaysOutputData: true` or empty-check IF gates unless rule 4's   mandatory-outcome case applies.3. Use `executeOnce: true` for a node that receives many items but should run   once, such as a summary notification, report generation, shared-context   fetch, or API call that does not vary per input item. Duplicate   notifications or repeated shared-context fetches usually mean this is   missing.4. Pick the right control-flow primitive:   - Per-item loop with side effects: `splitInBatches` with `batchSize: 1`,     feeding the per-item work and looping back via `nextBatch`.   - Drop items that do not match a predicate: `filter`.   - Two mutually exclusive paths that both do real work: IF with `.onTrue()`     and `.onFalse()` wired on the workflow builder — never as standalone     statements on the IF node variable.   - Many mutually exclusive paths keyed off a value: Switch with     `.onCase(index, target)`.   - Mandatory outcome when upstream can be empty (digest/alert must still send):     set `alwaysOutputData: true` on every node that can emit zero items before     the effect — often both the HTTP fetch (empty `[]`) and the filter (all rows     dropped). Not on the formatter or notifier; consumers that receive zero     items never run. `alwaysOutputData` delivers an empty result as one item     with empty json (`{}`), not zero items — a downstream formatter or Code     node must treat empty-json items as zero rows (e.g. `const rows =     $input.all().filter(i => Object.keys(i.json).length > 0)`) before counting     or listing them.   - A Filter or IF only selects items; it does not perform the requested side     effect. If the user asks to archive, update, delete, send, or create only     matching items, wire the corresponding action node on the matching path.5. Input and output indices are zero-based. `.input(0)` and `.output(0)` are the   first input and output. `.input(1)` is the second input, not the first.6. When Code nodes score, classify, or gate on free-text human fields   (amounts, timeframes, priorities, intent), normalize before comparing —   humans write "≈ $12,500", "1.5k", "in three weeks", "ASAP". Strip currency   symbols/separators before parsing numbers, take the lower bound of ranges,   match time units broadly (day/days, week/weeks…), and give every classifier   an explicit fallback bucket — a one-phrasing regex silently misroutes every   other phrasing.7. Inserting a node into an existing connection A→B changes what B receives:   `$json` and auto-mapped fields in B now read the inserted node's output, not   A's. Write/create/send nodes output their **API response** (ids, metadata,   `ok` flags), never the data that flowed into them — so inserting one   in-line (e.g. an ensure-the-target-exists step before a write) silently   replaces the payload with metadata. Keep the data path intact instead:   branch the inserted node in parallel from the data producer, reorder it   upstream of the data producer, or have B reference `$('Data Node')`   explicitly.8. A polling trigger (Gmail Trigger, Outlook Trigger, or similar) feeding an   action that creates or writes records must ensure each polled item is   processed once — poll cursors are best-effort bookkeeping (they reset when   the trigger node is recreated or renamed) and every still-matching item is   then re-delivered as a duplicate. Either restrict the trigger to   unread/unprocessed items AND mark each item handled once its record exists,   in a way the trigger's own filter excludes — mark as read when filtering   unread, move out of the watched folder, or apply a label only if the   trigger's query also excludes that label (a label does not mark a message   read) — or record handled ids in a Data Table: look the id up before   creating the record, skip ids already seen, and insert it only after the   create succeeds. An unread filter alone is not enough: if no step ever   marks the item read, it never excludes anything. Wire the mark-as-handled   step AFTER the record-creating node, so a mid-run failure cannot consume an   item without producing its output — this trades a rare duplicate (create   succeeded, marking failed) for never losing an item; do not invert it. ## Tool Naming Rules Always set an explicit `config.name` on every `tool(...)` node — concisesnake_case action names (`get_email`, `add_labels`, `mark_as_read`) describingwhat the tool does. Never prefix with the service/family name(`gmail_get_email`, `slack_send_message` are wrong) unless the user explicitlyasked for that exact name. ## Node Configuration Safety Rules - Fetch `nodes(action="type-definition")` before configuring nodes. Generated  definitions and `@builderHint` annotations are the source of truth.- Use live `nodes(action="explore-resources")` for resource locator, list, and  model fields when credentials are available.- If a configuration is unclear after reading the definition, ask for  clarification or use placeholders. Do not guess.- Pay attention to `@builderHint` annotations in search results and type  definitions. They contain node-specific configuration rules and examples.- Gmail archive: the message resource has no `archive` operation. To archive a  Gmail message, remove the `INBOX` label with `operation: 'removeLabels'` and  `labelIds: ['INBOX']`; do not add an invented `ARCHIVE` label. ## Expression Reference Available variables inside `expr('{{ ... }}')`: - `$json`: current item's JSON data from the immediate predecessor node only.- `$('NodeName').item.json`: access another node's output item paired with the  current item.- `$input.first()`, `$input.all()`, and `$input.item`.- `$binary`: binary data from the current item.- `$now` and `$today`: Luxon date/time helpers.- `$itemIndex`, `$runIndex`, `$execution.id`, `$execution.mode`,  `$workflow.id`, and `$workflow.name`. Variables must always be inside `{{ }}`: ```tsexpr('Hello {{ $json.name }}')expr('Report for {{ $now.toFormat("MMMM d, yyyy") }} - {{ $json.title }}')expr('{{ $("Source").all().map(i => ({ option: i.json.name })) }}')``` When `$json` is unsafe, reference the source node explicitly. This matters forAI Agent subnodes, fan-in nodes after IF/Switch/Merge, and values that come fromfurther upstream or from before a node that replaces item JSON: ```tssessionKey: nodeJson(telegramTrigger, 'message.chat.id')eventId: nodeJson(extractEventId, 'eventId')``` Use `$('NodeName').item.json.field` or `nodeJson(sourceNode, 'field')` forper-item upstream values. Do not use `.first()` or `$input.first()` forper-item data in a multi-item workflow; it always reads item 0 and makes everydownstream item reuse the first value. Use `.first()` only for a true globalfirst item, such as a single configuration row. ## SDK Patterns Reference Define nodes first, then compose the workflow: ```tsconst startTrigger = trigger({  type: 'n8n-nodes-base.manualTrigger',  version: 1,  config: { name: 'Start' },}); const fetchData = node({  type: 'n8n-nodes-base.httpRequest',  version: 4.3,  config: { name: 'Fetch Data', parameters: { method: 'GET', url: placeholder('API URL') } },}); export default workflow('id', 'name').add(startTrigger).to(fetchData);``` When two upstream data sources are independent, do not chain them if that wouldmultiply items. Use `executeOnce: true` or parallel branches plus Merge. For Merge nodes, input indices are zero-based: ```tsconst combine = merge({  version: 3.2,  config: { name: 'Combine Results', parameters: { mode: 'combine', combineBy: 'combineByPosition' } },}); export default workflow('id', 'name')  .add(startTrigger)  .to(sourceA.to(combine.input(0)))  .add(startTrigger)  .to(sourceB.to(combine.input(1)))  .add(combine)  .to(processResults);``` For IF, each branch is a complete processing path. Wire branches on the workflowbuilder, not as standalone calls on the IF node variable. Chain steps inside abranch with `.to()`, or pass an array for parallel fan-out. ```tsconst isImportant = ifElse({  version: 2.2,  config: {    name: 'Is Important',    parameters: {      conditions: {        options: { caseSensitive: true, leftValue: '', typeValidation: 'strict', version: 2 },        conditions: [          { id: 'priority', leftValue: expr('{{ $json.priority }}'), rightValue: 'high', operator: { type: 'string', operation: 'equals' } },        ],        combinator: 'and',      },    },  },}); export default workflow('id', 'name')  .add(startTrigger)  .to(isImportant)  .onTrue(handleImportant)                               // single step  .onFalse(sendHolding.to(createTicket.to(alertSlack))); // chained multi-step// Equivalent inline form: .to(isImportant.onTrue(a).onFalse(b))// Parallel fan-out on a branch: .onFalse([a, b, c])``` Do NOT wire branches as standalone statements after `export default` — thosecalls never reach the builder (`workflow-sdk validate` flags this). ```ts// WRONGexport default workflow('id', 'name').add(startTrigger).to(isImportant);isImportant.onTrue(handleImportant); // never reaches the builderisImportant.onFalse(sendHolding);``` For Switch, wire cases the same way — `.to(switchNode).onCase(0, a).onCase(1, b)`or inline — using zero-based `.onCase(index, target)` for each rule output. Error routes work the same way on any node: `.to(fetchNode).onError(notify)`routes the error output and leaves the cursor on `fetchNode`, so a following`.to(next)` continues the main branch and a second `.onError()` adds anotherhandler. The inline form `.to(fetchNode.onError(notify))` is equivalent. Bothforms set `onError: 'continueErrorOutput'` on the node for you. Call`.onError()` once for each handler — it takes one handler, not an array. For Split in Batches, use it for per-item side effects and loop back with`nextBatch`. Do not add a separate IF gate just to check whether items exist. For AI Agent workflows: - Attach language models, memory, tools, parsers, retrievers, vector stores, and  other subnodes to the agent as subnodes.- Tool nodes must have explicit concise `config.name` values.- Prefer `fromAi(...)` for values the agent should supply to tools.- Use explicit node references instead of `$json` in subnodes when the value  comes from a trigger or a main-flow node. ## Additional SDK Functions - `placeholder('hint')`: marks a parameter value for user input (use directly as  the parameter value; `workflow-sdk validate` flags wrapping it in `expr()`).- `.output(n)`: selects a zero-based output index.- `.onError(handler)`: connects a node's error output to a handler, on the node  or on the workflow builder. It sets `onError: 'continueErrorOutput'` on the  node, so you do not declare that in the config.- `nodeJson(node, 'field.path')`: creates an explicit expression reference to a  specific node's JSON output.- Subnode factories follow the same pattern as `languageModel()` and `tool()`:  `memory()`, `outputParser()`, `embeddings()`, `vectorStore()`, `retriever()`,  `documentLoader()`, and `textSplitter()`. ## Trigger URL Sharing After building a workflow that uses a trigger with an HTTP endpoint, share thefull production URL with the user. Use the Webhook base URL and Form base URLfrom Instance Info in the system prompt. Each trigger type has a distinctpattern: - **Webhook Trigger**: `{webhookBaseUrl}/{path}` (where `{path}` is the node's  webhook path parameter).- **Form Trigger**: `{formBaseUrl}/{path}` (or `{formBaseUrl}/{webhookId}` if  no custom path is set). Form Trigger lives under `/form/`, NOT `/webhook/` —  they are separate URL prefixes. Do NOT use the Webhook base URL for Form  Triggers.- **Chat Trigger**: how the end user reaches this workflow depends on the  node's `public` parameter — pick the right guidance for the current value,  do not default to sharing a URL.  - **`public: false` (the default)**: there is NO end-user HTTP URL. Tell the    user to open the workflow in the editor and click the **Open chat** button    on the workflow canvas — that opens the built-in test chat. Do NOT share a    webhook URL, and do NOT suggest flipping `public: true` just to enable    testing — the in-editor chat is the intended testing path for private chat    workflows.  - **`public: true`**: the public chat URL is    `{webhookBaseUrl}/{webhookId}/chat` — share it after the workflow is    published. `{webhookId}` is the node's unique webhook ID; read it from the    workflow JSON, never guess. End users can open this URL in a browser.  The `/chat` suffix is unique to Chat Trigger — do NOT append it to Form  Trigger or Webhook URLs. (Your own testing via `executions(action="run")` and  `verify-built-workflow` works regardless of `public` or publish state.) **These URLs are for sharing with the user only.** Do NOT hardcode them intoworkflow code or build specs unless the workflow actually needs to send orstore its own public endpoint. ## Completion Do not report a build as done until you have made the grouping decision described in[Node Groups](#node-groups) and checked what the build did with it. A dropped-group warningnames what was invalid — a duplicate name, a member that does not exist, a boundary the rulesreject: fix what the warning reports and build again. A `GROUPING_DECISION_MISSING` error meansthe build was refused: fix the source, or pass the opt-out with a reason. A`GROUP_DROPPED_OVER_CEILING` error also refuses the build: a declared group was invalid and thecanvas is still over the ceiling. Fix the boundary the message names — the opt-out does notapply. If the top level is still above{{TOP_LEVEL_ITEM_CEILING_PLACEHOLDER}} items with groups in place, name each remaining item andwhy it cannot join a group. For a successful build, finish with one concise sentence naming the workflow andwhat changed. Include the workflow ID when it is available. If setup isrequired, say plainly that setup is needed; do not tell the user to open a setupwizard or navigate away from the n8n Assistant panel. When the workflow exposesa Webhook, Form, or Chat Trigger, follow [Trigger URL Sharing](#trigger-url-sharing)and include the correct end-user URL (or in-editor chat guidance) in thatsummary.
Discovery context

Discovered by repository scan. No exact path reference found in the snapshot’s root AGENTS.md.

← All n8n skillsProject instructions →