Omniverse USD Performance Tuning

Omniverse USD Performance Tuning

Scope

Use for broad USD performance work: slow loading, low FPS/interactivity, high GPU or system memory, GPU crash/device lost, validation failures, CAD/conversion-quality triage, profiling, or requests to optimize a scene. This skill owns the user-facing workflow; setup, authentication, profiling, validation, mutation, and reporting are executed by phase references when reached.

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

Mandatory session-start gate

Before any tuning output, except a static classification-only answer, follow skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md. That reference owns output_path, setup-preflight.json, Format A/Format B, and forbids silent ad hoc probing.

Required behavior:

• Missing or unreadable preflight: invoke setup-usd-performance-tuning.
• Present preflight: print Format A and wait for Continue, Change Kit, Switch to standalone, or Re-run probe.
• Runtime already confirmed in this session: use compact Format B:

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

For standalone/usd-optimize packages, runtime evidence must include package/sentinel checks plus shared-library or import/load verification, not just the Python executable/version. For omniverse:// assets, route through omniverse-authentication before setup, triage, or first open.

Entry-skill and decision rules

• Name omniverse-usd-performance-tuning as the entry skill whenever any runtime path is verified: Kit, standalone, or a partial stack such as usd-validation-nvidia only. If the requested tool or operation is missing, return the specific blocker code such as blocked_missing_usd_optimize or blocked_missing_usd_optimize_operation; do not substitute a different workflow.
• Name setup-usd-performance-tuning as entry only when no runtime path is verified and runtime choice/setup is the first unresolved problem.
• This is ownership, not phase order: authentication, setup, and triage still run in their normal order.

Planning decision — derive decision from the response's shape, never from whether the request named a destructive op (the harness enforces the shape invariants):

• ready_to_plan — nothing in this response awaits the user; committed_milestones equals planned_phases. This is the default for generic optimization: the lossless canonical chain, plus a proactive auto-within-tolerance bounded-loss pass (an over-tessellated, visually-toleranced target reduced at its conservative per-target band, applied with a one-line notice rather than a prompt).
• approval_required — this response halts at a gate it is surfacing now; committed_milestones is a strict prefix of planned_phases, and approval_required_reason names the gate. The trigger is an unresolved decision the agent must surface before it can plan the op, not the fact that an op is destructive. Default primitive-fitting on a fitting-candidate scene (e.g. BIM/CAD pipe and duct runs with fitPrimitives at default args) is the standard, expected win and stays ready_to_plan, gated at execution. A bounded-loss op (decimateMeshes, fitPrimitives) becomes inline-elicited — its tolerance or data-preservation parameter must be answered now — only when it would run above the conservative band, on a functional-precision target (articulated/physics/sim-ready/metrology/variant-bearing), or under an explicit preservation intent (the user asks to keep UVs/displayColors/subsets). A decimateMeshes request with no stated tolerance is inline-elicited via its one upfront mm_tolerance question. A restructure-decision the response is presenting now is approval_required for the same reason. See usd-optimize-run-operations/references/operation-safety.md for the apply-authority classes.
• blocked — a blocked_code applies.
• Future gates that genuinely fire later — a downstream restructure-decision not yet reached, identity-gated ops collected for the Phase 7 opt-in menu — belong in gates_observed, never in decision.

Canonical plan contract

For broad optimization, structured plans/status summaries must: