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://mp-staging.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/usd-structure-assessment/references/restructure-decision/README.md

Restructure Decision

When to Use

Use to decide whether a monolithic USD stage should be restructured (asset-boundary materialization + hierarchy dedupe) before optimization, or optimized as-is. Asks the user; invokes apply-restructure when the user confirms.

Instructions

Confirm the target asset, artifact, or user intent and check the prerequisites listed below.
Read only the referenced files needed for the current phase, failure mode, or output contract.
Follow the workflow, rules, and safety gates in this reference before invoking downstream references or shell commands.
Return the result using the Output Format section and name any blocked prerequisite or unresolved user decision.

Pre-flight Checklist

Before presenting the restructure gate, re-read and confirm:

[ ] SA report contract — phase_recommendation, hierarchy_dedupe, asset_boundary_suggestions fields.
[ ] setup-preflight.json runtime header — know what runtime is available.
[ ] Present all three options (restructure / optimize-as-is / exit) — do not pre-select on the user's behalf.

Output Format

Return a concise status or report that names the input, selected runtime or evidence source, actions planned or performed, artifacts written, blockers, and the next validation or user-decision step. When a schema or template is referenced below, conform to that contract.

Purpose

Phase 2e of the canonical optimization flow (see skills/omniverse-usd-performance-tuning/references/workflow.md). After usd-structure-assessment has classified the asset and usd-hierarchy-dedupe-candidates has produced asset-boundary signal, this skill is the user-confirm gate that decides whether to restructure the stage before optimization.

This is a small decision-tier skill. It does not perform the rewrite - that's the execution-tier apply-restructure, which uses pxr/Sdf USD authoring to materialize boundaries and apply the hierarchy-dedupe rewrite described in skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/references/hierarchy-dedupe-rewrite-tool-spec.md.

Prerequisites

A completed usd-structure-assessment report including:
- phase_recommendation (structuring | optimization | already_optimized).
- hierarchy_dedupe.recommended and hierarchy_dedupe.top_candidates (when present).
- The §2.7 asset-boundary identification output (when the stage is monolithic).
Optional: usd-hierarchy-dedupe-candidates read-only candidate report when the stage is monolithic.
Optional: Phase 2c usd-validation-runner findings corpus (informs the decision when validators flagged structural-only issues that restructure would help with).

Examples

"Should I restructure this CAD stage before running mesh ops?"
"The factory.usd is monolithic with 12 repeated assemblies - what's next?"

Inputs

The agent assembles a decision packet from prior phases:

Input	From	Used to decide
SA classification	`usd-structure-assessment` Phase 2a	Monolithic vs composed; restructure recommended?
Asset-boundary candidates	`usd-structure-assessment` §2.7 + `usd-hierarchy-dedupe-candidates`	Where the cut points are if restructure is chosen
Validator findings	Phase 2c `usd-validation-runner` sweep	Whether structural-only fixes would be wasted on a stage about to be restructured
Instancing assessment	Phase 2d (read from SA `instancing` field)	Estimated leverage from restructure
User constraints	session context	Time budget, mutation policy, output policy

Decision branches

Compute the recommended branch from the inputs, then always present the choice to the user - do not auto-proceed.

SA classification	hierarchy_dedupe.recommended	Recommended	Branches offered
`monolithic-needs-restructure`	true	ask (see below)	deduplicate-internally / extract-as-assets / optimize-as-is / exit
`monolithic-needs-restructure`	false	decompose-for-selective-loading	decompose-for-selective-loading / optimize-as-is / exit
`monolithic-fine-as-is`	—	optimize-as-is	optimize-as-is / exit
`monolithic-fine-as-is` + `payload_count=0` + clear boundaries	—	ask	decompose-for-selective-loading / optimize-as-is / exit
`composed` (already structured)	—	continue (no Phase 2f)	continue (Phase 3) / exit
`phase_recommendation = already_optimized`	—	jump to Phase 6	jump-to-verify / continue / exit

When hierarchy_dedupe.recommended=true

Present exactly two restructure strategies (plus optimize-as-is and exit):

Deduplicate hierarchies internally — Scene Optimizer's deduplicateHierarchies creates internal references to shared prototypes within the same stage file. The referencing prims are marked instanceable=true. The stage remains monolithic (single file, no payloads). Fastest path; appropriate when selective loading is not needed.
Extract duplicate hierarchies as payloaded, instanced assets — The hierarchy-dedupe rewrite tool runs with mode: external_prototype, extracting each shared prototype as an external asset file. Each instance site references the prototype via a payload arc, making it independently loadable. This is the full restructure: the monolith becomes an assembly root + prototype assets. Appropriate when selective loading matters (large scenes, collaborative workflows, streaming).

Both strategies produce instanced prototypes. The difference is whether prototypes live inside the stage (internal references, SO handles it) or as separate files (external payloaded assets, apply-restructure handles it).

The boundary plan records:

goal: deduplicate_internally → SO's deduplicateHierarchies in Phase 4
goal: extract_as_assets → hands off to apply-restructure with dedupe.mode: external_prototype

Do NOT offer a "selective loading without instancing" option — extracting N identical subtrees as N independent files without sharing a prototype is always wrong when the hash confirms structural identity.

Selective loading (no dedupe candidates)

When hierarchy_dedupe.recommended=false but usd-structure-assessment reports payload_count: 0 and clear spatial, discipline, linked-model, category, or building-wing boundaries, present a selective-loading choice:

decompose-for-selective-loading: materialize the chosen boundary level as loadable sub-assets (payloads). Each boundary becomes its own file.
optimize-as-is: keep the monolithic delivery package and proceed to validation / SO optimization.
exit: write the diagnosis/report and stop.

If the user picks decompose-for-selective-loading, ask which candidate level from asset_boundary_suggestions.candidate_levels should be used unless the user already specified it. This path still hands off to apply-restructure; the boundary plan should record goal: selective_loading so downstream mesh ops know the split is for packaging and workflow, not for instancing.

Extract-as-assets authoring details

When the user picks extract-as-assets, the authoring recipe in restructure-mode.md §"Instanced Asset Extraction" applies:

Identical subtrees share one prototype file.
Each instance site gets a lightweight placement prim (instanceable=true) inside its payload layer.
Instancing is decided per dedupe group, not globally. Some extracted assets may be instanceable (their group passes the instancing-readiness gate) while others are extracted as unique payloads.
The boundary plan records the per-group decision.

The apply-restructure skill handles the file extraction and assembly-root rewrite. This skill (restructure-decision) only captures the user's choice.

User overrides the recommendation

When SA recommends optimize-as-is (or already_optimized) but the user picks restructure anyway, confirm the user's goal before authoring. Restructure does not improve geometry-level metrics — those land in Phase 4. What restructure actually buys:

Selective loading via payloads — split a 1 GB monolithic stage into per-floor / per-discipline payloads the user can load on demand.
Modular collaboration — separate sub-assets so multiple authors can edit in parallel without conflict.
Per-asset Phase 4 targets — Phase 4 mesh ops can run on shared prototypes once, with results propagating to all instance sites.

Ask the user which of those they want and capture it in the decision packet so Phase 4 knows whether to target prototypes or the monolith. Do not assume restructure-for-its-own-sake.

deduplicate-internally

User accepts the dedupe candidates but wants the stage to stay monolithic. Skip Phase 2f (apply-restructure). Record the choice and selected groups in the optimization plan. Phase 4 includes deduplicateHierarchies in the SO op chain (gated by operationsAvailable).

Continue to Phase 3 with the original monolithic stage.

extract-as-assets

User accepts the boundary candidates and wants external payloaded assets. Invoke apply-restructure with:

restructure_plan: the boundary cut points + dedupe candidates + dedupe.mode: external_prototype.
output_dir: where to write prototype USDs and the new assembly root.
dry_run: false (writes are executed).

apply-restructure returns a manifest of new prototype paths + the new assembly stage root path. Continue to Phase 3 with the restructured stage.

decompose-for-selective-loading

User wants selective loading boundaries without hierarchy dedup (no dedupe candidates exist in this branch). Invoke apply-restructure with:

restructure_plan: the selected boundary level + goal: selective_loading.
output_dir: where to write payload USDs and the assembly root.
dry_run: false (writes are executed).

Continue to Phase 3 with the decomposed stage.

optimize-as-is

User accepts the existing structure. Skip Phase 2f. Continue to Phase 3 (instancing) and Phase 4 (mesh ops) targeting the original stage.

exit

User declines mutation. Skip to Phase 6e and write a diagnosis-only optimization report capturing the SA + validator findings.

jump-to-verify

Used when SA's phase_recommendation = already_optimized. The agent runs Phase 6a/6b on the original stage to confirm and writes the report.

How to ask

The Phase 2e prompt commits the user to a structural decision that downstream phases cannot easily undo. The user must see exactly which Kit / Scene Optimizer / Asset Validator versions authored the assessment and will execute the restructure. Prepend the full runtime context block from skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md (Format A) before any of the analysis or choice text below. Source: the runtime_context object in <output_path>/setup-preflight.json (canonical location; see skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md Where artifacts live). If that file is missing, invoke setup-usd-performance-tuning first.

Present the recommended branch with the evidence behind it, then list the alternatives. Example:

─── Runtime context ───────────────────────────────────────────────────────
Kit application:    USD Composer 110.1.0
  path:             D:\build\chk\usd_composer-fat\110.1.0+main.…\kit
  build:            110.1.0+main.10181.f4b28ef2.gl.windows-x86_64.release
Scene Optimizer:    omni.scene.optimizer.core 110.0.4
Asset Validator:    omniverse-asset-validator 1.x.y via kit-extension
───────────────────────────────────────────────────────────────────────────

