@n8n/instance-ai 1.13.2 → 1.14.0

package/skills/workflow-builder/SKILL.md

@@ -61,10 +61,18 @@ with the same `filePath`. Do not send inline workflow code or string patches to
 
 ## Escalation
 
-If you are stuck or need information only a human can provide, use `ask-user`.
-Do not retry the same failing approach more than twice. Never re-ask a question
-the user has already answered, deferred, or skipped — treat a skip as permission
-to assume a sensible default or leave the detail for setup, and move on. Never
+Before the first successful `build-workflow` call, use `ask-user` only when a
+missing choice changes the workflow's intent or topology, such as which
+destination service to use. Do not ask for setup details after the service is
+known; recipients, accounts, resources, channels, credentials, and timezone
+belong in placeholders or unresolved `newCredential()` calls until post-build
+setup.
+
+After the first build, or when the workflow intent is genuinely ambiguous, use
+`ask-user` if you are stuck or need information only a human can provide. Do not
+retry the same failing approach more than twice. Never re-ask a question the
+user has already answered, deferred, or skipped — treat a skip as permission to
+assume a sensible default or leave the detail for setup, and move on. Never
 solicit API keys, tokens, passwords, or other secrets through `ask-user`; route
 credential collection through workflow setup or credential setup surfaces.
 
@@ -84,6 +92,12 @@ tokens, Slack channel IDs, Telegram chat IDs, or sample recipient lists. After
 the build, `workflows(action="setup")` opens an inline setup card in the AI
 Assistant panel so the user can fill placeholder values.
 
+Do not ask for missing setup values before the first successful build. Once the
+service or workflow shape is known, missing email recipients, notification
+targets, account labels or IDs, channel IDs, resource IDs, credentials,
+timezone, and similar node configuration belong in placeholders during the
+initial build; route them to setup only after the workflow is saved.
+
 Do not replace concrete user-provided or discoverable values with placeholders.
 If the prompt gives a real URL, channel name, table name, label, folder,
 database, or other literal selector, preserve that value and only use a
@@ -135,6 +149,14 @@ When mapping downstream fields from an OpenAI node, read
 7. Write complete TypeScript SDK code to the workspace `filePath`, or read and
    selectively edit the existing `.workflow.ts` file for workflow changes. 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.
 8. Call `build-workflow` with `filePath`.
    For planned build follow-ups where `buildTask.isSupportingWorkflow === true`,
    pass `isSupportingWorkflow: true`; that saved supporting workflow is the
@@ -184,6 +206,12 @@ If the saved workflow is only a draft, misses the intended outcome, or has weak
 evidence, edit the same workflow source file and call `build-workflow` with the
 same `filePath`, then inspect and verify again.
 
+Do not tell the user a workflow is fixed, verified, tested, or working from a
+successful build, save, or static `validate` alone — only from a
+`verify-built-workflow` or `executions` run that exercised the failing path, or
+state explicitly that you could not verify and why. Never dismiss a live
+execution error as a harness or stale-state artifact without re-running.
+
 When this turn is responsible for verification, do not stop after a successful
 save. The job is done when one of these is true:
 
@@ -192,9 +220,18 @@ save. The job is done when one of these is true:
 - 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 can
+be called again with `workflowId` if the original `workItemId` is no longer in
+context. For alternate deterministic scenarios, pass `fixtureOverrides` for
+nodes already classified as simulated. Use raw `executions(action="run")` only
+for 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 the
+fixture-backed branch coverage first and run a separate live smoke check, or
+state exactly which branch remains unverified.
+
 Trigger input shapes:
 
-- Manual or Schedule: use `executions(action="run")` when appropriate. Schedule
+- Manual or Schedule: use `verify-built-workflow` when appropriate. Schedule
   usually needs no `inputData`.
 - Form Trigger: pass a flat field map, for example
   `{ "name": "Alice", "email": "a@b.c" }`. Do not wrap in `formFields`.
@@ -256,6 +293,14 @@ resource:
 For resources that cannot be created via n8n, explain clearly what the user
 needs to create manually and what ID or value belongs in setup.
 
+If part of the requested workflow is infeasible (no node or API for it, a source
+that blocks automated access, an action that cannot be performed
+programmatically, or a third-party API whose region/use-case coverage you have
+not verified), do not quietly substitute a stand-in and present it as the
+requested capability. Flag the substitution as an approximation that may not
+work — and any unverified region/country support — and name that gap in the
+one-line completion summary so the result is not mistaken for the original ask.
+
 ## Compositional Workflows
 
 For complex workflows, you may decompose work into supporting sub-workflows and
@@ -368,19 +413,27 @@ column names.
   explicitly expects an object and the placeholder is the direct value of one
   field.
 - For unresolved resource-locator fields (values shaped like `{ __rl: true,
-  mode, value }`, such as Slack channel selectors), use the resource-locator
-  object shape instead of a raw `placeholder()` string. Pick the mode per the
-  resource-locator rule in Node Configuration Safety Rules: a `name`/`url`
-  mode with the known value when the locator offers one and you know the
-  resource by name; otherwise id mode with an empty value and a cached result
-  name, for example `{ __rl: true, mode: 'id', value: '',
-  cachedResultName: 'Select support channel to monitor' }`.
+  mode, value }`, such as Slack channel or Google Sheets document selectors),
+  use the resource-locator object shape instead of a raw `placeholder()`
+  string. Prefer the locator's picker (`list`) mode when it offers one, since
+  it gives the user a searchable picker at setup, with an empty value and a
+  `cachedResultName` hint, for example `{ __rl: true, mode: 'list', value: '',
+  cachedResultName: 'Select support channel to monitor' }`. Not every locator
+  has a `list` mode; when it doesn't, use a `name`/`url` mode with the known
+  value, or `id` mode only when you have a concrete ID. Never use `id` with an
+  empty or placeholder value.
 - 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.
 - 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: