Omniverse Usd Performance Tuning

NVIDIAOfficialCreated by NVIDIA Omniverse

Skill
Workflow
Software development
Apache-2.0
Medium risk
Has scripts

From the author

Diagnose and optimize USD stages for slow loading, high memory, low FPS or validation; preserve asset boundaries and reuse shared definitions.

— the description by NVIDIA Omniverse

AutoGineer summary

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

This skill provides a structured workflow for diagnosing and optimizing USD stages. It focuses on improving performance metrics like load times, memory footprint, and frame rates by identifying and optimizing unique asset definitions, reusing shared definitions, and pruning unnecessary data. The process emphasizes preserving original asset boundaries, animation, and interface requirements, ensuring that downstream applications remain functional after optimization.

What it does

Inspects USD stages to identify performance bottlenecks and structural inefficiencies.
Classifies assets into atomic, package, or aggregate structures to guide optimization.
Performs native USD optimization operations on disjoint scopes.
Publishes semantic libraries to enable efficient asset reuse.
Validates composition, ownership, and interface accessibility of the optimized output.
Profiles the final output against the original baseline to report measured improvements.

When to use it

When a USD stage suffers from slow loading times or high memory consumption.
When rendering performance (FPS) needs improvement in a production environment.
Before finalizing a USD assembly for downstream consumption.
When you need to standardize asset structures according to factory-level guidelines.

Advantages

Maintains asset boundaries and critical metadata during optimization.
Reduces scene complexity through intelligent reuse of shared definitions.
Provides verifiable reports on performance gains and composition integrity.
Supports large-scale scene optimization by processing independent definition scopes.

Usage examples

“Inspect the USD stage at /data/factory.usdc for performance issues and prepare a review workspace.”: The agent initializes the workspace, runs the inspection script, and provides a summary of candidates for optimization.
“Submit the optimization decisions for the factory stage based on the generated JSON.”: The agent processes the boundary decisions, executes the optimization operations, and generates the final optimized USD assembly.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/nvidia/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

Purpose

Improve loading, memory use or rendering for the requested workload. Preserve the prim paths, appearance, placement and behavior required by downstream applications. Follow the component/subcomponent model in NVIDIA's Factory-Level USD Structuring guide. Apply the relevant parts of that model; a static asset does not need new animation or physics.

Inputs

Required: the source USD stage. When no workload is specified, use factory layout planning and visualization and record that assumption in the request/report. Explicit workload and preservation requirements take precedence. Optional: an output workspace, preservation requirements, physical error budget, existing library indexes and recorded runtime evidence. Use values from the current user request; reuse recorded values only while they remain applicable. Follow setup when no output path is supplied.

Prerequisites

Verify the selected runtime and required capabilities using setup. Keep its preflight record with the run; installation and remote access are conditional steps described there.

Instructions

Inspect. Establish the workload, preservation requirements and output workspace. Set up progress and dashboard access before assessment. Verify setup and inspect the selected source configuration.
Judge boundaries. Review equipment, service-system sections and architectural elements in the selected configuration, including animation and interiors. Record owners, editable interfaces, equipment categories and optional families using boundary guidance.
Classify and author. Classify accepted assets children before parents. Capture or reuse the original profile before authoring. Prepare reusable definitions, materials and occurrence opinions using asset authoring.
Optimize unique definitions. Run supported native operations concurrently on disjoint scopes with the recorded physical budget.
Publish semantic libraries. Use one writer per category layer and remap consumer references.
Check composition. Check authored ownership, references, bindings, placement, animation and interface accessibility through the written-output checks.
Profile and report. Compare the final consumer with the original baseline under comparable conditions and report measured benefits, completion and operations by asset definition.

sequenceDiagram
    participant A as Agent
    participant T as USD tools
    participant W as Definition workers
    participant L as Library publisher
    participant D as Read-only progress dashboard
    Note over A,L: One compact progress state also renders text progress
    T-->>D: Recorded phase, assessment rounds, counters and decision reasons
    A->>T: Inspect original selected configuration
    T->>T: Collect cached child-to-parent summaries and repetition nominations
    T->>T: Load supplied indexes once and batch authored product clues
    T-->>A: Product review groups, member context, animation and reuse evidence
    loop Until boundaries and interiors are reviewed
        A->>A: Select asset boundaries, then identify required internal prims and properties
        A->>T: Submit boundary decisions with reviewed scope, required edits, category and optional family
        T->>T: Reuse unchanged source evidence, recompute boundary-dependent results
        opt Geometry ownership requires reconstruction
            T->>T: Regroup or native split, remap paths and reassess affected regions
        end
        T-->>A: Remaining candidates and member exceptions
    end
    T->>T: Classify selected child assets before parent assets, confirm reuse
    T->>T: Capture or reuse original baseline profile
    T->>T: Confirm accepted product identities from source and supplied indexes; reconcile complete parent-child groups
    T->>T: Skip worker inputs for confirmed groups; author remaining materials, editable prims and occurrence overrides
    T->>T: Determine merge groups on prepared interiors; preserve selected child assets and required prims
    T->>W: Read-only input USD layers for existing-library matching
    par Independent preparation jobs
        W->>W: Confirm remaining product, exact source or authorized normalized reuse; preserve occurrence placement
        W->>W: Consolidate accepted product or compatible exact/normalized leaf inputs; retain every occurrence
    end
    W-->>T: Confirmed library hits and definitions requiring optimization
    T->>W: Owned geometry prim paths in read-only input layers
    par Independent definition scopes
        W->>W: Remove small meshes when authorized; apply asset representation: reserve merge inputs or fit analytic prims; reduce, merge (native clustering if required), prune, flatten, prune
    end
    W->>L: Geometry outputs and assembly authoring outcomes
    L->>L: Share eligible static whole definitions within current category publication
    L->>L: Share remaining whole meshes; write USD reuse metadata and compact index
    L->>T: Output USD stage with rewritten references and dependencies
    T->>T: Check authored composition, ownership, animation and interfaces
    T->>T: Profile final output USD stage and report results by asset definition
    T-->>A: Measured changes, coverage and unresolved work
    T-->>D: Final verdict and report/library paths

