Skip to content
Open
Show file tree
Hide file tree
Changes from 5 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion skills/uipath-maestro-flow/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@
Do not hand-write the skeleton.
`--sdk-source` decompiles the trigger-only artifact `flow init` writes into the project's `.flow-sdk/<Name>.flow.ts`, creating the folder; the source carries the flow id and name the product already assigned — a hand-written `flow('<name>')` invents an id instead.
So the stub is the seed rather than litter: the first `compile -o` overwrites it in place.
`init` answering "already exists and is not empty. Use --force to overwrite" means it exists: never pass `--force`; edit it. Drop `--sdk-source` for a flow that will hold an Extract document node — it is CLI-authored throughout ([`references/extract-document-node.md`](references/extract-document-node.md)).
`init` answering "already exists and is not empty. Use --force to overwrite" means it exists: never pass `--force`; edit it. Drop `--sdk-source` for a flow that will hold an Extract document node — it is CLI-authored throughout; asked for in a `.flow-sdk/` project, it goes in a new one ([`references/extract-document-node.md`](references/extract-document-node.md)).
**Maestro Automate is `--automate` on the same `flow init`:** when the request names **Maestro Automate** as the product, run `( cd "<Solution>" && uip maestro flow init <Name> --automate --sdk-source )`; the bare verb ("automate invoice intake") asks for a plain Flow.
Nothing after `init` changes; the flag writes `runtimeOptions.profile` into `operate.json` plus a `.maestro_automate` marker, and `compile -o` rewrites only the `.flow`, so both survive.

Expand All @@ -56,7 +56,7 @@
<!--skill-flavor:sdk-project-layout:end-->

<!--skill-flavor:sdk-connector-discovery:start-->
Integrations with non-UiPath systems are handled through connectors. **Choose the node before writing it.** For an external service or data (weather, Slack, a REST API), run `uip maestro registry search '<brand or service name>'` over the local connector library, unless the request names the transport itself ("over HTTP, not a connector" means `http()`): a hit is a connector, `"total": 0` is a miss and means `http()` (not for an external agent: see the table), and a usage error means the library is not cached, so run `uip maestro registry pull` first. For another tenant capability (agent, process), which that library does not hold, run the family's `uip maestro flow registry search` ([`references/agent.md`](references/agent.md)). For document extraction, default to a published IXP model ([`references/ixp.md`](references/ixp.md)); the Extract document node only when asked for by name or already in the flow ([`references/extract-document-node.md`](references/extract-document-node.md)). A `script()` returning fixed values is never a stand-in for that step, and `mock()` only marks a capability the search proved absent.

Check warning on line 59 in skills/uipath-maestro-flow/SKILL.md

View workflow job for this annotation

GitHub Actions / skills/uipath-maestro-flow

Possibly stale `uip maestro registry search <brand or service name>` (valid prefix: `maestro registry search`)
Connectors require [`.flow-sdk/bindings.json`](references/bindings.md).
`uip maestro registry pull` writes a descriptor per referenced connector to `.flow-sdk/connectors/<key>.ts`, and caches the library itself outside the project.
Prepared connector modules live at `.flow-sdk/connectors-local/<key>.ts`; their descriptor data is kept separately below `.flow-sdk/connectors-local/descriptors/<key>/`.
Expand Down
10 changes: 8 additions & 2 deletions skills/uipath-maestro-flow/references/extract-document-node.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ uip maestro flow validate Flow/Flow.flow --output json

