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.

• 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

• Multi-platform — Windows and macOS.
• Desktop and web — native desktop applications and browsers, driven through the same activities.
• Resilient targeting — targets are configured with strict or fuzzy selectors (reinforced by anchors), Computer Vision, or semantic matching;

  uia-configure-target

  picks the route and falls back between them automatically.
• Combined in a single automation — desktop and browser apps interoperate in one workflow with no bridge or handoff. Multi-screen, multi-application flows (read from a desktop app, act in a browser, verify across both) are first-class.

UiPath.UIAutomation.Activities

<MIN_VERSION>

26.10.2

uip rpa uia

<MIN_VERSION>

project.json

dependencies

• Plan-mode: approval of a plan whose Task 0 names the upgrade explicitly — both package ID and version. Plan approval IS the consent — do NOT re-ask at execution time.
• Interactive mode (no plan): a direct prompt before

  packages install

  runs.

<MIN_VERSION>

25.x

26.x

<MIN_VERSION>

uip rpa packages versions --package-id UiPath.UIAutomation.Activities --include-prerelease --project-dir "$PROJECT_DIR" --output json

uip rpa packages install --packages 'id=UiPath.UIAutomation.Activities,version=<MIN_VERSION>' --project-dir "$PROJECT_DIR" --output json

,version=<MIN_VERSION>

<MIN_VERSION>

.claude/rules/project-context.md

1. Read the first line of

   .claude/rules/project-context.md

   to extract the metadata comment:

   <!-- discovery-metadata: cs=N xaml=N deps=N -->

2. Count current files: Glob

   **/*.cs

   (excluding

   .local/

   and

   .codedworkflows/

   ) and

   **/*.xaml

   in the project directory
3. Count current dependencies: read

   project.json

   and count keys in the

   .dependencies

   object
4. Compare the current counts against the stored metadata values
5. For each count (cs, xaml, deps), compute the percentage difference:

   abs(current - stored) / max(stored, 1) * 100

6. If any individual count differs by 60–70% or more → run the discovery flow below
7. If all counts are within the threshold → context is fresh, proceed with the skill workflow

project.json

project.json

**/*.xaml

**/*.cs

obj/

bin/

Main.xaml

NewActivity*.xaml

TestCase.xaml

Main.cs

Sequence

Comment

Execute

AGENTS.md

1. Spawn the project discovery agent and wait for it to complete. Its definition lives inside this skill at

   agents/uipath-project-discovery-agent.md

   . Use whichever spawn mechanism your host supports:
   • Host registers plugin agents by name (e.g., Claude Code) → trigger the registered

     uipath-project-discovery-agent

     agent.
   • Host only spawns its own predefined subagents (e.g., UiPath Autopilot) → spawn a subagent and pass it that file (relative to this skill) as its instructions / custom skill. Grant it write access so it can produce the context files itself; a read-only subagent still works via step 3.
2. The agent writes the context files itself and returns a

   context-files:

   status line followed by the context document. Use the returned document as this session's project context — do NOT re-read the files it just wrote, and do NOT rewrite them.
3. Only when the agent reports

   context-files: not-written

   (read-only subagent host, or a write error) → write the returned content to both:

   • .claude/rules/project-context.md

     (create

     .claude/rules/

     directory if needed) — auto-loaded by Claude Code in future sessions

   • AGENTS.md

     at project root — the shared cross-agent context convention (read by UiPath Autopilot in Studio Desktop and other AGENTS.md-aware hosts). If

     AGENTS.md

     already exists, look for

     <!-- PROJECT-CONTEXT:START -->

     /

     <!-- PROJECT-CONTEXT:END -->

     markers and replace only between them; if no markers exist, append the fenced block at the end
4. If the agent returns

   SKIP: <reason>

   instead of a document, treat it as a gate trip: no context files now, write them yourself after the build.
5. Then proceed with the skill workflow

PROJECT_DIR

project.json

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.

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.

