Reasoning budget

Match reasoning to step difficulty and bias toward acting; for mechanical / IO / format steps, if a provided script already covers the task, run it — don't re-derive it.
Save deep, extended reasoning for the one genuinely hard judgment a script can't make for you.

Working style

Understand first, then decide. Read this skill's SKILL.md and understand the scripts it ships before you act. Then plan accordingly, such as run a script as-is when it fits, change a script when it's close, or write extra scripts to complement — based on what the scripts actually do, not a guess.
Plan the whole path up front, then chain. Outline the full sequence of steps before running anything, batch independent steps into one turn, and pipeline the whole plan in as few turns as possible. Don't do things that can be pipelined into one call turn-by-turn.
Inspect an input ONCE. To learn a file's structure (sheets/columns, pages, form fields, keys), dump it once — ideally to a file you then grep — never re-open the same file field-by-field or retry it with several libraries.
Don't repeat work. Do not rerun a command when its inputs and relevant state are unchanged, and do not reread an unchanged file, script, or SKILL.md already in context. After a tool or command may modify a file, reread the affected content before relying on it.
Write code once and reuse. If a step needs code, write it once as a small script (paths/params as CLI args) and call it; don't paste near-duplicate inline python across turns. Keep it terse — no comment banners or narration in inline scripts.
Keep outputs small. Don't put large tool results and outputs into the context, instead write them into a file and use tools to inspect them. If there is no tool available, you should write your own scripts to inspect the file.
Don't do anything unnecessary. Don't call tools, read files, or put results into context unless they're immediately needed.

UiPath Maestro BPMN

Work with UiPath Maestro (Process Orchestration)

.bpmn

projects across their lifecycle: author, validate, package, operate, and diagnose. Authoring is registry-driven: every

uipath:*

extension payload comes from a template the registry serves; the structural BPMN that holds those nodes together (process scaffold, sequence flows, gateways, events, boundary events, containers, multi-instance markers, and the diagram) is authored from the documented spec + canvas contract. Packaging, operating (upload, publish, run, manage), and diagnosing are driven through the UiPath CLI, covered in the capability references below.

When to use

Create a Maestro
```
.bpmn
```
from a description.
Edit
```
.bpmn
```
structure: gateways, events, boundary events, subprocesses, call activities, multi-instance loops, sequence-flow conditions, variables.
Add a UiPath extension node (RPA job, agent, HITL, queue, business rule, API workflow, Integration Service connector, internal message, timer).
Validate a
```
.bpmn
```
against the canvas rules before import.
Package, upload, publish, or run a project, and manage its jobs and instances.
Diagnose a failed or misbehaving run.

Editing an existing

.bpmn

(preserve what you did not author)

The skill can edit an existing file. Make surgical edits and preserve content you did not author: unknown

uipath:*

elements,

uipath:migrationVersion

, tags, imported Integration Service payloads, and stable element IDs. Do not regenerate the whole file or drop extension data the skill does not recognize — preserve-only structures (see the blocklist in references/structural-bpmn.md) round-trip untouched. Never normalize existing nodes to this skill's canonical templates: do not add missing attributes (e.g.

type="json" target="bodyField"

on an existing

uipath:input

) to elements the edit does not target — on untouched neighbors only wiring (

bpmn:incoming

bpmn:outgoing

) may change.

For

.flow

JSON use

uipath-maestro-flow

; for XAML/coded workflows use

uipath-rpa

; for Python agents use

uipath-agents

; for Case plans use

uipath-maestro-case

The model

Two halves make a valid Maestro

.bpmn

uipath:*
payloads — registry-owned. Each node's extension XML (

uipath:activity

uipath:event

uipath:mapping

, its

context

input

output

, and

bindingInfo

) comes from

uip maestro bpmn registry get <type>

xmlTemplate

. Never hand-author a
uipath:*
element from prose.

Structural BPMN — spec/canvas-owned. The registry emits no
```
<bpmn:definitions>
```
/
```
<bpmn:process>
```
, no sequence flows, no gateway conditions/defaults, no event-definition payloads, no boundary-event attributes, no subprocess/loop structure, and no diagram. Author all of these from references/structural-bpmn.md, which is grounded in the registry spec and the Studio Web canvas serializer.

