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 the user's answer. That reference owns the option set; do not restate or invent options here.
• 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:

• Start milestone lists with omniverse-usd-performance-tuning; include setup-usd-performance-tuning only as Phase 0 context when relevant.
• Set top-level decision to ready_to_plan for generic optimization.
• Include the chain through optimization-report in both committed_milestones and planned_phases.
• Use exact profile labels profile-stage:baseline and profile-stage:after; never emit bare profile-stage.
• Preserve this subsequence exactly, inserting optional analysis only where it does not reorder it:

omniverse-usd-performance-tuning -> profile-stage:baseline -> usd-structure-assessment -> usd-validation-runner -> restructure-decision -> apply-restructure -> usd-optimize-run-validators -> usd-optimize-interpret-validators -> usd-optimize-run-operations -> profile-stage:after -> compare-profiles -> optimization-report

Two milestones are conditionally required — when the trigger holds they must appear as committed milestones at this position, not merely be routed to:

• usd-hierarchy-dedupe-candidates — after usd-structure-assessment, before restructure-decision, whenever the stage shows repeated copied hierarchy, high mesh count with little or no instancing, or a monolithic root. Do not conclude hierarchy_dedupe.recommended: false without it.
• usd-edit-target-planner — after apply-restructure, before the Usd Optimize validator/operations chain, whenever the stage is composed (references or payloads) and each target must be optimized as its own root layer.

Do not list usd-optimize-run-validators or usd-optimize-interpret-validators before restructure-decision in broad optimization milestone summaries. Phase-aware validator routing still happens inside usd-validation-runner.

Default broad optimization to three scoped iterations unless the user opts out, asks for a quick pass, or stop criteria apply. Each iteration writes an interim report/update; later passes reuse prior evidence instead of restarting the full workflow.

Execution discipline

• Load references/workflow.md before end-to-end execution; it owns Phase 0-7 flow, Kit/standalone branches, validator routing, operation ordering, termination criteria, duration hints, and the default three-pass pattern.
• Do not treat nested phase names as checklist labels. Before executing a phase, load that phase's nested README.md or reference and follow it. Invoke downstream skill bodies only when their phase is reached.
• If local workspace instructions or helper commands are supplied, inspect them and use them to create, validate, or render required artifacts. If a file/tool is unavailable, report the observed blocker instead of fabricating completion.
• For binary or large assets, do not print raw contents. Use bounded metadata, checksums, sizes, validation/profile summaries, compact facts, or tool reports.
• Before reading Kit logs, usd-validation-nvidia CSVs, Usd Optimize 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 snapshots rather than full dumps or live streams.

Minimum context to gather: target stage, problem/goal, local/mounted/remote location, runtime, workload type when known, diagnosis-only vs mutation, and permission/output target for writes. Never overwrite the source unless explicitly allowed; prefer a separate optimized output for mutation. Do not invent thresholds, percentage wins, metrics, or runtime evidence.