Gitpulse
Merged
Size
XL
Change Breakdown
Refactor75%
Bug Fix25%
#28338refactor(instance-ai): Harmonize prompting between builders (no-changelog)

Node search bug fixed as prompting logic unified across AI builder packages

OL
OlegIvaniv
·Apr 13, 2026

Shared prompting content moves into workflow-sdk, eliminating drift between instance-ai and ai-workflow-builder.ee. Multi-word node search queries also fixed.

The n8n team has untangled a duplication problem that had crept into their AI workflow builder tooling. Both the instance-ai package and the ai-workflow-builder.ee package maintained their own copies of prompting content — expression references, workflow rules, parameter guides, best-practices documentation, and node recommendations. When one team updated their prompts, the other drifted out of sync.

This PR centralizes all that shared content in @n8n/workflow-sdk/prompts, creating a single source of truth. The 46 source files containing the duplicated content (roughly 5,900 lines) have been deleted. Both packages now import from the same shared modules.

The refactor also surfaces a bug in the node search engine. When searching for tool nodes to attach to an AI Agent — for example, a multi-word query like "data table tool" combined with connectionType="ai_tool" — the search returned zero results. The root cause was that searchByConnectionType called the fuzzy search directly with the raw query string, which breaks on multi-word input. A new fuzzySearchNodes method handles per-term splitting and display-name fallback, and both searchByName and searchByConnectionType now share it.

The node search tool's parameter documentation was also improved to make it clearer that agents should use connectionType="ai_tool" when looking for tool nodes.

In the @n8n/instance-ai and packages, prompts now compose from granular imports rather than inlining hundreds of lines of SDK rules and patterns. The best-practices registry is wired up through the shared package, with five guides re-enabled that were previously commented out (data-analysis, enrichment, knowledge-base, human-in-the-loop, monitoring).

View Original GitHub Description

Summary

Both instance-ai and ai-workflow-builder.ee had their own forked copies of the same prompting content, expression references, workflow rules, parameter guides, best-practices docs, node recommendations. When one got updated the other drifted. This PR moves all of that shared content into @n8n/workflow-sdk/prompts (both packages already depend on workflow-sdk) so there's a single source of truth, then deletes the 46 dead files that got replaced.

Also fixes a bug in the search-nodes tool where multi-word queries like "data table tool" returned 0 results when combined with connectionType, which meant the builder couldn't find auto-generated tool nodes (dataTableTool, googleCalendarTool, etc).

What changed

Moved SDK reference constants (expression reference, additional functions, workflow rules, SDK patterns) into workflow-sdk/src/prompts/sdk-reference/. Both packages now import from there.

Moved all 11 parameter guides (IF, Switch, Set, HTTP, Gmail, etc.), 2 node tips (Webhook, Structured Output Parser), and 4 node recommendations (text/image/video/audio generation) into workflow-sdk/src/prompts/node-guidance/. Extracted types locally so there's no dependency on framework-specific packages.

Moved the WorkflowTechnique enum, BestPracticesDocument interface, and all 16 guide classes into workflow-sdk/src/prompts/best-practices/. This also wired up 5 guides that were previously commented out (data-analysis, enrichment, knowledge-base, human-in-the-loop, monitoring).

Replaced the ~300-line inline SDK_RULES_AND_PATTERNS block in instance-ai's builder prompt with composed imports from the shared parameter guides. The instance-ai-specific stuff (AI Agent subnodes, Code Node, Data Table, Google Sheets, web app pattern) stays local.

Deleted 46 original source files across both packages (~5,900 lines).

Fixed searchByConnectionType in the node search engine, it was calling sublimeSearch directly with the raw query string, which breaks on multi-word input. Extracted a fuzzySearchNodes method (with per-term splitting + display-name fallback) that both searchByName and searchByConnectionType now share. Also improved the connectionType param description so the agent actually knows to use connectionType="ai_tool" when looking for tool nodes to attach to an AI Agent.

Layout

@n8n/workflow-sdk/src/prompts/
├── index.ts
├── sdk-reference/          expressions, functions, rules, patterns
├── node-guidance/
│   ├── parameter-guides/   11 guides + types
│   ├── node-tips/          2 tips + types
│   └── node-recommendations/  4 recs + types + format utility
└── best-practices/
    ├── types.ts            WorkflowTechnique enum, interfaces
    └── guides/             16 guide classes + registry

Review / Merge checklist

  • I have seen this code, I have run this code, and I take responsibility for this code.
  • PR title and summary are descriptive. (conventions) <!-- **Remember, the title automatically goes into the changelog. Use `(no-changelog)` otherwise.** -->
  • Docs updated or follow-up ticket created.
  • Tests included. <!-- A bug is not considered fixed, unless a test is added to prevent it from happening again. A feature is not complete without tests. -->
  • PR Labeled with Backport to Beta, Backport to Stable, or Backport to v1 (if the PR is an urgent fix that needs to be backported)
© 2026 · via Gitpulse