The asset analysis shows:
  - 1 monolithic root layer, 0 references, 0 prototypes.
  - 4 repeated assembly patterns detected (suggesting 4 candidate prototypes
    saving an estimated 47% of prims).
  - 8 of the 12 Tier 2 validator failures will be invalidated by restructuring
    (geometry that's about to be replaced).

Recommended: extract as payloaded, instanced assets. This will:
  - Materialize 4 prototype USDs to <output_dir>/prototypes/
  - Rewrite the root assembly to reference them
  - Run subsequent mesh ops on the prototypes (changes propagate)

Alternatives:
  - optimize-as-is: skip restructure, run mesh ops on the monolith. Faster
    to start but fewer downstream wins.
  - exit: write a diagnosis-only report and stop.

Which would you like?

Output

Record the user's choice in the optimization plan and emit it for downstream phases:

{
  "phase": "2e",
  "choice": "deduplicate-internally | extract-as-assets | decompose-for-selective-loading | optimize-as-is | exit | jump-to-verify",
  "recommended": "deduplicate-internally",
  "reasoning": "monolithic with 4 repeated patterns; restructure recommended",
  "boundary_plan_ref": "<path to plan packet for apply-restructure>",
  "user_confirmed_at": "<ISO 8601 timestamp>"
}

Rules

Always present the choice; do not auto-proceed even when SA's recommendation is high-confidence.
Headless / batch / non-interactive contexts: If the agent cannot ask the user (e.g. running in a scripted pipeline or with no interactive session), STOP and write the decision as a blocker in the preflight or report artifact. Do NOT substitute a default choice like "optimize-as-is" on the user's behalf. The gate exists because restructure-vs-optimize-as-is has irreversible consequences that only the user can weigh. Write a restructure_decision_pending artifact and halt Phase 2e until a human confirms.
Do not recommend restructure when SA's phase_recommendation = already_optimized.
Always present the selective-loading choice when SA reports payload_count: 0 and clear asset-boundary candidates, even if hierarchy dedupe is not recommended and the asset is otherwise ready for mesh optimization.
If the user picks deduplicate-internally, skip Phase 2f (apply-restructure). The stage stays monolithic. Record the choice and continue to Phase 4 where SO's deduplicateHierarchies runs (gated by operationsAvailable).
If the user picks extract-as-assets, hand off to apply-restructure with the boundary plan and goal: extract_as_assets; do not perform writes from this reference.
If the user picks decompose-for-selective-loading, hand off to apply-restructure with the selected boundary level and goal: selective_loading; do not perform writes from this reference.
If the user picks exit, immediately go to Phase 6e (optimization-report) - do not silently continue to Phase 3.

Limitations

Decision skill only; does not write USD files.
Depends on SA's classification quality; if SA's phase_recommendation is missing, return to usd-structure-assessment rather than guessing.
Asset-boundary candidates from SA §2.7 are suggestions, not enforcement; the user can override the cut points before invoking apply-restructure.

Troubleshooting

If SA reports no candidates and the user wants to restructure anyway, ask for explicit cut points (prim paths) before invoking apply-restructure.
If validator findings (Phase 2c) say the asset has structural issues that would block restructure (e.g. unresolved references), surface them to the user before asking for a choice.
If the USD Python runtime is unavailable in the active environment, apply-restructure cannot author the rewrite. In that case extract-as-assets and decompose-for-selective-loading are effectively unavailable; tell the user clearly and offer deduplicate-internally, optimize-as-is, or exit only.

References

Read before deciding:

skills/omniverse-usd-performance-tuning/references/workflow.md - the canonical 7-phase flow context for where this gate sits.
skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/instancing-readiness/references/instancing-tradeoffs.md - merge safety and dedupe trade-offs that affect the restructure-vs-optimize-as-is call.
usd-structure-assessment/README.md §2.7 (Asset boundary identification) - the source of boundary candidates.
usd-structure-assessment/references/usd-edit-target-planner/README.md - downstream skill that places the restructure outputs into a coherent edit-target plan.

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

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

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by NVIDIA Omniverse

Omniverse USD Performance Tuning

When to Use

Instructions

Output Format

Entry skill rule

Runtime context — session-start gate (mandatory)

Runtime artifact token budget

Plan-time vs execution-time approval

Output expectation

Purpose

Prerequisites

Examples

Triage order

Optimization ordering

Rules

Limitations

Troubleshooting

References

Required execution flow

Files

references/usd-structure-assessment/references/restructure-decision/README.md

Restructure Decision

When to Use

Instructions

Pre-flight Checklist

Output Format

Purpose

Prerequisites

Examples

Inputs

Decision branches

When hierarchy_dedupe.recommended=true

Selective loading (no dedupe candidates)

Extract-as-assets authoring details

User overrides the recommendation

deduplicate-internally

extract-as-assets

decompose-for-selective-loading

optimize-as-is

exit

jump-to-verify

How to ask

Output

Rules

Limitations

Troubleshooting

References

Requirements and compatibility

Security

Attribution and licence

Related skills

Diagnosing Bugs

Systematic Debugging

Performance Optimization

Debugging And Error Recovery

Animation Performance

Parallel Debugging

Download ZIP