Uipath Maestro Flow

Reasoning budget

• Match reasoning to step difficulty; bias toward acting. For mechanical / IO / format steps, if a uip verb covers the task, run it — never hand-derive what the CLI emits (node configure detail and bindings[], format layout, registry get node shapes).
• Save deep reasoning for the judgments no verb can make for you: node-type selection (the external-service ladder), topology, and how data moves from one node's output into the next node's input.

Working style

• Understand first, then decide. Read this file and the capability index for the work at hand, then plan against what the CLI verbs do — not a guess. uip maestro flow <verb> --help and uip maestro flow registry get <node-type> are ground truth for flags and node shapes.
• Plan the whole path up front, then chain. Outline the sequence before running anything, batch independent steps into one turn, pipeline the rest (rule #10). Do not run turn-by-turn what could have been chained.
• Inspect an input ONCE. To learn a shape — a node type's schema, a connector's fields, an existing .flow's nodes — dump it once and search that output. Never re-read a file field-by-field or re-query the registry once per field.
• Don't repeat work. Never rerun a command whose inputs and relevant state are unchanged, or re-read an unchanged file already in context. After a command may have rewritten a file (node configure, format), re-read it before relying on its contents.
• Prefer the CLI to ad-hoc code. Scripting languages are a last resort for .flow edits and need user approval first (rule #9). When code is warranted, write it once with paths as arguments; no near-duplicate inline snippets across turns.
• Keep outputs small. Extract with --output json --output-filter when you know the fields (rule #1). When the payload is large or the command is slow or side-effecting — flow debug, job traces, registry get — redirect the whole envelope to a file outside the solution tree (uip maestro flow debug <project-dir> --output json > /tmp/flow-debug.json) and search the file, so re-reading it never means re-running the command.
• Don't do anything unnecessary. No tool call, file read, or result pulled into context before it is needed.

UiPath Flow Skill

Guide for creating, editing, validating, debugging, publishing, diagnosing, and evaluating UiPath Flow projects with the uip CLI and .flow format.

Capabilities

• Author — Build and edit .flow files; add nodes, edges, variables, subflows, transforms, and triggers; explore the registry; validate and format locally; apply node ownership; configure connectors, triggers, managed HTTP, inline-agent scaffolding, IxP/document-extraction nodes, IxP models, and Data Fabric entity nodes; plan complex flows first. Read references/author/CAPABILITY.md.

• Create projects with uip maestro flow init.

• Operate — Publish, run, and manage deployed flows; debug real systems, trigger processes, inspect jobs/traces, and pause, resume, cancel, or retry instances. Read references/operate/CAPABILITY.md.

• Push to Studio Web with uip solution upload.
• Deploy to Orchestrator with uip maestro flow pack plus uip solution publish.

• Diagnose — Investigate failed or misbehaving runs; triage flow debug or deployed runs; inspect incidents, runtime variables, and deployed BPMN; recognize missing =js:, misshapen nodes, HITL-stuck, reused-reference-ID, and single-nested-layout failures. Read references/diagnose/CAPABILITY.md.
• Evaluate — Design and run evaluations; create evaluators and eval sets, add data points, pin entry points, run Studio Web evaluations, poll status, fetch results, and compare runs. Read references/evaluate/CAPABILITY.md.

• Decide whether to call uip solution upload (almost always do not auto-run; ask first).

Capability router

Critical rules (universal)

Tool vocabulary. Edit means in-place replacement, Write a full-file write, Read/Glob/Grep file access, Bash shell, and a progress list the harness task list. Map them to equivalent tools elsewhere; preserve reviewable diffs and use shell file edits only as a last resort.

1. Use --output json; prefer --output-filter for extraction. Filters are global and run against the Data envelope, so expressions start at Data without a Data. prefix. Registry search returns a flat PascalCase array (NodeType, DisplayName, Description, AvailableOnTenant), not Data.Nodes or lowercase fields. Example: uip maestro flow registry search <keyword> --output json --output-filter "[*].{NodeType:NodeType,DisplayName:DisplayName,Description:Description,AvailableOnTenant:AvailableOnTenant}". With --local, omit AvailableOnTenant. Use python3 -c or jq only after verifying shape and when JMESPath cannot express the transform. See cli-conventions.md §3.

2. flow debug consent comes from the mandate. It executes the flow for real (sends emails, posts messages, calls APIs), so run it only when the request is for a flow that works — asked to build something that does X, or to make it work. Building and validating does not discharge that; flow validate checks JSON schema and graph structure, not runtime behavior, so a validated-but-never-debugged flow is unverified rather than finished. Ask when the request stops at review, one node, or validate; with nobody to ask, report the flow as unverified instead of letting a passing validate stand as the result. Debug also overwrites the Studio Web solution matching the local .uipx SolutionId, so never debug a solution this run did not scaffold.

3. Search before creating or declaring resources absent. For named agents, API workflows, RPA processes, and similar resources: (a) pull and search the tenant registry with uip maestro flow registry pull --force && uip maestro flow registry search "<name>" --output json; pull first because the cache expires after 30 minutes, login is required, and only published resources are returned; (b) search locally with uip maestro flow registry list --local --output json or search "<name>" --local (no login; returns sibling projects in the same .uipx solution); an empty keyword search does not prove absence, so confirm with list --local; (c) scaffold, mock, or create only when both searches find no match and the user explicitly requests embedding/creation or no published resource satisfies the need.

   "Coded" and "low-code" describe implementation style, not inline status. Use uipath.agent.autonomous only when explicitly asked to embed/inline/create an agent. Use core.logic.mock only when the resource is neither in the solution nor published. See rpa and agent.

   Apply the same discipline to connectors: derive the connector key from a registry search node type (uipath.connector.<connector-key>.<activity>), never the brand name — the registry key is often prefixed or qualified differently, so a guessed key silently misses the real connector; discover connections with uip is connections list "<connector-key>" --all-folders. An unverified key or missing --all-folders makes an empty result a false negative.

   It also applies to ANY external service named in the prompt — not just in-tenant resources. Before picking a node type for a named service (Slack, open-meteo, Stripe, any REST API), run uip maestro flow registry search "<service>" --output json and follow the Selecting External Service Nodes ladder (connector → managed HTTP → RPA). Manual core.action.http.v2 is the bottom of that ladder, chosen only after a search finds no connector — never a first guess from the brand name. This holds even when full planning is skipped (see greenfield.md — Select the node type for each external service).

   Two tells that you skipped the search and took the brand-name shortcut — both are build defects, not valid manual-mode HTTP: (a) you authored a manual-mode core.action.http.v2 node whose url targets a well-known SaaS API domain that has a connector (slack.com/api/*, api.github.com, *.salesforce.com, graph.microsoft.com, …); (b) you declared an in variable to hold that service's API token or secret (e.g. a slackToken holding an xoxb-… bot token, an apiKey, a bearer token). A connector-backed flow never carries the raw credential — the IS connection does. If you find yourself writing either, stop: run uip maestro flow registry search "<service>" and uip is connections list "<connector-key>" --all-folders, then use the connector activity (or connector-mode HTTP: authentication:"connector" + targetConnector + a bound connectionId/folderKey). Manual mode is legitimate only for a service the search proves has no connector.

4. Never invoke other skills automatically — when a flow needs an RPA process, agent, or app, identify the gap and provide handoff instructions. Let the user decide when to switch skills. One exception — IXP extraction with documents in hand: when the flow needs document extraction, the user supplied sample documents, and registry search "uipath.ixp" shows no extractor covering them, invoke the uipath-ixp skill to build and deploy the model, then resume the flow (plugins/ixp/impl.md — If the Model Does Not Exist Yet). Resolve the target Orchestrator folder for the deployment before invoking — from the user's request when it names one, otherwise per rule #5 (its non-interactive fallback applies) — and pass it in the handoff; the sibling stops rather than guess a folder. There is deliberately no separate consent gate on the tenant writes this creates: the project and folder deployment fulfil the extraction request itself, and the one consequential choice — where the deployment lands (deployments have no delete API) — is exactly the folder decision rule #5 just routed. Do NOT drive uip ixp project or deployment commands from this skill instead of invoking it — the sibling's guides carry guardrails this skill does not. If uipath-ixp is unavailable in the session, fall back to core.logic.mock plus an Open Questions entry, exactly as when no documents were supplied.

5. Always present finite decisions as a dropdown with a final "Something else" escape hatch. Whenever the skill needs a decision (which solution, publish vs debug vs deploy, which connector, trigger type, or resource to bind, etc.), ask with the enumerated choices plus "Something else" last for free-form input; never ask open-ended in chat when a finite set of sensible defaults exists. If the user picks "Something else", parse their answer and continue. No structured-question facility on the harness → ask in chat as a numbered list with "Something else" last. Non-interactively (CI/headless, no user available) → take the marked recommended option, proceed, and record the decision prominently in the final report; if none is recommended, stop and report the open decision instead of guessing. Consent gates (destructive operations, tenant writes) are never auto-answered — in non-interactive mode, stop and report the blocked step; flow debug is not one of them, and is governed by the mandate rule above. These fallbacks define "ask the user" / "confirm with the user" wherever this skill's references require it.

6. Discover the target solution before scaffolding. A Flow project must use double nesting: <Solution>/<Project>/<Project>.flow. Before any new uip solution init or uip maestro flow init, run find . -maxdepth 2 -type f -name '*.uipx' -print. If a solution exists, stop and ask which to use: one option per solution, "Create a new solution", then "Something else". Do not silently adopt, initialize, delete, or repair an existing solution, even if a new one was requested. If creating one, ask for its name rather than defaulting to the Flow name.

   If none exists, create one automatically, defaulting its name to the Flow name unless specified. Prefer solution-first: uip solution init "<SolutionName>" --output json && cd "<SolutionName>" && uip maestro flow init "<FlowName>" --output json, producing <SolutionName>/<FlowName>/<FlowName>.flow and registering it in the parent .uipx (Data.SolutionRegistration.Status: "Registered"). Names are independent. A current CLI may auto-scaffold outside a solution as <FlowName>Solution/<FlowName>Solution.uipx with Data.AutoCreatedSolution; use that only when the solution name does not matter. --skip-solution-registration creates a bare single-nested project that fails Studio Web upload and packaging. If the target directory is non-empty, init leaves it untouched. Never omit cd, or it auto-scaffolds a duplicate solution. Finish with one project.uiproj; remove strays. See author/greenfield.md Step 2.

7. Narrate progress only when requested or clearly opted into. Otherwise work silently and surface decisions, failures, consent gates, and the final result. When engaged, use one short plain-English line per logical step across CLI calls, shell builtins, edits, and searches; do not narrate flags or JSON structure. See shared/ux-narration-and-todos.md §When to engage.
8. Maintain a user-facing progress list only when tracking or verbosity is requested. In silent mode there is no user-facing todo list (the agent MAY track privately). When engaged, journeys above trivial complexity get granular step-level todos; counts follow actual work, not a target. Hide registry lookups, parsing, and file reads inside their logical step. See shared/ux-narration-and-todos.md for triggers, granularity, thresholds, and pivots.
9. Each node has exactly one author: Edit/Write or CLI, never both. CLI-owned nodes are connector activities (uipath.connector.<key>.<op>), connector triggers (uipath.connector.trigger.<key>.<trigger>), wait-for-events (uipath.connector.event.<key>.<event>, configured like triggers), and managed HTTP (core.action.http.v2); add/configure them with uip maestro flow node add and node configure. All others—triggers, control flow, logic, HITL, patterns, agents, resource nodes, and queues—are user-owned and should be authored directly with Edit or Write. Never full-file Write a flow containing CLI-owned nodes because it can clobber CLI-set bindings[] and inputs.detail; use Edit or configure CLI-owned nodes last. Their inputs.detail is a =jsonString:essentialConfiguration envelope rejected when hand-authored. Inline-agent CLI is limited to uip agent init / refresh / validate --inline-in-flow; the uipath.agent.autonomous node is user-owned. Scripting (python, node, jq, sed, awk, or shell heredocs) is a last resort for user-owned edits and requires explicit approval after explaining state bypass, opaque diffs, and lack of interruption points. See author/CAPABILITY.md — Node ownership and author/editing-operations.md — Tool Selection Ladder.
10. Batch independent tool calls and chain dependent CLI calls. A typical greenfield build is three turns: T1 scaffold, pull the registry, and add CLI-owned nodes in one chained Bash, alongside independent registry/file reads; T2 read the scaffold while editing/adding the End node and edges; T3 chain configure, validate, and format. Split only when later work depends on stdout or a mutation. A user-requested snapshot or checkpoint is exactly such a boundary: capture it immediately after the named mutation and before optional validate, format, or later mutations, even when the commands share one Bash call, and never let a later command failure skip writing it. See author/greenfield.md — Three-turn execution map.
11. Cross-node bindings in =js: require $vars. Use =js:$vars.<nodeId>.output...; bare =js:<nodeId>.output... resolves to undefined. See variables-and-expressions.md — IS Activity Inputs Require =js:.
12. Node and edge IDs must begin with a letter. Use descriptive camelCase node IDs and edge_<sourceNodeId>_<sourcePort>_<targetNodeId>_<targetPort> edge IDs. Reserve UUIDs for the top-level flow id and entryPointId.

Anti-patterns (universal)

• Never use --format json; use --output json.
• Do not pipe JSON to python3 -c or jq for simple extraction; use --output-filter, verify shape first, and use external parsers only for unsupported transforms. A valid but wrong filter can return Data: []; keys(@) fails on arrays, so probe with type(@) first. See cli-conventions.md §3.
• Never substitute flow debug for flow validate as the structural check, and never re-run a completed debug to reshape its output, because debug has real side effects and re-uploads the solution on every run. This does not excuse skipping the one mandated run in rule #2. Extract report fields from the payload the completed run already returned; when that run faulted, read the cause from Data.incidents[].dependentFaultCode and Data.variables.elements[].outputs.Error.detail — see diagnose/troubleshooting-guide.md — Step 0.
• Never run flow debug in the background or under a short tool timeout. It takes 1 to 5 minutes and prints only at exit, so a backgrounded run reads as "no result". Run it in the foreground with a tool timeout of at least 10 minutes and wait — see operate/run.md — Debug.
• Never silently choose the first registry match. Use the Connector Disambiguation ladder in connector/planning.md — Disambiguation, deferring to Integration Service rules.
• Never conclude that no connection exists from bare uip is connections list; use a registry-derived connector key and --all-folders.
• Never represent customFieldsRequestDetails.parameterValues as an object map. Studio Web emits Map<string,string|null> as [[key, value], ...]; inner keys are camelCase (objectActionName, parameterValues). See connector/impl.md Step 6c.
• Never treat validation exit code 0 as completion when warnings remain. Resolve every warning. A connector-keyword warning about generic core.action.http.v2 without a connection binding means a brand-name shortcut was used; bind the connector before shipping or debugging.
• Never issue setup or finalization CLI calls one per turn; chain them per rule 10 and the Three-turn execution map.
• Never write a reference field you could not resolve. If uip is resources run list fails (403/401 on an expired grant, 5xx), you have no ID: do not substitute the display name, a well-known alias, or a remembered ID — stop and report the failed resolve. See reference-resolution.md — When the Lookup Call Fails.

Trouble? Use /uipath-feedback to report unexpected behavior.