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; build conversational flows for text chat or voice; plan complex flows first. Read references/author/CAPABILITY.md.

<!--skill-flavor:project-creation-scope:start-->

• Create projects with uip maestro flow init.

<!--skill-flavor:project-creation-scope:end-->

• 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.

<!--skill-flavor:upload-scope-bullets:start-->

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

<!--skill-flavor:upload-scope-bullets:end-->

• 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.

<!--skill-flavor:upload-eval-scope-bullet:start-->

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

<!--skill-flavor:upload-eval-scope-bullet:end-->

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. Second exception — non-catalog connector activity (Tier 2): when registry search (after a registry pull --force re-check) confirms the connector exists but carries no curated activity for the operation, and uip is connectors metadata <connector-key> reports Flags.V4Compatible: true, invoke the uipath-platform skill's activity generation (activity-generation.md) to produce the activity metadata JSON and scripts, then resume the flow and author the node per connector/impl-inline.md. Do NOT fall through to Managed HTTP (core.action.http.v2) on a V4-compatible connector just to avoid the handoff — the ladder in connector/planning.md — Decision Order ranks the generated activity above it, and Managed HTTP connector mode is correct only when the connector is not V4-compatible. Do NOT drive uip is activities metadata generate / script update from this skill's own instructions instead of invoking the sibling — its guide carries the vendor-docs grounding and script-validation guardrails this skill does not. If uipath-platform is unavailable in the session, fall back to Managed HTTP connector mode (http/impl-connector.md) and record in the final report that the preferred Tier 2 activity was not generated.

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.