{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/ui-automation-guide.md

1. Pre-flight Window Baseline — list top-level windows once; decide whether to launch the app (package guide § Window Baseline).
2. 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).
3. Capture all targets screen by screen via

   uia-configure-target

   and screen advancement (package guide § Multi-Step UI Flows).
4. Then enter authoring phase: project-context discovery (the precondition above), write code, validate.

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.
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", "Robotic Enterprise Framework", "based on the X template"), an industry/domain pattern (SAP, ERP, banking, mainframe), or otherwise hints at a non-blank starter, run

     uip rpa templates search --query "<term>" --output json

     first. Selection rule against

     Data[*]

     :
     • User named a specific non-Official template (e.g. "Enhanced REFramework", "Lite ReFrameWork") AND a

       Marketplace

       item's

       title

       or

       packageId

       substring-matches the user's specific qualifier → ask the user (Official + that Marketplace item are both candidates). Do NOT auto-pick.
     • Exactly one

       source == "Official"

       match AND user did not name a non-Official template → use it; pass

       --template-package-id <packageId> --template-package-version <version>

       to

       init

       . Proceed without asking.
     • Multiple

       Official

       matches OR only

       Marketplace

       matches → present candidates (

       packageId

       ,

       version

       ,

       source

       ,

       title

       ) to the user and ask which to use. Never silently pick a Marketplace template.
     • No matches → fall back to a built-in

       --template-id

       and tell the user nothing was found.
   • Built-in

     --template-id

     keywords map without a search:

     library

     →

     LibraryProcessTemplate

     ,

     test automation

     /

     test project

     →

     TestAutomationProjectTemplate

     , otherwise

     BlankTemplate

     . When

     --template-package-id

     is set,

     --template-id

     is ignored. Full decision flow: environment-setup.md § Template selection. 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.
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. Catches what

     validate

     misses (unknown members, invalid enums, CacheMetadata / member resolution, attribute-form C# JIT) — full list at cli-reference.md § Errors

     build

     catches that

     validate

     misses. 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.
   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. Cadence per Rule 18: batch-author, then validate. Project-level

   build

   runs once at the end of the edit session (or at any compile-verification gate) — not after every Edit, because

   build

   is project-scoped and rebuilds the entire project regardless of which file changed.

   validate

   clean alone is not "validated"; it cannot see member or enum errors — 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). See cli-reference.md § Validation Iteration Loop.
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 IN FULL, and the UIA package's authoring guide it mandates (

   {PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/ui-automation-guide.md

   ) IN FULL — including the mode-specific section (For Coded Workflows or For XAML Workflows). 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 package guide exists only after the package is installed — verify § 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 Prerequisites (top of this file) — 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 § UIA Prerequisites. 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.

   run

   /

   debug start

   success/failure verdict comes from the outer

   Result

   (and equivalently the inner

   HasErrors

   ), NEVER from any log entry's

   Level

   . A successful workflow may emit

   Log Message

   activities at

   Error

   or

   Warning

   level as observability — those are workflow-emitted data, not CLI failures. Compile failures, validation failures, and unhandled runtime exceptions all flip

   HasErrors

   and propagate to the outer

   Result

   . Treating log-entry levels as a failure signal flips green runs to "failed" and burns retries on healthy workflows. In a debug session, check

   DebugState

   first — a

   Suspended

   response means an exception awaits your decision (continue / retry / ignore / cancel) while

   HasErrors

   is still

   false

   . See cli-reference.md § run and debugging.md § Reading Debug Output Effectively.
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.

