uipath-maestro-flow

name	uipath-maestro-flow
description	TRIGGER for `.flow` files, UiPath Flow / Maestro Flow build or edit requests, adding or listing IXP model/document-extraction nodes for a Flow. UiPath Maestro Flow (.flow) — build, edit, run, debug, fix, evaluate. Create, connect nodes; connector, approval, script, subflow, ixp; triggers, schedules; validate. Upload, publish, manage runs, instances. Diagnose errors, incidents, traces. Design eval sets, evaluators, run Studio Web evals via `uip maestro flow eval`. `uip maestro flow` CLI. DO NOT TRIGGER for raw IXP project labelling/prediction review/prompt tuning outside Flow→uipath-ixp; C#/XAML→uipath-rpa; standalone agents→uipath-agents.
allowed-tools	Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion

UiPath Flow Skill

Comprehensive guide for creating, editing, validating, debugging, publishing, diagnosing, and evaluating UiPath Flow projects using the uip CLI and .flow file format. The skill is organized into four capabilities — Author, Operate, Diagnose, Evaluate — each with its own index doc.

When to use this skill

Author — building or editing a .flow file. Read references/author/CAPABILITY.md.

• Create a new Flow project (uip maestro flow init)

• Edit a .flow file — add nodes, edges, variables, subflows, transforms, triggers
• Explore available node types via the registry
• Validate or format a Flow file locally
• Apply Node ownership — Edit/Write for user-owned nodes, CLI for CLI-owned nodes (see Author capability)
• Configure connector, connector-trigger, or managed HTTP nodes; scaffold inline-agent projects
• Add IxP / document-extraction nodes to a flow, or list IxP models available to Maestro Flow through the flow registry
• Plan a complex flow before building

Operate — publishing, running, or managing a deployed flow. Read references/operate/CAPABILITY.md.

• Push a flow to Studio Web (uip solution upload)
• Deploy a flow to Orchestrator (uip maestro flow pack + uip solution publish)

• Debug a flow end-to-end against real systems
• Trigger a deployed process
• Check job status or stream traces
• Pause, resume, cancel, or retry a running instance

Diagnose — investigating a failed or misbehaving run. Read references/diagnose/CAPABILITY.md.

• Triage a failed flow debug or deployed process run
• Read incidents, runtime variables, deployed BPMN
• Recognize known failure modes (missing =js:, misshapen nodes, HITL-stuck, reused reference IDs, single-nested layout)

Evaluate — designing and running evaluations against a deployed flow. Read references/evaluate/CAPABILITY.md.

• Create evaluators (exact-match, json-similarity, contains, llm-judge-*) for a Flow project
• Create eval sets, add data points (test cases), pin entry points
• Start Studio Web eval runs, poll status, fetch results, compare runs

