/uipath-api-workflow

name: uipath-api-workflow
description: "UiPath API Workflow assistant — author, run, validate, package, publish, deploy, and troubleshoot JSON workflows for `uip api-workflow`. Load for ANY create/edit of a `Workflow.json` / API workflow project; with `evals/` present, tests come first (TDD). Covers Sequence, Assign, JavaScript, If (#Wrapper/#Then/#Else), ForEach, DoWhile, Break, TryCatch, Wait, Response, nested; files as JobAttachment refs via File to Base64 / Base64 to File (`$helpers.file.*`, `serializeData()`, `--input-file`/`--output-dir`); HTTP / IS connector activities via `uip api-workflow registry`. Operate: run, IS connections, pack/publish/deploy. Test/eval: `evals/<scope>/eval-sets/` datasets (exact-match, Evaluations panel); loop until green. Triggers on API workflows, project type \"Api\", JSON with `document.dsl`/`do[]`, those activity types, or file/base64 handling. Agent evals (`evals/eval-sets/`, no scope) & coded agents→uipath-agents. Flow & its evals→uipath-maestro-flow. .xaml/coded RPA→uipath-rpa. Coded Apps→uipath-coded-apps."
allowed-tools: Bash, Read, Write, Edit, Glob, Grep

UiPath API Workflow Assistant

<!--skill-flavor:surface-summary:start--> Build, run, and publish UiPath API Workflows: JSON conforming to CNCF Serverless Workflow DSL 1.0.0 with UiPath activity extensions. Workflows run through `@uipath/api-workflow-executor` and `uip api-workflow run`, and package as `Type: "Api"` projects through `uip solution pack`. <!--skill-flavor:surface-summary:end--> <!--skill-flavor:host-command-contract:start--> <!--skill-flavor:host-command-contract:end-->

> **TDD gate — read first (rule 22).** For create/edit requests, check `<project>/evals/` beside `Workflow.json`, never at workspace or solution root. If absent, Evaluations is off: do not ask about tests or loop mode; author normally. If present, stop before authoring and ask whether existing rows remain/change or empty tests should be added, and whether to run/retry until all pass or author once. After both answers, declare schemas, write/update evals first, then author. A request not to ask skips these questions, not runtime consent; run rows only when requested. Later behavior changes require asking whether affected expectations should change.

When to Use This Skill

Use for API workflow JSON creation/editing and activities including Sequence, Assign, JavaScript, Log Message, If, ForEach, DoWhile, Break, TryCatch, Wait, Response, HTTP Request, and connector activities. Use the connector and testing references for Studio Web connector workflows and project `evals/` layouts.

<!--skill-flavor:surface-lifecycle-scope:start-->

• Local runs, validation, build/packaging, publishing

<!--skill-flavor:surface-lifecycle-scope:end-->

• User wants to **handle a file** in an API workflow — take a file input, send a file as base64 to an API, turn a base64 payload back into a file, or asks about `JobAttachment`, `$helpers.file`, `serializeData()`, `--input-file` / `--output-dir`. See [references/files-and-base64.md](references/files-and-base64.md)
• Starting a workflow from a connector event (Slack button clicked, new Outlook calendar entry), or inspecting/changing an existing trigger (`call: "UiPath.IntSvcEvent"`). See [references/trigger-authoring-guide.md](references/trigger-authoring-guide.md)

<!--skill-flavor:surface-operations-scope:start-->

• Operating published workflows

<!--skill-flavor:surface-operations-scope:end-->

Do not use for `.flow` Maestro flows (`uipath-maestro-flow`), `.xaml` or coded RPA (`uipath-rpa`), coded agents (`uipath-agents`), or Coded Web Apps (`uipath-coded-apps`). API-workflow evals are only `evals/` beside `Workflow.json` using `evals/<scope>/eval-sets/`; `evals/eval-sets/` is for low-code agents and Flow evals for `uipath-maestro-flow`.

Core Principles

0. **Escalate judgment-based forks before building.** If a connection is unavailable, no curated activity exists, an undocumented HTTP fallback is needed, an assumed input is missing, or structurally different workflows are plausible, perform only shared discovery, then stop with trade-offs and a recommendation. Do not build every branch. Mechanical choices need no escalation. 1. **Know before writing.** Read an existing workflow before editing and the relevant template before creating. <!--skill-flavor:runtime-validation-contract:start--> 2. **Start minimal, iterate to correct.** Add one activity at a time. Run with `--no-auth --output json` after each addition. Fix what breaks. Repeat. 3. **Validate before running.** `uip api-workflow validate` is autonomous/offline. `run` is runtime validation, may access HTTP or connections, and requires consent. <!--skill-flavor:runtime-validation-contract:end--> 4. **Fix by category:** Structure > Expression > Activity Config > Logic.

Critical Rules

1. **Workflow JSON.** Top level has `document` with `dsl: "1.0.0"`, `evaluate` with `language: "javascript"` and `mode: "strict"`, and `do` containing one root sequence. Root sequence names may vary; read the file. See [references/workflow-file-format.md](references/workflow-file-format.md).

2. **WorkflowStart.** It is first in the root sequence, hydrates variable defaults into `$context.variables`, forwards inputs to `$input`, and must not be removed, renamed, or modified. Only it uses `isTransparent: true`.

3. **Activity objects and keys.** Each activity is one single-key object in a `do` array. Keys are globally unique, including wrapper suffixes such as `#Wrapper`, `#Then`, `#Else`, and `#Body`.

4. **Exports.** Every activity except Log Message should export output. Assign uses `{ ...$context, variables: { ...$context.variables, ...$output } }`; all others use `{ ...$context, outputs: { ...$context?.outputs, "<ActivityKey>": $output } }`. See [references/expressions-and-context.md](references/expressions-and-context.md).

<!--skill-flavor:designer-literal-runtime-comparison:start--> 5. **Literal expressions.** In Assign `set`