@uipath/skills 1.195.0

package/skills/uipath-human-in-the-loop/references/hitl-node-quickform.md

@@ -0,0 +1,392 @@
+# HITL QuickForm Node — Direct JSON Reference
+
+The agent writes the `uipath.human-in-the-loop` node directly into the `.flow` file as JSON. **Direct JSON is the default.** A CLI opt-in is available when the user explicitly requests it, or as a fallback if direct JSON writing fails — see [CLI reference: uip maestro flow hitl add](../../uipath-maestro-flow/references/shared/cli-commands.md#uip-maestro-flow-hitl-add).
+
+---
+
+## Step 1 — Extract the Schema Through Conversation
+
+Before designing the schema, ask these focused questions if the business description doesn't answer them. **Ask all missing ones in a single message — never one at a time.**
+
+| What you need to know | Question to ask |
+|---|---|
+| What the reviewer sees | "What information does the reviewer need to make their decision?" |
+| What they fill in | "Does the reviewer need to enter any data, or just click Approve/Reject?" |
+| What actions they take | "What are the named actions — e.g. Approve/Reject, or something domain-specific like Accept/Negotiate/Decline?" |
+
+**Common business descriptions → schema translations:**
+
+| Business description | Schema shape |
+|---|---|
+| "Human reviews and approves/rejects an invoice" | `inputs: [invoiceId, amount]`, `outcomes: [Approve, Reject]` |
+| "Reviewer checks agent-drafted email before sending" | `inputs: [draftEmail, recipientName]`, `inOuts: [emailBody]`, `outcomes: [Approve, Reject]` |
+| "Escalate to human when confidence < 0.7" | `inputs: [agentReasoning, confidenceScore]`, `outputs: [action, notes]`, `outcomes: [Retry, Skip, Escalate]` |
+| "Human fills in missing vendor data" | `inputs: [rawExtract]`, `outputs: [vendorName, costCenter]`, `outcomes: [Submit]` |
+| "Approve before writing to ServiceNow" | `inputs: [proposedChange, targetSystem]`, `inOuts: [finalValue]`, `outcomes: [Approve, Reject]` |
+
+---
+
+## Step 1b — Discover Upstream Variables
+
+Before designing input field bindings, read **both** `workflow.variables.nodes` and `workflow.variables.globals` from the `.flow` file.
+
+### Node outputs (`variables.nodes`)
+
+Each entry exposes exactly what `$vars` paths are available:
+
+```json
+{ "id": "fetchInvoice.output", "type": "object", "binding": { "nodeId": "fetchInvoice", "outputId": "output" } }
+```
+
+The `id` field is the `$vars` path — `fetchInvoice.output` → `$vars.fetchInvoice.output`. Nested field access appends `.fieldName` (e.g., `$vars.fetchInvoice.output.invoiceId`).
+
+> **Binding path key = upstream script output key, not the HITL field `id`.** The HITL field `id` identifies the form field (lowercase, used for rendering). The binding path key is the property name in the upstream script's `return` statement. These are different things. If the script returns `{ supplierName: "Acme" }` and you give the HITL field `"id": "suppliername"`, the correct binding is `vars.fetchSupplier.output.supplierName` — NOT `vars.fetchSupplier.output.suppliername`. The field `id` is irrelevant to the binding path. Always look at the upstream script source to derive the key, never at the HITL field schema you are writing.
+
+**outputId by node type:**
+
+| Node type | outputId | Access pattern |
+|---|---|---|
+| HTTP node | `output` | `$vars.{nodeId}.output.body.{field}` |
+| Script node | `output` | `$vars.{nodeId}.output.{field}` |
+| Prior HITL node | `output`, `status` | `$vars.{nodeId}.output.{field}` |
+| Agent node | `output` | `$vars.{nodeId}.output.content` |
+| Trigger (manual) | `output` | `$vars.start.output.{field}` |
+
+### Flow-level globals (`variables.globals`)
+
+Also read `workflow.variables.globals`. Each entry has an `id` that maps directly to a `$vars` reference — no node prefix, no `.output` segment:
+
+```json
+{ "id": "customerName", "direction": "in", "type": "string" }
+```
+
+→ HITL binding: `"vars.customerName"` (no `=js:$` prefix — HITL binding is a raw path)
+
+**When to use globals instead of node outputs:** When data was declared as a flow-level input variable (e.g. the trigger passes it as a named parameter via `triggerNodeId`), it lives in `globals` with `direction: "in"`. Bind directly to `vars.<globalId>` — do not add `.output` or a node prefix.
+
+| Source | HITL `binding` format | Expression format (other nodes) |
+|---|---|---|
+| Node output | `vars.<nodeId>.output.<field>` | `=js:$vars.<nodeId>.output.<field>` |
+| Flow global (`direction: "in"`) | `vars.<globalId>` | `=js:$vars.<globalId>` |
+
+> **`binding` vs `variable` prefix rule:** `binding` (input/inOut fields) uses the full path starting with `vars.` because it references an existing variable path. `variable` (output/inOut fields) is just a **name** with no prefix — it declares a new global variable, not a reference to an existing one.
+
+For the full variable system, see → [How $vars paths are constructed in Flow](../../uipath-maestro-flow/references/shared/variables-and-expressions.md)
+
+---
+
+## Step 2 — Design the Schema
+
+The node schema uses `fields[]` entries inside `inputs.schema`. Use these conceptual roles to plan the fields before writing the node JSON:
+
+| Role | `direction` value | Human can… | Use for |
+|---|---|---|---|
+| Input field | `"input"` | Read only | Context the human needs to make a decision |
+| Output field | `"output"` | Write | Data the automation needs back |
+| InOut field | `"inOut"` | Read + modify | Data the human can see and optionally correct |
+
+**Supported field types:** `text` (maps from `string`), `number`, `boolean`, `date`
+
+**Design rules:**
+- Input fields: everything the human needs to decide — IDs, amounts, context; bind to upstream node output via `binding`
+- Output fields: only what downstream nodes actually use; set `required: true` for mandatory outputs
+- `outcomes`: use domain-specific names (Approve/Reject, not just Submit)
+- Keep it focused — don't add fields the automation won't use
+
+**Show the designed schema to the user and confirm before writing the node.**
+
+---
+
+## Full Node JSON
+
+```json
+{
+  "id": "invoiceReview1",
+  "type": "uipath.human-in-the-loop",
+  "typeVersion": "1.0",
+  "display": { "label": "Invoice Review" },
+  "inputs": {
+    "type": "quick",
+    "title": "Invoice Review",
+    "recipient": {
+      "channels": ["Email", "ActionCenter"],
+      "connections": {},
+      "assignee": { "type": "group" }
+    },
+    "priority": "Low",
+    "schema": {
+      "schemaId": "a3f7c2d1-8b4e-4f9a-b2c5-6d8e1f3a7b9c",
+      "fields": [
+        {
+          "id": "invoiceid",
+          "label": "Invoice ID",
+          "type": "text",
+          "direction": "input",
+          "binding": "vars.fetchInvoice.output.invoiceId"
+        },
+        {
+          "id": "amount",
+          "label": "Amount",
+          "type": "number",
+          "direction": "input",
+          "binding": "vars.fetchInvoice.output.amount"
+        },
+        {
+          "id": "notes",
+          "label": "Notes",
+          "type": "text",
+          "direction": "output",
+          "variable": "notes",
+          "required": false
+        },
+        {
+          "id": "decision",
+          "label": "Decision",
+          "type": "text",
+          "direction": "output",
+          "variable": "decision",
+          "required": true
+        }
+      ],
+      "outcomes": [
+        { "id": "approve", "name": "Approve", "type": "string", "isPrimary": true,  "action": "Continue" },
+        { "id": "reject",  "name": "Reject",  "type": "string", "isPrimary": false, "action": "End" }
+      ]
+    }
+  },
+  "outputs": {
+    "output": {
+      "type": "object",
+      "description": "Task result data",
+      "source": "=result",
+      "var": "output",
+      "properties": {
+        "notes":    { "type": "string" },
+        "decision": { "type": "string" },
+        "Action":   { "type": "string", "enum": ["Approve", "Reject"], "default": "Approve" }
+      }
+    },
+    "status": {
+      "type": "string",
+      "description": "Task completion status",
+      "source": "=result.Action",
+      "var": "status",
+      "enum": ["Approve", "Reject"],
+      "default": "Approve"
+    }
+  }
+}
+```
+
+**Required fields:** `id`, `type`, `typeVersion`. Position goes in the top-level `layout.nodes` object (keyed by node id), not on the node itself.
+
+**Node ID rule:** camelCase from the label, strip non-alphanumeric, append `1` (increment to `2`, `3`... until unique among existing node IDs). Example: `"Invoice Review"` → `invoiceReview1`.
+
+---
+
+## Definition Entry
+
+Every `.flow` file must have one definition entry for `uipath.human-in-the-loop` in `workflow.definitions`. Add it exactly once — deduplicate by `nodeType`.
+
+```json
+{
+  "nodeType": "uipath.human-in-the-loop",
+  "version": "1.0",
+  "category": "human-task",
+  "tags": ["human-task", "hitl", "human-in-the-loop", "approval"],
+  "sortOrder": 50,
+  "display": {
+    "label": "Human in the Loop",
+    "icon": "users",
+    "shape": "square"
+  },
+  "handleConfiguration": [
+    {
+      "position": "left",
+      "handles": [
+        {
+          "id": "input",
+          "type": "target",
+          "handleType": "input"
+        }
+      ],
+      "visible": true
+    },
+    {
+      "position": "right",
+      "handles": [
+        { "id": "completed", "label": "Completed", "type": "source", "handleType": "output", "showButton": true, "constraints": { "forbiddenTargetCategories": ["trigger"] } }
+      ],
+      "visible": true
+    }
+  ],
+  "model": { "type": "bpmn:UserTask", "serviceType": "Actions.HITL" },
+  "inputDefaults": {
+    "type": "quick",
+    "schema": {
+      "fields": [],
+      "outcomes": [{ "id": "submit", "name": "Submit", "type": "string", "isPrimary": true, "action": "Continue" }]
+    },
+    "recipient": {
+      "channels": ["Email", "ActionCenter"],
+      "connections": {},
+      "assignee": { "type": "group" }
+    }
+  },
+  "outputDefinition": {
+    "output": { "type": "object", "description": "Task result data", "source": "=result", "var": "output" },
+    "status": { "type": "string", "description": "Task completion status", "source": "=result.Action", "var": "status" }
+  }
+}
+```
+
+---
+
+## Edge Wiring
+
+Wire the `completed` output handle to the downstream node. Edge ID format: `{sourceNodeId}-{sourcePort}-{targetNodeId}-{targetPort}` (append `-2`, `-3` on collision).
+
+```json
+{ "id": "invoiceReview1-completed-processApproval1-input", "sourceNodeId": "invoiceReview1", "sourcePort": "completed", "targetNodeId": "processApproval1", "targetPort": "input" }
+```
+
+**Always wire `completed`.** A HITL node with no edge on `completed` blocks the flow forever.
+
+---
+
+## `variables.nodes` — Regenerate After Every Node Add/Remove
+
+The HITL node exposes two outputs (`output`, `status`). After adding it, **completely replace** `workflow.variables.nodes` by iterating all nodes and collecting their outputs:
+
+```json
+"variables": {
+  "nodes": [
+    {
+      "id": "invoiceReview1.output",
+      "type": "object",
+      "description": "Task result data",
+      "binding": { "nodeId": "invoiceReview1", "outputId": "output" }
+    },
+    {
+      "id": "invoiceReview1.status",
+      "type": "string",
+      "description": "Task completion status",
+      "binding": { "nodeId": "invoiceReview1", "outputId": "status" }
+    }
+  ]
+}
+```
+
+Include entries for **all** nodes in the flow, not just the HITL node. Replace the entire array — do not append. Add one `output` entry and one `status` entry per HITL node — no per-field entries. Output and inOut field values from the task are accessible via `$vars.<nodeId>.output.<fieldId>` at runtime (fields are embedded in the output object, not exposed as separate node variables).
+
+Output-direction and inOut-direction fields are also materialized as workflow-level globals in `variables.globals` with `direction: "inout"` — these are accessible directly as `$vars.<field.variable>` without a node prefix (e.g. `variable: "decision"` → `$vars.decision`).
+
+---
+
+## Schema Conversion — Examples
+
+The agent translates the user's business description into the `fields[]` and `outcomes[]` arrays. No CLI needed — apply these rules directly.
+
+### Rules
+
+| What | Rule |
+|---|---|
+| field `id` | lowercase label, spaces→`-`, strip non-alphanumeric. `"Invoice ID"` → `"invoiceid"`, `"Due Date"` → `"due-date"` |
+| `direction` | `inputs[]` items → `"input"`, `outputs[]` → `"output"`, `inOuts[]` → `"inOut"` |
+| field `type` | `"string"` → `"text"`, `"number"` → `"number"`, `"boolean"` → `"boolean"`, `"date"` → `"date"` |
+| `binding` | **Input / inOut fields only.** Format: `"vars.<nodeId>.output.<field>"` for node outputs; `"vars.<globalId>"` for flow globals. **No `=js:$` prefix** — HITL binding is a raw path, not an expression. |
+| `variable` | **Output / inOut fields only** — absent on input fields. Format: `"<name>"` (**no** `vars.` prefix — just the variable name). Defaults to the camelCase of the field `id` if not specified. |
+| `required` | omit if false; set `true` for mandatory outputs |
+| `outcomes[0]` | `isPrimary: true`, `action: "Continue"` |
+| `outcomes[1+]` | `isPrimary: false`, `action: "End"` |
+| `schema.schemaId` | Generate a fresh UUID (e.g. `crypto.randomUUID()` or any UUID v4) |
+
+### Example 1 — Simple approval (inputs only + outcomes)
+
+Business description: *"Reviewer sees invoice ID and amount, clicks Approve or Reject"*
+
+```json
+"fields": [
+  { "id": "invoiceid", "label": "Invoice ID", "type": "text",   "direction": "input", "binding": "vars.fetchData1.output.invoiceId" },
+  { "id": "amount",    "label": "Amount",     "type": "number", "direction": "input", "binding": "vars.fetchData1.output.amount" }
+],
+"outcomes": [
+  { "id": "approve", "name": "Approve", "type": "string", "isPrimary": true,  "action": "Continue" },
+  { "id": "reject",  "name": "Reject",  "type": "string", "isPrimary": false, "action": "End" }
+]
+```
+
+### Example 2 — Write-back validation (inOut — human can edit before confirming)
+
+Business description: *"Human sees the AI-drafted email, can edit it, then clicks Send or Discard"*
+
+```json
+"fields": [
+  { "id": "recipient",  "label": "Recipient",  "type": "text", "direction": "input", "binding": "vars.draft1.output.recipient" },
+  { "id": "emailbody",  "label": "Email Body", "type": "text", "direction": "inOut", "binding": "vars.draft1.output.body", "variable": "emailBody" }
+],
+"outcomes": [
+  { "id": "send",    "name": "Send",    "type": "string", "isPrimary": true,  "action": "Continue" },
+  { "id": "discard", "name": "Discard", "type": "string", "isPrimary": false, "action": "End" }
+]
+```
+
+### Example 3 — Data enrichment (output — human fills in missing fields)
+
+Business description: *"Agent couldn't extract vendor name or cost center. Human fills them in and clicks Submit."*
+
+```json
+"fields": [
+  { "id": "rawextract",  "label": "Raw Extract",  "type": "text", "direction": "input",  "binding": "vars.extract1.output.rawText" },
+  { "id": "vendorname",  "label": "Vendor Name",  "type": "text", "direction": "output", "variable": "vendorName",  "required": true },
+  { "id": "costcenter",  "label": "Cost Center",  "type": "text", "direction": "output", "variable": "costCenter", "required": true }
+],
+"outcomes": [
+  { "id": "submit", "name": "Submit", "type": "string", "isPrimary": true, "action": "Continue" }
+]
+```
+
+### Example 4 — Exception escalation (multiple outcomes + notes output)
+
+Business description: *"If agent confidence is low, escalate. Human sees reasoning and score, can Retry, Skip, or Escalate further."*
+
+```json
+"fields": [
+  { "id": "reasoning",       "label": "Agent Reasoning",  "type": "text",   "direction": "input",  "binding": "vars.classify1.output.reasoning" },
+  { "id": "confidencescore", "label": "Confidence Score", "type": "number", "direction": "input",  "binding": "vars.classify1.output.score" },
+  { "id": "notes",           "label": "Notes",            "type": "text",   "direction": "output", "variable": "notes" }
+],
+"outcomes": [
+  { "id": "retry",    "name": "Retry",    "type": "string", "isPrimary": true,  "action": "Continue" },
+  { "id": "skip",     "name": "Skip",     "type": "string", "isPrimary": false, "action": "End" },
+  { "id": "escalate", "name": "Escalate", "type": "string", "isPrimary": false, "action": "End" }
+]
+```
+
+> **`outcomeType` for middle outcomes:** Use `"Neutral"` when the outcome is neither clearly positive nor negative (e.g., Skip, Defer, Hold).
+
+---
+
+## Runtime Variables
+
+After the HITL node, downstream nodes can reference:
+
+| Variable | Type | What it contains |
+|---|---|---|
+| `$vars.<nodeId>.output` | object | All `output` and `inOut` field values keyed by **field `id`** |
+| `$vars.<nodeId>.output.<fieldId>` | varies | Individual field value using the field's `id` (e.g. `$vars.invoiceReview1.output.decision`) |
+| `$vars.<nodeId>.status` | string | Selected outcome name (e.g. `"Approve"`, `"Reject"`) |
+| `$vars.<globalId>` | varies | Workflow-global variable for output/inOut fields — accessible without node prefix. The `globalId` equals `field.variable` directly (e.g. `variable: "notes"` → `$vars.notes`) |
+
+> **`fieldId` not `variable`**: The output object properties are keyed by the field's `id` (e.g. `"decision"`), not by the `variable` property. The `variable` property (`"approvalResult"`) creates a separate workflow-global variable (`$vars.approvalResult`) — it does not change the key used in the output object. If a field has `"id": "dec1"` and `"variable": "approvalResult"`, access it via the object as `$vars.nodeId.output.dec1`, or directly as `$vars.approvalResult`.
+>
+> **Common mistake:** A field with `"id": "approved"` and `"variable": "legalApproval"` must be read as `$vars.<nodeId>.output.approved` — **not** `$vars.<nodeId>.output.legalApproval`. Using the `variable` name as the key produces `undefined` at runtime; `flow validate` does not catch it.
+
+**In a downstream script node:**
+```javascript
+const output = $vars.invoiceReview1.output;
+// Access by field ID, not variable name
+if ($vars.invoiceReview1.status === "approve") {
+  await updateSystem(output.vendorName, output.costCenter);
+}
+```

package/skills/uipath-human-in-the-loop/references/hitl-patterns.md

@@ -0,0 +1,154 @@
+# HITL Business Pattern Recognition Guide
+
+Use this guide to decide whether a business process needs a Human-in-the-Loop node, and where to place it — even when the user has not explicitly asked for one.
+
+---
+
+## When to Recommend HITL
+
+Look for these signals in the business description or process context:
+
+### Approval gate
+The automation produces something that requires sign-off before it can proceed.
+
+| Signal phrases | Examples |
+|---|---|
+| "approve", "sign off", "authorize", "get approval" | Invoice approval, PO sign-off, budget authorization |
+| "four-eyes check", "dual control", "maker-checker" | Financial transactions, compliance workflows |
+| "review before posting", "validate before sending" | CRM updates, email campaigns, database writes |
+
+**Insertion point:** After the automation generates the artifact to review, before it takes the action requiring approval.
+
+---
+
+### Exception escalation
+The automation hits a case it cannot resolve autonomously and needs a human decision.
+
+| Signal phrases | Examples |
+|---|---|
+| "if uncertain / low confidence, escalate" | AI agent confidence threshold |
+| "edge case", "anomaly", "exception handling" | Fraud alerts, out-of-policy transactions |
+| "escalate to manager / supervisor" | Customer service workflows |
+
+**Insertion point:** Inside a conditional branch where the automation detects it cannot proceed alone.
+
+---
+
+### Data enrichment
+The automation extracted or generated data that is incomplete — a human must fill in the gaps.
+
+| Signal phrases | Examples |
+|---|---|
+| "fill in missing fields", "enrich", "complete the record" | Partially extracted invoice data |
+| "human validates / corrects" | OCR output verification |
+| "needs human input before continuing" | Missing vendor code, unknown cost center |
+
+**Insertion point:** After extraction/generation, before the downstream step that requires complete data.
+
+---
+
+### Compliance and audit checkpoint
+A regulation or internal policy requires documented human sign-off.
+
+| Signal phrases | Examples |
+|---|---|
+| "compliance", "audit trail", "regulatory sign-off" | SOX controls, GDPR consent flows |
+| "must be reviewed by", "requires attestation" | Legal review gates, privacy impact assessments |
+
+**Insertion point:** At the mandated checkpoint defined by the regulation or policy.
+
+---
+
+### Write-back validation
+An agent or automation is about to write to an external system — a human must confirm the proposed change.
+
+| Signal phrases | Examples |
+|---|---|
+| "before writing to", "before posting to", "agent writes to ServiceNow / SAP / CRM" | Any write to a system of record |
+| "human confirms before agent acts" | Autonomous agent guard rails |
+
+**Insertion point:** Immediately before the write/post action.
+
+---
+
+### Agentic output review
+An AI agent produced a document, draft, classification, or recommendation — a human must verify it before the result is used or published.
+
+| Signal phrases | Examples |
+|---|---|
+| "review AI-generated content", "human verifies before sending" | Agent-drafted emails, RCA reports, meeting summaries |
+| "check before publishing", "validate AI output" | AI-written case notes, support ticket responses |
+| "human in the loop for AI decisions" | Any LLM output going to a system of record or customer |
+
+**Insertion point:** After the agent node, before the downstream action that consumes the output.
+
+---
+
+### IT / change management approval
+A change request or access request needs human authorization before the automation executes it.
+
+| Signal phrases | Examples |
+|---|---|
+| "CAB approval", "change request", "change window" | IT change management (ServiceNow, Jira Service Management) |
+| "access request", "provision access", "grant permission" | Identity and access management workflows |
+| "runbook approval", "deployment sign-off" | DevOps release gates |
+
+**Insertion point:** After the automation prepares the change record, before it applies the change.
+
+---
+
+### HR and offer / contract workflows
+A document or decision with legal or HR significance must be reviewed before it is sent to a third party.
+
+| Signal phrases | Examples |
+|---|---|
+| "offer letter", "employment contract", "onboarding approval" | HR hiring workflows |
+| "termination review", "performance decision" | HR case management |
+| "contract terms", "counter-sign", "legal review gate" | Procurement, vendor onboarding |
+
+**Insertion point:** After document generation, before the document is dispatched.
+
+---
+
+### Customer communication approval
+An automation is about to send a message on behalf of a person or brand — a human must review tone, accuracy, or content before it goes out.
+
+| Signal phrases | Examples |
+|---|---|
+| "approve before sending", "review draft email", "check before posting" | Customer support responses, marketing emails |
+| "agent-written reply", "draft response" | Helpdesk, CRM follow-ups |
+
+**Insertion point:** After the draft is generated, before the send/post action.
+
+---
+
+### Financial transaction approval
+A monetary action above a threshold or of a certain type requires human sign-off.
+
+| Signal phrases | Examples |
+|---|---|
+| "above threshold", "over limit", "exceeds budget" | PO approval, expense reimbursement over limit |
+| "wire transfer", "payment release", "credit note" | AP/AR workflows |
+| "price override", "discount approval" | Sales quote approval |
+
+**Insertion point:** After the automation determines the transaction details, before it submits the payment or posts the entry.
+
+---
+
+## When NOT to Recommend HITL
+
+- The process description is fully automated with no decision point (e.g. "process all invoices automatically")
+- The human interaction is asynchronous notification only (use email/Slack activity instead)
+- The user explicitly says no human review is needed
+- The decision can be made by a rule or AI model with sufficient confidence
+- The user is asking about **runtime task management** — reassigning, monitoring, cancelling, or checking the status of existing Action Center tasks. These are operational questions answered by `uip tasks` commands or the Orchestrator UI, not by adding a HITL node. A question like "how do I reassign a task sitting for 3 days?" is task administration, not automation authoring — do not recommend adding a HITL checkpoint in response.
+
+---
+
+## Proactive HITL Recommendation
+
+If a business description contains any of the above signals but the user has not asked for a HITL, flag it:
+
+> "This process includes [signal]. Before the automation [action], a human should review [data]. I recommend inserting a HITL node here — want me to add it?"
+
+Then proceed to Step 3 (schema design) only after the user confirms.

package/skills/uipath-ixp/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: uipath-ixp
+description: "[PREVIEW] UiPath IXP (Document Understanding) — review IXP predictions with Claude, confirm valid fields, improve prompts, publish models."
+---
+
+# UiPath IXP Document Extraction Assistant
+
+Skill for working with UiPath IXP (Intelligent eXtraction Platform) projects — creating projects, uploading documents, reviewing predictions, and improving extraction quality.
+
+## When to Use This Skill
+
+- User asks to create an IXP project, upload documents, or train a document extraction model
+- User asks to label, review, or confirm document predictions
+- User asks to improve extraction scores, prompts, or field instructions
+- User asks to publish or manage IXP model versions
+- User provides a taxonomy file to import into a project
+- User asks for the project taxonomy at a specific trained model version — what the schema looked like when version N was published (use `deployments get-taxonomy <project-name> --version <N>`)
+
+## Critical Rules
+
+1. **ONLY use `uip ixp` CLI commands as documented in this skill** — do NOT use curl, do NOT call REST APIs directly, do NOT grep/read source code, do NOT explore the codebase.
+2. **Run workflows end-to-end automatically** — do NOT ask the user to do individual steps.
+3. **Always use `--output json`** when parsing CLI output programmatically.
+4. **Use `/tmp/ixp/<project-name>/` as the working directory with this structure:**
+   ```
+   /tmp/ixp/<project-name>/
+   ├── docs/         # Document files (<document-id>.pdf, .png, …) — downloaded once, reused across sessions
+   ├── taxonomies/   # Taxonomy snapshots (v1.json, v2.json, …) — new version after each update-prompts
+   └── prompts/      # Instruction update payloads (field_updates.json, group_updates.json, …)
+   ```
+   At the start of any workflow: `mkdir -p /tmp/ixp/<project-name>/{docs,taxonomies,prompts}`. If the directory already exists from a previous session, **reuse existing files** — do not re-download documents that are already present. Do NOT use the Write tool for `/tmp/ixp/` paths — on Windows it resolves to a different location than bash.
+5. **Use heredocs for `--updates`** — for `fields update-prompts --updates` and `groups update-prompts --updates`, use heredocs (`cat > /tmp/ixp/<project-name>/prompts/field_updates.json << 'EOF' ... EOF`) then `"$(cat /tmp/ixp/<project-name>/prompts/field_updates.json)"`.
+6. **Never use `UID` as a variable name** — it is a readonly shell variable. Use `DOC_ID`, `DOCUMENT_ID`, etc.
+7. **Always use the project `Name`, never the `Title`** — the `project list` output has both `Name` (e.g., `my_invoices-f1afa9ef-ixp`) and `Title` (e.g., `My_Invoices`). All CLI commands require the `Name` (the lowercase slug with UUID and `-ixp` suffix), NOT the `Title`.
+8. **Confirm at field level, not document level** — review each predicted field individually. Confirm only the fields that are correct using `labelling confirm --fields`. Fields with wrong predictions are left unannotated. **`--corrections` is ONLY for OCR-mangled values** — the prediction found the right field in the right location and the bytes-on-page are right, but the text was garbled (e.g., `MSIÓÓÓ601020/` → `MSI0601020`). Do NOT use `--corrections` to flip a wrong boolean, fix a wrong inferred/computed value, or change any value where the prediction itself was the wrong answer — those are NOT CONFIRMED. Overriding a non-OCR prediction is manual extraction (forbidden by rule 11).
+9. **Do NOT manually extract values** — all labelling goes through `labelling confirm` with predictions from IXP.
+10. **Max 8 documents for taxonomy suggestion** — the suggest-taxonomy endpoint accepts at most 8 attachment references.
+11. **Claude is the reviewer, not the extractor** — IXP generates predictions, Claude validates them. For each document, review predicted field values against the document file (Read tool handles PDF, PNG, JPG, etc.). Confirm correct fields (`labelling confirm --fields`), correct OCR-mangled values (`--corrections`), and skip wrong fields. Do NOT manually extract values. If a field's F1 is low, improve the **prompt** so IXP predicts better values.
+12. **Confirm a field as missing by listing it in `confirm --fields`, only when IXP also predicted nothing** — `labellings confirm --fields f1,f2,f3` treats every listed field uniformly: if IXP predicted a value, it's confirmed; if IXP predicted nothing for a listed field, a missing marker is written. The explicit listing IS the confirmation that the empty state is intentional. Only include a field in `--fields` for the missing case when IXP itself predicted no value (or an empty value) AND the field is genuinely absent from the document. If IXP predicted a wrong value, leave the field NOT CONFIRMED (omit it from `--fields`) — choosing "missing" yourself is the same kind of extractor decision rule 11 forbids. Use `labellings mark-missing` only as a fallback when `confirm --fields` is a no-op for a field you expected it to handle — this happens when the field has a prior annotation but doesn't appear in the current `get-predictions` output for that document (e.g., model behavior or the taxonomy changed between iterations). In that case, `mark-missing` reaches the stale annotation and overwrites it with a missing marker; `confirm` can't.
+
+## Quick Start
+
+1. Run `uip ixp projects list --output json` to see existing projects
+2. To create a new project: follow [Project Setup Guide](references/project-setup-guide.md)
+3. To improve an existing project: follow [Improve Prompts Guide](references/improve-prompts-guide.md)
+4. To label documents on an existing project: follow [Label Documents Guide](references/label-documents-guide.md)
+
+If the user provides a taxonomy file, use `--skip-taxonomy` and `import-taxonomy` (Option B in the Project Setup guide).
+
+## Task Navigation
+
+| User request | Action |
+|-------------|--------|
+| "Create an IXP project" / "Upload documents to a new project" | [Project Setup Guide](references/project-setup-guide.md) — **new** projects only (uploads + taxonomy in one call). For **existing** projects, see the "Upload a document" row below. |
+| "Import this taxonomy" / provides a taxonomy file | [Project Setup Guide](references/project-setup-guide.md) — Option B (`--skip-taxonomy` + `import-taxonomy`) |
+| "Label documents" / "Review predictions" | [Label Documents Guide](references/label-documents-guide.md) |
+| "Improve scores" / "Fix prompts" / "Improve F1" | [Improve Prompts Guide](references/improve-prompts-guide.md) |
+| "Publish the model" / "Tag as live" | `uip ixp projects publish <project-name> --output json` |
+| "Show metrics" / "What are the scores?" | `uip ixp projects get-metrics <project-name> --output json` |
+| "List projects" | `uip ixp projects list --output json` |
+| "Configure the model" | `uip ixp projects configure-model <project-name> [options] --output json` |
+| "Upload a document" / "Add documents to an existing project" | `uip ixp documents upload <project-name> <file> --output json` — see [CLI Reference § Uploading documents](references/cli-reference.md#uploading-documents-to-an-existing-project). One file per call; loop for multiple. For brand-new projects use `projects create` instead. |
+| "Delete a document" / "Remove a document" | `uip ixp documents delete <project-name> <document-id> --output json` — irreversible, triggers retrain. To delete by filename, look up the `DocumentId` via `documents list` (the `Filename` column shows the original upload name). |
+| "Add / delete / rename a field group" | `uip ixp groups {add,delete,rename} <project-name> --name <name> ... --output json` — see [CLI Reference § Groups](references/cli-reference.md#groups). `groups add` requires `--instructions` and `--fields '<json>'` with at least one field. `delete` requires `--confirm-data-loss`. |
+| "Add / edit / rename / delete a data type" | `uip ixp data-types {add,update-instructions,rename,delete} <project-name> --name <name> ... --output json` — see [CLI Reference § Data Types](references/cli-reference.md#data-types). `add` requires `--kind` (text/date/money/number/boolean/choice) and `--instructions`. `--input-value` (exact-match/inferred) is required only for `--kind text` and `--kind choice`; the other kinds don't have this property and the CLI rejects the flag for them. `delete` requires `--confirm-data-loss` because referencing fields break. |
+| "Add / delete / rename / retype a field" | `uip ixp fields {add,delete,rename,change-type} <project-name> --group <name> --field <name> ... --output json` — see [CLI Reference § Fields](references/cli-reference.md#fields). `change-type` deletes annotations and requires `--confirm-data-loss`. |
+| "Mark a field as missing for a document" | Include the field's id in `uip ixp labellings confirm <project-name> <document-id> --fields <ids> --output json` alongside any content fields you're confirming. When IXP's prediction for that field is empty, the explicit listing writes a missing marker; when it has content, the content is confirmed. **Only list a field for the missing case if IXP also predicted nothing for it.** See Critical Rule 12. Use `labellings mark-missing` only as a fallback when `confirm --fields` is a no-op for a field you expected it to handle — typically a field with a prior annotation that the current prediction no longer includes (model or taxonomy changed between iterations). |
+| "Undo / unconfirm a wrong confirmation" | `uip ixp labellings unconfirm <project-name> <document-id> --fields <ids> --output json` — rolls back an earlier `confirm` or `mark-missing` for the listed fields. Every other annotation on the document is carried forward. |
+| "Set overall extraction instructions" / "Update project prompt" | `uip ixp projects update-prompt <project-name> --prompt "<text>" --output json` — replaces the taxonomy-wide prompt (the "Overall extraction instructions" field in the IXP UI). Distinct from `fields update-prompts` (per-field) and `groups update-prompts` (per-field-group). |
+
+## Common Pitfalls
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Metrics don't change after a prompt update | Re-evaluation hasn't completed | Wait ~2 minutes for retrain. |
+| ModelVersion doesn't advance | Retrain still in progress | Any change to model inputs (labellings OR instructions) triggers a full retrain. Wait ~2 min then retry. |
+| Field instructions conflict with label_def instructions | `fields update-prompts` only edits per-field instructions, NOT the parent label_def instructions | Before iterating, read the label_def `instructions` and update them with `groups update-prompts` if they contradict the per-field prompts. |
+
+## Reference Navigation
+
+- [CLI Commands Reference](references/cli-reference.md) — all `uip ixp` commands with options and output formats
+- [Project Setup Guide](references/project-setup-guide.md) — create a new project, review and label documents
+- [Improve Prompts Guide](references/improve-prompts-guide.md) — iterative optimization loop with regression detection
+- [Label Documents Guide](references/label-documents-guide.md) — reusable workflow for reviewing and confirming predictions