@n8n/instance-ai 1.19.3 → 1.20.1

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAomCa,QAAA,kBAAkB,GAAG,CAAC,gBAAgB,EAAE,YAAY,CAAU,CAAC;AAE/D,QAAA,yBAAyB,GAAG,CAAC,UAAU,CAAU,CAAC;AAClD,QAAA,yBAAyB,GAAG;IACxC,GAAG,QAAA,kBAAkB;IACrB,GAAG,QAAA,yBAAyB;CACnB,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAiqCa,QAAA,kBAAkB,GAAG,CAAC,gBAAgB,EAAE,YAAY,CAAU,CAAC;AAE/D,QAAA,yBAAyB,GAAG,CAAC,UAAU,CAAU,CAAC;AAClD,QAAA,yBAAyB,GAAG;IACxC,GAAG,QAAA,kBAAkB;IACrB,GAAG,QAAA,yBAAyB;CACnB,CAAC"}

package/dist/workspace/workspace-paths.d.ts

@@ -1,4 +1,6 @@
-export declare function normalizeWorkspaceRelativePath(path: string, options?: {
+export interface NormalizeWorkspaceRelativePathOptions {
     resourceLabel?: string;
-}): string;
+    workspaceRoot?: string;
+}
+export declare function normalizeWorkspaceRelativePath(path: string, options?: NormalizeWorkspaceRelativePathOptions): string;
 export declare function joinWorkspacePath(root: string, path: string): string;

package/dist/workspace/workspace-paths.js

@@ -2,9 +2,21 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeWorkspaceRelativePath = normalizeWorkspaceRelativePath;
 exports.joinWorkspacePath = joinWorkspacePath;
+function stripWorkspaceRootPrefix(path, workspaceRoot) {
+    const root = workspaceRoot.replace(/\/+$/, '');
+    if (root.length === 0)
+        return path;
+    const collapsed = path.replace(/\/{2,}/g, '/');
+    if (collapsed === root)
+        return '';
+    return collapsed.startsWith(`${root}/`) ? collapsed.slice(root.length + 1) : path;
+}
 function normalizeWorkspaceRelativePath(path, options = {}) {
     const label = options.resourceLabel ?? 'Workspace';
-    const trimmed = path.trim().replace(/^\.\/+/, '');
+    let trimmed = path.trim().replace(/^\.\/+/, '');
+    if (options.workspaceRoot && trimmed.startsWith('/')) {
+        trimmed = stripWorkspaceRootPrefix(trimmed, options.workspaceRoot);
+    }
     const segments = trimmed.split('/');
     const normalized = segments.filter((segment) => segment.length > 0 && segment !== '.').join('/');
     if (normalized.length === 0 ||
@@ -13,7 +25,8 @@ function normalizeWorkspaceRelativePath(path, options = {}) {
         trimmed.includes('\\') ||
         trimmed.includes('\0') ||
         segments.some((segment) => segment === '..')) {
-        throw new Error(`${label} path must stay within the workspace root: ${path}`);
+        throw new Error(`${label} path must stay within the workspace root: ${path}. ` +
+            'Pass a workspace-relative path like src/workflows/my-workflow.workflow.ts.');
     }
     return normalized;
 }

package/dist/workspace/workspace-paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"workspace-paths.js","sourceRoot":"","sources":["../../src/workspace/workspace-paths.ts"],"names":[],"mappings":";;;;AAAA,wCACC,IAAY,EACZ,OAAO,GAA+B,EAAE;IAExC,MAAM,KAAK,GAAG,OAAO,CAAC,aAAa,IAAI,WAAW,CAAC;IACnD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAClD,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEjG,IACC,UAAU,CAAC,MAAM,KAAK,CAAC;QACvB,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QACvB,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;QACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;QACtB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;QACtB,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,IAAI,CAAC,EAC3C,CAAC;QACF,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,8CAA8C,IAAI,EAAE,CAAC,CAAC;IAC/E,CAAC;IAED,OAAO,UAAU,CAAC;AACnB,CAAC;AAED,2BAAkC,IAAY,EAAE,IAAY;IAC3D,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC;IACvD,MAAM,cAAc,GAAG,8BAA8B,CAAC,IAAI,CAAC,CAAC;IAE5D,OAAO,cAAc,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,cAAc,EAAE,CAAC,CAAC,CAAC,GAAG,cAAc,IAAI,cAAc,EAAE,CAAC;AAC9F,CAAC"}
+{"version":3,"file":"workspace-paths.js","sourceRoot":"","sources":["../../src/workspace/workspace-paths.ts"],"names":[],"mappings":";;;;AAWA,SAAS,wBAAwB,CAAC,IAAY,EAAE,aAAqB;IACpE,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC/C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEnC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAC/C,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IAClC,OAAO,SAAS,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACnF,CAAC;AAED,wCACC,IAAY,EACZ,OAAO,GAA0C,EAAE;IAEnD,MAAM,KAAK,GAAG,OAAO,CAAC,aAAa,IAAI,WAAW,CAAC;IACnD,IAAI,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAChD,IAAI,OAAO,CAAC,aAAa,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACtD,OAAO,GAAG,wBAAwB,CAAC,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IACpE,CAAC;IACD,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEjG,IACC,UAAU,CAAC,MAAM,KAAK,CAAC;QACvB,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QACvB,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;QACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;QACtB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;QACtB,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,IAAI,CAAC,EAC3C,CAAC;QACF,MAAM,IAAI,KAAK,CACd,GAAG,KAAK,8CAA8C,IAAI,IAAI;YAC7D,4EAA4E,CAC7E,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAC;AACnB,CAAC;AAED,2BAAkC,IAAY,EAAE,IAAY;IAC3D,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC;IACvD,MAAM,cAAc,GAAG,8BAA8B,CAAC,IAAI,CAAC,CAAC;IAE5D,OAAO,cAAc,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,cAAc,EAAE,CAAC,CAAC,CAAC,GAAG,cAAc,IAAI,cAAc,EAAE,CAAC;AAC9F,CAAC"}

package/knowledge-base/reference/anthropic-output-shape.md

@@ -0,0 +1,72 @@
+# Anthropic node output shape
+
+Node type: `@n8n/n8n-nodes-langchain.anthropic`
+
+Use this when mapping downstream fields from an Anthropic node with
+`$json.<field>` or `$('NodeName').item.json.<field>`, or when parsing its
+output in a Code node.
+
+## Text → Message (`resource: text`, `operation: message`)
+
+With **Simplify Output** enabled (default), the node emits:
+
+```json
+{
+  "content": [
+    { "type": "text", "text": "..." }
+  ],
+  "merged_response": "..."
+}
+```
+
+**`$json.content` is an ARRAY of content blocks, not a string.** Never treat
+`$json.content` itself as the reply string.
+
+**`content[0]` is not guaranteed to be a text block.** The array is passed
+through from the Messages API unfiltered: with **Web Search** or **Code
+Execution** enabled it also contains `server_tool_use` and
+`*_tool_result` blocks, and citations can split the answer across multiple
+`text` blocks. Read the assistant text with one of:
+
+- **`$json.merged_response`** — all `text` blocks joined into one string; the
+  simplest field to consume downstream. Only present when the node option
+  **Include Merged Response** is enabled, so prefer enabling it.
+- **`$json.content.find(c => c.type === 'text')?.text`** — the first text
+  block, safe regardless of node options. Keep the `?.`: a turn can end with
+  no text block at all (e.g. cut off mid-tool-use by the iteration cap or
+  `max_tokens`).
+- `$json.content[0].text` — only safe in the plain default configuration
+  (no web search / code execution).
+
+### Parsing model-generated JSON in a Code node
+
+When you ask the model to reply with JSON, the JSON string lives inside a
+text block. Parse the text block's `text`, not `content`:
+
+```javascript
+// Correct
+const text = $json.content.find((c) => c.type === 'text')?.text;
+if (!text) throw new Error('Model returned no text block');
+const parsed = JSON.parse(text);
+
+// Wrong — content is an array of blocks, JSON.parse will throw
+const parsed = JSON.parse($json.content);
+```
+
+Models often wrap JSON in markdown fences even when told not to; strip them
+defensively before parsing:
+
+```javascript
+const text = $json.content.find((c) => c.type === 'text')?.text ?? '';
+const raw = text.trim().replace(/^```(?:json)?\s*/, '').replace(/\s*```$/, '');
+const parsed = JSON.parse(raw);
+```
+
+### Caveats
+
+- **`simplify: false`**: `$json` is the full Messages API response (`id`,
+  `role`, `model`, `content`, `stop_reason`, `usage`, …). The `content` array
+  has the same shape and the same non-text-block caveats as above.
+- **No response-format option.** Unlike the OpenAI node, the Anthropic node
+  has no `json_object`/`json_schema` output mode — JSON replies always arrive
+  as a string inside a text block and must be parsed by you.

package/knowledge-base/reference/open-ai-output-shape.md

@@ -52,6 +52,9 @@ reference:
   Pick the index that matches the text you need.
 - **Structured / JSON output** (`text.format.type` of `json_object` or
   `json_schema`): `content[].text` is parsed into an **object**, not a string.
+  In a Code node, use it directly (`$json.output[0].content[0].text.someField`)
+  — calling `JSON.parse`, `.slice`, `.trim`, or other string methods on it will
+  throw or misbehave.
 - **`simplify: false`**: `$json` is the full Responses API payload (`id`, `status`,
   `output`, `usage`, …). Message text is still under `output`, but `output` may
   also include non-message items (reasoning, tool calls, etc.).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@n8n/instance-ai",
-  "version": "1.19.3",
+  "version": "1.20.1",
   "main": "dist/index.js",
   "module": "src/index.ts",
   "types": "dist/index.d.ts",
@@ -38,7 +38,7 @@
     "@mozilla/readability": "^0.6.0",
     "@opentelemetry/api": "1.9.1",
     "@thednp/dommatrix": "^2.0.12",
-    "ai": "^7.0.37",
+    "ai": "^7.0.48",
     "csv-parse": "6.2.1",
     "fast-glob": "3.3.3",
     "flatted": "3.4.2",
@@ -52,20 +52,20 @@
     "psl": "1.9.0",
     "source-map-support": "0.5.21",
     "turndown": "^7.2.2",
-    "undici": "^7.28.0",
+    "undici": "^7.29.0",
     "@e965/xlsx": "0.20.3",
     "zod": "3.25.76",
     "zod-from-json-schema-v3": "npm:zod-from-json-schema@^0.0.5",
-    "@n8n/agents": "0.19.3",
-    "@n8n/ai-utilities": "0.27.2",
-    "@n8n/api-types": "1.34.2",
-    "@n8n/utils": "1.42.0",
-    "@n8n/mcp-browser": "0.16.0",
-    "@n8n/workflow-sdk": "0.27.2",
-    "n8n-workflow": "2.34.2"
+    "@n8n/agents": "0.20.1",
+    "@n8n/ai-utilities": "0.28.1",
+    "@n8n/api-types": "1.35.1",
+    "@n8n/mcp-browser": "0.17.0",
+    "@n8n/utils": "1.43.0",
+    "@n8n/workflow-sdk": "0.28.0",
+    "n8n-workflow": "2.35.0"
   },
   "devDependencies": {
-    "@ai-sdk/anthropic": "^4.0.20",
+    "@ai-sdk/anthropic": "^4.0.27",
     "@langchain/core": "1.2.0",
     "@types/luxon": "3.2.0",
     "@types/psl": "1.1.3",
@@ -77,7 +77,7 @@
     "vitest": "^4.1.9",
     "vitest-mock-extended": "^3.1.0",
     "@n8n/typescript-config": "1.9.0",
-    "@n8n/vitest-config": "1.19.0"
+    "@n8n/vitest-config": "1.20.0"
   },
   "license": "SEE LICENSE IN LICENSE.md",
   "homepage": "https://n8n.io",

