PromptUGUI skill

---
name: authoring-promptugui-xml
description: Use when authoring or editing PromptUGUI `.ui.xml` files (XML-driven uGUI for Unity 6+) —
If a task involves any XML-to-UI related content, it is highly likely to be based on this Skill.
---

# Authoring PromptUGUI `.ui.xml`

PromptUGUI is a Unity 6+ package that turns compact XML files into runtime uGUI hierarchies. The description file is **pure structure + named handles** — no logic, no data binding expressions. All event/data wiring happens C#-side via `Get<T>(id)` and R3 `Observable<T>`; see the **scripting-promptugui-csharp** skill for that side.

This skill covers everything you need to write or edit a `.ui.xml` correctly. Read top-to-bottom once; afterwards the **Quick Reference** at the end is enough.

## Validation & feedback loop (run after every write)

Every `.ui.xml` write MUST be verified before reporting the work done. Three steps, in order — each catches a different layer of mistake:

### 1. Full validate CLI for every `.ui.xml` (catches semantic mistakes XSD can't express)

```
dotnet run --project Library/PackageCache/com.promptugui.core@<hash>/.lint/UIXmlLint -- <path/to/your.ui.xml>
dotnet run --project Library/PackageCache/com.promptugui.core@<hash>/.lint/UIXmlLint -- Assets/   # 整个目录递归
```

- **Local / embedded packages have no `PackageCache` copy.** The `Library/PackageCache/com.promptugui.core@<hash>/…` path only exists when
  PromptUGUI is resolved from a registry. If `Packages/manifest.json` pins itwith a `file:` path (local / embedded package — common in symlinked or
  monorepo checkouts), there is no PackageCache copy; the `.lint/UIXmlLint` project (and the `Runtime/Core/Lint/` rule source) live at that `file:`
  source instead. Resolve the real base from the manifest: grep com.promptugui.core Packages/manifest.json # e.g. "file:../../PromptUGUI"
  dotnet run --project /.lint/UIXmlLint -- <path/to/your.ui.xml>
- No Unity required — pure .NET, runs anywhere `dotnet` is installed.
- **Inside Unity, the same lint is a menu: `Tools › PromptUGUI › Lint All UI XML`** (via MCP: `execute_menu_item("Tools/PromptUGUI/Lint All UI XML")`, then `read_console`). It lints every `.ui.xml` under `Assets/`, one Console line per finding (same `file:line: [CODE] …` spelling, the asset as context), warnings for rule findings and errors for what `UI.Open()` would throw on. Prefer it when a Unity instance is open: it resolves `<Import src>` through the **Addressables** settings and reads the **common libraries** straight from `PromptUGUISettings`, so it reaches the expanded pass where the CLI would need `--src-root`.
- The CLI merges the common libraries too — it finds the `PromptUGUISettings` asset under `Assets/` by itself (or takes `--settings <file.asset>` / `--commons <src>[@<as>]`), and `--src-root <dir>` tells it the folder short Addressables addresses / `UseResourcesResolver(root)` keys are relative to. A src it cannot resolve skips that file's expanded pass with a note (never a false `PUI-EXPAND`); the summary counts how many files that was.
- Surfaces context-dependent rules that XSD can't easily express, e.g. **`anchor` / `margin` on a direct child of `<VStack>` / `<HStack>` / `<Grid>`** (`PUI-LAYOUT-ANCHOR` / `PUI-LAYOUT-MARGIN`), or a bare `state-*` trigger with no `<Btn>` / `<Tab>` / `<Toggle>` ancestor (`PUI-STATE-NO-SOURCE`). Unity logs these as warnings (so `UI.Open()` doesn't break), but the CLI promotes them to errors with non-zero exit code so they don't slip through.
- Exit 0 = clean. Exit 1 = at least one parse error or rule violation; STOP and fix before reporting done.
- Rule code lives in `Library/PackageCache/com.promptugui.core@<hash>/Runtime/Core/Lint/` and is shared with `ScreenInstantiator`'s warning path — same logic, one source of truth.
- **Runtime warnings / errors point back at the markup too.** Anything Unity logs about a node — a lint rule at `UI.Open()`, a sprite that failed to resolve, an `FxImage` blur / glow kernel warning, a hard `ParseException` — ends with a second line `  at <Tag id='x'> src:line (via src:line)`, the same `src:line` spelling the CLI prints (`src` is the resolver key / `LoadDocument` label, not a filesystem path; a node inside a Template body names the template's declaration line, `via` the invocation). Read it from `read_console` to find what to edit; clicking the Console entry pings the GameObject in the Hierarchy.

### 3. Unity MCP live feedback

XSD catches structural errors and a couple of identity constraints — element/attribute names, attribute patterns (`<Icon name>`), and **duplicate `id=` within the same Screen / Template body** (via `xs:unique`). Unity still catches the rest — parser semantic errors (anchor/size conflicts, missing `ref=`, Template namespace clashes), runtime hot-reload errors.

After every `.ui.xml` write:

```
mcp__UnityMCP__refresh_unity(compile="request", mode="force")
mcp__UnityMCP__read_console(action="get", types=["error","warning"])
# Notice: this is a CoplayDev/unity-mcp, user may use official unity mcp.
```

**If MCP for Unity is unavailable** (call fails / no Unity instance): Note that the Unity MCP connection is prone to disconnection; therefore, we must first take the following steps: