usd-editor

Original：🇺🇸 English
Translated

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

9installs
Sourcetomkrikorian/visionosagents
Added on

NPX Install

npx skill4agent add tomkrikorian/visionosagents usd-editor

Tags

Translated version includes tags in frontmatter
usda-file-editingusd-cli-toolsprim-manipulationvariant-managementxform-operations

SKILL.md Content

View Translation Comparison →

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:
  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

ReferenceWhen 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.
usdcrush
When compressing USD or USDZ assets for size.
usdextract
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 
    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.