package/skills/agent-builder/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: agent-builder
+description: >-
+  Load before calling build-agent for a new or existing n8n Agent. Governs
+  prerequisite creation, faithful handoff of the user's request, agent
+  targeting across turns, builder questions, testing, and publishing. Use
+  directly for routine follow-ups when the conversation already targets an
+  Agent; rerun intent-recognition only when the requested artifact is no
+  longer clear.
+recommended_tools:
+  - build-agent
+  - build-workflow
+  - data-tables
+---
+
+# Agent Builder
+
+## Routing
+
+Use this skill after `intent-recognition` chooses an agent-anchored design, or
+when the conversation already targets an Agent and the user is continuing that
+build. Do not rerun intent recognition for routine Agent edits or extensions.
+Use `build-agent` only for Agent artifacts.
+
+## Faithful handoff
+
+Treat `message` as a faithful handoff of the user's request, not an Agent build
+specification authored by you. Forward the user's wording as close to verbatim
+as possible. Include only:
+
+- Requirements, constraints, and implementation choices the user explicitly
+  stated.
+- Explicit answers or decisions from earlier turns that are necessary for the
+  current request.
+- Prerequisite workflows or data tables you created for this Agent.
+
+Never infer, invent, expand, recommend, or prescribe implementation details the
+user did not request, and never present your assumptions as user requirements.
+In particular, do not choose or tell the builder which model, instructions,
+tools, tool types, integrations, channels, MCP servers, workflows, skills,
+tasks, memory, credentials, triggers, schedules, approvals, or test strategy to
+use.
+
+Do not translate an outcome or named service into a specific implementation.
+For example, forward "a Slack agent that says hello to me" without turning it
+into a request for a Slack node tool. Preserve unspecified and ambiguous
+implementation details so the builder can resolve them with its own guidance
+and interactive tools.
+
+## Prerequisites
+
+Before the first `build-agent` call, create every prerequisite the builder
+cannot create:
+
+- Create a workflow tool only when one Agent tool call must run an ordered
+  multi-node procedure, or when the user explicitly needs that workflow to be
+  reusable, manually callable, or usable outside the Agent. Follow
+  `workflow-builder`, then pass the built workflow in `workflowContext`.
+- When the Agent will store or query tabular data, follow `data-table-manager`
+  and create the required tables via `data-tables`. The builder cannot create
+  tables.
+
+List prerequisite names and schemas in `message`. Let the builder gather the
+remaining Agent-specific requirements, including model, credentials,
+integrations, and direct tools.
+
+If a `builderReply` lists missing workflows or tables, create them and call
+`build-agent` again. Never ask the user to create them manually.
+
+## Targeting across turns
+
+Address Agents in this conversation with `agentRef`, a short stable key similar
+to a workflow `filePath`.
+
+- For the first Agent, pass a fresh `agentRef` and `name`.
+- Reuse that `agentRef` on later calls. Calls with neither `agentRef` nor
+  `agentId` continue editing the current Agent.
+- To build an additional Agent, pass `createNew: true` with a different
+  `agentRef` and `name`.
+- To edit an Agent not built in this conversation, pass its `agentId` once,
+  optionally with an `agentRef`, then prefer the returned `agentRef`.
+
+Naming or renaming the current Agent never silently creates another one.
+
+## Builder-owned interactions
+
+When the user asks to test, run, publish, activate, make usable, unpublish, or
+otherwise change the Agent, forward that intent in `message`. The builder owns
+its internal testing tools; do not conclude testing is unavailable because
+those tools do not appear in your toolset.
+
+When the builder needs a user choice, credential, chat channel, or approval, it
+surfaces an interactive card in this chat. Do not relay the question yourself;
+the `build-agent` call resumes with the user's answer.

