Index of every page on this site: llms.txt
All skills
n8n-io avatar

/workflow-builder

@273d130 official
by n8n - Workflow Automationn8n-io/n8n211k stars
61,599
Run it yourself

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.

  • 15 files
  • 81.8 KB
  • Updated 2 days ago
  • GitHub
Use this Skill: https://skilld.dev/gh/n8n-io/n8n/workflow-builder

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈184 tokens for metadata: the name and description. ≈2.9k when used: this file. ≈18k more on demand in 14 files.

Description uses 9.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈737 characters, or 9.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.
  • Several files: when one step writes or changes two or more files (for example the sources of several supporting workflows), put them all in one workspace_edit_files call, not one call for each file. Read two or more files with one workspace_read_files call.

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 once with every node the workflow could need, not only the service nodes. Include utility nodes (Set, IF, Switch, Code, Wait, Sort, Filter) in that first call. There is no limit on how many you request. Fetch again only for a node you did not expect. Use exact node IDs and discriminators. 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). 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) 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 Code nodes, read knowledge-base/reference/workflow-builder-guardrails.md before writing code.

References

Load a reference only when its trigger applies:

  • Multi-workflow decomposition (reusable or independently testable parts): compositional-workflows.
  • The user explicitly asks for a new credential, or you choose HTTP Request authentication: the credential-choices reference.
  • Discovery results carry setupPreference or aiGateway, list_credentials returns a Gateway credits entry, or the user asks about Gateway credits: service-selection.
  • Diagnosing a Data Table lookup miss: the data-table-playbook reference, before the first query_data_table call.
  • Building or attaching an error workflow: the error-workflows reference. settings.errorWorkflow must be the real ID of a separate published workflow; n8n has no global error workflow setting.

Verification

The inlined postBuildFlow.instructions decide who verifies and how. This section applies only when they or the current turn make you responsible.

Build/save success is not workflow-quality evidence. Inspect the persisted workflow (the bound source file, or get_workflow_as_code with workflowId when it may have changed outside this conversation) and judge it against the user's requested outcome. Claim a workflow works only from a workflow_builder_verify_built_workflow or run_workflow run that exercised the claimed path; otherwise say what you could not verify.

The job is done when the workflow is verified by tool evidence, setup is routed or deferred, a remediation guard says shouldEdit: false, or you are blocked after one repair attempt per unique failure signature. On shouldEdit: true, make one batched repair in the source file and rebuild with the same filePath.

Credential Rules

  • Call list_credentials early when the task touches external services.
  • Use newCredential('Credential Name', 'credential-id') only when the user selected a credential, exactly one unambiguous match exists, or the workflow already had it. Otherwise use newCredential('Suggested Credential Name'); setup collects real ones later.
  • When list_credentials has no suitable instance, call search_credential_types and prefer a dedicated credential type.

SDK Code Rules

The SDK source lint in workflow_builder_build_workflow reports common SDK and Code-node defects, such as forbidden imports in Code nodes or an unsolicited sticky(). Fix every reported finding, then build again.

  • Native node first: shape, compute and format fields with Edit Fields (Set) and expressions; use Filter, IF / Switch, Sort, Remove Duplicates, Aggregate, Split Out, Limit and Merge for the rest. A Code node is only for multi-pass algorithms, $getWorkflowStaticData state, or a step that would need three or more nodes.
  • Write Code nodes in JavaScript unless the user explicitly asks for Python.
  • SDK source builds a static graph and does not run. Build strings with template literals, not .map() or .join(). Do runtime joining, aggregation, or transforms with expr() in a native node. For values an agent supplies to a tool, write fromAi(...) directly, never ($) => $.fromAi(...). Full allowed/forbidden list and "Native node mappings" table: knowledge-base/reference/workflow-sdk-language.md.
  • Import only the symbols you use from @n8n/workflow-sdk.
  • Use expr('{{ $json.field }}') for expressions. $json is only the current item from the immediate predecessor; use $('Node').item.json.field or nodeJson(node, 'field') for anything further upstream.
  • Use string values for discriminators (resource: 'message').
  • Always use newCredential() for authentication, never placeholder strings or invented IDs.

Define nodes first, then compose:

const startTrigger = trigger({
  type: 'n8n-nodes-base.manualTrigger',
  version: 1,
  config: { name: 'Start' },
});

const fetchData = node({
  type: 'n8n-nodes-base.httpRequest',
  version: 4.3,
  config: { name: 'Fetch Data', parameters: { method: 'GET', url: placeholder('API URL') } },
});

const isImportant = ifElse({ version: 2.2, config: { name: 'Is Important', parameters: { conditions } } });

export default workflow('id', 'name')
  .add(startTrigger)
  .to(fetchData)
  .to(isImportant)
  .onTrue(handleImportant)                               // single step
  .onFalse(sendHolding.to(createTicket.to(alertSlack))); // chained multi-step
// Inline form: .to(isImportant.onTrue(a).onFalse(b)). Fan-out: .onFalse([a, b, c])
// Switch: .onCase(0, a).onCase(1, b). Merge: wire sources to combine.input(0), combine.input(1).
// Errors: .to(fetchNode).onError(notify). AI subnodes: languageModel(), memory(), tool(), …

Node Groups

{{GROUPING_GUIDANCE_PLACEHOLDER}}

Declare a group with .group(name, members, { description }) on the workflow builder; members are the node handles. Before you emit a .group(...), read knowledge-base/reference/node-groups.md for the rules that make a group valid. An invalid group is dropped with a warning: fix what the warning reports and build again. A GROUPING_DECISION_MISSING error means the build was refused: add groups, or pass groupingDecision: 'not_warranted' with a groupingReason. If the top level is still above {{TOP_LEVEL_ITEM_CEILING_PLACEHOLDER}} items with groups in place, name each remaining item and why it cannot join a group.

Completion

For a successful build, finish with one concise sentence naming the workflow and what changed, with the workflow ID when available. If setup is required, say so plainly; do not tell the user to leave the n8n Assistant panel. For a Webhook, Form or Chat Trigger, follow Trigger URL Sharing in the post-build-flow reference.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 273d130. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 days ago
  • TypeScript
  • n8n
  • workflow
  • automation
  • nodes
  • data-tables
  • credentials
  • sdk

README badge

README badge for n8n-io/n8n/workflow-builder

Generates and maintains n8n workflows using the TypeScript SDK, handling new workflows, edits, repairs, and workflow-local data tables. Use this skill directly for single-workflow builds without planning overhead; load planning only when coordinating multiple workflows or shared cross-task data structures.

Generated from the current SKILL.md.

When should I load this skill versus the planning skill?
Load workflow-builder directly for all single-workflow requests, including new workflows and edits. Load planning only when you need to coordinate multiple workflows or share data across them.
Can I use this skill to build workflows with the TypeScript SDK?
Yes. This skill generates complete, valid TypeScript code using @n8n/workflow-sdk and handles the full build-to-verification cycle.
Does this skill patch existing workflows or only create new ones?
It handles both. For small fixes, it uses patch mode to replace exact code segments. For larger rewrites, it rebuilds the full workflow.
What do I do if a required credential is missing?
The skill will block and report which credential setup is required before continuing. Credential collection is routed through workflow setup surfaces, not through the skill itself.
Does the skill verify the workflow after building it?
Verification follows the orchestrator's post-build flow. If the current turn is responsible for verification, the skill will inspect and test the saved workflow; otherwise, a checkpoint task handles it.

Generated from the current SKILL.md. These answers refresh after source changes.