Use the provided tools for traversal, native operations, authoring and checks; the agent supplies engineering judgments. Preserve current variant selections, authored animation, required materials and interfaces. Trust supported USD Optimize operations with valid settings and scopes. Deep geometric comparisons and whole-scene edit trials belong in development tests, not ordinary execution.

Complete when every unique definition has an executed or evidenced unchanged outcome, every asset has justified ownership and structure, and the written consumer passes composition checks. Retain native failures, unresolved judgments and missing required capabilities as incomplete work. Repeat only affected work when evidence changes.

Scope and authorization

Diagnosis and validation requests remain read-only. An optimization request authorizes work in a separate output workspace within its stated preservation limits.
Never overwrite source layers or inherited libraries without explicit authorization.
Reuse authorization already given. Ask only for a missing decision that changes identity, required appearance or a loss budget; explain the affected component and consequence.
Report only observed changes. Measure rendering before claiming higher FPS or lower GPU use.

Load only the relevant guidance

Request	Read
Validation only	Setup, then the validation section of operations
Approved operation chain	Setup, operations, verification
Existing or persistent asset library	Add the library index requirements to the assessment
Missing standalone runtime	Installation
Remote stage	Remote access before the first open
Report from completed evidence	Verification

Use upstream package guidance for selected operation mechanics and proxy workflows. Keep large logs on disk as specified in setup.

Limitations

Convert CAD input with the source converter's workflow and NVIDIA's CAD conversion guidance. Render profiling requires NVIDIA/omniperf or the user's available profiler; USD open and traversal timings alone do not establish rendering improvements.

Troubleshooting

For unavailable imports, operations or remote assets, follow setup. For incomplete execution or failed composition checks, follow verification; retain the failed artifacts and report the missing capability or failed check.

Examples

After runtime preflight, use the verified Python interpreter from setup to inspect a stage:

python scripts/successor_assessment.py inspect --source /data/factory.usdc --workspace /data/factory-review

Review the generated candidates using boundary guidance, fill the generated decision template, then submit it:

python scripts/successor_assessment.py decide --workspace /data/factory-review --decisions /data/factory-review/decisions.json

These commands perform assessment; continue through the instructions above only when review is complete. Run from the skill directory; generated data stays in the workspace.

Output Format

Maintain live progress and editable steering throughout execution.

For end-to-end optimization, provide the written USD assembly, validated report JSON, and generated Markdown and HTML reports. State the runtime, operations actually executed, preservation and coverage results, measured changes, source-write status, and artifact paths. Diagnosis-only work may return a findings summary stating that no optimized stage was written.

Files

