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.
83%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
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):
workspace_write_file
(typically src/workflows/main.workflow.ts), then build.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.
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.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.searchListMethod, loadOptionsMethod or
resourceLocator parameter, call get_node_parameter_options when a
credential is available. For new model choices, follow model-selection.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.output fixtures on it.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.
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.
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.
Prefer n8n sources over guessing. Consult, in this order:
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)data-table-manager, debugging-executions, …).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.
Load a reference only when its trigger applies:
compositional-workflows.credential-choices reference.setupPreference or aiGateway, list_credentials
returns a Gateway credits entry, or the user asks about Gateway credits:
service-selection.data-table-playbook reference,
before the first query_data_table call.error-workflows reference.
settings.errorWorkflow must be the real ID of a separate published
workflow; n8n has no global error workflow setting.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.
list_credentials early when the task touches external services.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.list_credentials has no suitable instance, call
search_credential_types and prefer a dedicated credential type.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.
$getWorkflowStaticData
state, or a step that would need three or more nodes..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.@n8n/workflow-sdk.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.resource: 'message').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(), …{{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.
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.
n8n-io/n8n
c44c87a
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.