<!--skill-flavor:extract-find-flow:start-->
0. **Find the flow.** Everything here edits a `.flow` on disk. When the user describes a flow they are already building and none exists locally, they may be referring to one
that lives in Studio Web and has to be pulled down first — ask them for its URL or solution id, since nothing lists them ([Starting from a flow in Studio Web](extract-document-taxonomy.md#starting-from-a-flow-in-studio-web)).
that lives in Studio Web and has to be pulled down first — ask them for its URL or solution id, since nothing lists them ([Starting from a flow in Studio Web](extract-document-taxonomy.md#starting-from-a-flow-in-studio-web)). **Where the project folder holds `.flow-sdk/`, do not edit its `.flow`:** that flow is compiled from TypeScript source, so the node goes in a separate project ([Adding the node](#adding-the-node)), and every later step runs on that project's `.flow`.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[blocker][Correctness & logic] Distinguish source ownership from SDK caches

A .flow-sdk/ directory can hold only bindings and connector caches; SKILL.md calls it the SDK work directory, and registry prepare writes there. Its presence does not prove a maintained .flow.ts owns this Flow. This new step-0 guard also applies before edits to an existing extraction node, so a CLI-authored Flow with caches gets redirected to another project instead of receiving the requested edit. Check actual source ownership and cover a cache-only directory; do not treat every .flow-sdk/ as authoritative TypeScript.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 6b0d86d. The redirect now keys on a supplied source, the same test SKILL.md and brownfield.md use for "A supplied source": a .flow-sdk/<Name>.flow.ts the task handed over, not one decompiled for an edit. It applies only to adding a new node.

  • A .flow-sdk/ holding only bindings.json, connectors/ or connectors-local/ is called out as the SDK's cache: edit the .flow as usual.
  • A flow that already holds an Extract document node is edited in place, so an edit to an existing node is no longer redirected.

Step 0, the "Adding the node" paragraph and the SKILL.md sentence all use the same test. The Studio Web flavor replaces all three, so its output is unchanged.

<!--skill-flavor:extract-find-flow:end-->
1. **Declare the file the flow takes in,** unless it already has one: `uip maestro flow variables create <file> invoice -d in -t file --description '<what the document is>'`. This is what makes `$vars.start.output.invoice` resolve, so it comes before the node that reads it.
2. **Add the node** with `--label` naming what it extracts, and `--input` carrying `fileRef`.
Expand All @@ -58,7 +58,13 @@ The feature is new and tenant-gated, so not every tenant has it yet. Nothing in
## Adding the node

<!--skill-flavor:extract-sdk-mixing:start-->
**These commands edit the `.flow` file, so they do not mix with a project built from TypeScript source.** A project initialised with `--sdk-source` generates its `.flow` from a `.flow.ts` by compiling, and the next compile overwrites whatever `nodes create` and `nodes schema set` wrote. Check for a `.flow-sdk/` directory before starting. Where one exists, build the Extract document flow in a separate project without source and keep to the CLI — the SDK's `dynamicExtract()` is not the route here ([document-pipeline.md](document-pipeline.md) explains its limits). Do not alternate between the two and re-apply the CLI edits after each compile.
**These commands edit the `.flow` file, so they do not mix with a project built from TypeScript source.** A project with a `.flow-sdk/` directory generates its `.flow` from `.flow-sdk/<Name>.flow.ts` by compiling, and the next compile — the user's or a later turn's — overwrites whatever `nodes create` and `nodes schema set` wrote. Check for `.flow-sdk/` before starting. Where one exists, even when the user names that flow:

1. Leave that project as it is: no change to its `.flow`, none to its `.flow.ts`.
2. Build the Extract document flow in a new project in the same solution, without source: `( cd "<Solution>" && uip maestro flow init <NewName> )`, no `--sdk-source`. Keep to the CLI — the SDK's `dynamicExtract()` is not the route here ([document-pipeline.md](document-pipeline.md) explains its limits).
3. Tell the user why the step is in `<NewName>` and not in their flow: their flow is compiled from its TypeScript source, and the next compile would delete a node added to its `.flow`.

Do not alternate between the two and re-apply the CLI edits after each compile.
<!--skill-flavor:extract-sdk-mixing:end-->

`--label` sets the canvas name and seeds the node id. Give it a name that says which document and which fields, not "Extract" — a flow with two extraction nodes is common, and the label is what the user reads on the canvas and in a trace. Run `uip maestro flow nodes list <file> --output json` afterwards to get the id that was minted; later commands address the node by that id.
Expand Down
Loading