creating-flow

name	creating-flow
description	Creates Robomotion automation flows with the @robomotion/sdk TypeScript builder. Owns the full lifecycle: requirements → plan → build → validate → deploy. Also use when the user has a plan ready and wants the flow code written.

Robomotion Flow Builder

Robomotion is an RPA platform with a TypeScript SDK and a visual node editor. This skill is a thin index over the reference docs in ./docs/. Read the relevant doc when a topic comes up — don't try to memorize it from this file.

Hard Rules (SDK rejects violations at validate time)

The SDK enforces these. Violations throw at robomotion validate / build with descriptive messages, so the agent never silently produces broken flows:

1. Node IDs MUST be 6-char lowercase hex — /^[0-9a-f]{6}$/. f.node(), .then(), f.edge() reject non-hex IDs ('begin', 'label', 'maps', uppercase) at registration. Pick fresh hex per node. See ./docs/reference/id-format.md.
2. Subflow node ID = subflows/<id>.ts filename, exactly. Both must be 6-hex. The Designer's "enter subflow" UX depends on the match.
3. f.addDependency(namespace, version) is validated against the live package index. version must be concrete ('latest' is rejected) and must exist in the package's published versions list. namespace must exist in https://packages.robomotion.io/stable/index.json. Run robomotion get packages <ns> or robomotion describe package <ns> to resolve real versions before calling addDependency. Never invent a version.
4. Terminal nodes (Debug, Log, Stop, GoTo, End, WaitGroup.Done) have 0 outputs — wire TO them via f.edge(), never .then() from them.
5. Every Core.Flow.GoTo references a Core.Flow.Label id that exists in the same flow file.

Required First Line