Workflow

Work the four steps quickly, but keep the path matched to the user's ask. Treat requests to discover before authoring, save raw registry JSON/evidence, or "do not author yet" as discovery-only even if they describe an eventual BPMN. In that mode, immediately create

registry-evidence/

, run and save

registry pull --output json

registry list --output json

registry search ... --output json

, and

registry get <type> --output json

for each requested type; do not read deep authoring references or scaffold a project. For authoring asks, author early: do not pre-read every reference before writing. Read a reference only when you reach the structure it covers, get the needed templates, then write the first complete draft before further spelunking. If references/structural-bpmn.md or references/expression-authoring.md directly covers the requested construct, write a first complete draft before further spelunking.

For registry-evidence-only tasks, be command-first and time-boxed:

Create
```
registry-evidence/
```
before anything else.

Run the registry command forms the user asked for. For RPA job + internal message discovery, use

uip maestro bpmn registry list --limit -1 --output json

uip maestro bpmn registry get Orchestrator.StartJob --output json

, and

uip maestro bpmn registry get Maestro.ReceiveMessageEvent --output json

If
```
uip
```
is unavailable in a temp/smoke sandbox, or if it writes a valid JSON failure object such as
```
"Result": "Failure"
```
instead of registry content, do not search the repo for a replacement CLI or inspect test fixtures. Still issue the required
```
list
```
and
```
get
```
command forms once each with output redirected to their evidence files (allowing failure with
```
|| true
```
), so the transcript shows the discovery loop:
```
uip maestro bpmn registry list --limit -1 --output json
```
and
```
uip maestro bpmn registry get <type> --output json
```
. Record the failed CLI attempts in
```
registry-evidence/cli-error.txt
```
, then overwrite any failure JSON in the expected
```
registry-evidence/*.json
```
files with valid JSON evidence from
```
skills/uipath-maestro-bpmn/validator/bpmn-spec.json
```
containing the same extension types and stop. The final evidence files must literally contain the discovered type names, for example
```
Orchestrator.StartJob
```
and
```
Maestro.ReceiveMessageEvent
```
.

Discover.
```
uip maestro bpmn registry pull
```
once (cached for the session — do not re-pull), then
```
list
```
/
```
search
```
to map intent to extension types;
```
uip is connections list --all-folders
```
for live connections (always
```
--all-folders
```
— a folder-scoped list silently misses connections). Confirm every selection with the user (use AskUserQuestion). Never fabricate an identifier. See references/registry-workflow.md.
Get templates.
```
uip maestro bpmn registry get <type> --output json
```
for each chosen registry-owned node only. Enrich
```
Intsvc.*
```
connector nodes with
```
--connection-id
```
/
```
--object-name
```
. Do not call
```
registry get
```
for structural gaps the registry never owns: sequence flows, gateways, events, boundary events, multi-instance/loop markers,
```
errorMapping
```
/retry structure, or diagrams. If a registry template's BPMN host tag is PascalCase (for example
```
<bpmn:SendTask>
```
or
```
<bpmn:ReceiveTask>
```
), normalize the host tag to the serializer's lower-camel BPMN element (
```
<bpmn:sendTask>
```
,
```
<bpmn:receiveTask>
```
) while preserving the
```
uipath:*
```
payload exactly.
Assemble. Author directly from the complete minimal file in references/structural-bpmn.md plus each node's
```
xmlTemplate
```
(fill placeholders only). That skeleton already shows variables, the entry point, a branch, and the diagram. Do not reverse-engineer authoring patterns from task fixtures or generated package files — fixture spelunking is the top reason authoring runs out of time. Add only the structural pieces your process needs (extra gateways, events, boundary events, containers, multi-instance markers, expression/error mappings, retry attributes), then run
```
uip maestro bpmn format <file.bpmn>
```
to generate the diagram. If
```
format
```
reports
```
unknown command
```
, update the CLI (see references/cli-conventions.md); if upgrading is unavailable, use the fallback DI structure in references/structural-bpmn.md. For local authoring prompts, use the plain project layout
```
<ProjectName>/<ProjectName>.bpmn
```
with
```
<ProjectName>/project.uiproj
```
; do not create
```
*Solution/
```
, package files, or
```
.uipx
```
artifacts unless the user explicitly asks to package or operate the project. When adding draft or preserve-only case-management variants, include a real lowercase
```
<uipath:caseManagement version="v1">...</uipath:caseManagement>
```
payload with synthetic content as a separate preserve-only extension. Do not treat an
```
Orchestrator.StartCaseMgmtProcess*
```
typed activity shell as a substitute for that payload when the user asks to preserve case-management contract variants. When asked to preserve a generic unsupported
```
uipath:Activity
```
, write the actual capitalized element
```
<uipath:Activity version="v1">...</uipath:Activity>
```
. Do not write
```
<uipath:activity><uipath:type value="uipath:Activity" ... />
```
; that is a lowercase typed shell, not the preserve-only generic payload. When writing public-safe placeholders into XML attribute values, XML-escape angle brackets: use
```
&lt;TENANT_URL&gt;
```
,
```
&lt;FOLDER_KEY&gt;
```
, and
```
&lt;CONNECTION_NAME&gt;
```
in attributes. Raw
```
<PLACEHOLDER>
```
text is only safe in element text or CDATA; unescaped angle brackets inside attributes make the BPMN not well-formed. When routing on an Actions.HITL user task's outcome, the sequence-flow conditions from the exclusive gateway must reference the exact variable bound by the HITL template's
```
<uipath:output ... var="...">
```
(for example
```
=vars.Var_HitlResult == "approve"
```
), not only a copied or derived script variable. For Integration Service draft notes, name every CLI-owned blocker literally, including the exact phrase
```
connection binding
```
, plus dynamic schemas, generated outputs,
```
bindings_v2.json
```
, and package metadata. Avoid softer wording such as "connection and process binding" because it hides the concrete artifact the CLI must supply. If the user asks to package or operate, run
```
uip maestro bpmn update-metadata <file.bpmn>
```
to generate the five package metadata files. Only fall back to the minimal local metadata shape in references/shared/local-metadata-regeneration-guide.md when the CLI is unavailable. Do not copy CLI scaffold metadata shapes into a synthetic local project.
Validate. Run the CLI validator — it runs the full PO.Frontend canvas rule set (structural rules plus variable, method-call, input-type, and event-object checks) offline, plus deploy-readiness checks:
bash
```
uip maestro bpmn validate <file.bpmn> --output json
```
Exit 0 = valid; exit 1 = validation failed (the envelope lists each issue with its rule code). Warnings are reported but do not fail the run. Validate once; fix only error-severity findings. Do not re-validate in a loop chasing warnings. If
```
validate
```
reports "unknown command" or clearly skips the structural rules, the installed CLI predates them — update it (see references/cli-conventions.md). See references/structural-bpmn.md#validation.

Operate and diagnose

Beyond authoring, this skill packages, ships, runs, and diagnoses Maestro projects through the UiPath CLI.

Package and operate (package a project, upload to Studio Web, publish or deploy, run or debug instances, and manage jobs, instances, incidents, and lifecycle actions): see references/operate/CAPABILITY.md.
Diagnose (fetch incidents, variables, and element executions, and trace a failed run back to its BPMN element): see references/diagnose/CAPABILITY.md.

Any cloud-side change (upload, publish, deploy, run, pause, resume, cancel, retry, migrate) requires explicit user consent, and local validation should pass first.

Structural coverage

This skill teaches authoring of the full surface the canvas supports. What the registry serves a template for vs. what you author by hand:

Structure	Source
Node `uipath:*` payloads (RPA, agent, HITL, queue, business rule, API workflow, IS connector, internal message, timer, script, variables)	Registry `xmlTemplate`
`<bpmn:definitions>` / `<bpmn:process>` scaffold + namespaces	Authored (registry gap)
Sequence flows, `conditionExpression` , gateway `default`	Authored (registry gap)
Gateways: exclusive, parallel, inclusive, event-based (complex is preserve-only)	Authored (registry gap)
Events + event-definition matrix: message, timer, error, terminate (end-only). Signal/escalation/conditional/link/compensate/cancel/multiple are preserve-only	Authored (registry gap); payload per canvas serializer
Boundary events: `attachedToRef` , interrupting/non-interrupting ( `cancelActivity` )	Authored (registry gap)
Subprocess, event subprocess ( `triggeredByEvent` ), call activity	Authored (registry gap); call-activity payloads from registry
Multi-instance / loop characteristics	Authored from canvas contract — registry exposes no template (registry gap)
`bpmndi:BPMNDiagram` (shape per node, edge per flow)	Generated via `uip maestro bpmn format <file.bpmn>` — registry emits none (registry gap)

Flagged registry gaps: the registry serves no template for structural BPMN, sequence-flow conditions, event-definition payloads, boundary-event attributes, multi-instance markers, or the diagram. These are authored from the spec + canvas contract in references/structural-bpmn.md and honestly surfaced to the user as gaps when asked.

Rules

Registry owns every
uipath:*
payload. Author from
```
registry get
```
templates; never hand-write
```
uipath:
```
XML from prose.
Never fabricate an identifier. Connection IDs, process/queue/connector keys, app IDs, folder ids/paths come from discovery or the user.
Structural BPMN is authored, not invented. Follow the spec/canvas contract in references/structural-bpmn.md; flag honestly what the registry does not expose. BPMN XML element names are case-sensitive: use exact lower-camel tags such as
```
<bpmn:startEvent>
```
,
```
<bpmn:intermediateCatchEvent>
```
,
```
<bpmn:scriptTask>
```
, and
```
<bpmn:endEvent>
```
. Do not write PascalCase tags like
```
<bpmn:IntermediateCatchEvent>
```
.
Confirm before authoring. Confirm the chosen connector/connection/process and the process structure with the user (AskUserQuestion).
The diagram is mandatory. Import is diagram-driven — every node needs a
```
BPMNShape
```
, every flow a
```
BPMNEdge
```
, or it will not appear on the canvas.
Node type is a child element, never an attribute. Every
```
uipath:activity
```
/
```
uipath:event
```
/
```
uipath:mapping
```
declares its type as
```
<uipath:type value="<Type>" version="v1" />
```
inside the wrapper. Never write
```
<uipath:activity type="…">
```
— the canvas will not recognize the node. Event extension types (
```
Intsvc.WaitForEvent
```
,
```
Intsvc.EventTrigger
```
,
```
Maestro.ReceiveMessageEvent
```
,
```
Maestro.SendMessageEvent
```
) must use
```
<uipath:event>
```
, including when the BPMN host is task-like such as
```
<bpmn:receiveTask>
```
.
No
--
in XML comments. XML forbids
```
--
```
(double-hyphen) inside
```

```
, so never paste CLI commands or flags (
```
--output
```
,
```
--connection-id
```
,
```
--object-name
```
) into a comment — it makes the file unparseable. Keep comments minimal.
Use
--output json
for parsed CLI calls.
Public-safe always. No customer XML, tenant URLs, real IDs, or private names — see references/public-safety.md.
Confirm before any cloud change. Upload, publish, deploy, run, pause, resume, cancel, retry, and migrate require explicit user consent; validate locally first.

References

Topic	Read
Discover → template → bind → assemble loop	references/registry-workflow.md
Structural BPMN, event matrix, boundary events, containers, multi-instance, diagram, validation	references/structural-bpmn.md
Runtime expressions, `vars.` / `bindings.` / `iterator.` , `=js:` (Jint) syntax	references/expression-authoring.md
CLI conventions and the side-effect boundary	references/cli-conventions.md
Keeping content public-safe	references/public-safety.md
Package, upload, publish, run, or manage instances	references/operate/CAPABILITY.md
Diagnose a failed or misbehaving run	references/diagnose/CAPABILITY.md
Project layout and generated package files	references/shared/project-layout.md

uipath-maestro-bpmn

NPX Install

Tags

SKILL.md Content

Reasoning budget

Working style

UiPath Maestro BPMN

When to use

Editing an existing
`.bpmn`
(preserve what you did not author)

The model

Workflow

Operate and diagnose

Structural coverage

Rules

References