uipath-maestro-flow git:20260909.103aba0A

Immutable. This exact content is served forever at /api/v1/blob/ff518ea635bfe007.

---
name: uipath-maestro-flow
description: "TRIGGER for `.flow` files, UiPath Flow / Maestro Flow build/edit requests, and adding or listing IXP model/document-extraction nodes for a Flow. Build, edit, run, debug, fix, evaluate a Maestro Flow (.flow): create/connect nodes (connector, approval, script, subflow, ixp, data fabric entity), triggers, schedules, validate; build conversational flows (chat, chatbot, voice, phone calls); upload, publish, manage runs/instances; diagnose errors, incidents, traces; design eval sets, evaluators, run Studio Web evals. `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
---

# 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](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](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](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](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

| Goal | Reference |
|---|---|
| Create or edit a flow | [references/author/CAPABILITY.md](references/author/CAPABILITY.md) |
| Publish, deploy, debug, or manage lifecycle | [references/operate/CAPABILITY.md](references/operate/CAPABILITY.md) |
| Diagnose a failed or misbehaving run | [references/diagnose/CAPABILITY.md](references/diagnose/CAPABILITY.md) |
| Design/run evaluations | [references/evaluate/CAPABILITY.md](references/evaluate/CAPABILITY.md) |
| CLI syntax | [references/shared/cli-commands.md](references/shared/cli-commands.md) |
| CLI conventions, `--output json`, `--output-filter`, login, and `FOLDER_KEY` | [references/shared/cli-conventions.md](references/shared/cli-conventions.md) |
| `.flow` JSON format | [references/shared/file-format.md](references/shared/file-format.md) |
| Variables and `=js:` expressions | [references/shared/variables-and-expressions.md](references/shared/variables-and-expressions.md) |
| Wire node outputs to inputs | [references/shared/node-output-wiring.md](references/shared/node-output-wiring.md) |
| Shared action-node boilerplate | [references/shared/action-nodes.md](references/shared/action-nodes.md) |
| Optional progress narration and todos | [references/shared/ux-narration-and-todos.md](references/shared/ux-narration-and-todos.md) |

## 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](references/shared/cli-conventions.md#3-prefer---output-filter-for-extraction).
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](references/author/plugins/rpa/impl.md) and [agent](references/author/plugins/agent/impl.md).

   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](references/author/planning-arch.md#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](references/author/greenfield.md#select-the-node-type-for-each-external-service-runs-even-when-full-planning-is-skipped)).

   **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](references/author/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.
<!--skill-flavor:user-question-options-extra:start-->
<!--skill-flavor:user-question-options-extra:end-->
<!--skill-flavor:project-creation:start-->
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](references/author/greenfield.md) Step 2.
<!--skill-flavor:project-creation:end-->
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](references/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](references/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](references/author/CAPABILITY.md#node-ownership--who-authors-the-node) and [author/editing-operations.md — Tool Selection Ladder](references/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](references/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:`](references/shared/variables-and-expressions.md#is-activity-inputs-require-js-critical).
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](references/shared/cli-conventions.md#3-prefer---output-filter-for-extraction).
- 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](references/diagnose/troubleshooting-guide.md#step-0--read-the-cause-in-the-debug-output-you-already-have).
- 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](references/operate/run.md#debug--controlled-end-to-end-run).
- Never silently choose the first registry match. Use the Connector Disambiguation ladder in [connector/planning.md — Disambiguation](references/author/plugins/connector/planning.md#disambiguation--when-search-returns-multiple-connectors-for-the-same-intent), 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](references/author/plugins/connector/impl.md).
- 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](references/author/greenfield.md#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](../uipath-platform/references/integration-service/reference-resolution.md#when-the-lookup-call-fails-critical).

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