feat(uipath-api-workflow): add api workflow skills

[rares-baesu-uipath]

Summary

https://uipath.atlassian.net/browse/SW-26889

Introduces uipath-api-workflow, a new skill for authoring API workflow JSON files executed by uip api-workflow run. Focused on logical/hierarchical structuring — Sequence, Assign, JavaScript, If, ForEach, DoWhile, Break, TryCatch, Wait, Response — including deeply nested patterns. HTTP and Integration Service Connector activities are intentionally out of scope.

Adapted from the Autopilot StudioWeb api-workflow-architect skill; HTTP/Connector content stripped, control-flow content strengthened with nesting examples and a dedicated patterns reference.

What's in scope

• 10 activity types with required fields, export patterns, common mistakes, and per-type nesting hints in task-types.md
• Hierarchical patterns in a dedicated reference control-flow-patterns.md: nested If, multi-way branching via chained Ifs, ForEach with per-iteration If, nested loops with distinct iterators, conditional Break, exit-nested-loops via flag variable, TryCatch-around-loop vs TryCatch-inside-body, decision cheat sheet
• 4 templates verified end-to-end via uip api-workflow run --no-auth:
  • api-workflow-template.json — empty skeleton
  • conditional-workflow-example.json — TryCatch + ForEach + chained Ifs (multi-way branching)
  • loop-aggregation-example.json — DoWhile (Fibonacci) + ForEach (classification)
  • nested-control-flow-example.json — ForEach > DoWhile > TryCatch > If > Break (5 levels)
• CLI / packaging / publish docs for uip api-workflow run, uip solution pack, uip solution publish

What's deliberately out of scope

HTTP Request and Integration Service Connector activities. Both require StudioWeb-side editor metadata (a metadata.configuration blob plus a real connection UUID) that the CLI cannot generate cleanly today. Rather than emit broken cards that show as "blocked" in the StudioWeb designer, the skill explicitly directs users to author such activities directly in StudioWeb and merge them in. A follow-up could add uip case registry-backed metadata generation for known activity types — that path is identified in troubleshooting.md.

Key design decisions

The skill encodes several empirically verified runtime behaviors that an unaided agent gets wrong:

1. JsInvoke uses globals, not arguments[0]. Verified against @uipath/api-workflow-executor source — the script handler binds $context/$workflow/$input on globalThis via setVariables; the task body's arguments field is editor scaffolding that the runtime ignores.
2. Loop iterators and catch error variables get a literal $ prefix. for.each: "currentItem" binds the global as $currentItem (the $ is part of the identifier, not syntax). Same for for.at and catch.as. Forgetting the $ produces <name> is not defined.
3. $error is a ProblemDetails object, not a JS Error. Use $error.title / $error.detail / $error.originatingTaskName. There is no .message.
4. String literals in Assign.set and Response.response MUST be wrapped as "${'literal'}". StudioWeb's designer normalizes unwrapped strings to ${literal} on save, turning them into bare-identifier references that throw ReferenceError at runtime.
5. Each Assign sets exactly one variable. StudioWeb's designer collapses multi-key set blocks to a single key on save, silently dropping the rest. Multi-variable updates split into N sequential Assigns.
6. Globally unique keys across nested scopes, including #Wrapper / #Then / #Else / #Body suffixes.

Each of these is a Critical Rule in SKILL.md with a corresponding troubleshooting.md entry covering symptom + cause + fix.

Files

Path	Purpose
SKILL.md	15 critical rules + phase-based workflow + reference index
references/workflow-file-format.md	Top-level JSON skeleton, variables schema, WorkflowStart
references/task-types.md	Per-activity reference with nesting subsections
references/control-flow-patterns.md	Hierarchical pattern catalog
references/expressions-and-context.md	$context / $input / $workflow scopes, JS globals, strict-mode gotchas
references/cli-reference.md	All uip commands relevant to API workflows
references/troubleshooting.md	Categorized pitfalls + StudioWeb roundtrip section
assets/templates/*.json	4 templates (empty + 3 worked examples)

Test plan

• Run each template locally with uip api-workflow run --no-auth --output json and confirm success:
  • conditional-workflow-example.json with --input-arguments '{"transactions":[{"amount":1500},{"amount":2500},{"amount":300}]}' → expects tier: "GOLD", totalAmount: 4300, highValueCount: 2
  • conditional-workflow-example.json with negative amount input → expects tier: "INVALID", errorMsg populated from $error.title
  • loop-aggregation-example.json with '{"termCount":5}' → expects lastTerm: 8, fibSum: 19, classified array of 5 terms
  • nested-control-flow-example.json with the 3-task input → expects completed: 2, failed: 1
• Open each template in StudioWeb (alpha.uipath.com) and confirm:
  • All activities render without "block" icons
  • Save + reload preserves multi-Assign sequences (no silent collapse)
  • Run from designer produces same outputs as CLI runs
• Validate skill metadata: bash hooks/validate-skill-descriptions.sh exits 0
• CODEOWNERS entry added: /skills/uipath-api-workflow/ @rares-baesu-uipath
• Run a generation prompt from the test suite (e.g. "Make an API workflow that takes a score input and returns {grade}...") in a Claude Code session with the skill loaded; verify the output workflow respects single-key Assigns + wrapped literals + $-prefix loop vars + WorkflowStart on first attempt without manual fix-ups

[github-actions]

Claude finished @rares-baesu-uipath's task in 4m 50s —— View job

---

Review of PR #530 — uipath-api-workflow skill

• Read review criteria and project conventions
• Read full diff and all changed files
• Validate skill structure and frontmatter
• Check for test tasks
• Verify CODEOWNERS, links, cross-skill refs, secrets
• Apply skill scoring framework
• Post final review

---

Summary

Adds uipath-api-workflow, a new skill for authoring CNCF Serverless Workflow JSON files with UiPath extensions. Covers 10 activity types, 6 reference docs, 4 verified templates, and a thorough troubleshooting guide. The skill encodes several empirically-verified runtime behaviors (e.g., $-prefixed loop variables, single-key Assign, wrapped string literals). Overall quality is high — the issues below are mostly internal consistency bugs where reference docs contradict the skill's own Critical Rules.

Change-by-Change Review

1. skills/uipath-api-workflow/SKILL.md

Severity: High

Strong SKILL.md with well-structured Critical Rules, clear workflow phases, and good anti-patterns section. Two issues:

• [PREVIEW] prefix in description (line 3): The current skill-structure.md rule on main says description MUST start with the brand/domain identity and must NOT be prefixed with metadata tags like [PREVIEW]. Preview status should be indicated in the SKILL.md body (e.g., a > **Preview** callout under the H1). The description currently starts with "[PREVIEW] UiPath API Workflow assistant" — should be "UiPath API Workflow assistant" with a preview callout added to the body.
  Fix this →

• Dual-numbered rule 4 / 4a / 4b (lines 38–43): Rules 4, 4a, and 4b all use the number 4. This is mildly confusing for LLM consumption; renumbering 4a→5, 4b→6 (and shifting subsequent rules) would make references unambiguous. Low — not blocking.

2. skills/uipath-api-workflow/references/troubleshooting.md

Severity: High

Comprehensive pitfall catalog. One critical documentation bug:

• Wrong fix for loop iterator reference (lines 80–83): The "Wrong variable reference for loop iterator" entry suggests the fix is ${currentItem}, ${currentItemIndex} — without the $ prefix. This directly contradicts Critical Rule 8a and task-types.md line 225, which both confirm the correct form is ${$currentItem}, ${$currentItemIndex}. An agent following this troubleshooting advice would introduce the exact bug the skill warns about.
  Fix this →

3. skills/uipath-api-workflow/references/expressions-and-context.md

Severity: Medium

Good reference overall. Two issues in the Available Scopes table:

• Contradictory catch binding rows (lines 15–16): Two rows describe catch bindings — line 15 says ${$error} (correct, with $ prefix), line 16 says ${error} (incorrect, without $). Per Critical Rule 8a and task-types.md line 365, the $ prefix is required. The second row should be removed entirely — it contradicts the first and would confuse an agent.
  Fix this →

4. skills/uipath-api-workflow/references/task-types.md

Severity: Medium

Thorough activity reference. Two issues in the Assign section:

• Multi-key set in minimal example (lines 60–67): The Assign minimal JSON shows "set": { "userName": "John Doe", "count": 0 } — a multi-key set. Critical Rule 4b explicitly states each Assign MUST set exactly one variable because StudioWeb collapses multi-key sets. The example should show a single-key set.
  Fix this →

• Unwrapped string literal (line 60): The same example uses "userName": "John Doe" instead of "userName": "${'John Doe'}". Critical Rule 4a requires wrapping string literals to survive StudioWeb roundtrip.

5. CODEOWNERS

Severity: Medium

The new /skills/uipath-api-workflow/ @rares-baesu-uipath entry is correct. However, the diff includes two unrelated removals:

• Guardrails entry removed (was line 31): /skills/uipath-agents/references/lowcode/capabilities/guardrails/ entry deleted, but the directory still exists on main. This removes ownership tracking from existing files.
• Review skill entry removed (was line 58): /skills/uipath-review/ entry deleted — the directory no longer exists, so this removal is fine.

The guardrails removal should be in a separate PR or at minimum confirmed with the listed owners (@apetraru-uipath @valentinabojan @ctiliescuuipath).

6. skills/uipath-api-workflow/references/control-flow-patterns.md

Severity: OK

Excellent pattern catalog. 10 patterns with clear tree diagrams, JSON examples, and an anti-patterns section. Globally unique key numbering convention is well-explained. Decision cheat sheet at the end is a nice touch for LLM consumption. No issues found.

7. skills/uipath-api-workflow/references/workflow-file-format.md

Severity: OK

Clean file format reference. Top-level structure, variables schema, WorkflowStart system activity, and project structure all well-documented.

8. skills/uipath-api-workflow/references/cli-reference.md

Severity: OK

Covers uip api-workflow run, uip solution pack/publish/deploy, and uip login. Includes a "Commands That Do NOT Exist" section — good for preventing agent hallucination.

9. assets/templates/*.json (4 files)

Severity: OK

All four templates are well-formed JSON. They correctly demonstrate:

• Single-key Assigns with wrapped string literals (${'PLATINUM'}, ${'GOLD'}, etc.)
• $-prefixed loop variables ($currentItem, $currentItemIndex, $currentTask, $taskIndex, $term, $termIndex)
• Proper #Wrapper/#Then/#Else If structure
• Proper #Body loop structure
• Globally unique keys across nested scopes
• then: "exit" on branches, then: "end" on Response

Templates practice what the skill preaches — good internal consistency.

What's Missing

• Test tasks: No tests/tasks/uipath-api-workflow/ directory. Most skills are not yet test-compliant, but given the PR description includes a detailed test plan, at least a smoke task would strengthen confidence.
• Preview callout in SKILL.md body: If [PREVIEW] is removed from the description (per current rules), a > **Preview** callout should be added under the H1.

Area Ratings

Area	Status	Notes
Frontmatter	Issue	[PREVIEW] prefix violates current skill-structure.md rules; description is 787 chars (under 1024 ✓), front-loads identity ✓, includes → redirects ✓
E2E Tests	Issue	No tests/tasks/uipath-api-workflow/ directory
Skill Body	OK	Strong Critical Rules, clear workflow phases, good anti-patterns section
References & Assets	Issue	Troubleshooting has wrong loop-variable fix; expressions doc has contradictory catch rows; task-types Assign example contradicts Critical Rules 4a/4b
Repo Hygiene	Issue	CODEOWNERS has unrelated guardrails removal; no secrets/personal paths ✓; no cross-skill refs ✓

Issues for Manual Review

• Runtime accuracy of templates: The templates should be verified with uip api-workflow run --no-auth --output json as described in the test plan. I cannot execute CLI commands to confirm.
• StudioWeb roundtrip: The PR claims templates roundtrip cleanly through StudioWeb — this needs manual verification in alpha.uipath.com.
• Trigger scope overlap: Verify the skill doesn't false-trigger on prompts about .flow files or other UiPath project types. The → redirects look correct but real-world trigger matching should be tested.
• $-prefix behavior claim: The skill asserts the executor binds loop variables with a literal $ prefix (e.g., $currentItem), citing empirical verification. This is a foundational claim — if wrong, most templates would fail. The templates reportedly pass, which validates it indirectly.

Conclusion

Request changes. The skill is well-crafted with excellent domain knowledge, but has three issues that need fixing before merge:

1. High — Remove [PREVIEW] from description (SKILL.md:3): Violates current skill-structure.md rules on main. Move preview status to a body callout.
2. High — Fix wrong loop-variable reference in troubleshooting (troubleshooting.md:80-83): Currently suggests ${currentItem} instead of ${$currentItem} — following this advice introduces the exact bug the skill warns about.
3. Medium — Remove contradictory catch binding row (expressions-and-context.md:16): Duplicate row says ${error} without $, contradicting the correct row above it.
4. Medium — Fix Assign example to match Critical Rules (task-types.md:60-67): Multi-key set with unwrapped string literal contradicts rules 4a and 4b.
5. Medium — Separate unrelated CODEOWNERS removal (CODEOWNERS): Guardrails directory still exists; removing its ownership entry should be confirmed with listed owners or done in a separate PR.

---

[github-actions]

⚠️ Smoke test coverage gap — the following changed skills have no tests under tests/tasks/:

• uipath-api-workflow

Consider adding smoke tests before merging.

[liviubobocu]

we need template examples and references in workflows towards Connector activities, (Unified HTTP Activity, Connector HTTP activities like Slack Http Request or regular DAP connectors like Slack Send Reply.)

[liviubobocu]

I think we should also address uip cli version pinning for capabilities tied to a specific version. The CLI is changing fast and this will help both us users and agents.

[liviubobocu]

we can also add incremental, besides distinct here.

[liviubobocu]

there is a type mismatch here, the Response task produces an output with classified property as well, and the property is missing here

[liviubobocu]

here we can mention that currentItem and currentItemIndex can be also renamed and we can also use the renamed versions as well

[liviubobocu]

here the conformation may be misleading. we are not 100% following the spec in some aspects. I hope this wouldn't lead to hallucinated versions from the spec into the workflow. to mitigate this I think we can address having enough workflow examples for the agent to mitigate spec losses.

[liviubobocu]

here I think a scenario that is more close to real usage would help, like fetching some data and verifying the data is correct