fix(skills): align API workflows with Studio Web capabilities

[astridstaicu]

Summary

Follow up the generic skill-flavor framework with the first evidence-led API Workflow correction.

• keep the canonical SKILL.md and shared references as the source of truth
• add sparse Studio Web overrides only for host-specific project creation, VFS paths, authentication, execution, resource metadata, lifecycle, and diagnostics
• create API projects through the live proxy-tools-Solution / CreateProjects schema; never through init or fabricated metadata
• retain the useful embedded browser CLI surface for static validate, registry resolve / stub, and read-only uip is discovery
• require explicit consent plus a fresh proxy-tools-Api schema read before RunProject
• allow the host-intercepted active-solution uip solution publish bridge only after an explicit publish request; keep local pack/deploy/login and nonexistent uip api-workflow publish forbidden
• preserve all default/local CLI behavior in the default package

Live Studio Web evidence

Test project: FlavorApiCodex0807A

• CreateProjects created a second API Workflow project and real generated tree
• uip api-workflow validate returned ApiwfValidate / Valid
• registry resolve/stub returned ActivityResolveSuccess and ActivityStubSuccess
• embedded uip api-workflow run failed before WorkflowStart with No worker implementation available
• live RunProject({ projectName: "FlavorApiCodex0807A" }) succeeded and returned UIPATH_SW_FLAVOR_0807
• init, bindings sync, and resource refresh were denied without artifacts
• uip solution publish --help returned help without starting publication

Validation

• npm run skills:validate — default 25 skills / 1703 files / 0 replacements; Studio Web 25 / 1703 / 68 sparse replacements
• npm run skills:test — 48/48 pass
• npm run skills:build — both trees marker-free
• npm run skills:pack — default and Studio Web npm packages verified
• git diff --check — pass

Related Autopilot package-consumption PR: https://github.com/UiPath/Autopilot/pull/4920

[astridstaicu]

Live Studio Web evidence video

Internal UiPath evidence (requires access to UiPath/Autopilot):

Play or download the evidence video

This test directly motivated the sparse Studio Web overrides in this PR:

• CreateProjects is the real project-creation path; standalone init is denied
• static validate and registry resolve/stub work in the browser CLI
• embedded api-workflow run fails before WorkflowStart with No worker implementation available
• the live proxy-tools-Api / RunProject path succeeds after explicit consent
• local pack/build, bindings sync, resource refresh, and mutating Integration Service commands must not be presented as supported Studio Web operations
• solution publish --help is read-only and did not publish

Full evidence is preserved internally at Autopilot commit cdbb541ab4. Companion runtime PR: UiPath/Autopilot#4921.

[github-actions]

Claude finished @astridstaicu's task in 5m 13s —— View job

---

PR Review: fix(skills): align API workflows with Studio Web capabilities

• Read review criteria and project conventions
• Read full diff and existing PR conversation
• Read all changed files in full
• Check skill-specific requirements (links, cross-refs, secrets, CODEOWNERS)
• Post review findings

---

Summary

Adds evidence-led Studio Web sparse overrides for the uipath-api-workflow skill: new flavor blocks in the canonical SKILL.md and references (cli-reference, connector-activity-discovery, troubleshooting, workflow-file-format, expressions-and-context, operating-published-workflows), plus 5 new Studio Web override files (SKILL.md, cli-reference.md, connector-activity-discovery.md, troubleshooting.md, operating-published-workflows.md) and 1 modified override (workflow-file-format.md). The canonical description is updated for hosted-environment awareness and the compose-skill-flavor test is substantially expanded to verify the Studio Web contract integrity.

Change-by-Change Review

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

Severity: Low

Frontmatter: name matches folder, description is 983 chars (under 1024 cap). The new description replaces the compact → redirect notation (For .flow Maestro→uipath-maestro-flow) with the more verbose Do not trigger for .flow Maestro (use uipath-maestro-flow), ... phrasing. Per .claude/rules/skill-structure.md, descriptions "MUST include compact redirects for commonly confused sibling skills using → notation" and "MUST NOT use verbose TRIGGER when: / DO NOT TRIGGER when: clauses." The new phrasing is borderline — it's a single sentence, not a DO NOT TRIGGER when: section header, but it uses ~22 more characters and deviates from the → convention. Not blocking, but worth aligning.

