feat(uipath-agents): document file support for low-code agents

[andreibalas-uipath]

Summary

• Adds the file-as-input pattern (job-attachment $ref schema) to agent-definition.md so agents can declare file inputs/outputs with the canonical schema.
• Adds a new built-in tools capability folder (capabilities/built-in-tools/) with an overview and the first walkthrough (analyze-attachments). Built-in tools use $resourceType: "tool", type: "internal" and need no solution-level files or uip solution resource refresh.
• Reinforces the metadata-only semantics of {{input.<file-field>}} via four new Critical Rules (18–21) and two new Anti-patterns (21–22) — the agent must call a file-handling built-in tool to read contents.
• Wires navigation: Capability Registry row, SKILL.md task table row, and disambiguation pointers between the context-resource attachment form and the file-as-input form.

Test plan

• All relative links in new and edited files resolve (custom check, 0 broken).
• hooks/validate-skill-descriptions.sh exits 0; SKILL.md description still 217 chars (well under 1024).
• Validated end-to-end against a real low-code agent built using the updated skill (SupportTriageSolution/FileSummarizer): correct job-attachment schema, separate UUIDs, schema sync between agent.json and entry-points.json, and a directive system prompt that prevents the metadata-hallucination failure mode the new Critical Rule 18 warns about.
• Skill activates correctly when an author asks "accept a file as input" or "summarize a PDF".

🤖 Generated with Claude Code

[github-actions]

Claude finished @andreibalas-uipath's task in 3m 41s —— View job

---

PR Review: feat(uipath-agents): document file support for low-code agents

• Read review criteria and project conventions
• Read full PR diff
• Read existing PR conversation
• Read all changed files in full
• Verify relative links resolve
• Check for cross-skill references, secrets, and structural issues
• Post review

---

Summary

Adds the job-attachment file-as-input pattern and a new built-in-tools capability folder to uipath-agents, with four new Critical Rules (18–21), two new Anti-patterns (21–22), and disambiguation callouts across context/process docs. Also bundles unrelated fixes to uipath-maestro-flow (removed connector anti-pattern, connectionFolderKey → folderKey rename, test refactor).

Change-by-Change Review

1. skills/uipath-agents/SKILL.md (+1 row)

Severity: OK

New task table row routes "Accept files as agent input / call the Analyze Files built-in tool" to built-in-tools.md. Link verified; consistent with existing table format.

2. skills/uipath-agents/references/lowcode/agent-definition.md (+63/−1)

Severity: OK

New § File Attachments section with canonical job-attachment schema, field table, metadata-only semantics callout, and two new Common Edits (Add a File Input Field, Add a File Output Field). The $ref row added to the Schema Types table is clean. User Message section updated with metadata-only note. All links resolve. Steps are properly ordered and reference entry-points.json mirroring.

3. skills/uipath-agents/references/lowcode/capabilities/built-in-tools/built-in-tools.md (new, 74 lines)

Severity: OK

Clean capability overview. Follows the established pattern from process.md and context.md. Four local Critical Rules, resource shape template, lifecycle steps, tool registry table. Cross-references to critical-rules.md, agent-definition.md, and sibling walkthroughs all resolve. The > Other built-in tools exist... callout is a good forward-looking hook.

4. skills/uipath-agents/references/lowcode/capabilities/built-in-tools/analyze-attachments.md (new, 114 lines)

Severity: Low

Thorough walkthrough with Pairing Pattern, full canonical resource.json, step-by-step walkthrough, and Gotchas. All links resolve.

One observation: the full job-attachment definition block appears both here (inside the tool's inputSchema, lines 43–58) and in agent-definition.md (lines 118–133). This is defensible — each JSON context (agent input, tool input) carries its own copy, and the Gotchas section (line 106) explicitly documents this: "Each schema (agent input, agent output, tool input) carries its own copy." However, if either schema ever changes, both files need updating. Consider adding a single-line note in one location pointing to the other as the second copy, to aid future editors. Not blocking.

5. skills/uipath-agents/references/lowcode/critical-rules.md (+12/−2)

Severity: OK

Rules 18–21 are well-scoped: metadata-only semantics (18), canonical schema (19), explicit configuration (20), no solution-level files (21). Anti-patterns 21–22 are proper inversions of rules 18/20. Header counts updated correctly (17→21, 20→22).

6. skills/uipath-agents/references/lowcode/lowcode.md (+2 rows)

Severity: OK

Two new Capability Registry rows — "Add a built-in tool" and "Accept a file as agent input or return a file as output". Consistent format. Links verified.

7. skills/uipath-agents/references/lowcode/capabilities/context/attachments.md (+3/−1)

Severity: OK

Added $resourceType/contextType annotation to the intro and a disambiguation callout directing users to built-in-tools for the file-as-input pattern. Helpful — this prevents the common confusion between "attachments context" and "file input field".

8. skills/uipath-agents/references/lowcode/capabilities/context/context.md (+2)

Severity: OK

Matching disambiguation callout at the Decision section level. Good placement.

9. skills/uipath-agents/references/lowcode/capabilities/process/process.md (+1/−1)

Severity: OK

Added cross-reference to built-in-tools.md with type: "internal" discriminator note. Clean one-line addition.

10. skills/uipath-maestro-flow/references/author/CAPABILITY.md (−1 anti-pattern)

Severity: Medium — scoping / justification

Removed the anti-pattern: "Never replace a registered connector operation with core.logic.mock because configuration cannot run." The remaining core.logic.mock anti-pattern (line 78) only covers the "same solution" case. The removed rule covered a different scenario — when node configure can't run (no live tenant, sandbox restrictions). The PR description doesn't explain why this was removed. If the guidance is now wrong due to a CLI change, that's fine, but it should be noted. If it was removed as cleanup, the scenario it protected against (downgrading connectors to mock when config can't run) is still a real failure mode.

