USD Editor
Description and Goals
This skill guides safe, minimal edits to USD ASCII (.usda) files and the proper use of USD command-line tools. It focuses on preserving stage structure, using correct specifiers and property types, and avoiding composition mistakes while making targeted changes.
Goals
- Make precise edits without disrupting existing USD composition
- Preserve file formatting and authoring style
- Use correct prim specifiers, property types, and relationships
- Avoid common USD pitfalls (wrong paths, missing xformOpOrder, broken connections)
- Guide safe manipulation and inspection of USD assets using the command-line tools
What This Skill Should Do
When asked to modify a .usda file, this skill should:
- Inspect the stage structure - Identify root prims, scopes, and relevant paths.
- Choose the correct specifier - Use for edits to existing prims, for new prims.
- Edit only what is necessary - Preserve unrelated content and formatting.
- Respect composition - Avoid changing subLayers, references, or variants unless asked.
- Validate connections and paths - Ensure targets are valid and type-compatible.
If the change is material- or shader-related for RealityKit, prefer the
skill for node-specific guidance.
Quick Start Workflow
- Locate the prim path you need to edit (search by prim name or ).
- Determine whether you should an existing prim or a new one.
- Apply the smallest possible change (attribute value, relationship target, or child prim).
- If adding transforms, update to match your new ops.
- Re-check any paths or connections you touched.
Information About the Skill
Core Concepts
Stage and Layer
A USD stage is composed of one or more layers. A .usda file is a single ASCII layer that can sublayer or reference others.
Prim and Specifier
A prim is a scene graph node. Specifiers control behavior:
creates,
modifies,
defines a reusable template.
Properties
Attributes store typed data; relationships (
) point to other prims.
Composition Arc
Mechanisms like sublayers, references, and payloads that bring other USD data into the stage.
SdfPath
A path to a prim or property, written like
or
</Root/Mat.outputs:surface>
.
List Editing
USD list ops (
,
,
,
) modify lists without replacing them.
Variants
Variant sets provide alternative content branches for a prim.
Time Samples
Animated or time-varying data stored in
dictionaries.
Reference Tables
| Reference | When to Use |
|---|
| When you need a refresher on .usda syntax, values, and path formats. |
| When adding or editing prims, attributes, or relationships. |
| When touching sublayers, references, payloads, or variant sets. |
| When editing transforms, xformOps, or stage units/up axis metadata. |
| When modifying animated/time-sampled properties. |
| When you need a quick reference for common USD command-line tools. |
| When converting, flattening, or inspecting USD files. |
| When validating USD or USDZ assets, including RealityKit-focused checks. |
| When rendering images from USD files. |
| When inspecting the prim hierarchy of a USD file. |
| When creating or inspecting USDZ packages. |
| When compressing USD or USDZ assets for size. |
| When extracting files from USD-compatible packages. |
Implementation Patterns
Override an Existing Prim
usda
over "Mesh"
{
token visibility = "invisible"
}
Add a Simple Xform with Translate
usda
def Xform "Pivot"
{
double3 xformOp:translate = (0.0, 0.1, 0.0)
uniform token[] xformOpOrder = ["xformOp:translate"]
}
Bind a Material Relationship
usda
rel material:binding = </Materials/Mat>
Pitfalls and Checks
- Don't replace a prim with when you only need an .
- Keep consistent with the ops you add or remove.
- Verify targets exist and match the expected property type.
- Avoid editing composition arcs unless explicitly requested.
- Preserve existing formatting and comments to minimize diff noise.