build-workflow

---
name: build-workflow
description: "Build an n8n workflow using the code open in the workspace, then validate and test it before calling it done. Use when the user asks to create, build, or change an n8n workflow, to automate a task, to add a scheduled job or a webhook, or to connect n8n to the application in this repository. Triggers: build an n8n workflow, automate this, add a webhook, schedule this, wire n8n to my API, create a workflow."
compatibility: Requires Kiro with Agent Plugins support and n8n 2.34.0 or later with workflow builder tools enabled.
metadata:
  author: n8n
  version: "1.0.0"
---

# Building n8n workflows from Kiro

Apply the [connect-n8n pre-flight](../connect-n8n/SKILL.md) before the first n8n
tool call in a conversation. Use the tools and schemas the server actually lists.
Use the native connection selected by that preflight throughout the task. If
multiple instances are present, resolve the intended one before any write.

The n8n MCP server sends its own build instructions when it connects. Those cover
the tool sequence: read the SDK reference, get best practices, discover nodes, get
node types, validate, then save. **Follow them. Do not re-derive them and do not
work around them.**

Locate `get_workflow_sdk_reference` and `get_workflow_best_practices` in the
advertised tools and use their returned schemas. If Kiro truncates the activation
result, read its saved tool response before choosing a tool. Do not guess a tool
name from the task description or skip the references when a guessed name fails.

Kiro 1.1.70's bundled-power activation text omits nested schemas and enum choices.
Native MCP workflow updates still need acceptance testing.
Reading the saved response does not restore those omitted fields. If a needed
object or array schema is missing, report that client limitation before the
affected call; do not construct unknown arguments by trial and error. See the
[setup troubleshooting](../../docs/setup-helper.md#troubleshooting).

This file covers what the server cannot know: you are in an editor, with the
user's code open.

## Use the workspace

A chat client building an n8n workflow only has what the user typed. You have the
repository. Read it before you ask.

- **Find the real endpoint.** If the user wants a workflow that calls their API,
  read the route definitions rather than asking for the URL. Match the actual path,
  method, and payload shape.
- **Match the payload to the code.** When a workflow posts to the user's service,
  build the body from the type or schema in the repo, not from a guess.
- **Read the environment files.** `.env.example`, `docker-compose.yml`, and the
  config module tell you the hostnames and ports the workflow has to reach. Never
  read secrets out of `.env` and never put a secret into a workflow. Use an n8n
  credential.
- **Check what already exists.** Search the repo for existing webhook handlers or
  cron jobs before you build a workflow that duplicates one.

## Wiring n8n to code under development

When the workflow and the application talk to each other, say which side owns
what, and build both halves.

**n8n calls the application.** The workflow needs a reachable URL. `localhost` in
a cloud n8n instance means the n8n container, not the user's machine. Say this
explicitly rather than building something that silently cannot work. Offer a
tunnel, a deployed environment, or a self-hosted n8n on the same network.

**The application calls n8n.** The workflow needs a Webhook trigger. Build the
workflow first, read the production webhook URL off it, then write the calling
code in the repo with that URL. Do not invent the URL. The production endpoint
requires publication; a saved draft or a pinned test does not make it live.

**Both.** Build and validate the n8n side first. Then write the application side
against the returned URL and contract. Keep the real round trip marked unverified
until you have tested the reachable endpoint with the user's authorization.

## Test before you claim it works

The build loop has a verification step and it is not optional.

- Validate before you save. A validation error is cheaper than a failed run.
- Test after you save, and **read the result**. Report whether the test used
  simulated external outputs or real integrations.
- Report what the test actually returned. If it failed, say so and fix it. Do not
  describe an untested workflow as done.

Use the pin-data preparation tool the server lists. It returns output schemas;
generate sample items that match them and pass those items to `test_workflow`.
Inspect the actual pin-data map before running: a node omitted from that map is
not made safe merely by the tool's name.

A successful pinned test verifies only the nodes that executed against those
samples. It cannot prove an API URL, credential, external request, or webhook
round trip works when that part was simulated. State which nodes were pinned
and what still needs a real check. Do not publish just to obtain a green test.

### A test run is not a dry run

The pin-data preparation tool identifies triggers, credentialed nodes, and HTTP
Request nodes for simulation. **Unpinned nodes execute for real**, including
Execute Command, file reads and writes, and Code nodes that do their own I/O.

Before testing, inspect the unpinned nodes and their effects. Check again after
an edit that changes those effects or after changing the pin data.

- If every unpinned node is pure data shaping (Set, If, Merge, plain Code), test
  without asking.
- If an unpinned node does I/O or changes state, name the node, target, and effect.
  Obtain authorization for that effect before the call unless the user has
  already authorized it. For example: "The unpinned Execute Command node will
  write a file on the n8n execution host. May I run that test?" A pinned Slack
  node does not send a message.
- If the user declines, validate and stop there. Tell them the workflow is
  unverified and why, rather than quietly calling it done.

Pinning the side-effecting node is often the better answer. Offer it.

For a real integration check, use `execute_workflow` only when its effects are
authorized. Specify the intended execution mode, trigger, and inputs using the
advertised schema. Follow the returned execution ID with `get_workflow_execution`
and request `includeData: true` when node results are needed. A started execution
is not a completed test. Report success only after reading its final result.

A Manual Trigger emits an empty item. If a repeatable manual smoke test needs
sample input, add a pure data node that supplies it. The pin-data map passed to
`test_workflow` does not supply input to a later `execute_workflow` call.

## Publishing

Creating a workflow does not activate it. `publish_workflow` does.

Publish only when the user has authorized publication of this workflow. A
published workflow with a schedule or webhook can start real work. For an
existing workflow, distinguish the edited draft from its published version;
report when a fix is still a draft. Changes to workflow-level settings on an
already published workflow can reactivate it, so check and authorize their live
effects before applying them too.

## Credentials

- Call `list_credentials` and reuse what the user has. Do not create a duplicate.
- Never write a key, token, or password into workflow parameters. Credentials are
  a separate object for a reason.
- If no credential fits, say which one the user has to create and where. You
  cannot create one for them.

## When a tool is missing

Follow [connect-n8n](../connect-n8n/SKILL.md) to check the version, enabled features,
license, OAuth grant, and workflow access. Name the missing tool and its purpose.
Do not guess scope names, bypass an access restriction, or ask for all permissions.

From n8n-io/n8n-kiro-power at 782ab71, shown as plain text under its license: Apache-2.0 (permissive). The license text is in LICENSE.

• SKILL.md7.8 KB · f97cdb546e8d

1 file, 7.8 KB in total. Each file has a sha256 in the pin's manifest; the first 12 characters are shown.