UitoolkitSAFE

AI automation skills specifically designed for Unity

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: unity-uitoolkit
description: Build Unity UI Toolkit (UITK) UIs
---

> **Before calling any skill in this module:** if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via `GET /skills/recommend?includeSchema=true`) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.

## Triggers
- Authoring runtime or editor UI with UI Toolkit
- Writing USS/UXML
- Wiring a UIDocument
- Binding UI to data
- Building world-space UI
- 用 UI Toolkit 编写运行时或编辑器 UI、编写 USS/UXML、接入 UIDocument、把 UI 绑定到数据源、做世界空间 UI

# Unity UI Toolkit Skills

Use this module for Unity UI Toolkit only: `UXML` for structure, `USS` for styling, `UIDocument` for scene attachment, and `PanelSettings` for runtime rendering.

> **Requires Unity 2022.3+**. Do not mix this module with `ui_*` UGUI/Canvas skills.
> **Localization**: Match visible UI text to the user's language. Chinese conversation -> Chinese labels/placeholders/button text. USS class names and CSS variables stay English.

## Operating Mode

- **Approval**:查询类 skill(`uitk_read_file` / `uitk_find_files` / `uitk_get_panel_settings` / `uitk_list_documents` / `uitk_inspect_uxml` / `uitk_list_uss_variables` / `uitk_inspect_document` / `uitk_runtime_binding_list` / `uitk_worldspace_panel_get` / `uitk_element_reference_get`,源码标 `SkillMode.SemiAuto`)直接执行;其余文件/场景写入类(`uitk_create_*` / `uitk_write_file` / `uitk_add_*` / `uitk_modify_element` / `uitk_runtime_binding_add` / `uitk_uxml_upgrade` / `uitk_worldspace_panel_create` 等,标 `SkillMode.FullAuto`)需用户 grant,grant 后服务端一步执行返结果。
- **Auto / Bypass**:未被禁列表拦截的 skill 直接执行。
- 本模块**含 Delete 类 skill**:`uitk_delete_file`、`uitk_remove_element`、`uitk_remove_uss_rule` 标记为 `SkillOperation.Delete`,被 `IsForbiddenInSemi` 静态拦截 —— 仅 **Bypass** 模式或加入 **Allowlist** 才能调用。
- 本模块**另含 2 个域重载类 skill**:`uitk_create_editor_window` 与 `uitk_create_runtime_ui` 会生成 `.cs` 文件、必然触发域重载,因此标 `MayTriggerReload = true`。`IsForbiddenInSemi` 直读这个 flag,所以它们和上面的 Delete 类同样被静态拦截 —— **Approval 与 Auto 下都返 `MODE_FORBIDDEN`,且这不是"需 grant"、grant 也给不了**,仅 **Bypass** 或命中 **Allowlist** 才能调用。这两个是上面第一条"其余写入类需用户 grant"的例外。
- 同一个 flag 还有第二个后果:**`?mode=transactional` 的批量链里含这两步,会在执行前被 400 拒绝**,错误点名违规的 `steps[i]`。原因是域重载会清空编辑器 undo 栈,事务批量的回滚承诺无法兑现,所以服务端选择前置拒绝而不是事后失败。要在事务批量的流程里生成脚本,把这两步拆出去单独调用。
- **Asset 重导行为**:所有写文件/删文件 skill 通过 `AssetDatabase.ImportAsset(path)` 对单个 USS/UXML 资产单独触发导入,**不会**调 `AssetDatabase.Refresh()` 触发全项目扫描;批量创建依次单独 Import。但 USS/UXML 是 ScriptedImporter 类型,Import 仍会重建依赖此资产的 PanelSettings/UIDocument 引用,触发 IMGUI 检查器刷新与场景视图重绘。

**DO NOT** (common hallucinations):
- `uitoolkit_create_button` / `uitoolkit_create_label` do not exist -> use `uitk_add_element`
- `uitoolkit_set_style` does not exist -> use `uitk_add_uss_rule`, `uitk_remove_uss_rule`, or `uitk_modify_element`
- `uitoolkit_create_canvas` does not exist -> UI Toolkit uses `UIDocument`, not Canvas
- `uitk_*` and `ui_*` are different systems. Do not mix UI Toolkit structure/styling assumptions into UGUI workflows
- USS is **not full CSS**. `display:grid`, `box-shadow`, `calc()`, `@media`, `::before`, `z-index`, and gradients are unsupported
- `binding-path` (on `uitk_add_element` / `uitk_modify_element`) is the **old SerializedObject** editor binding. It is not runtime data binding -> use `uitk_runtime_binding_add` for that
- Do not add a `PanelRenderer` through `component_add`; it needs world-space setup -> use `uitk_worldspace_panel_create`

**Routing**:
- For UGUI Canvas/Button/Text/Image -> use the `ui` module
- For XR world-space Canvas conversion -> use `xr_setup_ui_canvas`
- For generated starter layouts -> use `uitk_create_from_template`
- For attaching an existing UXML to a scene object -> use `uitk_create_document` or `uitk_set_document`

## Skills

### File Skills

| Skill | Use | Key parameters |
|-------|-----|----------------|
| `uitk_create_uss` | Create USS file | `savePath`, `content?` |
| `uitk_create_uxml` | Create UXML file | `savePath`, `content?`, `ussPath?` |
| `uitk_read_file` | Read USS/UXML content | `filePath` |
| `uitk_write_file` | Overwrite USS/UXML content | `filePath` (**must end `.uss` or `.uxml`**), `content` |
| `uitk_delete_file` | Delete USS/UXML file | `filePath` |
| `uitk_find_files` | Search files by name/path | `type?`, `folder?`, `filter?`, `limit?` |
| `uitk_create_batch` | Create 2+ files in one call | `items` |

> **`uitk_write_file` is not a general file writer.** `filePath` must end in `.uss` or `.uxml` (case-insensitive). Any other extension — including none at all — is rejected with `SEMANTIC_INVALID`, `validValues: [".uss", ".uxml"]` and a `relatedSkills` pointer to `script_create`. The check runs **before** the target directory is created, so a rejected call leaves no file and no stray folder behind. Do not reach for this to write a `.cs` file: use `script_create`, which correctly declares the domain reload that writing a script causes.

### Scene Skills

| Skill | Use | Key parameters |
|-------|-----|----------------|
| `uitk_create_document` | Create `UIDocument` GameObject | `name`, `uxmlPath?`, `panelSettingsPath?`, `sortOrder?`, `parentName?`/`parentInstanceId?`/`parentPath?` |
| `uitk_set_document` | Change UIDocument asset bindings | `name`/`instanceId`, `uxmlPath?`, `panelSettingsPath?` |
| `uitk_create_panel_settings` | Create PanelSettings asset | `savePath`, `scaleMode`, `referenceResolutionX/Y`, Unity 6 world-space options |
| `uitk_get_panel_settings` | Read PanelSettings values | `assetPath` |
| `uitk_set_panel_settings` | Update PanelSettings selectively | `assetPath`, changed fields only |
| `uitk_list_documents` | List scene UIDocuments | none |
| `uitk_inspect_document` | Inspect live VisualElement tree | `name`/`instanceId`/`path`, `depth` |

> **Version-gated `PanelSettings` parameters — rejected by name, never silently dropped.** On both `uitk_create_panel_settings` and `uitk_set_panel_settings`, `renderMode`, `f

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.