USD Editor

Guide for modifying USD ASCII (.usda) files, including prims, properties, composition arcs, variants, and transforms. Use when editing or reviewing .usda fil...

Description and Goals

This skill guides safe, minimal edits to USD ASCII (.usda) files and the proper use of official 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:

1. Inspect the stage structure - Identify root prims, scopes, and relevant paths.
2. Choose the correct specifier - Use over for edits to existing prims, def for new prims.
3. Edit only what is necessary - Preserve unrelated content and formatting.
4. Respect composition - Avoid changing subLayers, references, or variants unless asked.
5. Validate connections and paths - Ensure SdfPath targets are valid and type-compatible.

If the change is material- or shader-related for RealityKit, prefer the shadergraph-editor skill for node-specific guidance.

Quick Start Workflow

1. Locate the prim path you need to edit (search by prim name or SdfPath).
2. Determine whether you should over an existing prim or def a new one.
3. Apply the smallest possible change (attribute value, relationship target, or child prim).
4. If adding transforms, update xformOpOrder to match your new ops.
5. 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: def creates, over modifies, class defines a reusable template.

Properties

Attributes store typed data; relationships (rel) 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 </Root/Child> or </Root/Mat.outputs:surface>.

List Editing

USD list ops (prepend, append, delete, add) modify lists without replacing them.

Variants

Variant sets provide alternative content branches for a prim.

Time Samples

Animated or time-varying data stored in timeSamples dictionaries.

Reference Tables

Reference	When to Use
usd-syntax	When you need a refresher on .usda syntax, values, and path formats.
prims-properties	When adding or editing prims, attributes, or relationships.
composition-variants	When touching sublayers, references, payloads, or variant sets.
transforms-units	When editing transforms, xformOps, or stage units/up axis metadata.
time-samples	When modifying animated/time-sampled properties.
command-line-tools	When you need a quick reference for common USD command-line tools.
usdcat	When converting, flattening, or inspecting USD files.
usdchecker	When validating USD or USDZ assets, including RealityKit-focused checks.
usdrecord	When rendering images from USD files.
usdtree	When inspecting the prim hierarchy of a USD file.
usdzip	When creating or inspecting USDZ packages.
usdedit	When you need the official text-editing workflow for a USD-readable file.

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 def when you only need an over.
• Keep xformOpOrder consistent with the ops you add or remove.
• Verify SdfPath targets exist and match the expected property type.
• Avoid editing composition arcs unless explicitly requested.
• Preserve existing formatting and comments to minimize diff noise.