Fix this →

11. skills/uipath-maestro-flow/references/author/references/plugins/connector/impl.md (−15 lines)

Severity: Medium — inconsistency

Changed connectionFolderKey to folderKey in the inputs.detail field list (line 14) and removed the "No-Live-Tenant / Planned Configuration Mode" section and the connectionFolderKey mapping note. However, data-fabric/impl.md still references connectionFolderKey in 5 places (lines 82, 509, 546, 582, 616, 649). If the CLI now consistently uses folderKey, the data-fabric file should be updated too. If connectionFolderKey is still the correct field name in data-fabric context, the rename in impl.md may be wrong.

Fix this →

12. tests/tasks/uipath-maestro-flow/e2e/devcon_expense_approval.yaml (refactored) + deleted check_devcon_expense_approval.py

Severity: Low

Replaced a 123-line Python validator with multiple file_contains + command_executed checks. Added a hitl add command check (good — validates the agent used the CLI). The file_contains checks are individually weaker than the Python script's semantic validation (e.g., '"number"' anywhere in the flow ≠ "the amount field specifically is type number"), but collectively they cover the key signals. The total weight rebalancing (Python script was 16.5, replaced checks sum to ~15) is reasonable. The command_executed for hitl add at weight 2.0 closes the gap.

13. tests/tasks/uipath-maestro-flow/smoke/registry_discovery.yaml (−1 line)

Severity: OK

Removed Start by refreshing the registry cache with... from initial_prompt while the success criteria still requires registry pull. Good change — the test should verify the skill teaches the agent to pull, not hand-hold via the prompt.

What's Missing

• PR scoping: The uipath-maestro-flow changes (CAPABILITY.md anti-pattern removal, connector folderKey rename, test refactor) are functionally independent from the uipath-agents file support work. Per repo convention ("one logical change per PR"), these would be cleaner as a separate PR. Not blocking, but worth noting for future PRs.
• System prompt guidance for analyze-attachments: The walkthrough shows the user message template but not a system prompt example. Critical Rule 18 says "instruct the agent to call it" and the PR description mentions a "directive system prompt that prevents the metadata-hallucination failure mode." A one-line system prompt example (e.g., "When you receive a file attachment, call the Analyze Files tool to read its contents — do not attempt to infer contents from metadata.") would strengthen the walkthrough. Not blocking.

Area Ratings

Area	Status	Notes
Frontmatter	OK	No frontmatter changes; existing description still 217 chars
E2E Tests	OK	Existing builtin_tool test covers this capability area; maestro-flow test refactored cleanly
Skill Body	OK	New SKILL.md row routes correctly
References & Assets	OK	2 new files + 5 updated files; all links verified; no orphans
Repo Hygiene	OK	CODEOWNERS covers uipath-agents; no secrets; no binaries

Issues for Manual Review

• Domain accuracy of connectionFolderKey → folderKey rename: Verify whether the uip maestro flow node configure --detail CLI now uses folderKey end-to-end, and whether data-fabric/impl.md should be updated to match.
• Removed "No-Live-Tenant" section in connector/impl.md: Confirm this scenario (sandbox without live tenant, can't run node configure) is no longer relevant or is covered elsewhere.
• analyze-attachments runtime behavior: The canonical resource.json schema cannot be verified by automated review — confirm toolType: "analyze-attachments" and the input/output schema match the actual platform implementation.

Conclusion

The uipath-agents file-support additions are well-structured, thorough, and follow repo conventions cleanly. Critical Rules 18–21 and the disambiguation callouts effectively prevent the metadata-hallucination failure mode. The two Medium items are both in the bundled uipath-maestro-flow changes: (1) the removed connector anti-pattern should be justified or restored, and (2) the connectionFolderKey → folderKey rename should be applied consistently to data-fabric/impl.md if it's a real CLI change.

---