package/skills/credential-recipe-research/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: credential-recipe-research
+description: >-
+  Lookup procedure for Simplified Custom Auth recipe fields — sources the auth
+  template, the key-issuing docsUrl and an auth-rejecting testUrl from the
+  provider's real documentation instead of memory. Load before composing
+  credentialHints for a service without a dedicated credential type (the
+  post-build-flow setup step), or when asked to fix a recipe whose template,
+  key page or test endpoint is wrong.
+recommended_tools:
+  - research
+  - workflows
+---
+
+# Credential Recipe Research
+
+A recipe is only as good as the documentation it came from. This is a
+procedure, not guidance: execute every step with the `research` tool and keep
+only findings you can point to on a fetched page. Guessed URLs are how users
+end up on the wrong page with a key that can't be verified.
+
+Inputs: the service name and the API host(s) the workflow's nodes call.
+
+## 1. Auth scheme (template)
+
+Fetch the provider's authentication docs — `research(action="web-search")`
+with `"<service> API authentication"`, then `fetch-url` the best docs hit.
+Record the scheme EXACTLY as documented: header name, prefix word, casing
+(`Authorization: Key {{api_key}}` vs `Bearer {{api_key}}` vs a custom header
+like `xi-api-key`). If the documented auth is basic, digest, or OAuth, stop:
+that is not expressible as a template — use the matching generic type instead
+(see the workflow-builder skill's credential ladder).
+
+## 2. Key page (docsUrl)
+
+Find where a logged-in user CREATES or COPIES the key. The URL is not shown
+in the form — the AI Assistant help thread presents it as THE place to get
+the value, so a wrong URL sends the user to a dead end with full confidence:
+
+- Search `"<service> dashboard API keys"`, and scan the fetched auth docs for
+  phrases like "get your key from", "Dashboard → API Keys", "console",
+  "settings".
+- The answer normally lives on an app/console/dashboard host —
+  `console.apify.com/settings/integrations`,
+  `elevenlabs.io/app/settings/api-keys`, `replicate.com/account/api-tokens`,
+  `app.tavily.com/home` — not under `/docs`, `/reference`, or
+  `/documentation`.
+- Accept a docs-domain URL only when the fetched page shows keys are actually
+  issued there (some ReadMe-style logged-in portals do).
+- NEVER construct a dashboard path by analogy (`/account/api-keys`,
+  `/dashboard/keys`, …). Dashboards are apps behind a login: a fetch answers
+  200 for any invented route, so the path cannot be verified by fetching.
+  Emit a deep dashboard URL only when it appears VERBATIM on a page you
+  fetched; when the docs only describe navigation ("Dashboard → API Keys")
+  without a literal URL, use the dashboard/app root they reference — a
+  shallower real page beats a deeper invented one.
+- Nothing conclusive after both steps → omit docsUrl. Never pass off the API
+  reference as the key page.
+
+## 3. Verification endpoint (testUrl)
+
+Find a documented, side-effect-free GET that rejects a bad key with 401/403.
+Check the API reference in this order and stop at the first qualifying hit:
+
+1. Account/profile/me endpoints — `/v1/account`, `/v2/users/me`, `/v1/user`.
+2. Usage/quota endpoints — e.g. fal's `/v1/models/usage`, Tavily's `/usage`.
+3. List/discovery endpoints — `/v1/templates`, `/v1/models`, `/v1/voices`.
+
+Rules, all mandatory:
+
+- The endpoint must appear on a page you fetched — never construct a path by
+  analogy with other APIs.
+- Never one of the workflow's own endpoints, never a resource or action URL,
+  never anything that can trigger billable work. Setup rejects workflow-URL
+  collisions, and the probe reports unexpected statuses as "could not be
+  verified" — an invented URL only costs the user trust.
+- Skip endpoints that answer 2xx regardless of the key: auth-optional
+  endpoints (Pexels search) or services that signal auth errors in the
+  response body (Apollo's `auth/health`, TikTok) — a status probe cannot
+  verify through them.
+- Nothing qualifies → omit testUrl. The credential saves fine and the card
+  honestly reports it could not be verified, which beats a false green.
+
+## 4. Compose
+
+Fill `credentialHints` (field list and example in the post-build-flow skill)
+from the findings above only. `suggestedName` names the service ("Apify API
+Token"); never include a real secret.

package/skills/debugging-executions/SKILL.md

@@ -31,7 +31,8 @@ name what is unconfirmed instead of repeating a success claim.
 
 Use `executions(action="run")` with `inputData` matching the trigger's output
 shape — do not rebuild the workflow with a Manual Trigger. For trigger
-`inputData` shapes, read `knowledge-base/reference/trigger-input-data-shapes.md`
+`inputData` shapes, read
+`${N8N_WORKSPACE_DIR}/knowledge-base/reference/trigger-input-data-shapes.md`
 when a sandbox workspace is available.
 
 ## Failed execution

package/skills/intent-recognition/SKILL.md

@@ -5,24 +5,25 @@ description: >-
   owns the top-level control flow — workflow-anchored, agent-anchored,
   needs-clarification, or out-of-scope) and embeds_other (whether the other
   primitive appears embedded inside — an agent step inside a workflow, or a
-  workflow invoked as an agent tool). Must be used before deciding the intent
-  of any automation request, including compound requests with multiple
-  independent automations, mid-build extensions to an existing workflow or
-  agent, one-off questions or reports that need external systems you cannot
-  query directly, and requests that need clarification before an anchor can
-  be chosen, before choosing workflow-builder, planning, or an agent-oriented
-  design.
+  workflow invoked as an agent tool). Must be used whenever the current turn
+  requires choosing or reconsidering the intent of an automation request,
+  including compound requests, independent automations introduced mid-build,
+  one-off questions or reports that need external systems you cannot query
+  directly, and requests that need clarification before an anchor can be
+  chosen. Do not load for routine edits or extensions when the conversation
+  already targets a workflow or Agent.
 ---
 
 # Intent recognition
 
 ## Purpose
 
-Use this skill to classify an automation request before designing or building
-it. This skill must be used before deciding whether a request is
-workflow-anchored, agent-anchored, needs clarification, or out of scope, and
-before deciding whether the other primitive is embedded inside it. The
-deciding question is not a single "workflow or agent" label — it is two
+Use this skill when an automation request still needs to be classified before
+designing or building it, or when a new turn may require reconsidering the
+current artifact. Do not load it again for a routine edit or extension when the
+conversation already targets a workflow or Agent, unless the user introduces
+an independent automation or the new request carries its own anchor signal.
+The deciding question is not a single "workflow or agent" label — it is two
 questions: who owns the top-level control flow, and does the other primitive
 show up inside that flow.
 
@@ -76,8 +77,8 @@ Two orthogonal decisions per request, or per part for compound requests:
 
 - workflow-anchored + `true`: an agent embedded as a workflow step (e.g. a
   scheduled pipeline whose middle step is open-ended investigation).
-- agent-anchored + `true`: workflows invoked as tools of the agent; see Adding
-  tools to an agent to distinguish them from direct tools.
+- agent-anchored + `true`: workflows invoked as tools of the agent; see Agent
+  tool shape to distinguish them from direct tools.
 - `n/a` for needs-clarification and out-of-scope.
 
 **Migration from the old taxonomy**: old **hybrid** → workflow-anchored,
@@ -87,37 +88,29 @@ only when the user wants a persistent, triggerable automation. Old
 **ambiguous** → needs-clarification. Old **workflow** and **agent** map
 directly onto the matching anchor value.
 
-## Adding tools to an agent
+## Agent tool shape
 
 After choosing an agent-anchored design, decide whether each capability should
 be a direct agent tool or a workflow tool:
 
-- **Direct agent tools are the default.** Forward requests to add capabilities
-  to `build-agent` near-verbatim so the delegated builder can choose MCP,
-  node-backed, provider, or custom tools. One node-backed capability or
-  multiple independent node tools stay on the agent build path with
+- **Direct agent tools are the default.** One node-backed capability or multiple
+  independent node tools stay on the Agent build path with
   `embeds_other: false`.
 - Use a **workflow tool** only when one agent tool call must run an ordered
   multi-node procedure, or when the user explicitly needs that workflow
   reusable, manually callable, or usable outside the agent. Build the workflow
   first, pass it to `build-agent` via `workflowContext`, and set
   `embeds_other: true`.
-- Create required **data tables** via `data-table-manager` → `data-tables`
-  before `build-agent` when the agent will store or query tabular data — the
-  builder cannot create tables.
-- Before the first `build-agent` call, create every prerequisite the builder
-  cannot: required data tables and any workflow tools the agent will invoke.
-  Pass built workflows in `workflowContext` and list every prerequisite
-  name/schema in `message`. Then let the builder gather remaining agent-specific
-  requirements (model, credentials, integrations).
-- If a `builderReply` lists missing workflows or tables, create them and call
-  `build-agent` again — never ask the user to create them manually.
 
 Count the nodes required inside one tool invocation, not the total number of
 tools on the agent. For example, looking up and inserting Data Table rows are
 two direct node tools; an atomic lookup-transform-write procedure is one
 workflow tool.
 
+After choosing an agent-anchored design, load `agent-builder` before calling
+`build-agent`. It owns prerequisite creation and the handoff to the delegated
+builder.
+
 ## Decision Steps
 
 0. If the user is mid-build on an existing workflow or agent, apply context
@@ -224,7 +217,7 @@ that agent, never a spawned workflow.
   that drafts a tailored renewal pitch for each account from its usage
   history embeds an agent; a nightly job that condenses each ticket into a
   two-sentence summary does not.
-- For an agent with workflow tools, apply Adding tools to an agent.
+- For an agent with workflow tools, apply Agent tool shape.
 
 **Context continuity** (step 0): inside a workflow build, a request to insert
 a scoring step stays a bounded LLM step, not a new agent. Inside an agent

package/skills/planning/SKILL.md

@@ -58,11 +58,13 @@ with direct `data-tables` and `parse-file` calls.
 
 ## Knowledge Base
 
-**Consult the knowledge base before planning.** Read the relevant `.md` guides
-and templates for each technique the request involves (`knowledge-base/index.json`,
-`knowledge-base/best-practices/index.json`, and linked files). Use
-`workspace_execute_command` with `rg` or `find` under `knowledge-base/templates/`
-to locate matching SDK examples — never load `templates/index.json` wholesale.
+**Consult the knowledge base before planning.** It lives at the workspace root.
+Read the relevant `.md` guides and templates for each technique the request
+involves (`${N8N_WORKSPACE_DIR}/knowledge-base/index.json`,
+`${N8N_WORKSPACE_DIR}/knowledge-base/best-practices/index.json`, and linked
+files). Use `workspace_execute_command` with `rg` or `find` under
+`${N8N_WORKSPACE_DIR}/knowledge-base/templates/` to locate matching SDK
+examples — never load `templates/index.json` wholesale.
 Skip only for trivial mechanical edits you have already reviewed in this thread.
 
 ## Method