Every flow file (main.ts and every subflows/*.ts) starts with this exact import — copy verbatim, including helpers you don't currently use (Bun won't flag dead imports, but missing ones become runtime ReferenceError):

import { flow, Message, Custom, JS, Global, Flow, Credential, AI } from '@robomotion/sdk';

For library files swap flow for library / subflow. Full reference: ./docs/reference/imports.md.

Builder grammar

• f.node(id, type, name, props) — param order. Only emit non-default props (Go runtime fills defaults from pspec).
• .then() for sequential, .edge() for multi-port wiring.
• Message(name) for variables · Custom(value) for literals · JS(expr) for one-line JS · Credential({vaultId, itemId}) for secrets.
• Input-port props (in*, plus opt* props that map to input ports like optTimeout, optUrl, optMaxRetries) MUST be wrapped in a scope helper, even for numbers and booleans — optTimeout: Custom('30'), not optTimeout: 30. Raw 30 is silently dropped because the runtime expects {scope, value}.
• func is a literal string (NOT JS()). Enum/option props (optType, optMethod, optMode, …) are plain strings (NOT Custom()).
• Common node props are the only numeric/boolean literals that take raw values: delayBefore: 2, delayAfter: 0.5, continueOnError: true. Everything else input-bound goes through Custom() / Message() / JS().
• ES5-only inside func: no =>, no template literals, no const/let, no destructuring. No require() / fs / Buffer / process (pure JS sandbox).
• Loops: Label → ForEach → body → GoTo. Stop is standalone, wired via f.edge() on ForEach port 1.
• Library projects use library.create(id, name, fn) with Begin/End nodes (no .start()). Inline subflows use subflow.create(name, fn).
• Every flow ends with .start(). Every flow has a Core.Flow.Stop node.
• Core.* packages (Core.Trigger, Core.Browser, Core.Programming, Core.CSV, Core.Flow, Core.Vault, Core.Net, Core.Excel, …) are embedded in the robot — NEVER call f.addDependency('Core.*', …). The Designer auto-loads them. Only call f.addDependency(ns, ver) for non-Core.* packages. When updating an existing flow, NEVER bump existing addDependency versions; only add missing ones.

Full grammar: ./docs/sdk-grammar.md. Architecture: ./docs/architecture.md.

Diagnostic map

Map an error symptom to the doc that fixes it. When validate_flow fails, look up the symptom here before reading the full failure trace.

Symptom	Likely cause	Fix
[SDK] Invalid node ID '<x>' in f.node('<x>', …)	Semantic / non-hex ID	./docs/reference/id-format.md — pick 6-hex
[SDK] Invalid subflow filename '<x>.ts'	Subflow filename non-hex	Rename file + update parent SubFlow node ID to match
version must be concrete; 'latest' and empty are not allowed	f.addDependency(ns, 'latest')	robomotion describe package <ns> → pin a real version
package '<ns>' not found in repository	Hallucinated namespace	robomotion get packages <kw> → use the real namespace
version '<v>' is not published for <ns>	Wrong version pinned	Pick from available_versions returned by validator
Cannot chain from node (outputs=0)	.then() after Debug/Log/Stop/GoTo/End	Wire TO terminals via f.edge(), never FROM them
Invalid input port 0. Node has 0 input(s) on a Label	Wired into Core.Flow.Label (Label has 0 inputs in some pspecs)	Use Core.Flow.GoTo with optNodes.ids: [<labelId>] to jump to the Label
Vault has to be selected at runtime	Missing optCredentials on Core.Vault.GetItem	./docs/patterns/credentials.md
inLabel property not found on GoTo	Wrong property	optNodes: { ids: [...], type: 'goto', all: false }
Core.Programming.If not found	Node doesn't exist	Core.Programming.Function with outputs: 2 (./docs/patterns/conditions.md)
Wrong node name (e.g. Core.CSV.Read, Browser.Click)	Common naming mistake	./docs/reference/node-naming.md
inPath: Custom('$Home$/file') literal not resolved	System variables only resolve in Function nodes	global.get('$Home$') + '/file' (./docs/reference/system-variables.md)
optTimeout: 30 (or any numeric input prop as raw literal) silently dropped / not honored	Input-port props need a scope helper, even for numbers	optTimeout: Custom('30'). Raw literals are reserved for delayBefore / delayAfter / continueOnError.
Any CSV / Excel / Sheets / SQLite / Pandas / Airtable / DOMParser / DataTable node in scope	Custom data shape is wrong (e.g. {header: [...]}, rows as arrays)	MANDATORY read ./docs/patterns/data-tables.md — the format is {columns: [...], rows: [{key: value}]} with row keys matching column names
Write produces empty cells / ErrFilePath / "table not recognized"	header instead of columns, or rows are arrays not objects	./docs/patterns/data-tables.md — the property is columns, never header; rows are objects keyed by column name, never positional arrays

Drift-prone reminders before every Write / Edit of flow code:

• Never output TypeScript as chat text — always use Write / Edit. Plans and explanations stay in chat.
• Hex IDs from the start. Cross-references (optNodes.ids, Catch.optNodes.ids, subflow filenames) must use the same hex.
• For browser flows: explore the live page first (Skill(exploring-browser) or mcp__browser__* after ToolSearch warmup). Don't guess selectors.
• For any flow that touches CSV / Excel / Google Sheets / Excel 365 / SQLite / Airtable / Pandas / DataTable / DOMParser nodes — read ./docs/patterns/data-tables.md BEFORE writing the Function that builds the table. The format is {columns: [...], rows: [{key: value}]}, never {header: ...} and never rows-as-arrays. Don't reason from the node name; the doc is the source of truth.
• Validate BEFORE save — save_flow only compiles, it does NOT pspec-validate.

Pattern reference

Read these docs before writing the corresponding code:

Pattern	Doc
Loops (Label → ForEach → body → GoTo)	./docs/patterns/loops.md
Conditions (Function with outputs: N)	./docs/patterns/conditions.md
Credentials (vault + categories)	./docs/patterns/credentials.md
Browser automation (incl. proxy)	./docs/patterns/browser.md
Exception handling (Catch, continueOnError)	./docs/patterns/exceptions.md
Branches & parallel (ForkBranch, WaitGroup)	./docs/patterns/branches.md
Subflows (Begin/End, multi-output)	./docs/patterns/subflows.md
Data tables (CSV / Excel / Sheets / SQLite / Pandas / Airtable / DOMParser / DataTable) — MANDATORY before writing any code that produces or consumes msg.table	./docs/patterns/data-tables.md
Captcha solving	./docs/patterns/captcha.md

References:

Topic	Doc
Imports (every scope helper + example)	./docs/reference/imports.md
Node ID format (the hex rule)	./docs/reference/id-format.md
System variables ($Home$, $TempDir$)	./docs/reference/system-variables.md
Node naming (wrong → correct)	./docs/reference/node-naming.md
Credential categories (field layouts)	./docs/reference/credential-categories.md

For schemas, examples, and package docs, use the robomotion CLI (it's already on PATH, call it by bare name):

Need	Command
Cross-source fuzzy/semantic search	robomotion search <query>
Find packages	robomotion get packages [query]
Find nodes	robomotion get nodes [query] [--in <ns>]
Find templates	robomotion get templates [query] [--category <name>] [--tag <name>]
Full node schema + docs + example	robomotion describe node <type>[,<type>...]
Package info (incl. published versions)	robomotion describe package <namespace>
Template source	robomotion describe template <slug>
Package docs (llms.txt)	robomotion docs <namespace> [--grep <pattern>]
List vaults / vault items	robomotion get vaults · robomotion get vault-items <vault-id>
List robots	robomotion get robots

Public templates repo: github.com/robomotionio/robomotion-templates is the canonical source. Prefer cloning/forking a matching template over building from scratch.

Workflow

Full step-by-step: ./docs/workflow.md. Outline:

0. Gather requirements (interactive only) — credentials (commit to a vault-item pick, don't quiz the user), URLs, files, iteration, error handling.
1. Discover — robomotion search, robomotion get nodes, robomotion docs <namespace> (MANDATORY for every non-Core.* package).
2. Plan — output plan as chat text, then AskUserQuestion(["Build it", "Modify plan"]).
3. Write — read 1-2 relevant ./docs/patterns/*.md, verify property names with robomotion describe node, then Write main.ts (and any subflows/<id>.ts). For browser flows: explore live first.
4. Validate — call validate_flow MCP tool. Pspec-checks AND dependency-checks. MUST run BEFORE save.
5. Save — save_flow if registered (Designer / pi); else git commit && git push from inside the flow dir. This is the terminal step. Stop here and report success — do NOT chain into running the flow. Running is a separate user request handled by the running-flow skill.

If invoked in direct mode ("Write main.ts for X", "Generate a flow that does Y"), skip 0-2 and jump to 3.

Browser caveat: if code changed after the initial exploration (different selectors, new actions), re-verify selectors against the live page before saving. Selectors are owned by Step 3, not a post-save step.

Canonical example (simple chain)

For loop / conditional / subflow / catch examples, see the corresponding pattern docs — they have richer working snippets.

import { flow, Message, Custom } from '@robomotion/sdk';

flow.create('main', 'Simple Flow', (f) => {
  f.node('42ec21', 'Core.Trigger.Inject', 'Start', {})
    .then('7dbafc', 'Core.Programming.Function', 'Setup', {
      func: `msg.url = 'https://example.com'; return msg;`
    })
    .then('a06926', 'Core.Browser.Open', 'Open Browser', {
      outBrowserId: Message('browser_id')
    })
    .then('8e1c4b', 'Core.Browser.OpenLink', 'Navigate', {
      inBrowserId: Message('browser_id'),
      inUrl: Message('url'),
      outPageId: Message('page_id')
    })
    .then('d52f73', 'Core.Browser.Close', 'Close', {
      inBrowserId: Message('browser_id')
    })
    .then('b9a841', 'Core.Flow.Stop', 'Stop', {});
}).start();

CLI & MCP

• robomotion — self-sufficient CLI. Builds, validates, runs, searches, inspects. robomotion help for the full verb list.
• robomotion-browser-mcp — MCP server for interactive browser exploration (used by exploring-browser and mcp__browser__* tools).

The robomotion CLI shells out to robomotion-sdk-mcp internally for search-backed commands and calls api.robomotion.io directly for run/stop/vault/robot operations. No additional MCP servers required.

Regression suite

This skill ships with an automated eval suite at ./evals/ — Tier A pinpoint regressions (handcrafted fixtures, one rule each) plus Tier B integration tests (live main.ts from the public robomotion-templates repo). Run bun run skills/creating-flow/evals/run-evals.ts from the agent-skills root before committing edits to this SKILL.md or the ./docs/ files. See ./evals/README.md for adding new cases and the assertion grammar.

Related skills

• validating-flow — schema validation
• testing-flow — behavioral tests
• running-flow — execute on robot
• searching-packages — find packages, nodes, templates
• exploring-browser — interactive browser automation
• reversing-network — convert a browser flow to HTTP after capturing traffic