• Decide whether to call uip solution upload (almost always: don't auto-run; ask first)

Capability router

I want to...	Read
Create a new flow or edit an existing one	references/author/CAPABILITY.md
Publish, deploy, debug, or manage a flow's lifecycle	references/operate/CAPABILITY.md
Diagnose a failed or misbehaving flow run	references/diagnose/CAPABILITY.md
Design and run evaluations (uip maestro flow eval)	references/evaluate/CAPABILITY.md
Look up CLI command syntax	references/shared/cli-commands.md
Look up CLI conventions (--output json, --output-filter, login, FOLDER_KEY)	references/shared/cli-conventions.md
Understand the .flow JSON format	references/shared/file-format.md
Understand variables and =js: expressions	references/shared/variables-and-expressions.md
Wire one node's output into another node's input	references/shared/node-output-wiring.md
Look up action-node boilerplate shared across plugin impl.mds	references/shared/action-nodes.md
Narrate progress + maintain todos (opt-in — when user wants verbosity)	references/shared/ux-narration-and-todos.md

Critical rules (universal)

These rules apply across all four capabilities. Each capability index adds capability-scoped rules on top.

Tool vocabulary. Tool names in this skill use Claude Code conventions: Edit = in-place string replacement, Write = full-file write, Read/Glob/Grep = file read/search, Bash = shell, progress list = the harness's task list. On another harness, map each to its equivalent — the semantics (reviewable in-place diff vs wholesale rewrite, shell as last resort for file edits) carry unchanged.

1. ALWAYS use --output json and prefer --output-filter for extraction on all uip commands when parsing output programmatically. --output-filter <jmespath> is a global CLI flag applied to the Data envelope before printing — write expressions starting at Data (no Data. prefix). Canonical recipe: uip maestro flow registry search <keyword> --output json --output-filter "[*].{NodeType:NodeType,DisplayName:DisplayName,Description:Description,AvailableOnTenant:AvailableOnTenant}". registry search returns Data as a flat array of PascalCase objects (NodeType, DisplayName, Description, AvailableOnTenant) — NOT Data.Nodes, lowercase type, or lowercase category. With --local, AvailableOnTenant is omitted (no tenant lookup) — drop it from the projection. External parsers (python3 -c, jq) remain valid for transforms JMESPath cannot express; reach for them only after the shape is verified. Full mechanics, fall-back guidance, and shape-inspection probes: cli-conventions.md §3.

2. Do NOT run flow debug without explicit user consent — debug executes the flow for real (sends emails, posts messages, calls APIs).

3. Resource discovery order — search before creating. When the prompt references an existing resource by name ("use the X agent", "call the Y API workflow", "invoke the Z RPA process"), follow this order strictly before deciding the resource doesn't exist:

   1. Pull, then search the tenant registry — uip maestro flow registry pull --force && uip maestro flow registry search "<name>" --output json. Always pull first: search reads the local cache (populated by pull, expires after 30 min), so a search before a fresh pull can return empty for a resource that exists. Requires uip login; returns published resources.
   2. In-solution local discovery — uip maestro flow registry list --local --output json, or for keyword match. No login required; returns sibling projects in the same solution. An empty is not proof of absence (the keyword may not match the project's naming) — confirm with before concluding the resource is not in the solution.

6. Discover the target solution before you scaffold — a Flow project MUST live inside a solution (layout is always double-nested: <Solution>/<Project>/<Project>.flow). Before any uip solution init or uip maestro flow init for a NEW Flow, run find . -maxdepth 2 -type f -name '*.uipx' -print. If it lists one or more solutions, STOP — do not scaffold, initialize, delete, or repair anything. Ask which solution to use (dropdown per rule #5): one option per discovered solution, "Create a new solution", then "Something else" last; continue only after the answer. This holds even when the user says they want a new solution or supplies only a Flow-project name — never silently adopt an existing solution, and when they pick "Create a new solution", ask for its name rather than defaulting to the Flow-project name. If none are found, create one automatically (default its name to the Flow name unless the user specifies otherwise). Prefer solution-first — it works on every CLI version and lets you set the two names independently: uip solution init "<SolutionName>" --output json && cd "<SolutionName>" && uip maestro flow init "<FlowName>" --output json → <SolutionName>/<FlowName>/<FlowName>.flow, with the project auto-registered in the parent .uipx (Data.SolutionRegistration.Status: "Registered"); <SolutionName> and <FlowName> are independent and need not match. On a current CLI, running uip maestro flow init "<FlowName>" outside any solution instead auto-scaffolds <FlowName>Solution/<FlowName>Solution.uipx with the project at <FlowName>Solution/<FlowName>/ (response carries Data.AutoCreatedSolution) — convenient, but it forces the <FlowName>Solution name, so use it only when the solution name doesn't matter. --skip-solution-registration opts out of both auto-scaffold and registration, leaving a bare single-nested <Flow>/<Flow>.flow that fails Studio Web upload and packaging. If a non-empty directory already exists at the path you typed, init warns and leaves it untouched. Never drop the cd between solution init and flow init — flow init in the old directory auto-scaffolds a duplicate . One at finish; delete strays. See Step 2.

7. Narrate progress in plain English only when the user has opted into verbosity — silent by default. Engage when the user asks for narration / progress ("walk me through it", "show your steps", "verbose", "be detailed") or signals a verbosity preference; otherwise work quietly and surface only decisions, failures, consent gates, and the final result. When engaged: one short line per logical step, in user terms ("checking your tenant login", "adding the Slack node and wiring its inputs", "running validate") — no flag-level or JSON-structure-level detail, applied uniformly across uip CLI calls, shell builtins, file edits, and bulk searches. See shared/ux-narration-and-todos.md §When to engage.
8. Maintain a user-facing progress list only when the user has opted into progress tracking / verbosity. In silent mode there is no user-facing todo list (the agent MAY track privately). When engaged: any journey above the trivial threshold gets a granular list — one logical step ≈ one todo, granularity per-step not per-phase. The count emerges from the journey's actual steps; do not target a number. Bash plumbing inside a step (registry lookups, JSON parsing, intermediate file reads) is invisible — do not surface as todos. See shared/ux-narration-and-todos.md for the engage triggers, granularity rules, threshold table, and pivot rules.
9. Every node has exactly one author — Edit/Write or CLI, never both. Connector activities (uipath.connector.<key>.<op>), connector triggers (uipath.connector.trigger.<key>.<trigger>), wait for events (uipath.connector.event.<key>.<event> — a mid-flow event wait, configured exactly like a trigger), and managed HTTP (core.action.http.v2) are CLI-owned — use uip maestro flow node add + uip maestro flow node configure. Every other node type — triggers, control flow, logic, HITL, patterns, agents, resource nodes, queue — is user-owned: author the .flow JSON directly with Edit — or Write, but never a full-file Write on a flow that also contains CLI-owned nodes (it clobbers their CLI-set bindings[]/inputs.detail; Edit in place, or re-run node configure as the last step). inputs.detail on CLI-owned nodes is a =jsonString:essentialConfiguration envelope that the validator rejects when hand-authored. Inline-agent CLI is limited to agent project lifecycle (); the flow node itself is user-owned. Scripting languages (, , , , , inline shell heredocs) are a last resort for user-owned edits and require explicit user approval after the trade-offs (state bypass, opaque diff, no interruption point) are surfaced. (full table); (per-operation ladder).

Anti-patterns (universal)

• Never use --format json on any uip command — the flag is --output json (rule #1). --format produces error: unknown option '--format' and exit code 3 on every uip subcommand, not a helpful message pointing you at --output.
• Avoid piping uip ... --output json to python3 -c / jq for simple field extraction — use --output-filter instead (rule #1). The common failure mode: the agent assumes Data.Nodes (or another nested shape) and the external parser silently returns [] against Data's actual flat array, prompting a second and third retry with different access paths. --output-filter does not rescue a wrong-shape guess by itself — a valid expression that doesn't match (e.g. "Nodes" against the flat array) still returns Data: [] with exit 0; only an invalid expression (bad syntax, or a type error like keys(@) on an array) exits non-zero. The fix is the pinned shape in rule #1, so you write the right expression on call #1. Reserve external parsers for transforms JMESPath cannot express (multi-step joins, format conversion); when in doubt, verify the shape first — see cli-conventions.md §3 for the type(@) first-probe sequence (note: keys(@) throws on arrays, so use type(@) first).
• Never run flow debug as a validation step — debug executes the flow with real side effects (rule #2). Use flow validate for checking correctness.
• Never silently pick the first match from uip maestro flow registry search. When a search returns multiple connectors for the same intent, apply the canonical Connector Disambiguation ladder via connector/planning.md — Disambiguation, which defers to the Integration Service rules.
• Never conclude "no connection exists" from a bare uip is connections list — discovery requires and a connector key derived from , not a brand name (rule #3). Without both, "No connections found" is a false negative; do not surface it as an Open Question or ask the user to create one.

Trouble? If something didn't work as expected, use /uipath-feedback to send a report.