@n8n/instance-ai 1.17.3 → 1.19.0

package/skills/workflow-builder/SKILL.md

@@ -1,16 +1,19 @@
 ---
 name: workflow-builder
 description: >-
-  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, then call build-workflow with filePath. 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.
+  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
@@ -22,52 +25,67 @@ recommended_tools:
 
 # 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, valid
 TypeScript code using `@n8n/workflow-sdk` for new workflows and for existing
 saved workflow changes.
 
-This skill runs inside the orchestrator — no separate builder agent, handoff,
-or tool allowlist; use the orchestrator and workspace file tools already
-available this turn (plus any relevant tool-search/MCP tool). Workflow building
-runs in the orchestrator with this skill and `build-workflow`.
-
-For new single-workflow requests, build directly with
-`build-workflow({ filePath, sourceCode })` — the complete TypeScript SDK
-source in `sourceCode`; the tool writes the file and builds in one call. For
+Always write the complete TypeScript SDK source with
+`workspace_write_file` first, then call `build-workflow({ filePath })`. For
 existing saved workflow edits, call `workflows(action="get-as-code",
-workflowId)`, apply the edit to the returned code, then call
-`build-workflow({ filePath, workflowId, sourceCode })` the first time — all
-edits go through a workspace source file and `build-workflow`. Do not load
+workflowId)`, apply the edit to the returned code, write it to the file, then
+call `build-workflow({ filePath, workflowId })` the first time — all edits go
+through a workspace source file and `build-workflow`. Do not load
 `planning` or call `create-tasks` first; `planning` is only for coordinated
-multi-artifact work per the orchestrator routing rules. Use this skill for
-direct single-workflow builds/edits and during approved
-`<planned-task-follow-up type="build-workflow">` turns.
+multi-artifact work per the orchestrator routing rules. Do not create a plan
+just for verification.
+
+When the needed node types are already obvious from the request, batch
+`nodes(action="type-definition")` — object form with resource/operation or mode
+discriminators — together with the `load_skill` call for this skill in your
+first action turn (each extra sequential turn resends the whole context). When
+unsure which nodes to use, load this skill first and follow its research
+process below.
 
 ## Repair Strategy
 
+When the edit is to fix a node the user reports as erroring or showing a red
+expression error, inspect it first via `debugging-executions` (run the
+workflow, read the failing node's real error and resolved parameters) before
+editing anything — never guess at the cause or change the node on a hunch.
+
 When called with failure details for an existing workflow, start from the
 workspace source file if one is available in the conversation or tool output. If
 you only have a saved n8n workflow ID, use `workflows(action="get-as-code")`,
-make the smallest requested edit to the returned code, then call
-`build-workflow` once with `filePath` (a stable
-`src/workflows/<name>.workflow.ts` path), `workflowId`, and the full edited
-code as `sourceCode`. Later repairs should reuse the same `filePath`;
+make the smallest requested edit to the returned code, write it to a stable
+`src/workflows/<name>.workflow.ts` path, then call `build-workflow` once with
+`filePath` and `workflowId`. Later repairs should reuse the same `filePath`;
 `build-workflow` remembers the 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` alone — cheaper than resending full source. `sourceCode` must always
-be the complete source when used; never send string patches or fragments.
+`filePath`.
 
 ## Escalation
 
-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). Setup details — recipients, accounts, resources,
-channels, credentials, timezone — belong in placeholders or unresolved
-`newCredential()` calls until post-build setup. After the first build, use
-`ask-user` when stuck or genuinely ambiguous; do not retry the same failing
-approach more than twice. Never re-ask an answered, deferred, or skipped
+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 use
+for a capability the user did not name,
+discover coverage first and use an n8n credits–covered node instead of asking
+when the user has no credential for a comparable tool (see n8n credits
+Preference). Setup details — recipients, accounts,
+resources, channels, credentials, timezone — belong in placeholders or
+unresolved `newCredential()` calls until post-build setup. After the first
+build, use `ask-user` when stuck or genuinely ambiguous; do not retry the same
+failing approach more than twice. Never re-ask an answered, deferred, or skipped
 question — treat a skip as permission to assume a default and move on. Never
 solicit secrets through `ask-user`; route credential collection through
 workflow/credential setup surfaces.
@@ -87,13 +105,39 @@ Do not replace concrete user-provided or discoverable values with
 placeholders: 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 Guardrails
+## Knowledge Base
+
+**Prefer n8n sources over guessing.** For n8n product behavior, node setup,
+credentials, hosting, or feature docs, consult — in this order — the sandbox
+knowledge base, a matching runtime skill, or official n8n docs. Do not invent
+setup 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.
+   - `knowledge-base/index.json` — catalog of technique guides
+     (`knowledge-base/best-practices/index.json`; read the linked `.md` files)
+     and orchestration reference docs (`knowledge-base/reference/index.json`)
+   - `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
+   - `node-types/index.txt` — searchable catalog of available n8n nodes
+2. **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`
+   then load `n8n-docs` via `load_tool` (search "n8n docs" if it is not
+   visible) 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
 `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, list itemization, and Code-node safety.
+effect-specific gating, and list itemization.
 
 When mapping downstream fields from an OpenAI node, read
 `knowledge-base/reference/open-ai-output-shape.md` (v2+ text/response uses
@@ -139,12 +183,9 @@ build → publish → assign steps. Do not create one before the user opts in.
    `workflows(action="get-as-code", workflowId)`, apply your edit to the
    returned code, and pass the n8n `workflowId` only on the first
    `build-workflow` call.
-6. Produce complete TypeScript SDK code. For a new or fully rewritten source
-   file, do NOT write it with `workspace_write_file` — pass it directly as
-   `sourceCode` on the `build-workflow` call (the tool writes `filePath` and
-   builds in one step; a separate write call wastes a full round-trip). Use
-   file tools only to selectively edit an existing `.workflow.ts` for
-   follow-up changes and repairs. Do not put secrets in the source file.
+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
@@ -153,12 +194,21 @@ build → publish → assign steps. Do not create one before the user opts in.
    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.
-7. Call `build-workflow` with `filePath` (plus `sourceCode` for new or fully
-   rewritten source).
+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.
-8. Trace wiring before declaring done. For IF, Switch, Merge, AI-agent, loop, or
+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
@@ -168,15 +218,15 @@ build → publish → assign steps. Do not create one before the user opts in.
    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.
-9. Fix errors by editing the same workspace source file and calling
-    `build-workflow` again with the same `filePath`. Save again before any
-    verification step.
-10. Modify existing workflows by editing the workspace `.workflow.ts` source
+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. If the file was created from `workflows(action="get-as-code")`, pass
     the real n8n `workflowId` on the first `build-workflow` call so the file is
     bound to the saved workflow. Never pass local SDK workflow IDs as n8n
     workflow IDs.
-11. After a successful direct `build-workflow` result, if the tool output
+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,
@@ -290,8 +340,18 @@ scraping 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 that
-node over comparable alternatives *when the user has not named a specific
-tool*, and respect the constraints it reports:
+node over comparable alternatives *when the user has not named a specific tool
+and 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 credential
+for a comparable tool.
+
+The `suggested` list and search *rank* don't prioritize n8n credits coverage
+(individual search results still flag it). When the user asks for a capability
+they have no usable credential for, search that
+capability — or run `nodes(action="list", n8nConnectOnly=true)` — before
+committing, 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
@@ -362,10 +422,10 @@ n8n normalizes Data Table column names to snake_case, for example `dayName`
 becomes `day_name`. Always call `data-tables(action="schema")` before using a
 Data Table in workflow code so you use real column names.
 
-When building workflows that create or use tables, use the data table skill
-guidance already loaded by the orchestrator when available. Create or inspect
-tables directly with `data-tables`; do not invent table IDs, table names, or
-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 that
+skill for schema/row guidance. Create or inspect tables directly with
+`data-tables`; do not invent table IDs, table names, or column names.
 
 When the ask is a summary, digest, or report over a period ("weekly summary of
 what was recorded", "digest of this week's rows"), the summary branch must
@@ -377,33 +437,30 @@ 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 and
+Code-node defects: network calls / forbidden imports in Code nodes, nested
+template 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()`), and
+repeated `.onTrue()` / `.onFalse()` overwrites on the same IF variable. Fix
+every reported error and warning before calling `build-workflow`.
+
+- Code nodes need not always be necessary. You can use other n8n nodes to do the same thing. 
 - SDK builder code is a restricted subset of TypeScript that builds a static
