Omniverse Usd Performance Tuning

OpenAIOfficialCreated by NVIDIA OmniverseDistributed by OpenAI

Skill
Workflow
Software development
Apache-2.0
Medium risk
Has scripts

From the author

Top-level workflow skill for USD performance diagnosis and optimization. Use for slow loading, high memory, low FPS, or 'optimize my scene' requests; delegates auth/runtime setup to Phase 0 owners.

— the description by NVIDIA Omniverse

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The omniverse-usd-performance-tuning skill provides a structured, end-to-end procedure for addressing performance bottlenecks in USD assets. It manages the lifecycle of performance tuning, from initial runtime context setup and baseline profiling to composition auditing, validation, and targeted scene optimization. The skill enforces a rigorous milestone-based approach, ensuring that all destructive operations are planned and approved, and that performance improvements are verified through comparative profiling and standardized reporting.

What it does

Orchestrates the end-to-end USD performance tuning lifecycle.
Validates runtime environments and handles authentication for remote assets.
Conducts composition audits and structural assessments of USD stages.
Executes validated optimization operations using Scene Optimizer.
Generates structured optimization reports comparing baseline and post-optimization metrics.
Enforces safety gates for destructive operations and mutation.

When to use it

When a USD scene exhibits slow loading times or low frame rates.
When memory usage is excessively high or GPU crashes occur.
When you need to optimize a scene for better interactivity or performance.
When you need to diagnose CAD conversion quality issues.
When you need to validate a scene before and after applying optimizations.

Advantages

Ensures consistent performance diagnosis through a standardized workflow.
Prevents accidental data loss by requiring approval for destructive operations.
Provides clear, evidence-based reporting on performance improvements.
Integrates seamlessly with existing Omniverse validation and optimization tools.
Maintains strict separation between diagnosis, planning, and execution phases.

Usage examples

“This USD scene loads very slowly; please triage what I should check first.”: The agent will initiate the runtime context gate, perform a composition audit, and provide a structured plan to identify the source of the slow load time.
“Optimize my CAD scene for better performance.”: The agent will verify the runtime, assess the CAD conversion quality, and propose a milestone-based optimization plan including validation and profiling.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/openai/omniverse-usd-performance-tuning/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip omniverse-usd-performance-tuning.zip -d .agents/skills

Documentation by NVIDIA Omniverse

Omniverse USD Performance Tuning

When to Use

Use this workflow for broad performance asks such as slow loading, high memory, low FPS, GPU crashes, conversion-quality triage, or generic requests to optimize a USD scene.

Instructions

Start from the mandatory runtime context gate before producing tuning output, unless the prompt is only asking for a static classification test.
Classify broad optimization requests as ready_to_plan; reserve approval_required for prompts that explicitly name a destructive operation to execute before planning.
Plan the full canonical chain through optimization-report, preserving the structured milestone order and the profile-stage:baseline / profile-stage:after labels when listing milestones.
Invoke downstream skill bodies only when their phase is reached, and keep raw runtime artifacts on disk while reading compact summaries.

Frontmatter keeps version and tools at top level for agentskills.io runtime compatibility. NVCARPS discoverability fields live under metadata.

Output Format

Return a plan or status summary that names the selected entry skill, uses ready_to_plan for generic optimization requests, includes the full milestone chain through optimization-report, and labels profile phases as profile-stage:baseline and profile-stage:after. For structured outputs, the broad-optimization milestone subsequence is omniverse-usd-performance-tuning -> profile-stage:baseline -> usd-structure-assessment -> usd-validation-runner -> restructure-decision -> apply-restructure -> so-run-validators -> so-interpret-validators -> so-run-operations -> profile-stage:after -> compare-profiles -> optimization-report. End-to-end execution should produce an optimized stage when mutation runs and a report conforming to the optimization-report reference's schema (scripts/optimization-report.schema.json within that reference).

Use this workflow for broad performance asks such as slow loading, low FPS, high memory, GPU crashes, conversion quality, or "optimize my scene."

Entry skill rule

This skill is the named entry point for broad performance work whenever the agent has any verified way to do that work. Runtime probing details live in setup-usd-performance-tuning; this rule only decides which skill owns the user-facing performance request.

If the setup probe shows any verified runtime path - Kit, standalone, or even a partial stack such as Asset Validator only - enter here. If the user's requested tool is missing, return the specific blocked_code (blocked_missing_scene_optimizer, blocked_missing_so_operation, etc.) instead of substituting another workflow.
Enter at setup-usd-performance-tuning only when no runtime path is verified and runtime choice/setup is the first unresolved problem.
For omniverse:// assets, enter at omniverse-authentication first. Authentication precedes setup and triage for remote assets.

The decision is about ownership, not order. Setup, authentication, and triage all run in their normal phase order; this rule only fixes which skill the agent names as the entry skill in its response.

Runtime context — session-start gate (mandatory)

Before any other tuning output, follow the mandatory session-start gate in skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md. That reference owns output_path, the canonical setup-preflight.json location, Format A/Format B, and the "do not improvise a silent probe" anti-pattern.

Required outcomes:

Missing or unreadable preflight: invoke setup-usd-performance-tuning.
Present preflight: print Format A and wait for the user to choose Continue, Change Kit, Switch to standalone, or Re-run probe.
Confirmed runtime in the same session: use compact Format B for follow-up status.

[Kit: {runtime_context.kit.application} {runtime_context.kit.version}  |  SO: {runtime_context.sceneOptimizer.version}  |  AV: {runtime_context.assetValidator.version}]

Runtime artifact token budget

Before reading Kit logs, Asset Validator CSVs, Scene Optimizer logs, Tracy CSVs, or other runtime output, follow references/runtime-artifact-token-budget.md. Keep raw artifacts on disk, read summary JSON first, and use bounded log snapshots instead of full dumps or live streams.

Plan-time vs execution-time approval

approval_required at planning time is reserved for requests that explicitly name a destructive operation. Use the following rule when deciding between ready_to_plan and approval_required:

approval_required at planning time — the user's request itself names a destructive operation: "flatten this stage", "decimate the meshes", "merge prototypes", "delete unused prims", or any specific named mutation that cannot be undone within the same workflow. In this case the agent's first response must be an approval prompt that names the operation, before the agent commits to a plan that executes it.
ready_to_plan at planning time — the user's request is general: "optimize this scene", "make it load faster", "reduce GPU memory", "improve interactivity". The agent lays out the full plan, including any destructive operations the plan would invoke (for example so-run-operations with mergeMaterials), without withholding the plan itself. Approval for each destructive operation is requested alongside plan approval.

The distinction is between authorising a plan and authorising a destructive action. A general optimisation request authorises planning; it does not authorise execution of specific destructive operations.

For structured runtime-test responses and similar planning summaries:

A future restructure-decision prompt is a planned user-decision gate, not a reason to set the top-level response decision to approval_required for a generic optimization request.
For a generic optimization request, set decision: "ready_to_plan" and include the full intended chain in both committed_milestones and planned_phases, through optimization-report.
It is valid for gates_observed to include asks_user_for_restructure_decision while the top-level decision remains ready_to_plan.
Whenever a chain names profile phases, use the exact labels profile-stage:baseline and profile-stage:after; do not emit the ambiguous bare profile-stage token.
Start structured milestone lists with omniverse-usd-performance-tuning as the owning entry skill. Include setup-usd-performance-tuning only as additional Phase 0 context, not as a replacement for the entry skill milestone.
For broad optimization requests, preserve the milestone subsequence from Output Format above exactly, with optional extra analysis steps inserted only where they do not reorder it.
Do not list so-run-validators or so-interpret-validators before restructure-decision in broad optimization milestone summaries. Phase-aware validator routing still happens through usd-validation-runner; the SO validator executor/interpreter milestones appear after the restructure decision path in the structured plan contract.

Output expectation

End-to-end optimization work should produce both an optimized USD stage, when mutation is executed, and a structured optimization report conforming to the optimization-report reference's scripts/optimization-report.schema.json. The HTML report must be rendered from references/report-templates/optimization-report.html.template via render_preview.py — never hand-write HTML. Diagnosis-only work should still end with a report or summary that states no optimized stage was written.

Purpose

Route digital twin USD performance requests into the right diagnostic and optimization workflow while preserving evidence before mutation.

Prerequisites

Stage path or enough context to identify the target asset.
User goal: diagnosis only, validation, profiling, or processor execution.
Runtime availability status from setup-usd-performance-tuning when not already known.
Permission status for in-place mutation vs writing a separate optimized output.

Examples

"This USD loads slowly; triage what to check first."
"Route a low-FPS CAD scene through the performance workflow."

Triage order

Runtime gate. Follow the mandatory session-start gate above before validation, profiling, or optimization. Do not scan, probe, install, or pick Kit/standalone runtimes directly in this skill; setup-usd-performance-tuning owns probe/chooser/install dispatch and writes the preflight consumed here.
Identify the target problem:
- Load time.
- FPS or interactivity.
- GPU or system memory.
- Crash or device lost.
- CAD conversion quality.
- Validation failure.
Gather minimum context:
- Stage path and size.
- Whether the stage is local, mounted, or omniverse:// remote. For remote assets, route through omniverse-authentication before first open.
- Kit or USD runtime.
- Whether the workload is CAD, VFI, AIF, Isaac, or generic OpenUSD.
- Whether in-place mutation is allowed.
- Whether the user wants diagnosis only or processor execution.
Route:
- USD composition questions: usd-structure-assessment (composition is now part of the SA umbrella; deeper detail in skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/composition-audit.md).
- Validation and content issues: usd-validation-runner (master router; routes to validate-* family or so-run-validators based on intent).
- Edit/output decisions: usd-edit-target-planner (also owns variant/payload gates).
- Repeated copied hierarchy or high mesh count with no instancing: usd-hierarchy-dedupe-candidates.
- Restructure decision (monolithic stage, asset boundary materialization): restructure-decision.
- CAD converter settings: read references/cad-conversion/README.md (niche pre-USD concern; see reference for details).
- Scene Optimizer: so-run-validators, so-interpret-validators, so-run-operations.

