Uipath Rpa

UiPath RPA Assistant

Full assistant for creating, editing, managing, and running UiPath automation projects — both coded workflows (C#) and low-code RPA workflows (XAML). One UIA activity set covers every UI target: Windows and macOS, desktop and web, in a single automation — targets configured with strict or fuzzy selectors (reinforced by anchors), Computer Vision, or semantic matching; uia-configure-target picks the route and falls back automatically.

Reading the referenced files is imperative — read each required file in full. This SKILL.md is a router: it tells you which reference to open, not what it says. When a rule, the Task Navigation table, or a section points you to a reference for the task at hand, open it and read the whole file before acting — do not grep it for a keyword, skim the first screen, fall back to --help, or substitute prior knowledge. Exception: files whose rule prescribes a targeted lookup (Grep ^## for the table of contents, flags via <command> --help) — these are catalogs: read the matching sections, never the whole file. Most errors that slip past validate and surface at build or runtime trace back to a reference that was skipped or only partially read.

<!--skill-flavor:host-scope:start-->

<!--skill-flavor:host-scope:end-->

When to Use This Skill

• User wants to create a new UiPath automation project (coded or XAML)
• User wants to add a workflow, test case, or source file to an existing project
• User wants to edit an existing workflow or test case
• User wants to modify project configuration (dependencies, entry points)
• User asks about UiPath activities or how to automate something
• User wants to validate, build, run, or debug a workflow
• User wants to add dependencies or NuGet packages to a project
• User wants to create test cases with assertions
• User wants to call an Integration Service connector (Jira, Salesforce, ServiceNow, Slack, etc.)
• User wants to use UI automation to interact with desktop or web applications

UIA Prerequisites

UiPath.UIAutomation.Activities at or above the skill's minimum version is required for all UIA work — the minimum version, the version check, the discovery/install commands, and the upgrade-consent matrix (NEVER install or upgrade UIA silently) live in uia-starter-guide.md § UIA Prerequisites — the only source of truth; do not hardcode the version from memory.

Precondition: Project Context

<!--skill-flavor:project-context-precondition:start-->

Before doing any work, check .claude/rules/project-context.md in the project directory:

• Exists and fresh → proceed with the skill workflow.
• Missing or stale → run the skip gate, then — only if it does not trip — the discovery flow, both per environment-setup.md § Project Context Discovery: the staleness check (metadata-comment counts vs current counts, 60–70% threshold), the skip gate (greenfield / empty project / untouched scaffold — nothing to discover yet), the discovery-agent spawn options per host, and the handling of the agent's context-files: / SKIP: status lines (the agent writes the context files itself — do NOT re-read or rewrite them). Dispatch discovery AT MOST ONCE per session — if a discovery agent is already running or its context document was already produced, reuse that result; a later step that calls for "project-context discovery" means INTEGRATE the earlier dispatch, never spawn a second.
• Skip gate tripped (greenfield / empty / untouched scaffold) → no discovery agent and no context files now; after the build completes, write both context files yourself per the same section.

<!--skill-flavor:project-context-precondition:end-->

Step 0: Resolve PROJECT_DIR

Before creating or modifying anything, determine which project to work with. See references/environment-setup.md for the full procedure.

Quick check: Find project.json to establish {projectRoot}. That's it — no Studio Desktop check needed for the standard loop. uip rpa auto-launches a headless Studio (UiPath.Studio.Helm NuGet) on first call. Studio Desktop is required only for files diff and focus-activity. Coded UI automation's ObjectRepository.cs (the Descriptors.* class) regenerates on per-file validate once a [Workflow]/[TestCase] .cs is on disk (§ Capture-First Fast Path step 2; coded/operations-guide.md § Configure UI Targets).

Project Type Detection

After establishing PROJECT_DIR, first check project.json for targetFramework:

• targetFramework: "Legacy" (or field absent in an older project) → Legacy mode. Stop here and switch to the Legacy-mode workflow: references/legacy/legacy-mode-guide.md. Legacy projects use the standalone uip rpa-legacy CLI, .NET Framework 4.6.1, classic activities (no "X" suffix), and mscorlib assembly references. The rest of this SKILL.md (modern mode) does NOT apply to Legacy projects.
• targetFramework: "Windows" or "Portable" (Cross-platform) → Modern mode, continue below. Both use the uip rpa CLI — "Windows" here means Modern Windows-only, not Windows-Legacy.

uip rpa-legacy is for targetFramework: "Legacy" ONLY — never as a fallback when uip rpa is unavailable. It packs a Modern (Windows/Portable) project successfully and exits 0, so a passing pack is not evidence you picked the right tool. Fix uip rpa instead.

For modern projects, determine whether this is a coded or XAML project:

1. Coded mode — .cs files with [Workflow] or [TestCase] attributes exist AND no .xaml workflow files (beyond scaffolded Main.xaml)
2. XAML mode — .xaml workflow files exist AND no coded workflow .cs files
3. Hybrid — Both exist → consult coded-vs-xaml-guide.md to pick the right mode for each new file; default to matching the user's current request
4. New project — Neither exists → default to XAML. Switch to coded only when the user explicitly says "coded", ".cs", "C# workflow", "coded test case", or names a coded-specific trigger (custom data models / DTOs, unit-testable business logic). For all other phrasings ("create a workflow", "automate X", "build an automation"), use XAML. See coded-vs-xaml-guide.md for the full decision flowchart.

Routing: Once mode is determined, use the Task Navigation table below to find the right reference files. For guidance on choosing between coded and XAML approaches, see coded-vs-xaml-guide.md. For Legacy projects, follow references/legacy/legacy-mode-guide.md instead.

Authoring Mode Selection

Default to matching the project's existing mode. For new projects or ambiguous cases, default to XAML — it is the more common mode, has the widest activity coverage, and is the unmarked term in user vocabulary ("create a workflow" means XAML; "create a coded workflow" means coded). Switch to coded only on explicit user phrasing or a coded-specific trigger from the table below.

UI Automation Boundaries

For any task whose business behavior is "open an app/browser, click, type, scrape visible UI, submit a form, or verify UI state", the interaction layer MUST be UiPath UI Automation — NApplicationCard plus UIA activities (XAML), or uiAutomation.Open/Attach plus Object Repository descriptors — or, where the package's coded authoring guide § Selector-Only Targets allows it, CLI-captured selectors via TargetAppModel / Target.FromSelector — (coded). Do NOT substitute InvokeCode, PowerShell, Selenium, Playwright, Chrome DevTools Protocol, raw DOM JavaScript, HTTP form posts, or external browser-driver scripts. The coded fallback rows above apply only to non-UI helper logic (data transforms, parsing, DTOs, calculations, API-only integrations).

If target configuration is unavailable, fall back to the documented UIA indication path — never to an external browser automation shortcut.

The full prohibited-tool list, the UIA-only exploration requirement, and the InvokeJS/InjectJsScript exception scope are in the UIA package guide ({PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/ui-automation-guide.md) § Mandatory: Generate Targets Before Writing Any UI Code — read it in full per Rule 7 before any UIA work.

Placeholder-Selector Stub Pattern (when live app access is unavailable)

When generating a UI automation workflow without live app access (target capture cannot be run because the app is not installed, the agent has no UI, or the user explicitly deferred capture to a developer), emit real UIA activities with placeholder selectors and TODO Indicate markers — never Log stubs.

Forbidden: a workflow whose UI-interaction steps are Log("LoginWorkflow: type username") with a // TODO[selectors]: comment. The workflow passes build/validate and runs cleanly, but does nothing. This is the most expensive kind of stub — it looks complete, the validator says it's fine, and the failure mode is silent.

Required: the real UIA activity (NTypeInto, NClick, NGetText, NApplicationCard, etc.) with the target descriptor's selector left as a placeholder string and a TODO Indicate marker embedded in the activity's DisplayName (XAML) or in a // TODO[Indicate] comment immediately adjacent to the coded call. A developer opens Studio, clicks Indicate on each marked activity, and the workflow runs.

This applies to both XAML and coded modes. The full pattern with XAML and coded examples is in uia-starter-guide.md § Placeholder-Selector Stub Pattern — read it before authoring stub-mode workflows. It requires no UIA package or CLI.

Hybrid pattern — XAML orchestration + coded fallback for logic with no matching activity:

Main.xaml                  ← orchestration (XAML)
  └── InvokeWorkflowFile → ProcessData.cs  ← coded logic

For the full decision flowchart, InvokeCode extraction rules, and detailed hybrid patterns, see coded-vs-xaml-guide.md.

Capture-First Fast Path

When the request is "automate this dialog/form" or "build a UI test from these manual steps" — i.e. the bulk of the work is target capture, not coding — defer authoring-phase prerequisites until target capture is complete. The capture surface is interactive, app-state-sensitive, and time-bound; project-context discovery adds nothing during capture and steals time from it.

Fast-path order for capture-first tasks:

1. Read per Rule 7 — uia-starter-guide.md and the UIA package's core guide ({PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/ui-automation-guide.md), both IN FULL, plus the target-capture orchestration reference the core guide mandates.
2. [Coded mode only] Install packages + write the stub, before the first uip rpa command — install every activity package the workflow needs, and add an empty [Workflow] public void Execute() { } class (namespace per Rule 17), before the window baseline or any other uip rpa call. The host generates .local/.codedworkflows/ from the packages and coded files present when it first loads the project; load it stub-less and authoring hits CS0246 'CodedWorkflow' (cleared only by a host restart). Only ObjectRepository.cs refreshes on later validate — CodedWorkflow.cs's service accessors (uiAutomation, …) and the workflows.X cross-call methods are that first-load snapshot, so a later package install or new cross-called workflow needs a regen (coded/operations-guide.md § Configure UI Targets).
3. Pre-flight Window Baseline — list top-level windows once; decide whether to launch the app (package guide § Window Baseline).
4. Inventory targets from manual steps (Test Manager test case, PDD, or written script). Each "Click X" / "Enter Y" / "Select Z" / "Verify W" step maps to one OR element. Group by screen state (package guide § Capturing from Manual Test Steps), and decide every element and screen name now — apply them verbatim during capture.
5. Capture all targets screen by screen via uia-configure-target and screen advancement (package guide § Multi-Step UI Flows). Authoring only at screen boundaries — never between capture calls within a screen.
6. Then enter authoring phase: integrate project-context discovery (already dispatched if the precondition required it — at-most-once, never a second spawn), read your mode's authoring guide (Rule 7), write code, validate. Coded: validate once to regenerate ObjectRepository.cs, read it, and reference every target as Descriptors.<App>.<Screen>.<Element> — member names come from that file, never from the OR names passed at capture. Never author against string target names while the file is missing.

Skip this path when the task has no UI surface (data transforms, IS connector calls, headless file/email automation). Also skip it when the task HAS a UI surface but no live app to capture against (app not installed, no GUI, capture deferred to a developer) — there is nothing to capture, so use the § Placeholder-Selector Stub Pattern above instead. The Window Baseline does not tell you if the app is installed and has a GUI — validate that separately (e.g. look for the executable on disk) or ask the user.

Session Pre-warm

First heavy uip rpa call pays a ~22s Studio host cold-start (shared across validate/build/run/activities get-default-xaml/analyzer-rules list). When more than one is expected this session, background a cheap warm-up at session start so the tax hides behind planning:

uip rpa activities find --query log --output json > /dev/null 2>&1 &

On Windows PowerShell, & doesn't background — use Start-Process powershell.exe -ArgumentList ... (not pwsh). Never Start-Process -FilePath "uip" (or any .ps1): Windows opens it in Notepad, not PowerShell.

Skip when 0 or 1 heavy uip rpa calls are expected (read-only Q&A, single-file inspection) — the warm-up doesn't reclaim its cost.

Critical Rules

Rule numbering. Common Rules use 1–12 (below). Coded-specific rules 13–19 live in coded/codedworkflow-reference.md § Critical Rules — Coded; XAML-specific rules are an independent 16–24 sequence — 16–21a and 24 live in xaml/xaml-basics-and-rules.md § Critical Rules — XAML, 22 and 23 below. Numbers 16/17/18/19 appear in both mode sequences — the [Coded] / [XAML] prefix disambiguates. Cross-references ("Common Rule 10", "Rule 21", "Rule 24") always point to a uniquely-numbered rule.

Common Rules (Both Modes)

1. NEVER create a project without confirming none exists. Follow Step 0 resolution: check explicit path, project name, then CWD for project.json. Only create when confirmed no project matches AND user explicitly requests creation.

<!--skill-flavor:rules-project-creation:start-->

2. ALWAYS use uip rpa init to create new projects — never write project.json or scaffolding manually.
   • Before creating, decide if a template is needed. If the user names a template ("REFramework", "based on the X template") or an industry/domain pattern (SAP, ERP, banking, mainframe), run uip rpa templates search --query "<term>" --output json first and select per the decision flow in environment-setup.md § Template selection — its two hard constraints: NEVER silently pick a Marketplace template (present candidates and ask), and when the user's named template matches both an Official and a Marketplace item, ask — do NOT auto-pick. 2a. Pass --target-framework AND --expression-language explicitly on every uip rpa init — never omit them. Both are immutable after creation (Rule 23); omitting --target-framework silently yields a Windows project. Choose framework by where the automation runs: cross-platform / non-Windows runtime (Linux, container, serverless) or Studio Web editing → Portable (Cross-platform); Windows runtime using Windows-only capabilities (Excel COM, classic Office, WPF / PresentationFramework, Windows-only UIA) or Studio Desktop as the edit surface → Windows (not editable in Studio Web). A request needing both a cross-platform runtime and a Windows-only capability is contradictory — surface it, don't silently pick. Windows - Legacy is a last resort (explicit ask or hard .NET 4.6.1 need; never inferred from VB.NET or non-"X" classic activities) — create it in Legacy mode, not modern init. No signal → AskUserQuestion (Windows vs Cross-platform), framed around the runtime host. --expression-language: default VisualBasic, CSharp only on explicit request.

<!--skill-flavor:rules-project-creation:end-->

<!--skill-flavor:rules-validation-gate:start-->

3. Phase-gated validation. Two-phase validation:

   • Per-file (after every create or edit): uip rpa validate --file-path "<FILE>" --project-dir "<PROJECT_DIR>" --output json until 0 errors. Catches structural XAML, missing references, analyzer-rule violations, schema violations. Fix one thing per iteration.

   • Project-level build (after per-file validate is clean across all files in the edit session, and before declaring done): uip rpa build "<PROJECT_DIR>" --output json until clean. Covers the whole project — every workflow including ones you never edited or validated, plus project-scope analyzer rules and packaging — so per-file validate passing on each edited file does NOT establish that the project compiles. Coverage split: cli-reference.md § What each phase covers. If build errors, identify the offending file from the output and re-run validate --file-path on it.

   • 5-attempt cap per loop — 5 attempts for each file's per-file validate loop; a separate 5 attempts for the project-level build loop. Fix one root cause per iteration.

   • Smoke-test shortcut: A successful uip rpa run substitutes for the standalone end-of-session build — run compiles internally. Prefer run --skip-build when build has just passed; see cli-reference.md § Smoke Test.

   • Do NOT run uip rpa analyzer-rules list as an authoring prerequisite. validate and build already enforce the enabled analyzer rules and report violations with rule IDs and recommendations — pre-fetching the rule list is speculative cost (the unscoped call can take a minute or more). It is an on-demand command: run it when the user asks about the project's best-practice/analyzer rules, or when repeated violations of the same rule family suggest authoring against the full rule set. See cli-reference.md § analyzer-rules list.

   • Warnings do not gate delivery. Once validate and build report 0 errors, the gate is satisfied — deliver. Do NOT investigate or fix a warning unless the user asked about it or it blocks a stated acceptance criterion. Several warnings are correct-by-design on UIA projects and fire on every build (verification-feature, Automation Hub URL, duplicate display name): cli-reference.md § Expected non-defect warnings. Report warnings in the completion output; do not spend gate attempts on them.

   See cli-reference.md § Validation Iteration Loop.

4. ALWAYS bring every touched file to per-file validate clean AND verify the project builds before declaring done. The full cadence, caps, and what each phase catches: Rule 3. validate clean alone is not "validated" — the project-level build is mandatory before declaring done, and a clean gate is not runtime proof: for observable-output workflows, end the gate with one run and check outputs (execution-maps-guide.md § Gate ≠ runtime proof).

<!--skill-flavor:rules-validation-gate:end-->

5. Prefer UiPath built-in activities for Orchestrator integration, UI automation, and document handling. Prefer plain .NET / third-party packages for pure data transforms, HTTP calls, parsing.

6. ALWAYS ensure required package dependencies are in project.json before using their activities or services. 6a. Pre-edit verification gate. Two authoring actions are hard to roll back once build fails — verify before serialization, not after.

   • Removing a dependency — grep the project for usages before deleting an entry. A package may be the sole supplier of an activity used elsewhere (MergePDFs lives in the IntelligentOCR.StudioWeb family).
   • Writing a new activity tag — confirm via uip rpa activities find --query "<verb>" --output json and use the returned ClassName. Do not derive tag names from Studio display names. See common-pitfalls.md § Common Activity Name Confusions.

7. [UIA] Before writing ANY UIA activity (XAML <uix:N*> or coded uiAutomation.* / Descriptors.*), MUST read references/uia-starter-guide.md — via a two-step read, never a plain full Read: (1) Grep ^## Conditional Policies on it, (2) Read with limit set to that line; the two policy sections below the marker load only when their stated condition applies. Then the UIA package's core guide it mandates ({PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/ui-automation-guide.md) IN FULL, and — before authoring — your mode's authoring guide IN FULL (routed from the core guide's § Documentation). No exceptions for "simple" UIs. Skipping this rule is the most common cause of hallucinated selectors, wrong target XML, and missing OR descriptors. NEVER hand-write selectors — use uia-configure-target exclusively (the package guide explains how); the coded selector-only path skips only the Object Repository registration, not the capture. The package guide exists only after the package is installed — verify uia-starter-guide.md § UIA Prerequisites first (Rule 7a); if the package is installed but the guide file is absent, the installed version predates it — treat as below the minimum version. The starter guide owns the skill-side UIA policies: run/debug procedure + runtime selector recovery, the stub-mode deliverable pattern, and UI Library publishing. 7a. [UIA] Verify UIA prerequisites before invoking uia-configure-target. The minimum version and the prerequisite check live in uia-starter-guide.md § UIA Prerequisites — run that check first (do not hardcode the version from memory; that section is the only source of truth). If UiPath.UIAutomation.Activities is below the minimum or {PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/ui-automation-guide.md is absent (Rule 7 treats a missing guide as below-minimum), the uip rpa uia CLI is unavailable — and both target capture and indication depend on it, so indication is not a fallback when the package itself is missing. Ask the user to install/upgrade per that section. If they decline or the package cannot be installed, fall back to the Placeholder-Selector Stub Pattern (§ above) — real activities with TODO Indicate markers need no CLI. Never silently route to a non-existent skill path. Use indication capture only when a compatible UIA package is installed but uia-configure-target cannot see the element; record UI capture: indication-only in the plan header to skip uia-configure-target in that case. Runtime failure counts too: when the package is present but the UIA snapshot CLI's live scans fail persistently (driver/COM errors on every scan), first rule out a locked or non-interactive Windows session (LogonUI running = lock screen) — that needs an unlock, not a fallback. Only if scans still fail on an unlocked interactive session, treat capture as unavailable and use the Placeholder-Selector Stub Pattern.

8. Use --output json on all CLI commands whose output is parsed programmatically. 8a. A run / debug start verdict comes from Data — NEVER from the outer Result alone, and NEVER from a log line's level — and Data's shape depends on the backend that ran the workflow; identify it by its keys. Headless Studio (Helm — no Studio Desktop instance has the project open): Data is {output, hasErrors, errorMessage, profiling, debugState, debugDetails}; passed only when hasErrors is false, errorMessage is null, and debugState is null or "Completed"; a faulted run returns outer Result: "Failure" with those fields JSON-encoded in Message; a faulted debug start returns Result: "Success" with debugState: "Suspended" and the exception in debugDetails — the session is still alive and must be cancelled or continued. Studio Desktop (the project is open in a running Studio): Data is {output, errors, logEntries, debugState}; passed only when errors is empty AND output is "Session ended" — a missing entry point returns Result: "Success" with errors: [] and output: "Failed to open the file <path>", so both conditions are needed. Reading Result: "Success" as a verdict reports broken workflows as green on both backends. A successful workflow may emit Log Message activities at Error or Warning level as observability — on Helm they stream as [Level] lines above the envelope, on Desktop they are logEntries entries — and they are workflow-emitted data, not failures; treating them as a failure signal flips green runs to "failed" and burns retries on healthy workflows. Read the verdict from the envelope as printed: no --output-filter on run / debug start (the two backends have different keys, and a filter naming a key the current backend lacks fails the call after the workflow has already run), and never | tail / | head the payload — on Helm the log lines precede the envelope, on Desktop the verdict fields precede a long logEntries, so either cut drops something this rule needs (cli-reference.md § Capturing the verdict). Field meanings: cli-reference.md § Reading run / debug results and debugging.md § Output Format.

9. For "leverage / reuse / find shared libraries" requests, search the tenant feed — not the local filesystem, NuGet.org, or keyword-permutation loops. Run uip or libraries list --limit 500 --output-filter "<JMESPath>" --output json. On zero results from the filtered call, take the fallback branch — do not re-keyword. Skip when an SDD already records §16 "Shared libraries referenced" or the user has said "no shared libraries" earlier in the session. See tenant-library-search-guide.md for the full procedure.

10. Register every test case file in project.json → designOptions.fileInfoCollection. Applies to both XAML and coded test cases. Required keys, GUID format, JSON snippet, and full schema (including dataVariationFilePath for data-driven and publishAsTestCase for coded): references/testing-guide.md § project.json Registration and assets/json-template.md.

11. Test case structure: Given-When-Then. Applies to both XAML and coded test cases. See references/testing-guide.md § XAML Test Case Structure for the canonical patterns (the section's lead also points to the coded variant in coded/operations-guide.md).

12. Trigger activity placement. Two trigger types — identify from uip rpa activities find --query "<event>" --output json by reading isTrigger and triggerType. Placement rules differ.

    Integration triggers (isTrigger: true, triggerType: "integration") — strict placement. MUST be the first activity of Main.xaml's root Sequence; CANNOT be placed inside ui:TriggerScope. Bind Result to a workflow-scope variable; the rest of the Sequence is the handler. Connection asset (ConnectionId) required for IS-based triggers (Mail / GSuite / O365 / Salesforce / Jira / Slack / ServiceNow / any *.IntegrationService.Activities package); not required for Orchestrator-native triggers (TimeTrigger, QueueTrigger, ManualTrigger).

    Local triggers (isTrigger: true, triggerType: "local") — flexible placement. Place EITHER as the first activity of Main.xaml's root Sequence (Orchestrator dispatches a fresh job per event) OR inside <ui:TriggerScope.Triggers> with handler in <ui:TriggerScope.Action> (robot stays alive while the scope is active; trigger fires in-process). Both placements are valid — choose by runtime model. No connection asset required.

    Unknown triggerType (forward-compat — e.g. a future "scheduled") → read the bundled doc and ask the user. Do not assume placement.

    Reading existing XAML: activity inside <ui:TriggerScope.Triggers> must be a local trigger; an integration trigger there is broken — flag to the user. Activity at workflow root can be either type — check triggerType to disambiguate.

    See trigger-pattern-guide.md for worked examples, the SchedulingMode reference, the catalog of trigger activities, and the procedure for editing existing ui:TriggerScope workflows.