docs/plans/*.md

• If the header has

  Execution autonomy: autonomous

  : continue until ALL plan task checkboxes are

  [x]

  OR a concrete item from the plan's

  Stop conditions

  section is hit.
• If the header has

  Execution autonomy: interactive

  , or no plan file exists: use judgment and confirm with the user on material decisions.
• Before declaring the task done, re-read the plan and enumerate any unchecked boxes. If unchecked tasks remain and no Stop condition was hit, keep going — do not summarize partial work as "Done".
• "Feels expensive", "many tool calls used", "natural pause point", "partial result looks usable", and "too complex to continue in one session" are NOT Stop conditions. Only the concrete hard blockers in the plan's

  Stop conditions

  section count.
• Plan decisions already made are authoritative. Do not

  AskUserQuestion

  about structure, file count, selector strategy, or capture approach when the plan specifies them — those questions belonged to the planner.

1. [Coded] ALWAYS inherit from

   CodedWorkflow

   base class for workflow and test case classes (NOT for Coded Source Files).
2. [Coded] ALWAYS use

   [Workflow]

   or

   [TestCase]

   attribute on the

   Execute

   method.
3. [Coded] Update

   project.json

   →

   entryPoints

   when adding/removing workflow files in Process projects. Tests and Library projects do NOT use

   entryPoints

   — skip this step for those project types. For

   fileInfoCollection

   (required for every test case in every project type — XAML and coded alike), see Common Rule 10.
4. [Coded] One workflow/test case class per file, class name must match file name.
5. [Coded] Namespace = sanitized project name from

   project.json

   . Sanitize: remove spaces, replace hyphens with

   _

   , ensure valid C# identifier.
6. [Coded] Entry method is always named

   Execute

   .
7. [Coded] Use Coded Source Files for reusable code — plain

   .cs

   files without

   CodedWorkflow

   inheritance, no entry point.

1. [XAML] Activity docs are the source of truth — check

   {projectRoot}/.local/docs/packages/{PackageId}/

   first. Always.
2. [XAML] MUST understand project structure — read

   project.json

   , check expression language, scan existing patterns. NEVER generate XAML blind.
3. [XAML] Batch-author, single gate — author the complete workflow in one pass, sourcing each activity card → memory → Rule 21 triple (precedence in execution-maps-guide.md). Then per-file

   validate

   to clean, then one project

   build

   (Rule 3 cadence, 5-attempt caps unchanged); for observable-output workflows the gate ends with one

   run

   + output check (execution-maps-guide.md § Gate ≠ runtime proof). On failure: fix by error category (Rule 19); card-covered activities stay card-sourced — a gate failure does NOT reopen

   activities find

   /

   get-default-xaml

   ; >2 errors with ambiguous origin → bisect (stub out half the new activities, re-validate).
4. [XAML] Fix errors by category — Package → Structure → Type → Activity Properties → Logic.
5. [XAML] Flowchart node structure + ViewState both decide whether a Flowchart renders. Structure first: every

   FlowStep

   /

   FlowDecision

   /

   FlowSwitch

   MUST be a direct child of

   <Flowchart>

   (only direct children are added to the

   Flowchart.Nodes

   collection), wired through

   Flowchart.StartNode

   /

   FlowStep.Next

   /branches with

   <x:Reference>

   +

   x:Name

   . NEVER build the flow as a nested chain — one

   FlowStep

   physically nested inside the previous one's

   <FlowStep.Next>

   — because nested-only steps are absent from

   Flowchart.Nodes

   and the designer renders almost nothing, regardless of ViewState. Then ViewState: when generating new Flowchart/StateMachine/ProcessDiagram workflows, per-node ViewState is MANDATORY —

   ShapeLocation

   +

   ShapeSize

   on every node (

   ConnectorLocation

   optional, Studio auto-routes). Without it Studio stacks every node at (0,0) so they overlap into what looks like a single node, and Studio does NOT auto-arrange on open (see canvas-layout-guide.md). When editing existing files, do NOT modify ViewState on nodes you are not changing. For Sequences, ViewState is optional.
6. [XAML] Reading

   <Activity>.md

   from

   {PROJECT_DIR}/.local/docs/packages/...

   is a precondition for

   activities get-default-xaml

   — for every activity not on the common-activity card.
   • Card-listed activities and patterns: check references/common-activity-card.md and references/common-pattern-card.md first; on a card hit, author from the card entry alone — skip

     activities find

     , skip

     activities get-default-xaml

     , skip the per-activity MD read. Precedence: card → agent memory (execution-maps-guide.md § Cross-session memory) → full triple. A memory hit substitutes for the triple only;

     validate

     /

     build

     still gate.
   • All other activities: (1)

     activities find

     → class name, (2) read

     <Activity>.md

     first and extract a property checklist (required + use-case-relevant), (3)

     activities get-default-xaml

     → starter element, (4) diff your checklist against the starter and add what's missing — an empty checklist means you skipped step 2, go back.
   • Doc lookup order: primary

     {PROJECT_DIR}/.local/docs/packages/<PackageId>/activities/<Activity>.md

     ; fallback

     references/activity-docs/<PackageId>/<closest-version>/<Activity>.md

     for older package versions where

     .local/docs

     is empty. Exception —

     UiPath.UIAutomation.Activities

     has no bundled fallback:

     .local/docs

     (present only after the package is installed) is its sole activity-doc source. If it is absent, do not hunt for a bundled copy — follow Rule 7a (install with consent per § UIA Prerequisites, or use the Placeholder-Selector Stub Pattern — uia-starter-guide.md).
   • Trigger activities are special — read BOTH docs. When the class name ends in

     Trigger

     , the namespace contains

     .Triggers

     , or the description mentions "starts a job" / "Monitor Events" / "Trigger Scope", also read the bundled

     references/activity-docs/<PackageId>/<closest-version>/activities/<Activity>.md

     and the package's bundled

     overview.md

     . The auto-generated

     .local/docs

     version is sparse for triggers; the bundled hand-written docs carry placement guidance (entry-point vs.

     ui:TriggerScope

     ), deployment context, and cross-cutting namespace/assembly gotchas that the extractor does not capture. See Common Rule 12 and trigger-pattern-guide.md.
   • Skip-tax — concrete:

     activities get-default-xaml

     omits any property whose value equals the type default. For

     NGetText

     the starter is literally

     <uix:NGetText HealingAgentBehavior="SameAsCard" />

     with zero output properties — authoring from this alone produces

     NGetText.Value="..."

     (does not exist; the output member is

     TextString

     ), which

     validate

     accepts and

     build

     rejects. For

     NTypeInto

     that's 2 of 20 properties hidden.
   • Self-extending the card — "this activity feels simple, I'll add it to the card mentally" — is the failure mode. The card is the only allowlist; for non-card activities the MD read is the only check.
   • Full procedure: xaml/xaml-basics-and-rules.md § Activity Property Surface. 21a. [XAML] Built-in workflow activities: use the card only for this allowlist. Fast-path card activities are:

     Sequence

     ,

     If

     ,

     Switch<T>

     ,

     TryCatch

     ,

     While

     ,

     DoWhile

     ,

     ForEach<T>

     ,

     Assign

     ,

     LogMessage

     ,

     WriteLine

     ,

     Delay

     ,

     Throw

     ,

     Rethrow

     . If the activity is on this list, open references/common-activity-card.md and author from the card. If it is not on this list, check references/common-pattern-card.md next — its patterns cover e.g. text-file read/append/write, file copy, CSV, DataTable→CSV, queue publish, retry wrap,

     InvokeWorkflowFile

     , InvokeCode rows, HTTP→JSON — and follow full Rule 21 only when BOTH cards miss.

     Pick

     ,

     Parallel

     , and

     ParallelForEach<T>

     are intentionally on neither card; use full Rule 21. Studio's "While" / "Do While" / "For Each" toolbox items emit UiPath wraps (

     UiPath.Core.Activities.InterruptibleWhile

     /

     InterruptibleDoWhile

     /

     UiPath.Core.Activities.ForEach<T>

     ), not the framework

     System.Activities.Statements.While

     /

     DoWhile

     /

     ForEach<T>

     .
7. [XAML] MUST read references/xaml/xaml-basics-and-rules.md before generating or editing any XAML — then vet the plan against references/xaml/common-pitfalls.md. common-pitfalls.md is a catalog of independent gotcha sections — do NOT read it end-to-end: list its headings (Grep

   ^##

   on the file), then Read every section whose heading matches an activity, property, or feature in the workflow you are about to author. Unsure whether a section applies → read it. This is an authoring-time gate, not only a troubleshooting resource — consulting it first is cheaper than debugging a gotcha

   validate

   cannot see.
8. [XAML] NEVER change

   expressionLanguage

   or

   targetFramework

   on an existing project. Decide both proactively at init time (Common Rule 2a); this rule covers the immutability afterward. Both fields in

   project.json

   are fixed at creation time and apply to every XAML file in the project — flipping

   expressionLanguage

   (VisualBasic ↔ CSharp) invalidates every expression, and flipping

   targetFramework

   (Windows ↔ Portable/cross-platform, or Legacy) invalidates package references and activity compatibility. Do not attempt in-place conversion. If the user wants to convert an existing project, confirm with them, copy the project to a temporary folder, create a new project via

   uip rpa init --expression-language <VisualBasic|CSharp> --target-framework <Windows|Portable>

   (for a target of Windows - Legacy, create it in Legacy mode instead — modern

   init

   is not the legacy creation path), make sure all the defined workflows in the old project have an equivalent in the new project. Delete the copied project just after the new project has been successfully generated and the user agree with the changes.
9. [XAML] Wrap every container-activity body/branch in

   <Sequence>

   — even single-activity bodies. Studio's designer expects the wrap as a drop zone; Studio's emitter produces it.

   validate

   and

   build

   accept the bare form, so neither catches missing wrappers. Applies to creation and editing alike. Slots include

   If.Then

   /

   If.Else

   ,

   While

   /

   DoWhile

   body,

   ForEach.Body

   ,

   TryCatch.Try

   /

   Catch

   /

   Finally

   ,

   Switch.Default

   + each case,

   PickBranch.Trigger

   /

   Action

   ,

   NApplicationCard.Body

   . Full table with examples: xaml/xaml-basics-and-rules.md § Container Activity Bodies — Wrap in Sequence.

• assets/codedworkflow-template.md — Workflow, test case, helper-class, and Before/After-hooks boilerplate (all coded templates)
• assets/json-template.md —

  entryPoints

  and

  fileInfoCollection

  snippets
• environment-setup.md § Designing Project Structure — Project structure design guidelines (mode-agnostic)

• xaml/xaml-basics-and-rules.md — XAML anatomy, safety rules, editing operations (read before any XAML work)
• xaml/common-pitfalls.md — Activity gotchas, scope requirements, property conflicts
• data-manipulation-guide.md — DataTable LINQ (filter/sort/group/join/diff), strings, RegEx, DateTime, type conversion, collections, JSON; VB + C# forms
• error-handling-guide.md — Modern-mode error handling & resilience: exception taxonomy, Try/Catch discipline, Retry Scope, ContinueOnError, Throw/Rethrow, screenshot-on-error, Global Exception Handler (scaffold + registration + verdict logic), state recovery before retry, transaction boundaries, idempotent/compensating writes (duplicate-create safety), sensitive-data redaction, and retry ownership across layers
• reframework-guide.md — REFramework execution modes, SetTransactionStatus queue-guard fix, Config.xlsx leftover trap
• xaml/csharp-activity-binding-guide.md — Canonical C# binding forms per common activity property (flat lookup table + recipes) + § C# Expression Pitfalls (attribute-form VB JIT, ThrowIfNotInTree, OutArgument parse errors)
• xaml/canvas-layout-guide.md — Flowchart node vocabulary, structure & wiring, node registration, forbidden nested-chain pattern + Flowchart/State Machine/LRW canvas layout with ViewState
• xaml/long-running-workflow-guide.md — LRW package dependency, node vocabulary, gateway patterns, suspend/resume persistence
• xaml/jit-custom-types-schema.md — JIT custom type discovery
• library-authoring-guide.md — Produce reusable libraries: public-workflow contract, activity layout sidecar (display name, icon, widgets), error contract, SemVer, pack & publish to the libraries feed

project.json

dependencies

--include-prerelease

-preview

.local/docs

• If present → note the installed version. Then list available versions with

  --include-prerelease

  and compare:
  • If a newer version (stable or preview) exists, inform the user: state the installed version, the latest available version, and that newer packages offer the best support for activity generation (latest activity surface, accurate

    .local/docs

    , fewer signature mismatches). Ask whether to upgrade. Never force-upgrade an already-installed package.
  • If the installed version is already the latest, proceed to Step 2.
• If absent → install the latest version returned by

  packages versions --include-prerelease

  (preview is acceptable):

uip rpa packages versions --package-id <PackageId> --include-prerelease --project-dir "<PROJECT_DIR>" --output json
uip rpa packages install --packages 'id=<PackageId>,version=<LATEST_VERSION>' --project-dir "<PROJECT_DIR>" --output json

1. Check

   {PROJECT_DIR}/.local/docs/packages/{PackageId}/

   — auto-generated, most accurate. Use

   Glob

   +

   Read

   (not

   Grep

   —

   .local/

   is gitignored).
2. Fall back to bundled references at

   references/activity-docs/{PackageId}/

   — pick the version folder closest to what is installed.

• This skill (

  references/

  , relative to this SKILL.md) — policy this skill owns: prerequisites/version gating, run/debug orchestration, stub-mode deliverables, UI Library publishing.
• UIA activity pack (

  {PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/

  , installed via

  uip rpa packages install

  ) — the UIA authoring guide, target-capture orchestration, single-purpose task guides, concrete

  uip rpa uia

  CLI syntax, per-activity property surfaces, coded API surface, and the UIA skill internal procedures. Co-versioned with the package, so always source-of-truth over anything in this skill when they diverge.

• uia-starter-guide.md — read first for any UIA work (Rule 7). Mandates the package guide read, then owns the skill-side UIA policies: run/debug procedure (baseline → debug → cancel → window cleanup) + profiling + runtime selector failure recovery, the placeholder-stub deliverable pattern, and UI Library publishing. Version gating and upgrade consent: SKILL.md § UIA Prerequisites.

• ui-automation-guide.md

  — the entry point for all UIA authoring (Rule 7; read in full first — also the Rule 7a availability probe). Window baseline, capture orchestration, common pitfalls, control-specific interaction, coded and XAML patterns. Its § Documentation routes to everything else in the pack: target-capture orchestration, task guides, CLI command inventory, per-activity property surfaces, coded API surface, and the UIA skills (

  uia-configure-target

  ,

  uia-improve-selector

  ).

docs/plans/*.md

1. Re-read the plan and scan its task checkboxes.
2. If any

   [ ]

   boxes remain AND the plan's header says

   Execution autonomy: autonomous

   AND no

   Stop conditions

   item was hit — do not report done. Resume execution on the next unchecked task.
3. If unchecked boxes remain because a Stop condition was hit, name the exact stop-condition item in the report.
4. If the plan is fully checked off, or execution autonomy is

   interactive

   , proceed to the report format below.

1. What was done — files created, edited, or deleted (list file paths)
2. Validation status — per-file

   validate

   result (all files passed, or remaining errors) and project-level

   uip rpa build

   result. Both must be clean to claim verification —

   validate

   clean alone is insufficient (it does not detect unknown member names or invalid enum values). If

   build

   has not run since the last edit, say so explicitly rather than claiming success.
3. Plan completion — which task checkboxes in

   docs/plans/*.md

   are now

   [x]

   ; list any still

   [ ]

   and, for each, the Stop-condition item that interrupted it (or "not reached" if execution was cut short another way)
4. How to run — the

   uip rpa run

   (or

   uip rpa debug start

   ) command (if applicable)
5. Next steps — follow-up actions (configure connections, add OR elements, fill placeholders)
6. Trouble? — if the user hit issues during this session, mention: "If something didn't work as expected, use

   /uipath-feedback

   to send a report."