Optimization ordering

Follow the canonical ordering in workflow.md § Operation ordering invariants. The high-level rule: prototypes first → per-asset validation → stage-level operations last. The workflow reference owns the full invariant list (meshCleanup before decimateMeshes, deduplication before decimation, never merge if instanced, etc.) and the analysis-only ops catalogue.

Rules

Always run composition audit before mutation.
Always validate before and after processor execution.
Optimize prototypes before per-asset validation.
Do not run whole-stage mesh deduplication on very large CAD scenes before checking for hierarchy-level reuse.
Do not recommend a fixed optimization stack without bottleneck evidence.
Do not invent numeric thresholds or expected percentage wins.
Prefer canonical SO ops over specialty / documentary ones. The op curation in references/operations/_curation.json classifies every op as canonical, specialty, analysis, documentary, or deprecated. When more than one op could resolve the same finding, recommend the canonical one first and only reach for a specialty op when the user explicitly asks or the rationale warrants it. Specifically:
- For vertex welding, prefer canonical meshCleanup with explicit flags over the standalone mergeVertices op. The standalone op is a legacy/specialty surface; use upstream usd-optimize for the operation mechanics and local approval policy before mutating.
- For hierarchy dedupe, recommend usd-hierarchy-dedupe-candidates + apply-restructure (the USD-authored rewrite path).
- For per-mesh dedupe, recommend deduplicateGeometry (canonical) over findCoincidingGeometry (analysis — produces a report, not a change).
- Do not recommend documentary-status ops (e.g., boxClip, deletePrims, removeAttributes, removeUntypedPrims, merge outside its narrow non-instanced case) without an explicit user request. Documentary ops survive in the per-op references/operations/<key>.md routing stubs for completeness but are excluded from agent-initiated recommendations.
- Specialty ≠ documentary. Ops classified as specialty in _curation.json either (a) have validator-finding evidence that wires them into the so-interpret-validators chain (e.g. sparseMeshes, optimizePrimvars), or (b) are load-bearing escape hatches needed for specific downstream contexts (e.g. primitivesToMeshes when output must be UsdGeomMesh, utilityFunction for instancing toggles and material rebinding, pythonScript for so-create-proxy recipes). Recommend specialty ops when their validator fires OR when their downstream context applies — the suppression above only targets documentary ops.

Limitations

Does not replace downstream reference instructions; load each required reference before executing it.
Does not install runtimes directly; follow setup or install references when requirements are missing.
Does not authorize mutation when the user has not allowed writes.

Troubleshooting

If runtime status is unclear, run setup-usd-performance-tuning before profiling or validation.
If the reported problem is vague, gather stage path, workload type, and whether diagnosis or execution is requested.
If the workflow suggests mutation before evidence, return to baseline profiling and composition audit first.

References

Before routing, read:

skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/optimization-tradeoffs.md — identify which pipeline phase the scene is in (extraction, structuring, or optimization). The right action depends on the phase.
skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/factory-level-structuring.md — understand the three pillars (assets, aggregation, animation) and the seven-step structuring pattern.

If you have network access, prefer the live URLs (noted in each reference file) for the most current version.

Required execution flow

Read references/workflow.md for the canonical Phase 0-7 flow, including Kit/standalone branches, validator-stack routing, operation ordering, termination conditions, duration hints, and the optional iteration pattern. The compact root map at references/skill-map.md only routes agents into this workflow.

Do not treat downstream phase names as plain checklist labels. Before executing each step, load that phase's nested README.md reference and follow its instructions. Claude Code only exposes the public catalog skill; it does not recursively inject profile-stage, usd-structure-assessment, or other nested references.

The final deliverable must come from optimization-report: save both the structured JSON report and the generated Markdown summary. Do not substitute an ad hoc SUMMARY.md or chat-only recap for the optimization report.

For deeper subtopic guidance, consult the references:

skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/composition-audit.md, skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/layer-health.md - subtopic detail for SA's Phase 1 checklist.
skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/instancing-readiness/references/instancing-tradeoffs.md - merge safety, decision tree for instancing choices.
skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-edit-target-planner/references/variants-payloads.md - deeper variant/payload trade-offs (gates are inline in usd-edit-target-planner).
references/cad-conversion/README.md - CAD converter settings.
references/upstreams/usd-optimize.md - upstream SO mechanics and prebuilt package resolution.
skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-run-validators/references/infrastructure.md - local handoff for SO validator infrastructure.
skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/validation-scoping.md - tier 1/2/3 plan + scene-aware adjustment.
skills/omniverse-usd-performance-tuning/references/optimization-report/references/optimization-report-template.md - the data contract every phase populates.

For full Kit runtime profiling (FPS, frame time, Hydra/RTX metrics), refer to the external profiling skills at NVIDIA/omniperf.

Files

references/workflow.md

USD Performance Tuning Workflow

Canonical phase choreography for the omniverse-usd-performance-tuning entry skill. Each downstream skill body remains authoritative for how to execute its phase.

Read me first - JIT-loading directive

Read this workflow after the compact references/skill-map.md routes an optimization request here. Do NOT pre-read every skill or every reference.

Read a downstream nested reference only when you reach that phase.
Read a references/*.md ONLY when this workflow or a phase guidance directs you to.
The phase guidance below contains enough inline detail that you can start each phase without opening anything else.

The one exception: read optimization-report/references/optimization-report-template.md next, before starting Phase 0. It tells you which fields you must populate by end-of-flow so each phase can collect against the final data contract.

Reference-reading policy

Each references/*.md file starts with a header block:

If it has a Canonical URL, prefer the live URL when network access is available (the local copy is a snapshot).

The 7-phase canonical flow

Seven required phases (0-6) plus an optional Phase 7 (post-report iteration).

For structured milestone lists, preserve this broad-optimization subsequence: omniverse-usd-performance-tuning -> profile-stage:baseline -> usd-structure-assessment -> usd-validation-runner -> restructure-decision -> apply-restructure -> so-run-validators -> so-interpret-validators -> so-run-operations -> profile-stage:after -> compare-profiles -> optimization-report. Additional analysis skills may appear between these milestones only when they do not reorder the subsequence.

flowchart TD
  P0["Phase 0 Bring-up<br/>setup + auth"]
  P1["Phase 1 Open and characterize<br/>profile baseline + SA"]
  P2["Phase 2 Composition + discovery + restructure decision"]
  P3["Phase 3 Stage-level instancing"]
  P4["Phase 4 Per-sub-asset mesh ops"]
  P5["Phase 5 Stage-level ref replacement and cleanup"]
  P6["Phase 6 Verify and report"]
  P7["Phase 7 Optional iteration"]
  P0 --> P1 --> P2
  P2 -->|"already_optimized"| P6
  P2 -->|"exit"| P6
  P2 -->|"optimize-as-is"| P3
  P2 -->|"extract-as-assets / decompose"| P3
  P3 --> P4 --> P5 --> P6
  P6 --> P7
  P7 -->|"iterate"| P2
  P7 -->|"done"| End["Final report"]

Phase 0 - Bring-up (runtime gate + auth)

Owner: setup-usd-performance-tuning; omniverse-authentication (only for omniverse://); install-* are downstream tools.

Do not duplicate the setup chooser here. Phase 0 means:

Run the mandatory session-start gate from setup-usd-performance-tuning/references/runtime-context-header.md.
If preflight is missing or the user changes runtime, invoke setup-usd-performance-tuning. That skill owns Kit vs standalone choice, install dispatch, version capture, and setup-preflight.json.
If the target is omniverse://, invoke omniverse-authentication before the first remote probe, open, validation, profile, or operation.
Hand the resulting runtime_context and operationsAvailable list to later phases.

Phase 0 must complete before any other phase. The runtime choice changes how Phases 1a (profiling), 2c (validator commands), and 4 (op execution) execute. Other phases are runtime-agnostic.

SO unavailable outcomes

If the user explicitly asked to run Scene Optimizer operations and the selected runtime cannot load Scene Optimizer, stop with blocked_missing_scene_optimizer. If Scene Optimizer is present but a requested op key is absent from operationsAvailable, stop with blocked_missing_so_operation. Do not silently substitute structural-only work for a direct SO execution request.

For broad optimization requests, if setup finds Kit without the SO extension or standalone Python without a loadable SO library, and the user declines install dispatch, the flow may continue in structural-only mode:

Phase 1 runs as normal (SA + profile-stage quick-or-full).
Phase 2a/2b/2d run as normal.
Phase 2c runs the pre-mutation USD stack only (no SO perf rules - they require SO).
Phase 2e: restructure-decision may still ask. apply-restructure needs a USD Python runtime for the hierarchy rewrite path. If USD Python is unavailable, extract-as-assets and decompose-for-selective-loading are effectively unavailable — offer deduplicate-internally, optimize-as-is, or exit instead.
Phase 3 still works (instancing-readiness is pure USD); flips can be authored.
Phase 4 SKIPPED (mesh ops require SO).
Phase 5 SKIPPED (no optimized children to remap).
Phase 6: profile-stage AFTER + usd-validation-runner re-validation (pre-mutation USD stack only) + optimization-report with verdict structural-only and a clear note explaining that SO operations did not run.

This is the path E2E test scenarios commonly hit.

Phase 1 - Open and characterize the asset (two data channels)

Owner: profile-stage (1a) + usd-structure-assessment (1b). Both run; order does not matter (sequential is fine - the agent does NOT need to spawn parallel processes).

1a  profile-stage:baseline        (runtime metrics)
       Kit:        full mode - stage open time, VRAM, FPS, frame time (Tracy-backed)
       standalone: quick mode - stage open time only (no FPS, no VRAM)

1b  usd-structure-assessment       (structural analysis - one umbrella)
       Same skill body in both runtimes. Produces ~25 facts including
       prim/mesh/material counts + phase_recommendation
       (structuring | optimization | already_optimized) + validation_scope
       + asset_boundary_suggestions + asset_physical_context.
       In Kit, the agent may augment with SO analysis ops (printStats, etc.
       from references/operations/README.md) for finer-grained stats - this is
       not a separate phase step.

Populate the baseline portion of optimization-report/references/optimization-report-template.md from 1a + 1b before moving on. When returning structured plans or runtime-test milestone lists, label this phase exactly profile-stage:baseline.

Phase 2 - Composition, discovery, and restructure decision

Five steps (2a-2d) feeding the gate at 2e, plus optional 2f if the user chooses restructure.

2a  Composition structure analysis    (USE: usd-structure-assessment Phase 1.1-1.3 output)
       Classify: monolithic-needs-restructure | monolithic-fine-as-is | composed-and-how
       Identify explicit prototypes/scopes that can be targeted separately.

2b  Asset boundary inference          (USE: usd-hierarchy-dedupe-candidates + SA §2.7)
       Run hierarchy hashing for monolithic stages. Output is double-purpose:
       - Where to draw asset boundaries if we restructure
       - Stage-level instancing effectiveness signal
       SA's asset_boundary_suggestions field already promotes hash-aligned
       cut points.

2c  Phase-aware preliminary validator sweep   (USE: usd-validation-runner)
       Validation-runner loads `usd-validation-runner/references/validation-scoping.md` for tier
       selection. Subset is driven by SA's phase_recommendation (see
       Decision Tree in that reference for the full rules).
       Output: a "findings corpus" that informs 2e and Phase 4 op selection.

2d  Stage-level instancing assessment   (USE: dedupe-candidates output from 2b)
       For composed stages: are existing references actually instanceable?
       For monolithic stages: how much repeated content is there, and how much
       leverage would instancing give us?

2e  Restructure decision GATE              (USER-CONFIRM)
       Owner: restructure-decision
       Inputs: SA classification (2a), boundary signal (2b), validator
       findings (2c), instancing assessment (2d).
       Branches:
         - monolithic & restructure recommended & dedupe candidates -> ASK USER:
              deduplicate-internally (SO deduplicateHierarchies)
              / extract-as-assets (apply-restructure external prototypes)
              / optimize-as-is / exit
         - monolithic & restructure recommended & no dedupe -> ASK USER:
              decompose-for-selective-loading | optimize-as-is | exit
         - monolithic & fine as-is             -> continue (no restructure)
         - monolithic & fine as-is + payload_count=0 + clear boundaries
              -> ASK USER:
              decompose-for-selective-loading / optimize-as-is / exit
         - composed                            -> continue (assess existing
                                                  instancing per Phase 3)
         - already_optimized                   -> jump to Phase 6 verify

2f  If extract-as-assets or decompose-for-selective-loading chosen
                                              (USE: apply-restructure mode=restructure)
       Orchestrates USD-authored hierarchy rewrite + asset-boundary
       materialization (writes prototype USDs to disk, rewrites refs to point
       at them). Backend: pxr/Sdf Python. See usd-structure-assessment/references/apply-restructure/README.md
       Workflow - mode=restructure.
       Output: restructured stage ready for Phase 3.

    If deduplicate-internally chosen → skip Phase 2f. Stage stays monolithic.
       Phase 4 includes SO deduplicateHierarchies in the op chain.

Phase 3 - Stage-level scene-graph instancing

Owner: instancing-readiness (per-candidate gate); usd-edit-target-planner (where to author the flips, includes absorbed variant/payload gates).

3a  Enumerate instancing candidates:
       - For composed stages: existing references identified in 2a/2b
       - For restructured stages: the new prototype/reference structure from 2f
       - For monolithic-fine-as-is: any explicit instances or prototypes from 2a

3b  For each candidate:
       Run instancing-readiness gate:
         safe                -> mark instanceable=true
         overrides_found     -> skip (would create unnecessary prototype)
         variant_divergence  -> skip or escalate

3c  Choose edit target for the flips      (USE: usd-edit-target-planner)
       Override layer | per-asset edit | processor output | source repair
       Variant/payload gates are inline in the planner.
       For merge safety questions, see `usd-structure-assessment/references/instancing-readiness/references/instancing-tradeoffs.md`.

Phase 4 - Per-sub-asset mesh-level optimization

Owner: so-interpret-validators (build op chain from Phase 2c findings; T3 never auto-included) -> so-run-operations (single-asset driver; agent orchestrates per-target invocation per the "Agent-orchestrated batch mode" section in that skill body; adaptive concurrency by resource budget; prototype-first ordering).

4a  Enumerate optimization targets (1..N):
       - After restructure: each new prototype, shared layer, or loadable
         sub-asset from Phase 2f's `apply-restructure-manifest.json`
         `phase4_targets[]`, PLUS the remaining assembly root itself (it
         may still contain mesh data — ground planes, shared environment
         geometry, non-extracted sub-hierarchies). If the assembly root has
         0 mesh prims after extraction (pure Xform/reference hierarchy),
         skip it but log the skip decision.
       - Composed stage:    each referenced asset from Phase 2a
       - Monolithic-as-is:  the monolith itself (N=1)

4b  Adaptive parallelism (agent-orchestrated; not a driver flag):
       - Do not serialize independent targets by default.
       - Group targets by dependency: shared prototypes/layers first,
         then dependent non-prototype targets.
       - Choose initial concurrency from target weight and system resources
         (file size, mesh/vertex/material counts, op-chain cost, CPU/RAM/VRAM,
         disk and log headroom).
       - Run a pilot batch, inspect resource pressure and failures, then
         increase/decrease concurrency for the next batch.
       - Pause and offer a remainder script only when observed runtime/resource
         budget says continuing automatically is unsafe.

4c  Per-target op chain (built from Phase 2c findings via so-interpret-validators):
       Honor prototype-first ordering: prototypes BEFORE non-prototype targets
       so changes propagate.
       **Internal geometry removal runs FIRST** when SA flagged containment
       pairs with opaque enclosures:
         findOccludedMeshes (analysis) → removePrims (user-confirmed deletion)
       Then select remaining operations from so-interpret-validators findings.
       Use so-run-operations/references/config-from-evidence.md for
       evidence-to-config routing and
       so-run-operations/references/operation-safety.md for confirmation
       policy before mutation.
       Prefer meshCleanup for vertex welding; reach for standalone
       mergeVertices only when the user explicitly needs that
       upstream-documented behavior (see pipelines.md
       "mergeVertices op vs meshCleanup.mergeVertices parameter").
       Honor ordering invariants from
       so-run-operations/references/pipelines.md (merge caveats: never if
       instanced/streaming).
       Save each optimized output to a NEW path (don't overwrite source).

4d  Per-target cheap re-verify
       Re-run cheap validators on each optimized output to catch obvious
       regressions before stage assembly. Defers full re-validation to Phase 6.
       After restructure/decompose, follow the "Post-Restructure Validation
       Strategy" in validation-scoping.md — do not re-compose and sweep.

Runtime branch:
  Kit:        ops run via selected SO Python API inside Kit
  standalone: ops run via selected SO Python API or standalone wrapper
  All Python scripts probe the selected runtime first; do not assume
  `SceneOptimizerCore.getInstance()` when the runtime exposes only
  `acquire_interface().execute_operation(...)`.

Phase 4.5 - Layer cleanup after destructive in-place ops

Follow usd-structure-assessment/references/usd-edit-target-planner/references/output-saving.md. After destructive SO edits, write cleaned layers with Sdf.Layer.Export(<cleaned_path>), then update the new root's sublayers/references to point at those cleaned paths.

Do not use stage.Export() here unless the user explicitly wants a flattened deliverable. This cleanup step re-emits individual layers.

The disk-size deltas reported in Phase 6 are only meaningful after this cleanup pass.

Phase 5 - Stage-level reference replacement and cleanup

Owner: apply-restructure (mode=ref_remap). Same skill as Phase 2f - both phases are USD ref-rewriting. See usd-structure-assessment/references/apply-restructure/README.md Workflow - mode=ref_remap (Phase 5).

5a  Compute the impact set:
       For each optimized sub-asset from Phase 4, find every parent assembly
       that references it (recursively up the composition graph until reaching
       a stage root).

5b  Recursively copy and rewrite:
       For each parent assembly in the impact set, copy to a new path and
       rewrite its references to point at the optimized children. Repeat
       up the chain until the root stage has an optimized variant.

5c  Stage-level cleanup ops (now safe - references are stable):
       computeExtents, residual deduplicateGeometry on remaining unique
       content, final pruneLeaves, removePrims of nothing-references.

5d  Output: an "optimized stage root" path the user can open and verify.

Phase 6 - Verify and report

6a  profile-stage:after (same mode as baseline)

6b  Re-validate via usd-validation-runner (using the same scoping that ran in
    Phase 2c so the comparison is fair).

6c  compare-profiles                                  (verdict: improved | neutral | regressed | mixed)
       If regressed > 5%:    warn
       If regressed > 20%:   critical, recommend revert/halt

6e  optimization-report (final step of in-flow phases; honors the skill's
    existing "final step" contract).
       Populate against the optimization-report schema (`scripts/optimization-report.schema.json` within that reference). Match
       optimization-report/references/optimization-report-template.md. Include baseline metrics
       (Phase 1a/1b), after metrics (Phase 6a), all operations performed
       (Phase 4 + Phase 5), all validator findings (Phase 2c + Phase 6b),
       output_path = optimized stage root from 5d.

When returning structured plans or runtime-test milestone lists, label Phase 6a exactly profile-stage:after.

Phase 7 - Iterate (optional, post-report, agent-orchestration only)

7a  Compute "untapped options" - the diff between what was done and what could
    have been done. Examples:
       - Lossy operations (decimateMeshes, mergeVertices) skipped this pass
       - Tier 3 cross-component perf validators not run
       - Aggressive merge held back due to instancing concerns
       - Restructure declined at Phase 2e
       - Phase 4 adaptive batching paused remaining sub-assets due to resource
         budget; remainder script generated

7b  Offer to user (freeform, agent discretion):
       "Optimization complete. Verdict: <verdict>. The following were not
        applied this pass: [list]. Want to run another iteration with any
        of these enabled, or with adjusted parameters?"

7c  If user accepts iteration:
       Loop back to the relevant phase (typically Phase 2c with adjusted
       validator subset, or Phase 4 with new ops in the chain). Keep the
       baseline metrics from the FIRST pass (don't re-baseline).

7d  If user declines:
       Flow truly ends. The Phase 6e report stands as the final deliverable.

Phase 7 is optional. Always compute the "untapped options" list for transparency in the report (so the user can see what was held back even if they don't iterate). Use discretion on whether to actively offer iteration: do not nag if the user asked for "quick pass."

Validator-stack matrix

The usd-validation-runner skill is the master router. For tier 1/2/3 detail, JSON plan template, and scene-aware adjustment rules, read usd-validation-runner/references/validation-scoping.md.

Pre-Mutation USD Stack

Owned by usd-validation-runner. The package keeps only two local validation contracts here: the inline minimum-openability check and the validate-usd-asset-validator reference. External profile/package validators such as SimReady are deliberately outside this package and should be invoked only through their owning workflow when the user explicitly asks for them.

Performance stack (scoped)

(read usd-validation-runner/references/validation-scoping.md) -> so-run-validators -> so-interpret-validators.

Phase-aware subset

Owned by usd-validation-runner/references/validation-scoping.md → Decision Tree. Summary:

structuring → minimum-openability + targeted AV blockers only.
optimization → minimum-openability + scoped AV + perf stack (Tier 1+2; Tier 3 only on flagged targets).
already_optimized → minimum-openability + scoped AV + perf Tier 1 only.

Operation ordering invariants

These are local workflow-ordering invariants. Scene Optimizer operation mechanics, parameters, and defaults live upstream in usd-optimize; resolve the checkout through references/upstreams/usd-optimize.md.

findOccludedMeshes + removePrims FIRST — remove internal geometry before spending compute on anything else. Why clean, dedupe, or decimate meshes you're about to delete?
findOccludedMeshes + removePrims BEFORE meshCleanup.
findOccludedMeshes + removePrims BEFORE deduplicateGeometry.
Structure and hierarchy rewrites complete before mesh-level optimization; use usd-hierarchy-dedupe-candidates + apply-restructure before mesh-level deduplicateGeometry.
meshCleanup BEFORE decimateMeshes.
deduplicateGeometry BEFORE decimateMeshes.
generateNormals BEFORE meshCleanup only when normals are missing or invalid; otherwise skip — never overwrite user-authored normals.
data-quality-baseline first when validators report mesh-quality issues.
Never merge if scenegraph-instanced / point-instanced / streaming geometry is in play.
Deinstance/Flatten Instances BEFORE merge.
Set Instanceable AFTER reference-heavy authoring.
removePrims BEFORE pruneLeaves.
Common chain: fitPrimitives -> deduplicateGeometry -> organizePrototypes.
Prototype targets run before non-prototype targets; parallelize within each dependency group when resource budget allows.
Bounded-loss or destructive operations run only after operation-safety.md confirmation.
Per-operation argument defaults and caveats come from upstream usd-optimize operation docs.

Phase 4 prototype-first rule: optimize prototypes BEFORE non-prototype targets in the same batch so changes propagate to instances.

Analysis-only ops

The SO ops listed below produce reports but do not mutate the stage. They are not invoked by any named pipeline — agents reach for them on user request or as part of bespoke triage:

rtxMeshCount — RTX bucket counter; reports how many meshes fall into each RTX size bucket. Useful when the validator's RtxMeshCount rule fires and you need a breakdown before deciding between removeSmallGeometry, decimateMeshes, and merge.
sparseMeshes — exposes meshes with very low per-face vertex density; often a sign of poor authoring or failed import. Outside the default flow but useful when investigating draw-call counts.
utilityFunction — meta-utility op for ad-hoc SO scripting; rarely the right tool but available when one of the recipe skills needs it. See references/operations/utilityFunction.md.

For lossless coincidence/occlusion analyzers (findCoincidingGeometry, findFlatHierarchies, findOverlappingMeshes), prefer running them through so-interpret-validators once that skill wires them in (currently future-candidate per _curation.json).

findOccludedMeshes is now wired into the Phase 4 op chain via config-from-evidence.md — it runs first (before all other ops) on SA-flagged containment pairs with opaque enclosures, followed by removePrims for user-confirmed deletion of discovered internals.

Termination conditions

When	Outcome
Phase 0: direct SO execution requested but SO unavailable	Halt with `blocked_missing_scene_optimizer`; do not substitute another workflow.
Phase 0: requested SO op absent from the loaded runtime	Halt with `blocked_missing_so_operation`; surface supported alternatives if any.
Phase 0: broad optimization request, SO unavailable, and user declines install	Switch to structural-only path. Skip Phases 4-5; report `structural-only` in 6e.
Phase 0: User chooses "exit" at install prompt	Exit with reason "user declined runtime setup".
Phase 1a: profile-stage fails to open the asset	Halt with diagnostic; the asset cannot be optimized if it cannot be opened.
Phase 2c: SA's `phase_recommendation = already_optimized`	Skip Phases 2d-5; jump to Phase 6 verify; produce report with verdict `no-op-needed`.
Phase 2e: User chooses "exit" at restructure gate	Skip to Phase 6e and write a diagnosis-only report.
Phase 2e: User chooses "optimize as-is"	Skip Phase 2f; continue to Phase 3 with the original stage.
Phase 3b: All instancing candidates fail readiness	Skip Phase 3 result-application; continue to Phase 4. Note in report.
Phase 4d: A target's optimized output fails cheap re-verify	Discard that target's output; continue with other targets. Report failure in 6e.
Phase 6c: Verdict = regressed > 20% (critical)	Recommend revert (do not publish); user decides whether to publish anyway.
Phase 6c: Verdict = `mixed`	Report honestly; do not present as success.
Phase 6e: optimization-report writes successfully	In-flow phases end. Optional Phase 7 may follow.
Phase 7: User declines iteration	Flow truly ends. The Phase 6e report stands as the final deliverable.

Expected duration hints (typical large stages: ~100K prims, ~200K meshes)

These are guidance for setting user expectations and timeout windows, not hard SLAs.

Phase	Expected duration
Phase 0	< 1 min once user choices are recorded
Phase 1	~5 min (profile open + SA pass)
Phase 2c structural validators	~2 min
Phase 2c Tier 1 perf validators	~5 min
Phase 2c Tier 2 perf validators	~30 min
Phase 2c Tier 3 perf validators	hours - always confirm before running
Phase 4 per target	~10-30 min depending on op chain
Phase 5 ref-remap	~few min for typical impact sets
Phase 6 re-validation	same as Phase 2c

Requirements and compatibility

Written for: OpenAI Codex

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

The author says: Orchestrator skill. Downstream phases may require Kit, Scene Optimizer, Asset Validator, USD Python, writable output paths, and omniverse:// authentication selected by setup-usd-performance-tuning.

Security

What our scanner noticed· Medium risk

Large base64-encoded blobs
Instructions that use the network
Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

NVIDIA Omniverse

Publisher

OpenAI (Official)

Distributed by

OpenAI

Source

openai/plugins · plugins/nvidia/skills/omniverse-usd-performance-tuning · commit d420d13

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (written by AutoGineer)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by NVIDIA Omniverse or OpenAI.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download omniverse-usd-performance-tuning.zip