fix(api-workflow): align skill with the CLI's actual project surface (init/build/pack)

[rares-baesu-uipath]

Why

A private-preview client reported that the uipath-api-workflow skill does not enforce proper project structure. Root cause (confirmed against the Woolworths RCA + session logs and the CLI source): the skill steered agents to hand-assemble projects as project.json + workflows/WF_*.json and listed uip api-workflow init under "Commands That Do NOT Exist."

That project.json-only shape passes every runtime gate — validate, run, pack, publish, deploy — but Studio Web's import rejects it (invalid_project_folder) because it has no .uiproj, so the project never appears/edits in Studio Web. The defect is invisible until a human opens Studio Web.

uip api-workflow init (shipped well before that build) scaffolds the correct Studio Web editable shape and auto-registers the project in the solution .uipx. Had the skill used it, the wrong shape could not have been produced.

What changed

• Lead with uip api-workflow init. Rewrote rules 19/19a; the Studio Web contract is framed as the spec init satisfies — init is the one step that can't produce the wrong shape.
• Document the real command surface. Added init, build, and project-level pack to cli-reference.md — all three exist; the skill previously claimed init/build did not.
• uip solution new → uip solution init everywhere (the new verb was retired and now errors unknown command 'new').
• Troubleshooting fixes. uip api-workflow validate exists (was claimed absent); added the "runs/deploys but won't open in Studio Web" entry with safe remediation (re-scaffold via init, or in-place convert preserving the project Id — never project remove+add, which mints a new Id).
• Studio Web editable contract documented in workflow-file-format.md (the .uiproj/entry-points.json field rules).
• Fixed package_solution.yaml description (build is project-scoped, not absent).

Scope note (slimmed): an earlier revision also added a scripts/verify-studio-web-shape.mjs pre-pack gate + project.uiproj/entry-points.json reference templates. These were dropped to keep the PR focused on the actual fix — init already makes the wrong shape unproducible, so the gate is belt-and-suspenders drift defense better suited to a follow-up.

Verification

Built the CLI locally (bun run build, v1.198.0) and ran the documented flow as 11 assertions — all pass:

solution init → api-workflow init (registers in .uipx with Type:"Api" + project.uiproj + fresh Id) → validate Valid → solution pack (produces .zip) → api-workflow build → api-workflow pack (.nupkg) → init --skip-solution-registration standalone.

Repo CLI-verb checker: 0 High / 0 Medium.

Ran the changed coder-eval task skill-api-workflow-package-solution locally (experiments/default.yaml, tempdir driver) — passed, 3/3 criteria, weighted score 1.000. The agent scaffolded an API workflow and packaged it via uip solution pack --output json, producing ConstantSolution_1.0.0.zip.

Notes / follow-ups

• Self-contained: only touches uipath-api-workflow + its test. CODEOWNERS already covers the paths.
• The deeper upstream cause (planner/SDD scaffolding emitting the project.json shape into task T9) is out of scope here — recommend a follow-up in uipath-planner.

🤖 Generated with Claude Code

[github-actions]

Claude finished @rares-baesu-uipath's task in 2m 26s —— View job

---

Coder-eval task lint (advisory)

1 task YAML changed; verdicts: 0 Critical, 0 High, 0 Medium, 1 Low, 0 OK.

Rubric: .claude/commands/lint-task.md. This check is advisory and never blocks merge.

Evidence of passing run

❌ High — PR body does not claim the changed coder-eval task (skill-api-workflow-package-solution) was run and passed. The "Verification" section documents 11 CLI-level assertions against the skill itself, but does not assert that the coder-eval task was executed. Please edit the PR description to add a line like:

Ran skill-api-workflow-package-solution locally and it passed.

Per-task lint

tests/tasks/uipath-api-workflow/package/package_solution.yaml — verdict: Low

Issues:

• [Low] Meaningful coverage (lines 26–30): run_command uses find . -name '*.nupkg' -o -name '*.zip' | grep -q . — confirms an artifact exists but does not validate its contents. A stray .zip anywhere in the tree (or an agent running touch foo.nupkg) would satisfy this criterion independently of uip solution pack actually succeeding. Consider adding a run_command that inspects the artifact (e.g. unzip -l *.nupkg | grep -q '.json') or a json_check on uip solution pack --output json stdout to verify the pack command itself reported success.

Suggested fixes:

• Add a run_command criterion that cross-checks pack success, e.g.:

  - type: command_executed
    description: "solution pack reported success"
    tool_name: "Bash"
    command_pattern: 'uip\s+solution\s+pack.*--output\s+json'
    min_count: 1
    weight: 1.5
    pass_threshold: 1.0

  (This already partially exists as criterion 3 at weight 1.0 — consider raising weight or adding a run_command that parses its stdout for a success indicator.)

Notes: The only change in this PR is a description wording fix (line 5–8: "non-existent uip api-workflow build" → "project-scoped uip api-workflow pack/build"). Criteria, prompt, and tags are unchanged. The Low finding is pre-existing, not introduced by this PR.

Within-PR duplicates

No duplicate clusters detected (only 1 task YAML changed).

Conclusion

⚠ 1 task has issues, max severity Low (per-task) + High (missing passing-run claim). Advisory only — not blocking merge. The per-task Low finding is pre-existing. The only actionable item is adding a passing-run claim to the PR description.

---

[github-actions]

Claude finished @rares-baesu-uipath's task in 3m 15s —— View job

---

PR Review: fix(api-workflow) — align skill with CLI's actual project surface

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

---

Summary

Rewrites the uipath-api-workflow skill's project scaffolding guidance to lead with uip api-workflow init (which produces the correct Studio Web editable shape), documents three previously-claimed-nonexistent commands (init, build, pack), renames solution new → solution init, adds a pre-pack verification script and two reference templates, and adds a troubleshooting entry for the "runs but won't open in Studio Web" defect. Well-motivated fix with thorough verification.

Change-by-Change Review

1. skills/uipath-api-workflow/SKILL.md — Critical Rules 19/19a/19b

Severity: Medium (duplicate anti-patterns)

The new rules 19, 19a, and 19b are thorough and well-structured. The solution new → solution init rename in the Quick Start is correct. The pre-pack gate placement in the workflow is logical. Two issues:

• Duplicate anti-patterns (SKILL.md:298 and SKILL.md:300): Two bullets say nearly the same thing — "Do NOT trust 'it packed / published / ran' as proof a project opens in Studio Web." The first (line 298) mentions both init and verify-studio-web-shape.mjs; the second (line 300) mentions only the script. One should be removed. Similarly, lines 296 and 299 overlap: "hand-assemble a project" vs "ship an API project as project.json + workflows/WF_*.json" — these cover the same mistake from slightly different angles. Consolidating would tighten the section.

  Fix duplicates →

• Rule 19a length: Rule 19a is ~15 lines of dense prose inlined in Critical Rules. The detail is valuable, but SKILL.md loads into the agent's context on every activation. The Studio Web contract spec, conversion instructions, and "why this matters" block could be extracted to a dedicated reference (or a section anchor in workflow-file-format.md, which already has the contract). This is a judgment call given the severity of the bug this prevents — flagging as Low.

2. skills/uipath-api-workflow/assets/templates/entry-points-template.json (new)

Severity: OK

Clean template. <GENERATE_GUID> placeholder uses the correct <UPPER_SNAKE_CASE> convention. Fields match the contract in workflow-file-format.md.

3. skills/uipath-api-workflow/assets/templates/project-uiproj-template.json (new)

Severity: OK

Minimal and correct. <PROJECT_NAME> placeholder follows convention. ProjectType: "Api" matches the strict-enum requirement.

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

Severity: OK

The three new command sections (init, build, pack) are well-documented with flag tables, output samples, and failure modes. The solution new → solution init rename is clean with a clear deprecation note. The "Commands That Do NOT Exist" section correctly removed init and added the clarifying paragraph. End-to-end example updated consistently.

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

Severity: Low

