/workflow-builder

name: workflow-builder
description: >-
  Load before calling workflow_builder_build_workflow. Once the user wants a
  workflow, load it before you ask about that workflow. Do not load it to ask
  about a request that does not yet say what to build. Use for new one-off
  workflows, edits, repairs and post-build verification of one workflow (not
  requests only to run or inspect a saved workflow), and for its
  credentials, model choices, evaluations and error workflow. For any other new
  workflow, load intent-recognition first when it is listed. If the workflow
  writes Data Tables, load data-table-manager first. Do a one-time request (no
  repeat or trigger words) now, without asking whether to repeat it; for one
  node, load one-off-operations and use execute_node.

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 write TypeScript with `@n8n/workflow-sdk`. All work goes through one workspace source file and the `workflow_builder_build_workflow` tool (argument: `filePath`):

• **New workflow:** write the complete source with `workspace_write_file`

(typically `src/workflows/main.workflow.ts`), then build.

• **Edit or repair of a saved workflow:** reuse the source file already in

context. If you only have a workflow ID, call `get_workflow_as_code` with `workflowId`: it writes the source to a bound `src/workflows/<name>.workflow.ts` file and returns the `filePath` plus a `nodes` index with line numbers. Read only the lines you need, make the smallest edit with `workspace_str_replace_file`, then build with the same `filePath` (no `workflowId` needed; the build remembers it). Never re-emit the whole source, and do not fetch the same unchanged workflow again.

When the needed node types are already obvious from the request, make one `find_tools` call for every tool catalog tool the build will need (for example `search_nodes`, `get_node_types`, `workflow_builder_build_workflow`, `workflow_builder_verify_built_workflow`) in the same response as the `load_skill` call for this skill. Each extra sequential turn resends the whole context.

Process

1. **Find nodes.** If unsure which nodes fit, call `search_nodes` with `categories` (`notification`, `data_persistence`, `chatbot`, `scheduling`, `data_transformation`, `data_extraction`, `document_processing`, `form_input`, `content_generation`, `triage`, `scraping_and_research`). Call `search_nodes` with `query`/`queries` and short service names ("Gmail") for service-specific nodes. 2. **Read definitions.** Call `get_node_types` with the exact node IDs and discriminators you will use (up to ten per call). Follow `@builderHint`, `@default`, enum values, credential types and display conditions. 3. **Resolve real values.** For each `searchListMethod`, `loadOptionsMethod` or `resourceLocator` parameter, call `get_node_parameter_options` when a credential is available. For new model choices, follow `model-selection`. 4. **Announce credentials early.** When the `setup_credentials` schema offers `filePath`, call it with the complete list of known credential types right after the first node definitions, as the only tool call in that response. Wait for `preBuild: true`, then continue. Otherwise use the post-build setup. 5. **Write the source.** Decide node groups now (see [Node Groups](#node-groups)). When a live or nondeterministic node feeds IF/Switch logic whose branches need verification, declare `output` fixtures on it. 6. **Build.** Call `workflow_builder_build_workflow` with the `filePath`. Do not run a separate validation command before the build: the build runs the graph checks, the SDK source lint and the node schema checks.

• For new workflows, fix every blocking error.
• For edits, fix only the errors that your change introduced, and keep

unrelated existing nodes and code.

• Errors and warnings block the save. Informational findings do not.
• If the save stays blocked, report the blocker. Do not expand the scope.

7. **Trace wiring.** For IF, Switch, Merge, AI-agent, loop or multi-workflow wiring, trace each branch from source to target in the saved graph. Every requested side effect must be on a wired branch. 8. **Hand off.** If the build output contains `postBuildFlow.required: true`, follow the inlined `postBuildFlow.instructions` before verification, setup, publishing, testing, or any final summary. Do not call `workflow_builder_verify_built_workflow` directly from this skill for direct builds.

Keep visible text for the final step, unless blocked.

Asking and placeholders

If the service or workflow shape is clear, never stop before the first `workflow_builder_build_workflow` call to ask for setup values (recipients, IDs, channels, credential choices, timezone). Use `placeholder('descriptive hint')` for values only the user knows, and unresolved `newCredential()` calls. Never hardcode fake values, and never ask for setup values before the first successful build: `setup_workflow` opens an inline setup card in the n8n Assistant panel afterwards. Use `ask_user` before the build only when a missing choice changes the workflow's intent or topology. Never solicit secrets through `ask_user`.

Knowledge sources

**Prefer n8n sources over guessing.** Consult, in this order:

1. The knowledge base in the sandbox workspace, read with the workspace tools (not `load_skill`): `knowledge-base/index.json` (technique guides and reference docs), `knowledge-base/templates/` (search it; never load `templates/index.json` wholesale), and `node-types/index.txt` (searchable node catalog) 2. A matching runtime skill (`data-table-manager`, `debugging-executions`, …). 3. Official n8n docs: load `n8n-docs-assistant` and call `n8n-docs`.

For workflows with several external systems or effects, digests, non-trivial branching or C