ATTRIBUTION.mdAdded by AutoGineer964 B
BENCHMARK.md12.0 KiB
CHANGELOG.md2.4 KiB
LICENSELicence file added by AutoGineer11.2 KiB
SKILL.md10.2 KiB
agents/openai.yaml375 B
assets/progress-dashboard/app.jsScript9.8 KiB
assets/progress-dashboard/index.html2.4 KiB
assets/progress-dashboard/styles.css3.8 KiB
config/skillspector-baseline.yaml7.3 KiB
evals/README.md1.8 KiB
evals/evals.json12.4 KiB
evals/files/completed-run/after.usda399 B
evals/files/completed-run/before.usda399 B
evals/files/completed-run/evidence.json745 B
evals/files/factory/cases/factory.usda13.6 KiB
evals/files/factory/materials.usda1.8 KiB
references/asset-authoring.md10.1 KiB
references/component_scope.pyScript18.0 KiB
references/geometry_tolerance.pyScript2.1 KiB
references/install-standalone.md2.4 KiB
references/library-reuse.md7.6 KiB
references/operations.md22.4 KiB
references/operations/README.md7.9 KiB
references/operations/operations.json52.4 KiB
references/operations/registry-args.json2.1 KiB
references/operations/scripts/operations.schema.json6.2 KiB
references/optimization-report/scripts/apply_palette.pyScript13.3 KiB
references/optimization-report/scripts/asset_results.pyScript5.9 KiB
references/optimization-report/scripts/definition_verification.pyScript7.1 KiB
references/optimization-report/scripts/descent_convergence_common.pyScript9.0 KiB
references/optimization-report/scripts/optimization-report.schema.json39.4 KiB
references/optimization-report/scripts/structure_conformance.pyScript15.2 KiB
references/optimization-report/scripts/validate_report.pyScript55.2 KiB
references/remote-assets.md1.6 KiB
references/report-templates/optimization-report.html.template14.9 KiB
references/report-templates/optimization-report.md.template6.2 KiB
references/report-templates/render_preview.pyScript17.9 KiB
references/report-templates/theme.css711 B
references/setup-usd-performance-tuning/scripts/probe-snapshot.schema.json1.7 KiB
references/setup-usd-performance-tuning/scripts/setup-preflight.schema.json6.4 KiB
references/setup.md3.3 KiB
references/structure.md20.8 KiB
references/upstreams/usd-optimize.md6.3 KiB
references/usd-optimize-run-operations/scripts/asset_authoring.pyScript54.9 KiB
references/usd-optimize-run-operations/scripts/batch-plan.schema.json7.5 KiB
references/usd-optimize-run-operations/scripts/category_publication.pyScript6.3 KiB
references/usd-optimize-run-operations/scripts/current_run_reuse.pyScript11.6 KiB
references/usd-optimize-run-operations/scripts/material_optimization.pyScript4.9 KiB
references/usd-optimize-run-operations/scripts/material_publication.pyScript9.5 KiB
references/usd-optimize-run-operations/scripts/native_reconstruction.pyScript7.9 KiB
references/usd-optimize-run-operations/scripts/native_worker.pyScript68.4 KiB
references/usd-optimize-run-operations/scripts/pack_definitions.pyScript1.6 KiB
references/usd-optimize-run-operations/scripts/persistent_library.pyScript20.3 KiB
references/usd-optimize-run-operations/scripts/persistent_reuse.pyScript31.1 KiB
references/usd-optimize-run-operations/scripts/prim_regroup.pyScript14.9 KiB
references/usd-optimize-run-operations/scripts/run_batch.pyScript32.5 KiB
references/usd-optimize-run-operations/scripts/semantic_library.pyScript48.2 KiB
references/usd-optimize-run-operations/scripts/shared_geometry.pyScript25.5 KiB
references/usd-optimize-run-operations/scripts/status.schema.json7.9 KiB
references/usd-structure-assessment/references/apply-restructure/scripts/apply-restructure-manifest.schema.json35.3 KiB
references/usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/scripts/instance_candidate_finder.pyScript12.7 KiB
references/usd-structure-assessment/references/usd-mesh-fragmentation-candidates/scripts/mesh_fragmentation_finder.pyScript13.8 KiB
references/usd-structure-assessment/scripts/atomic_placement.pyScript4.9 KiB
references/usd-structure-assessment/scripts/audit-report.schema.json2.3 KiB
references/usd-structure-assessment/scripts/boundary_reasoning.pyScript36.0 KiB
references/usd-structure-assessment/scripts/discovery_preview.pyScript8.6 KiB
references/usd-structure-assessment/scripts/optimization-plan.schema.json1.5 KiB
references/usd-structure-assessment/scripts/structure_assessment.pyScript112.2 KiB
references/usd-structure-assessment/scripts/usd-structure-assessment-report.schema.json14.0 KiB
references/usd-validation-runner/references/validator-concepts.json35.8 KiB
references/usd-validation-runner/scripts/usd_validation_executor.pyScript37.4 KiB
references/usd-validation-runner/scripts/validation-report.schema.json3.5 KiB
references/usd-validation-runner/scripts/validation-scope-note.schema.json2.6 KiB
references/usd-validation-runner/scripts/validator-concepts.schema.json3.8 KiB
references/verification.md11.9 KiB
scripts/animation_context.pyScript6.8 KiB
scripts/composition_verification.pyScript16.9 KiB
scripts/failure_reporting.pyScript2.7 KiB
scripts/product_clues.pyScript6.2 KiB
scripts/progress_dashboard.pyScript12.6 KiB
scripts/stage_profile.pyScript15.7 KiB
scripts/successor_assessment.pyScript34.1 KiB
scripts/successor_execution.pyScript15.7 KiB
scripts/successor_progress.pyScript22.3 KiB
scripts/successor_reconstruction.pyScript19.6 KiB
scripts/successor_workflow.pyScript55.0 KiB
scripts/usd_tuning.pyScript24.7 KiB
skill-card.md5.5 KiB
skill.oms.sig26.5 KiB

references/optimization-report/scripts/optimization-report.schema.json