• troubleshooting.md:591: The command node scripts/verify-studio-web-shape.mjs <solutionDir> uses a bare relative path. Elsewhere in the skill (SKILL.md rules 19b, Quick Start, cli-reference.md), the script is referenced via the full plugin path (./.claude/plugins/uipath/skills/uipath-api-workflow/scripts/...) or via the $SKILL variable. This bare scripts/ path only works if the agent's cwd is the skill folder, which is unlikely. Consider matching the pattern used in SKILL.md rule 19b for consistency.

• The new "API workflow runs/deploys fine but does NOT appear or open in Studio Web" entry (lines 582–591) is excellent — thorough, actionable, and correctly references both the re-scaffold and in-place conversion paths.

• solution new → solution init rename on line 572: correct.

• Validation pitfalls fix (line 616): correctly documents both validate and run --no-auth as the two-validator chain.

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

Severity: OK

Section renamed from "Packaging Context" to "Studio Web editable contract" — better reflects the actual concern. The new field-rules table and the two blockquote callouts are clear and consistent with the SKILL.md rules. The standalone-project note is a useful addition.

7. skills/uipath-api-workflow/scripts/verify-studio-web-shape.mjs (new)

Severity: Low

Well-structured validation script. Error/warning classification is correct (HARD errors for shape-breaking issues, WARN for non-canonical but functional state). Two minor observations:

• verify-studio-web-shape.mjs:14-15: readJson() has no error handling — a malformed JSON file will throw an unhandled exception with a raw Node.js stack trace. Consider wrapping in try/catch with a clear error message (e.g., "Failed to parse <path>: invalid JSON") since agents will run this and need actionable output.
• The script uses ESM imports (import ... from "node:fs") which requires Node.js ≥16 and either a .mjs extension (present) or "type": "module" in package.json. The .mjs extension handles this correctly.

8. tests/tasks/uipath-api-workflow/package/package_solution.yaml

Severity: OK

Description update is accurate — build/pack are now project-scoped, not nonexistent. Tags and criteria unchanged. No functional impact.

What's Missing

• No test task for uip api-workflow init: This PR introduces init as the canonical way to create projects (the core fix). The existing package_solution.yaml tests the uip solution pack path but doesn't verify the agent uses init to scaffold. A command_executed check for uip\s+api-workflow\s+init in at least one task would validate that the skill teaches the new flow. Medium — recommend adding in a follow-up since the init command is the heart of this fix.
• No test task for the pre-pack verification gate (verify-studio-web-shape.mjs). The script is a new artifact the agent is told to run before every pack. Lower priority than init coverage since it's a secondary gate. Low.

Area Ratings

Area	Status	Notes
Frontmatter	OK	name matches folder, description unchanged, under 1024 chars
E2E Tests	Issue	Existing test updated correctly; no new task for the init command (Medium)
Skill Body	Issue	Duplicate anti-pattern bullets (Medium); rule 19a is long but justified
References & Assets	OK	New templates correct, CLI reference thorough, troubleshooting entry solid
Repo Hygiene	OK	CODEOWNERS covers paths, no secrets, no cross-skill deps, scoped changes

Issues for Manual Review

• CLI command accuracy: The init, build, and pack commands are documented with specific output codes (ApiWorkflowInit, ApiWorkflowBuild, ApiWorkflowPack) and flag behavior. The PR author verified these against CLI v1.198.0 — worth confirming these match the shipping CLI surface exactly.
• entry-points.json filePath convention: The skill mandates "content/Workflow.json" (with content/ prefix). Verify this is what init actually writes — the content/ prefix is non-obvious since the file sits at the project root, not in a content/ subdirectory.

Conclusion

Strong, well-motivated fix that corrects a real production defect (runtime success hiding a wrong project shape). The documentation is thorough and internally consistent. Two actionable items before merge:

1. Remove duplicate anti-pattern bullets in SKILL.md:298-300 (lines 299–300 are near-duplicates of 296 and 298). Quick fix.
2. Consider adding an init-focused test task — the whole PR exists because the agent wasn't using init; a test that checks command_executed for uip api-workflow init would close the loop. Can be a follow-up.

Overall: approve with nits — the duplicates in anti-patterns are the only thing worth fixing before merge.

---