---
name: unity-yaml-editing
description: Unity YAML text serialization editing workflow. Use when Codex needs to directly inspect, modify, create, or repair Unity serialized YAML files such as .unity scenes, .prefab assets, .asset ScriptableObject/config files, .mat, .controller, or other text-serialized Unity assets, especially when AIBridge inspector/prefab/scene APIs do not support the requested Prefab, Scene, ScriptableObjectTable, or custom asset operation.
---

# Unity YAML Editing

Use this Skill only after considering Unity/AIBridge APIs. UnityYAML is fragile; direct text edits are the fallback for unsupported serialized asset operations, deterministic repair work, and rare text-serialized asset authoring that AIBridge/Unity APIs cannot express.

## Decision Order

1. Prefer `aibridge` Inspector/SerializedProperty commands for single readable field edits on scene objects, prefab assets, and `.asset` files.
2. Prefer `inspector set_properties` for small batched field edits on one target.
3. Prefer `aibridge-prefab-patch` for complex Prefab child/component/property/array/reference edits it supports.
4. Prefer Unity Editor scripts when generating high-level assets that Unity can create more safely than text.
5. Use direct UnityYAML editing when AIBridge/Unity APIs cannot express the operation, for example:
   - Scene `.unity` structure/object creation or unsupported scene edits.
   - New Prefab asset authoring, paired `.meta` creation, or Prefab/Variant structures not covered by `prefab patch`.
   - ScriptableObjectTable, custom ScriptableObject `.asset`, `.mat`, `.controller`, or other serialized assets requiring unsupported structural changes.
   - Repairing malformed text serialization while preserving existing IDs and references.

## Required Workflow

1. Read `references/unity-yaml-reference.md` before editing.
2. Inspect a same-project example for every Unity component/class you will create; never write component schemas from memory.
3. Make a small, reviewable patch; preserve ordering, indentation, document headers, anchors, `m_Script`, GUIDs, and local fileIDs unless a new object must be created.
4. For new assets, create or preserve the paired `.meta` file and ensure its GUID does not already appear in the project.
5. For new MonoBehaviour/ScriptableObject documents, resolve the script `.meta` GUID first and use it in `m_Script`.
6. For new documents, allocate local fileIDs that do not exist in the same file and update every owning reference consistently.
7. Validate with Unity import/compile and targeted AIBridge hierarchy/properties inspection when possible.

## Hard Rules

- Do not use generic YAML formatters or parsers to rewrite UnityYAML files.
- Do not change `%YAML`, `%TAG`, `--- !u!<classID> &<fileID>` headers, class IDs, GUIDs, or fileIDs without a clear reference update plan.
- Do not invent Unity schema fields. Copy shape from an existing nearby object of the same class/component/script when possible.
- Prefer decimal floats in hand edits. Avoid editing Unity-generated hexadecimal float values unless preserving existing text unchanged.
- Keep `.meta` GUIDs stable. Creating a new asset requires creating/retaining the paired `.meta` file through Unity when possible.
- When adding Prefab nodes/components, update all reciprocal references in the same patch: parent `m_Children`, child `m_Father`, `GameObject.m_Component`, and component `m_GameObject`.

## Reference

- `references/unity-yaml-reference.md`: detailed UnityYAML format, editing patterns, safety checks, and validation checklist.