{
  "$comment": "SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.\nSPDX-License-Identifier: Apache-2.0",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "USD Performance Tuning Report",
  "description": "End-to-end report from a USD performance tuning session.",
  "type": "object",
  "required": [
    "asset_name",
    "output_path",
    "timestamp",
    "verdict",
    "optimization_score",
    "score_label",
    "reasoning",
    "measurement_context",
    "metric_groups",
    "metrics",
    "operations",
    "validators",
    "target_coverage"
  ],
  "additionalProperties": false,
  "properties": {
    "asset_results": {
      "description": "One entry per unique definition, joined from manifest decisions and worker receipts. Geometry metrics exclude child definitions; operation seconds exclude other phases.",
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "definition_id",
          "name",
          "source_prim_path",
          "semantic_category",
          "structural_type",
          "boundary_reason",
          "structure_reason",
          "independent_use",
          "disposition",
          "occurrences",
          "children",
          "before",
          "after",
          "operations",
          "retained_geometry",
          "reused_from_library"
        ],
        "additionalProperties": false,
        "properties": {
          "definition_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "source_prim_path": {
            "type": "string"
          },
          "product_identity": {"type": "object", "description": "Recorded product identification and accepted representation substitution."},
          "equipment_family": {"type": "string", "minLength": 1},
          "semantic_category": {
            "type": "string"
          },
          "structural_type": {
            "type": "string"
          },
          "boundary_reason": {
            "type": "string"
          },
          "structure_reason": {
            "type": "string"
          },
          "independent_use": {
            "type": "string"
          },
          "disposition": {
            "type": "string"
          },
          "occurrences": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "children": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "before": {
            "type": "object"
          },
          "after": {
            "type": "object"
          },
          "operations": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "order",
                "name",
                "status",
                "reason",
                "seconds"
              ],
              "additionalProperties": false,
              "properties": {
                "order": {
                  "type": "integer"
                },
                "name": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "reason": {
                  "type": "string"
                },
                "seconds": {
                  "type": [
                    "number",
                    "null"
                  ]
                }
              }
            }
          },
          "prior_operations": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "order",
                "name",
                "status",
                "reason",
                "seconds"
              ],
              "additionalProperties": false,
              "properties": {
                "order": {
                  "type": "integer"
                },
                "name": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "reason": {
                  "type": "string"
                },
                "seconds": {
                  "type": [
                    "number",
                    "null"
                  ]
                }
              }
            }
          },
          "retained_geometry": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "category": {
                  "type": "string"
                },
                "reason": {
                  "type": "string"
                }
              }
            }
          },
          "reused_from_library": {
            "type": "boolean"
          }
        }
      }
    },
    "report_summary": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "completion": {
          "type": "string"
        },
        "checks": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "limitations": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "next_run_instructions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },

    "asset_name": {
      "type": "string",
      "description": "Name of the asset that was optimized."
    },
    "input_path": {
      "type": "string",
      "description": "Path to the original input stage."
    },
    "output_path": {
      "type": ["string", "null"],
      "description": "Path to the optimized output stage; null for no_op (already-optimized) or runtime-forced structural_only runs where no optimized stage was written."
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp of when the report was generated."
    },
    "verdict": {
      "type": "string",
      "enum": ["improved", "neutral", "regressed", "mixed"],
      "description": "Overall optimization verdict from compare-profiles. Stays within this enum regardless of workflow_mode; use 'neutral' when no metrics changed. Degraded (Usd Optimize unavailable) and no-op runs are expressed via workflow_mode, not by inventing new verdict values."
    },
    "workflow_mode": {
      "type": "string",
      "enum": ["full", "structural_only", "no_op"],
      "description": "Execution mode for this run. 'full' = optimization/mutation ran (default when omitted); 'structural_only' = Usd Optimize was unavailable so only USD-structural work ran and no mesh operations executed; 'no_op' = no optimization was needed (e.g., structure assessment reported already_optimized). The verdict stays in its own enum in every mode."
    },
    "notes": {
      "type": "string",
      "description": "Free-form caveats the verdict and score cannot capture on their own: degraded-path explanation, the runtime or access blocker that prevented a stronger verdict, or the next profile capture needed to graduate it."
    },
    "next_profile_capture": {
      "type": "string",
      "description": "Required by SKILL.md on the runtime-forced degraded path (workflow_mode: structural_only): which runtime profiling should be captured later (e.g. Kit/omniperf FPS, VRAM, frame-time on the optimized stage) to graduate the structural verdict into a runtime one. Optional in all other modes."
    },
    "runtime_context": {
      "type": "object",
      "description": "Snapshot of the Kit / Usd Optimize / usd-validation-nvidia versions in effect for this run. Copied verbatim from setup-preflight.json so later readers can reproduce or audit the report. Mirrors the runtime-context fields defined in skills/omniverse-usd-performance-tuning/references/setup.md.",
      "required": ["usdOptimize", "assetValidator"],
      "properties": {
        "kit": {
          "type": "object",
          "required": ["application", "version", "path"],
          "description": "Kit application context. OPTIONAL: omitted on a standalone-only runtime (Kit is an opt-in render-profiling adjunct). When present, application/version/path are required.",
          "properties": {
            "application": {
              "type": "string",
              "description": "Friendly name of the Kit application, e.g. 'USD Composer', 'Isaac Sim', 'Kit SDK'."
            },
            "version": {
              "type": "string",
              "description": "Release version, e.g. '110.1.0'."
            },
            "path": {
              "type": "string",
              "description": "Absolute path to the Kit root."
            },
            "build": {
              "type": ["string", "null"],
              "description": "Full build identifier when present (e.g. '110.1.0+main.10181....release'); null when the install path does not encode one."
            }
          }
        },
        "usdOptimize": {
          "type": "object",
          "required": ["extension", "version"],
          "properties": {
            "extension": {
              "type": "string",
              "description": "Extension name, typically 'omni.scene.optimizer.core'."
            },
            "version": {
              "type": "string",
              "description": "Extension version, e.g. '110.0.4'."
            }
          }
        },
        "assetValidator": {
          "type": "object",
          "required": ["package", "version", "source"],
          "properties": {
            "package": {
              "type": "string",
              "description": "Package or extension name, e.g. 'usd-validation-nvidia' (pip distribution) or 'omni.asset_validator' (module)."
            },
            "version": {
              "type": "string",
              "description": "Package version."
            },
            "source": {
              "type": "string",
              "enum": ["pip", "standalone"],
              "description": "Where usd-validation-nvidia was loaded from."
            }
          }
        }
      }
    },
    "optimization_score": {
      "type": "number",
      "minimum": 0,
      "maximum": 10,
      "description": "Stage Optimization Score from 0-10, computed deterministically as round(sum(metric_groups[].score * metric_groups[].weight) / sum(metric_groups[].weight), 1) across scored stage/composition groups only. Exclude groups with score=null or weight=0. Runtime metrics such as RAM, VRAM, FPS, and frame time are excluded unless supplied by a separate runtime profiling report and explicitly treated outside this score. validate_report.py recomputes this weighted mean and rejects a declared score more than 0.05 away from it, so a hand-edited headline fails."
    },
    "score_scope": {
      "type": "string",
      "enum": ["stage_optimization"],
      "description": "Optional. Scope of optimization_score: legacy scope identifier for measured-area scores, not full runtime performance. Numeric scores remain in JSON for compatibility; the rendered report presents one measured-result verdict. Single-value enum kept for explicitness; not rendered (the renderer uses score_scope_label) and not gated, so it is optional rather than required."
    },
    "score_label": {
      "type": "string",
      "enum": ["excellent", "strong", "moderate", "neutral", "mixed", "regressed"],
      "description": "Human-readable score band derived from optimization_score: excellent >= 9.0; strong >= 7.5 and < 9.0; moderate >= 5.5 and < 7.5; neutral >= 4.5 and < 5.5; mixed >= 2.5 and < 4.5; regressed < 2.5. validate_report.py derives the band from the declared score and rejects a label that contradicts it."
    },
    "executive_summary": {
      "type": "string",
      "description": "Optional short reader-facing summary rendered near the top of the Markdown/HTML report."
    },
    "reasoning": {
      "type": "string",
      "description": "One to two concise paragraphs explaining why the agent chose the specific stage optimization approach for this asset, including the evidence that drove the choice and any tradeoffs."
    },
    "measurement_context": {
      "type": "object",
      "description": "Context for stage/composition measurements such as profiling mode, runtime, cache policy, sample count, and stage-open method.",
      "additionalProperties": {
        "type": ["string", "number", "boolean", "null"]
      }
    },
    "footprint": {
      "type": "object",
      "description": "Repack-normalized disk-footprint attribution (report-contract correction). A USDC/crate repack is the free re-encode any Export achieves; it is NOT the optimization. Report all three sizes and attribute the split so a repack-inflated headline cannot masquerade as the structural win. The storage dimension of the Stage Optimization Score and any footprint claim are measured against repack_normalized_baseline_bytes, never the raw input. Example: a large input that re-crates losslessly to a much smaller baseline (a free re-encode) and only then shows a smaller dedupe-into-shared-prototypes win off that normalized baseline. Optional block; when present, validate_report.py checks the arithmetic and fails closed on a repack-only 'win'.",
      "required": ["raw_input_bytes", "repack_normalized_baseline_bytes", "optimized_bytes", "structural_delta_pct", "scored_against"],
      "additionalProperties": false,
      "properties": {
        "raw_input_bytes": {
          "type": "number",
          "minimum": 0,
          "description": "Raw input stage size on disk as delivered (total referenced footprint, not root-layer size only)."
        },
        "repack_normalized_baseline_bytes": {
          "type": "number",
          "minimum": 0,
          "description": "Input losslessly re-crated to the same target encoding / USD version with zero dedupe. The honest baseline the structural win is measured against; isolates the free crate re-encode from the optimization."
        },
        "optimized_bytes": {
          "type": "number",
          "minimum": 0,
          "description": "Optimized output stage size on disk (same referenced-footprint basis as the inputs)."
        },
        "repack_delta_pct": {
          "type": "number",
          "description": "raw_input -> repack_normalized_baseline percent change. The free re-encode delta (expected <= 0); explicitly NOT the optimization."
        },
        "structural_delta_pct": {
          "type": "number",
          "description": "repack_normalized_baseline -> optimized percent change. The actual structural optimization win (dedupe into shared prototypes + instancing); the number the score and the run-scoring oracle gate against."
        },
        "raw_delta_pct": {
          "type": "number",
          "description": "raw_input -> optimized percent change. The total disk saving the user observes; true and useful but must not be conflated with the structural win."
        },
        "scored_against": {
          "type": "string",
          "enum": ["repack_normalized"],
          "description": "Pins that the storage dimension and any footprint claim score against the repack-normalized baseline, not the raw input. The only valid value; present so the contract is explicit and machine-checkable."
        },
        "disk_win_source": {
          "type": "string",
          "enum": ["none", "sharing", "sharing_only", "repack", "mesh_merge", "dead_data_removal", "unused_primvar_removal", "primvar_indexing", "layer_consolidation", "lossy_reduction", "decimation", "fit_primitive", "vertex_weld"],
          "description": "What produced a claimed disk reduction. The run-scoring oracle (its _guard_sharing_only_disk_win check) fails closed when structural_delta_pct is a real win (< -1%) but the source is NOT a legitimate byte-reduction lever: 'sharing'/'sharing_only' (instancing/hierarchy dedup), 'mesh_merge', 'repack', 'none', or unset all FAIL — the crate already byte-deduplicates identical arrays within a layer, so sharing frees ~no bytes and a merge just concatenates geometry (bytes ~= sum). A genuine disk win must be data removal (dead_data_removal / unused_primvar_removal), primvar_indexing, cross-file layer_consolidation, a lossy op (lossy_reduction / decimation / fit_primitive), or a coincident-seam vertex_weld (welds out the duplicated boundary verts a per-face split introduced — real bytes, credited here and NEVER attributed to the merge that exposed them)."
        },
        "notes": { "type": "string" }
      }
    },
    "structural_summary": {
      "type": "object",
      "description": "Scene-graph (axis-B) outcome the run-scoring oracle reads for the structural capture ratio and the measured-reuse gate. This is a RUNTIME / scene-graph claim (fewer composed prims, instancing, fewer draw calls from a within-prototype merge) and is flagged unverified-at-render until a runtime_profiling capture is attached; it is disk-neutral on its own (see footprint.disk_win_source for the disk axis).",
      "additionalProperties": true,
      "properties": {
        "reuse_measured": {
          "type": "boolean",
          "description": "True only when the run MEASURED the reuse it collapsed (distinct vs total prototypes/units). The scorer scores no axis-B credit for an unmeasured consolidation claim when the oracle sets ceilings.structural.requires_measured_reuse."
        },
        "authored_prim_delta_pct": {
          "type": "number",
          "description": "Authored-prim count percent change (negative = reduction). The primary axis-B metric; from instancing/dedup into shared prototypes. Instance-expanded scope."
        },
        "unique_prototype_count": { "type": "integer", "minimum": 0, "description": "Number of distinct prototypes after restructure." },
        "instance_ratio": { "type": "number", "minimum": 0, "description": "Instances / total occurrences; higher is more reuse, scored toward the ceiling." },
        "prototype_rendered_mesh_delta_pct": {
          "type": "number",
          "description": "PROTOTYPE-scope rendered-mesh percent change (negative = reduction) from a within-prototype mesh merge — 'merge once, benefit N'. The scorer credits THIS (not the instance-expanded count) for the draw-call axis-B win, so it does not double-count with authored_prim_delta_pct / instanced reuse."
        },
        "merge_applied": {
          "type": "boolean",
          "description": "Optional signal flag: true when a within-prototype mesh merge was performed in this run. Declarative only — the run-scoring oracle does NOT read it; it credits the merge (axis B) via prototype_rendered_mesh_delta_pct + merge_bounds_coherence and guards it via merge_identity_class + preservation.rendered_mesh_merged_count / rendered_triangle_count. Emit it for human/audit readability, not for scoring."
        },
        "merge_identity_class": {
          "type": "string",
          "enum": ["weak", "none", "strong"],
          "description": "Identity class of the units fused by the merge. A merge destroys per-part identity, so only 'weak' (anonymous, identity-not-wanted) or 'none' (identity-free fragments) units may be merged. 'strong' (an addressable component/subcomponent) is a legal VALUE so a run that did fuse a strong-identity unit can say so; the scorer's preservation gate then fails the run. Without 'strong' in the enum the honest report was schema-invalid, which left omitting the field — and omission clears the guard — as the only way to stay valid."
        },
        "merge_bounds_coherence": {
          "type": "number",
          "minimum": 0,
          "description": "Merged-prim AABB surface area / Sum(member AABB surface area). ~1 = the fused members were spatially adjacent (a legitimate draw-call merge). A value far above 1 means a merge of DISPERSED meshes that balloons the AABB and harms BVH/raytracing; the scorer grants NO draw-call credit when this exceeds MERGE_BOUNDS_COHERENCE_MAX (default 2.0), and the merge should not have been performed."
        },
        "frontier_descent_converged": {
          "type": "boolean",
          "description": "Report-side mirror of the apply-restructure manifest's frontier.descent_converged. Set true only when the bounded recursive de-duplication descent CONVERGED — a fresh one-level-down reuse re-scan found nothing new above the floor. validate_report.py's descent-convergence gate requires this true (with frontier_final_rescan_new_groups_above_floor == 0) OR a manifest frontier that records the same OR frontier_convergence_waived, before any Phase-4 geometry op (decimation / within-prototype merge / primitive-fit / quantization / topology edit) is permitted on a dedup/instancing run. Carry it here for manifest-less runs."
        },
        "frontier_final_rescan_new_groups_above_floor": {
          "type": "integer",
          "minimum": 0,
          "description": "Report-side mirror of the manifest field: the count of new shareable groups (occurrence >= 2, above the MINP floor) the terminal one-level-down re-scan found. 0 == converged. > 0 together with frontier_descent_converged == true is a contradiction the gate rejects (the descent was declared complete while reuse remained one level down)."
        },
        "frontier_convergence_waived": {
          "type": "boolean",
          "description": "Optional explicit user opt-out: true when the user chose to stop the descent before it converged and proceed to geometry ops anyway. Requires frontier_convergence_waiver_reason. Silence is NOT a waiver — the gate fails closed on an unconverged frontier with no recorded waiver."
        },
        "frontier_convergence_waiver_reason": {
          "type": "string",
          "description": "Required when frontier_convergence_waived is true: the recorded reason the descent was stopped early (e.g. addressability cost, user time budget)."
        },
        "notes": { "type": "string" }
      }
    },
    "safety_gate": {
      "type": "object",
      "description": "Correctness-precondition state (e.g. dangling material bindings repaired BEFORE structuring). Emit this block whenever a Phase-2c safety-gate validator reported issues: validate_report.py's safety-gate check requires it in that case, and the run-scoring oracle treats an omitted block as unresolved, so leaving it out is a reporting error rather than a clean run. The oracle also fails closed on a status that is not resolved/clear/none/passed/not_required, and on a block that records no status.",
      "additionalProperties": true,
      "required": ["status"],
      "properties": {
        "status": {
          "type": "string",
          "enum": ["resolved", "clear", "none", "passed", "not_required", "unresolved", "blocked", "failed"],
          "description": "resolved | clear | none | passed | not_required (cleared) vs. unresolved | blocked | failed (the scorer zeroes the run). Enumerated so a typo or an empty string is a schema error instead of a silently cleared gate."
        },
        "finding": { "type": "string" },
        "notes": { "type": "string" }
      }
    },
    "fidelity": {
      "type": "object",
      "description": "Lossy-tier fidelity evidence. The run-scoring oracle fails closed when max_deviation_within_band is false (a run that 'beats' a ceiling by over-decimating beyond the per-target band).",
      "additionalProperties": true,
      "properties": {
        "max_deviation_within_band": { "type": "boolean" },
        "band": { "type": "string" },
        "notes": { "type": "string" }
      }
    },
    "preservation": {
      "type": "object",
      "description": "Axis-A silent-loss block — the proof that an optimization (especially a 'lossless' dedupe/instancing pass) did not silently drop geometry. This is the hard gate the run-scoring oracle reads to catch a pass that shrank the disk or collapsed authored prims while quietly losing rendered meshes, geometry bytes, bounds, or binding integrity. Field names match exactly what the scorer consumes so the schema, scorer, and validator agree. Emit this block on any run that makes a structural/dedupe/instancing claim; a run whose oracle asserts axis-A scores 0 when the block is missing. Optional only for runs with no axis-A assertion (e.g. a pure no_op).",
      "required": ["rendered_mesh_count", "distinct_geometry_bytes_preserved", "bounds_preserved", "dangling"],
      "additionalProperties": false,
      "properties": {
        "rendered_mesh_count": {
          "type": "integer",
          "minimum": 0,
          "description": "Rendered-mesh count after optimization. Must equal the asset's known pre-optimization rendered-mesh count; the scorer fails the run (silent loss) on any change. Counts rendered meshes, not authored prims — an authored-prim collapse from dedupe/instancing is expected and is NOT a change here."
        },
        "distinct_geometry_bytes_preserved": {
          "type": "boolean",
          "description": "True only when the total distinct geometry bytes (the unique mesh data, ignoring instanced repetition) are preserved across the optimization. The scorer treats anything other than true as silent loss."
        },
        "bounds_preserved": {
          "type": "boolean",
          "description": "True only when the stage/world bounds are unchanged (within tolerance) after optimization. The scorer treats anything other than true as silent loss."
        },
        "dangling": {
          "type": "integer",
          "minimum": 0,
          "description": "Count of dangling relationships/bindings (e.g. material bindings pointing at removed prims) after optimization. Must be 0; the scorer fails the run when it exceeds the oracle's max_dangling (0 by default)."
        },
        "allow_merge": {
          "type": "boolean",
          "description": "Optional declaration: set true on a run that performed a within-prototype mesh merge. A merge fuses many small meshes into one, so the rendered_mesh_count legitimately DROPS by rendered_mesh_merged_count. NOTE: the run-scoring oracle relaxes the strict rendered-mesh-count equality based on the matching ORACLE's preservation.allow_merge (the golden config), NOT this report-side field — so this member is a human/audit-facing declaration, not a scorer input. The merge accounting itself is enforced via rendered_mesh_merged_count (rendered_mesh_count + rendered_mesh_merged_count == known); an unaccounted drop is still silent loss and fails closed."
        },
        "rendered_mesh_merged_count": {
          "type": "integer",
          "minimum": 0,
          "description": "How many rendered meshes the merge fused away (the declared drop). The scorer requires rendered_mesh_count + rendered_mesh_merged_count == the asset's known pre-merge count; distinct_geometry_bytes_preserved must still be true (a merge concatenates, it must not DROP geometry)."
        },
        "rendered_triangle_count": {
          "type": "integer",
          "minimum": 0,
          "description": "Renderable triangle total after optimization — the authoritative silent-loss invariant for a mesh merge. A merge fuses prims and welds coincident points, so rendered_mesh_count and distinct point counts legitimately change, but the renderable triangle total must not (a re-pack preserves every face). When the matching oracle asserts preservation.rendered_triangle_count, the scorer fails the run if this differs beyond the oracle's triangle_tolerance_pct — catching an over-coarse weld that collapses geometry even when the merge mesh-count accounting (rendered_mesh_count + rendered_mesh_merged_count == known) still balances. Emit it on any merge run."
        },
        "merge_locality_preserved": {
          "type": "boolean",
          "description": "Merge LOCALITY invariant: true only when every fused mesh stayed UNDER its named-component merge boundary — no geometry relocated to a shallower ancestor or the stage root. A single stage-wide merge buckets meshes by material across the whole stage and mergePoint=Parent resolves to their common ancestor (the root), dumping anonymous merged* blobs at the root and emptying the named kind-tagged components of their geometry. That is identity-destroying even when triangles and the mesh-count accounting balance, so on any allow_merge run the scorer fails closed unless this is true (and meshes_relocated_outside_boundary is 0). Compute it by checking each merged prim's parent against the expected boundary — kind-prim survival alone is NOT enough (the kind Xforms can survive while emptied). Scope one merge call per component to keep locality (references/operations.md, Interior merge)."
        },
        "meshes_relocated_outside_boundary": {
          "type": "integer",
          "minimum": 0,
          "description": "Evidence for merge_locality_preserved: count of fused prims that ended up outside their named-component boundary (e.g. at the stage root). 0 == local. Any positive value fails the preservation gate."
        },
        "notes": {
          "type": "string",
          "description": "Optional free-form note, e.g. how the rendered-mesh count and distinct-bytes/bounds were measured."
        }
      }
    },
    "runtime_profiling": {
      "type": "object",
      "description": "Optional handoff section for runtime performance profiling. Use Omniperf or an equivalent runtime profiler for RAM, VRAM, FPS, frame time, renderer, shader, and GPU metrics instead of folding them into the Stage Optimization Score.",
      "additionalProperties": false,
      "properties": {
        "status": {
          "type": "string",
          "enum": ["not_run", "external", "attached"]
        },
        "recommended_tool": { "type": "string" },
        "dashboard_url": { "type": ["string", "null"] },
        "artifact_path": { "type": ["string", "null"] },
        "summary": { "type": "string" },
        "caveat": { "type": "string" }
      }
    },
    "artifacts": {
      "type": "object",
      "description": "Optional provenance: report artifact paths generated from this JSON source of truth. Self-referential paths — not rendered by the report templates and not read by any gate, so the block and its members are optional (emit for traceability). additionalProperties stays false so a typo'd artifact key is still caught when the block is present.",
      "additionalProperties": false,
      "properties": {
        "json": { "type": "string" },
        "markdown": { "type": "string" },
        "html": { "type": "string" }
      }
    },
    "metric_groups": {
      "type": "array",
      "description": "Headline stage/composition impact areas for score cards. Runtime metrics should live under runtime_profiling, not as score groups.",
      "items": {
        "type": "object",
        "required": ["id", "display_name", "score", "status", "weight", "summary"],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "enum": ["load_time", "composition", "instancing", "storage_proxy", "structure_proxy", "validation", "other"]
          },
          "display_name": { "type": "string" },
          "score": {
            "type": ["number", "null"],
            "minimum": 0,
            "maximum": 10
          },
          "status": {
            "type": "string",
            "enum": ["measured", "proxy", "not_measured"]
          },
          "weight": {
            "type": "number",
            "description": "Relative weight for deterministic top-level score computation. Any non-negative scale is allowed as long as all scored groups in the report use the same scale; groups with score=null or weight=0 are excluded."
          },
          "summary": { "type": "string" },
          "caveat": { "type": "string" }
        }
      }
    },
    "metrics": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["name", "before", "after", "change_pct", "verdict"],
        "additionalProperties": false,
        "properties": {
          "name": { "type": "string" },
          "display_name": { "type": "string" },
          "category": {
            "type": "string",
            "enum": ["load_time", "composition", "instancing", "storage_proxy", "structure_proxy", "validation", "other"]
          },
          "unit": { "type": "string" },
          "direction": {
            "type": "string",
            "enum": ["lower_is_better", "higher_is_better"]
          },
          "evidence_type": {
            "type": "string",
            "enum": ["direct", "proxy"]
          },
          "before": { "type": "number" },
          "after": { "type": "number" },
          "change_pct": { "type": "number" },
          "verdict": {
            "type": "string",
            "enum": ["improved", "neutral", "regressed"]
          },
          "notes": { "type": "string" }
        }
      }
    },
    "operations": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["order", "name", "method", "result"],
        "additionalProperties": false,
        "properties": {
          "order": { "type": "integer" },
          "name": { "type": "string" },
          "method": { "type": "string" },
          "result": { "type": "string" }
        }
      }
    },
    "validators": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["name", "issues"],
        "additionalProperties": false,
        "properties": {
          "name": { "type": "string" },
          "issues": {
            "type": "integer",
            "description": "Count of reported findings for this validator row; use notes to distinguish failures, warnings, opportunities, or follow-up candidates."
          },
          "notes": { "type": "string" }
        }
      }
    },
    "target_coverage": {
      "type": "object",
      "description": "Phase-4 mesh-optimization coverage ledger, structurally parallel to the validation report's coverage_ledger. entries[] must cover the UNION of every iteration's apply-restructure manifest phase4_targets[]; complete is true only when every entry reached a resolved disposition. validate_report.py reconciles this against the upstream manifest(s) so a target that was never enumerated (e.g. an assembly_root dropped from a later iteration's manifest) fails closed instead of silently passing. Reconciliation is NOT optional once a restructure happened: if any entry has a restructure role (assembly_root | prototype | shared_layer | loadable_subasset) the gate requires a manifest, supplied via --manifest or recorded in source_manifests[]. A no_op / optimize-as-is-monolith run (no restructure roles) is manifest-free; an empty Phase-4 run is valid with entries: [] and complete: true.",
      "required": ["complete", "entries"],
      "additionalProperties": false,
      "properties": {
        "complete": {
          "type": "boolean",
          "description": "True only when every entry's disposition is one of optimized | exact_cache_hit | normalized_cache_hit | product_identity_hit | verified_unchanged | skipped_zero_meshes | skipped_user_declined and its required evidence passes. A 'blocked' or unresolved entry keeps this false and the report is not final."
        },
        "source_manifests": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Path(s) to the apply-restructure manifest(s) this coverage was reconciled against, one per restructure iteration. Recorded so validate_report.py can auto-load and reconcile them (resolved relative to the report file when not absolute), making reconciliation fail-closed rather than dependent on the operator remembering --manifest. Required in effect whenever any entry has a restructure role; omit for monolith/diagnosis runs."
        },
        "entries": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["path", "role", "mesh_count", "disposition"],
            "additionalProperties": false,
            "properties": {
              "path": {
                "type": "string",
                "description": "Phase-4 target file; reconciliation key against apply-restructure manifest phase4_targets[].path."
              },
              "role": {
                "type": "string",
                "enum": ["assembly_root", "prototype", "shared_layer", "loadable_subasset", "monolith"],
                "description": "Target kind. The restructure roles (assembly_root | prototype | shared_layer | loadable_subasset) trigger mandatory manifest reconciliation. 'monolith' is the non-restructured optimize-as-is target (N=1) and does not require a manifest."
              },
              "mesh_count": {
                "type": "integer",
                "minimum": 0,
                "description": "Default-predicate mesh count for this target (echoed from the manifest's authoritative count). disposition 'skipped_zero_meshes' is valid only when this is 0."
              },
              "optimized_mesh_count": {
                "type": "integer",
                "minimum": 0,
                "description": "How many of this target's meshes the Phase-4 op chain actually touched/optimized. When disposition is 'optimized' and mesh_count > 0, an optimized_mesh_count of 0 is flagged as a no-op masquerading as optimized. Minimal effort signal: a single count, not a before/after op-audit trail."
              },
              "disposition": {
                "type": "string",
                "enum": ["optimized", "exact_cache_hit", "normalized_cache_hit", "product_identity_hit", "verified_unchanged", "skipped_zero_meshes", "skipped_user_declined", "blocked"],
                "description": "exact_cache_hit = completed result reused under exact source identity; normalized_cache_hit = completed result reused under normalized source identity with recorded workload authorization; product_identity_hit = published representation reused under accepted product identity and recorded substitution; optimized = verified useful change; verified_unchanged = assessed operations with evidence and passed preservation checks; skipped_zero_meshes = no geometry to optimize (requires mesh_count and geometry_count == 0); skipped_user_declined = user opted out of optimizing this target; blocked = could not be processed (keeps complete=false)."
              },
              "operations": {
                "type": "array",
                "items": { "type": "string" },
                "description": "Optional: the mesh op chain applied to this target, for traceability."
              },
              "notes": { "type": "string" },
              "geometry_count": {
                "type": "integer",
                "minimum": 0,
                "description": "All geometry schemas, including analytic primitives and point instancers."
              },
              "assessment": {
                "type": "object",
                "properties": {
                  "complete": {
                    "type": "boolean"
                  },
                  "operations": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  }
                },
                "required": [
                  "complete",
                  "operations"
                ]
              },
              "verification": {
                "type": "object",
                "properties": {
                  "passed": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "passed"
                ]
              },
              "definition_id": {
                "type": "string",
                "minLength": 1,
                "description": "Definition identity within the writer layer. Omit only for legacy file-level coverage."
              }
            }
          }
        }
      }
    }
  }
}

Requirements and compatibility

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, Needs Node.js

The author says: Requires a verified standalone Usd Optimize/OpenUSD runtime for operations, usd-validation-nvidia for supported checks, and a writable output workspace. Remote assets require a working resolver. Render profiling is an external handoff.

Security

What our scanner noticed· Medium risk

Large base64-encoded blobs
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

NVIDIA (Official)

Source

NVIDIA/skills · skills/omniverse-usd-performance-tuning · commit fce3cca

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE-APACHE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

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

Download ZIP

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