New flavor marker blocks are well-formed (compact ``, no internal whitespace). Empty canonical blocks (host-command-contract, `host-command-scope`) correctly serve as flavor-only injection points. Body changes (rules 2, 3, 15, 17, 18, 20, 21) consistently generalize CLI-specific phrasing to be host-agnostic while keeping default behavior unchanged within the default package.

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

Severity: OK

22 new flavor markers wrap the correct sections: local project lifecycle (init/build/pack), runtime execution (run), registry auth, solution metadata, solution lifecycle, and command-existence guidance. The markers are minimal and well-placed. Default content is preserved.

3. skills/uipath-api-workflow/references/connector-activity-discovery.md

Severity: OK

14 new markers correctly cover: host-command-scope, registry-auth, discovery-flow, connection-remediation, validate-and-run, http-example-execution-proof, resource-lookup-runtime, generic-resource-runtime-diagnostic, solution-metadata, solution-resource-fields, worked-example-solution-metadata, registry-auth-limit, solution-metadata-antipattern. Each wraps the smallest passage that differs by flavor.

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

Severity: OK

Two small changes: --input-arguments JSON or caller → supplied by the execution caller and the comment updated. Host-agnostic without changing semantics.

5. skills/uipath-api-workflow/references/operating-published-workflows.md

Severity: OK

Single published-operations marker wrapping the entire operations section. Appropriate — the whole section's default content references uip or / uip is commands that the Studio Web override replaces entirely.

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

Severity: OK

18 new markers on runtime headings, file-path/JSON/input-args remediation, executor failures, cloud-run diagnostics, packaging errors, publish errors, validation pitfall, and debugging strategy. The existing runtime-validation fix text updates from "Two validators: ... then uip api-workflow run --no-auth" to consent-aware phrasing. "Assuming an edit succeeded" fix updated to reference static validation and explicit consent. All appropriate.

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

Severity: OK

3 new markers: runtime-description, runtime-input-output, and pre-existing project-structure. The --input-arguments reference generalized to "execution caller."

8. skill-flavors/studioweb/uipath-api-workflow/SKILL.md

Severity: OK

Previously had 7 blocks; now has 22. New blocks cover: surface-summary, host-command-contract (the key contract section), runtime-validation-contract, runtime-validation-limit, runtime-execution-consent, runtime-invocation-io, cli-reference-navigation, template-execution-proof, runtime-execution-antipattern, published-reference-navigation, solution-resource-template. The host command contract section is comprehensive: allowed CLI, execution via RunProject, publication via host-intercepted bridge, forbidden commands, working directory. All block names are unique and kebab-case.

9. skill-flavors/studioweb/uipath-api-workflow/references/cli-reference.md (NEW)

Severity: OK

101 lines, 11 blocks. Covers: host-command-scope banner, local-project-lifecycle replacement (forbids init/build/pack), runtime-execution replacement (documents RunProject path), registry-auth (inherited session), registry-auth-remediation, solution-resource-key, connector-typical-sequence (Studio Web variant), local-solution-metadata, local-solution-lifecycle (including the publish bridge with supported flags table), command-existence-guidance, api-workflow-publish-guidance. Well-structured with actionable CLI examples.

10. skill-flavors/studioweb/uipath-api-workflow/references/connector-activity-discovery.md (NEW)

Severity: OK

71 lines, 14 blocks. The discovery flow is cleanly adapted: steps 6-7 replace the default "validate then run" with consent-gated RunProject. Connection remediation removes uip is connections edit. Solution-metadata blocks forbid binding-sync/resource-refresh. All self-contained.

11. skill-flavors/studioweb/uipath-api-workflow/references/operating-published-workflows.md (NEW)

Severity: OK

9 lines, single block. Replaces the default operations table + uip or / uip traces commands with "use Studio Web capabilities, report gaps." Appropriately lean.

12. skill-flavors/studioweb/uipath-api-workflow/references/troubleshooting.md (NEW)

Severity: OK

105 lines, 18 blocks. Comprehensive replacements: runtime heading becomes "Runtime Errors in Studio Web," file-not-found references working directory, JSON syntax uses jq instead of node, runtime-input-arguments references RunProject schema, executor failures reference RunProject result, packaging/publish errors reference Unified Build and Publish history. Cloud-run diagnostics correctly forbids local uip or/trace fallbacks.

13. skill-flavors/studioweb/uipath-api-workflow/references/workflow-file-format.md

Severity: OK

3 blocks added (2 new: runtime-description, runtime-input-output; 1 updated: project-structure). Project structure expanded with concrete post-CreateProjects guidance (/solution/<projectName>, LsDirectory verification, forbidden metadata files).

14. tests/scripts/compose-skill-flavor.test.mjs

Severity: OK

Test renamed from "inherits all API Workflow references and adds only host scope" to "inherits API Workflow authoring guidance and applies its host command contract." 68 new lines add a full materialization test that:

• Builds the complete Studio Web flavor tree
• Verifies all 6 overridden files are marker-free
• Asserts presence of key contract terms (RunProject, consent, publish bridge flags, No worker implementation available)
• Asserts absence of forbidden commands (uip login, uip api-workflow init/build/pack/run, uip solution init/pack/deploy, uip is connections edit, etc.)
• Confirms default CLI reference preserves init, run, and publish commands

This is a thorough composition-integrity test.

What's Missing

• Description format (Low): The canonical SKILL.md description's redirect section uses Do not trigger for ... (use ...) instead of the repo-mandated → redirect notation. Consider reverting to: For .flow Maestro→uipath-maestro-flow, .xaml/coded RPA→uipath-rpa, coded agents→uipath-agents, Coded Apps→uipath-coded-apps. Fix this →
• CODEOWNERS for override path (Low): CODEOWNERS covers /skills/uipath-api-workflow/ but does not have a dedicated entry for /skill-flavors/studioweb/uipath-api-workflow/. The skill-flavors/ tree may have a wildcard entry or the existing owners may cover it — verify this is intentional.

Area Ratings

Area	Status	Notes
Frontmatter	OK	name matches, description 983 chars, valid YAML
E2E Tests	OK	Existing test tasks cover the skill; composition test substantially expanded
Skill Body	OK	Canonical changes are host-agnostic generalizations; flavor overrides are evidence-backed
References & Assets	OK	All links resolve; 5 new override files + 1 modified; no cross-skill refs; sparse overrides only
Repo Hygiene	OK	No secrets, no binary files, CODEOWNERS entry exists, changes scoped to api-workflow

Issues for Manual Review

• CLI command accuracy. The uip solution publish bridge flags (--description, --release-notes, --version, --location, --location-name, --personal-workspace) were derived from live testing per the PR description. Verify these flags remain stable in the Studio Web host.
• RunProject schema path. The overrides consistently reference /skills/synthetic/proxy-tools-Api/SKILL.md as the schema source. Confirm this synthetic skill path is stable across Studio Web deployments.
• jq availability. The troubleshooting override replaces node -e "JSON.parse(...)" with jq empty Workflow.json for JSON syntax validation. The PR assumes jq is available in the Studio Web browser shell — verify this.

Conclusion

Well-structured PR that correctly applies the sparse-flavor pattern to a complex skill. The canonical changes are minimal and host-agnostic; the Studio Web overrides are evidence-backed (live testing documented in PR description) and comprehensively tested by the expanded composition test. The only style issue is the description redirect format (Low). The substantive content — command contract, RunProject consent-gating, publish bridge, forbidden-command enumeration — is thorough and internally consistent across all 6 override files without concerning duplication.

Recommendation: Approve (with optional Low fix for the description redirect format).

---

[astridstaicu]

we can leave this empty, there's no auth error in autopilot in studio web