-  graph; it is not a Code node and does not run. Only SDK builder methods chain
-  on SDK objects. Native array/string methods (`.join()`, `.map()`), loops, arrow
-  functions, `new`, and globals like `Math`, `Date`, and `Object` are
-  unavailable. Build strings with template literals or explicit lines; do runtime
-  joining, aggregation, or transforms in a Code node or an n8n expression
-  (`expr()`). Full allowed/forbidden list:
+  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:
   `knowledge-base/reference/workflow-sdk-language.md`.
-
-- Code nodes have NO network access at runtime: `fetch()`, `axios`,
-  `XMLHttpRequest`, and `require` of http modules all fail in the sandbox. Make
-  every HTTP/API call with the HTTP Request node and transform its output in a
-  Code node, even when the user asks to fetch inside a Code node.
-
 - Use `@n8n/workflow-sdk`.
-- `export default workflow(...)...` must be the last statement in the file, with
-  all wiring composed inside that chain. Statements after it (e.g.
-  `ifNode.onTrue(...)`) do not reach the builder and their nodes are dropped.
 - 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.
-- Do not use TypeScript-only syntax that the workflow parser cannot interpret,
-  such as `as const`.
 - Use string values directly for discriminator fields like `resource` and
   `operation`, for example `resource: 'message'`.
-- When editing a pre-loaded workflow, remove `position` arrays from node
-  configs; they are auto-calculated.
+- When editing a pre-loaded workflow, remove every `position` array — from node
+  configs and from `sticky()` options alike. Positions are auto-calculated, and
+  the saved workflow's own layout is restored on save, so nothing you drop here
+  is lost. Leaving some in place is worse than dropping all of them.
 - 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
@@ -522,12 +579,6 @@ Follow these rules strictly when generating workflows:
    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. Do not add sticky notes (`sticky(...)` / `n8n-nodes-base.stickyNote`) unless
-   the user explicitly asks for canvas notes. They add visual noise and are
-   often poorly positioned. Put explanations in your chat reply instead. Even
-   when the SDK language reference documents `sticky()`, do not use it by
-   default. When editing a workflow, do not add or reintroduce stickies unless the user
-   explicitly asks for them.
 
 ## Tool Naming Rules
 
@@ -630,8 +681,6 @@ export default workflow('id', 'name')
 For IF, each branch is a complete processing path. Wire branches on the workflow
 builder, not as standalone calls on the IF node variable. Chain steps inside a
 branch with `.to()`, or pass an array for parallel fan-out.
-Never call `.onFalse()` more than once (same for `.onTrue()`); each repeat
-overwrites the previous target.
 
 ```ts
 const isImportant = ifElse({
@@ -659,16 +708,14 @@ export default workflow('id', 'name')
 // Parallel fan-out on a branch: .onFalse([a, b, c])
 ```
 
-Do NOT wire branches as standalone statements.
-Then branch nodes are omitted from the saved graph, and repeated `.onFalse()`
-calls keep only the last target.
+Do NOT wire branches as standalone statements after `export default` — those
+calls never reach the builder (`workflow-sdk validate` flags this).
 
 ```ts
 // WRONG
 export default workflow('id', 'name').add(startTrigger).to(isImportant);
 isImportant.onTrue(handleImportant); // never reaches the builder
-isImportant.onFalse(sendHolding);    // overwritten
-isImportant.onFalse(alertSlack);     // only this one would wire
+isImportant.onFalse(sendHolding);
 ```
 
 For Switch, wire cases the same way — `.to(switchNode).onCase(0, a).onCase(1, b)`
@@ -688,10 +735,8 @@ For AI Agent workflows:
 
 ## Additional SDK Functions
 
-- `placeholder('hint')`: marks a parameter value for user input.
-- `sticky('content', nodes?, config?)`: opt-in only when the user explicitly
-  asks for a sticky note on the canvas. Do not import or call it otherwise.
-  When used, it must still be added to the workflow.
+- `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. Requires
   `onError: 'continueErrorOutput'` in the node config.
@@ -701,9 +746,46 @@ For AI Agent workflows:
   `memory()`, `outputParser()`, `embeddings()`, `vectorStore()`, `retriever()`,
   `documentLoader()`, and `textSplitter()`.
 
+## Trigger URL Sharing
+
+After building a workflow that uses a trigger with an HTTP endpoint, share the
+full production URL with the user. Use the Webhook base URL and Form base URL
+from Instance Info in the system prompt. Each trigger type has a distinct
+pattern:
+
+- **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 into
+workflow code or build specs unless the workflow actually needs to send or
+store its own public endpoint.
+
 ## Completion
 
 For a successful build, finish with one concise sentence naming the workflow and
 what changed. Include the workflow ID when it is available. If setup is
 required, say plainly that setup is needed; do not tell the user to open a setup
-wizard or navigate away from the AI Assistant panel.
+wizard or navigate away from the AI Assistant panel. When the workflow exposes
+a 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 that
+summary.

package/dist/tools/templates.tool.d.ts

@@ -1,2 +0,0 @@
-import type { InstanceAiContext } from '../types';
-export declare function createTemplatesTool(context: InstanceAiContext): import("@n8n/agents").BuiltTool;

package/dist/tools/templates.tool.js

@@ -1,20 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createTemplatesTool = createTemplatesTool;
-const agents_1 = require("@n8n/agents");
-const zod_1 = require("zod");
-const sanitize_mcp_schemas_1 = require("../agent/sanitize-mcp-schemas");
-const inputSchema = (0, sanitize_mcp_schemas_1.sanitizeInputSchema)(zod_1.z.object({
-    templateId: zod_1.z.string().describe('The numeric id of the workflow template to load'),
-}));
-function createTemplatesTool(context) {
-    return new agents_1.Tool('templates')
-        .description('Load an n8n workflow template by its id. Returns the template workflow ' +
-        '(nodes and connections) to use as a starting point for building.')
-        .input(inputSchema)
-        .handler(async (input) => {
-        return await context.workflowTemplateService.getTemplate(input.templateId);
-    })
-        .build();
-}
-//# sourceMappingURL=templates.tool.js.map

package/dist/tools/templates.tool.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"templates.tool.js","sourceRoot":"","sources":["../../src/tools/templates.tool.ts"],"names":[],"mappings":";;;AAAA,wCAAmC;AACnC,6BAAwB;AAExB,wEAAoE;AAKpE,MAAM,WAAW,GAAG,IAAA,0CAAmB,EACtC,OAAC,CAAC,MAAM,CAAC;IACR,UAAU,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;CAClF,CAAC,CACF,CAAC;AAMF,6BAAoC,OAA0B;IAC7D,OAAO,IAAI,aAAI,CAAC,WAAW,CAAC;SAC1B,WAAW,CACX,yEAAyE;QACxE,kEAAkE,CACnE;SACA,KAAK,CAAC,WAAW,CAAC;SAClB,OAAO,CAAC,KAAK,EAAE,KAAY,EAAE,EAAE;QAC/B,OAAO,MAAM,OAAO,CAAC,uBAAuB,CAAC,WAAW,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAC5E,CAAC,CAAC;SACD,KAAK,EAAE,CAAC;AACX,CAAC"}