# Usd Layer Open

> Use this skill when implementing or verifying the generic boundary that opens a resolved USD layer resource and dispatches it to a registered layer-format handler.

- Skill: `nvidia-omniverse/usd-layer-open` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nvidia-omniverse/usd-layer-open`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nvidia-omniverse/usd-layer-open/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: NVIDIA-Omniverse (https://skillmd.com/u/nvidia-omniverse)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nvidia-omniverse/usd-layer-open

---


# usd-layer-open

Use this skill when implementing or verifying the generic boundary that opens a
resolved USD layer resource and dispatches it to a registered layer-format
handler.

## Spec Sources

- USD Core Spec Resource Interface sections covering resolving identifiers to
  resource locations, resource protocol interaction, extension resolution, and
  packaged resources
- USD Core Spec Document Data Model section `Formats`
- USD Core Spec Core File Formats sections `Text`, `Binary`, and `Package`

Pinned tag / commit: `v1.0.1`

## Provides

- Root layer resource opening after identifier resolution
- Format dispatch from a resolved resource location to declared format handlers
- Target-native layer-open result ownership
- Canonical layer-open dump adapter ownership
- Clear diagnostics for unsupported resource schemes or unsupported formats
- A boundary where USDA, USDC, and USDZ open paths compose with
  the same resource protocol

## Contract

This skill owns `contracts/handles/layer-open.handle.json`. Layer opening is the
integration boundary between resource protocol I/O and layer-format handlers. It
accepts an already-resolved resource location or a root input that is treated as
a concrete local resource by the target. It classifies the input through
`usd-resource-protocol`, selects a handler from the resolved location when the
extension is decisive, opens the resource through
`usd-resource-protocol`, and dispatches the opened bytes or local file-backed
path to the selected format handler.

Resolved `.usda`, `.usdc`, and `.usdz` extensions are decisive fast paths when
the corresponding handler is registered. A `.usda` resource dispatches to
`usda-layer-open`, a `.usdc` resource dispatches to `usdc-layer-open`, and a
`.usdz` resource dispatches to `usdz-layer-open`,
without reading resource content to inspect a text header, binary magic, or other
signature for the dispatch decision. Content signatures may be used only as a
fallback for ambiguous resources with no registered extension match. They must
not override an explicit `.usda`, `.usdc`, or `.usdz` resolved extension.

For the current `usda-single-layer` target, the only registered handler is
`usda-layer-open`, so the generic opener can only dispatch USDA text layers and
must report unsupported-format diagnostics for other formats. The domain output
is a target-native layer-open result containing either a document-model `Layer`
or diagnostics. It must not be a `Json`, Python `dict`, tagged JSON, or
canonical dump tree.

The `usdc-single-layer` target adds `usdc-layer-open` as a separate concrete
handler for `.usdc` resources while preserving the same target-native
layer-open result boundary and dump-adapter separation.

The `usdz-single-layer` target adds `usdz-layer-open` as a package-layer handler
for `.usdz` resources and `Package` resolved locations. Resource protocol owns
package spelling split into outer resource plus entry. USDZ package parsing,
default-layer selection, and entry byte views belong to `usdz-package-format`
through `usdz-layer-open`, not to this generic opener.

The generated dump command is a separate adapter. It may convert the native
layer-open result into the canonical layer dump JSON described by
`harness/dump_contract.md` for goldens, diagnostics, and benchmarks.

The opener does not own USDA grammar, USDC decoding, USDZ package parsing,
document-model storage, USD namespace paths, authored value representation,
listOps, or field semantics. It only owns resource-to-format dispatch and the
target entrypoint shape.

When the resource cannot be opened or the format is unsupported, diagnostics
should fail before parser-specific layer state is emitted.

## Handle Contract

This skill owns the entrypoint contract in
`contracts/handles/layer-open.handle.json`. That contract codifies the
ResolvedLocation-first dispatch flow: convert identifier to
`ResolvedLocation` through `usd-resource-protocol`, split package-typed
locations through `split_package`, select `.usda`/`.usdc`/`.usdz` handlers by resolved
extension before any content sniffing, read through `read_resource`, then invoke
the selected handler with the opened `ResourceReadResult` (including
`file_backed_path` when present for standalone file handlers). If there is no decisive extension match,
implementations may read the resource once and use a signature fallback before
choosing a handler.

## Boundary Guards

Defer resource location typing, local file URI conversion, resource reads,
resource writes, and unsupported resource protocol diagnostics to
`usd-resource-protocol`.

Defer USDA text-layer handling to `usda-layer-open`.

Defer canonical layer dump construction to an explicit adapter over the returned
document-model `Layer`.

Defer USDC binary parsing to `usdc-layer-open` and its `usdc-*` dependency
closure when that handler is in the active target scope.

Defer USDZ package parsing, default-layer selection, and package-entry lookup to
`usdz-layer-open` and `usdz-package-format`.

Defer USD namespace path grammar and spec-path identity to `usd-paths` through
the parser/document-model dependency closure.

Do not implement text parsing, binary parsing, package parsing, sublayer
loading, reference/payload loading, value clip loading, composition, asset
resolution search paths, value resolution, or stage population in this generic
opener.

Do not call `usd-resource-protocol.read_resource` from concrete handlers; the
entrypoint owns resource I/O and hands the opened `ResourceReadResult` to the
concrete handler. Concrete handlers that invoke resource protocol reads
directly with a raw identifier string are a contract violation.

## Test Obligations

- dispatch a local filesystem USDA layer to `usda-layer-open` and emit the
  canonical layer dump through the adapter
- dispatch a local filesystem USDC layer to `usdc-layer-open` when that handler
  is present in the active target scope and emit the canonical layer dump
  through the adapter
- dispatch a supported local `file` URI USDA layer to `usda-layer-open` and emit
  the same canonical layer dump through the adapter when file URI cases are
  added
- expose a domain API whose success value is a document-model `Layer`, not a
  JSON object
- dispatch a supported local `file` URI USDC layer to `usdc-layer-open` when
  that handler is present in the active target scope
- the entrypoint converts the input identifier to a `ResolvedLocation` through
  `usd-resource-protocol` before format dispatch; raw-identifier suffix matching
  before resolution is a contract violation
- format dispatch reads `ResolvedLocation` metadata first and may consult an
  opened resource signature only as an ambiguous-resource fallback; suffix
  matching on the raw identifier before resolution is a contract violation
- `.usda` and `.usdc` resolved extensions dispatch automatically to
  `usda-layer-open` or `usdc-layer-open` when the handler is registered; this
  extension fast path must not read resource content to inspect a header or magic
  value before selecting the handler
- content-signature dispatch is only a fallback for ambiguous resources with no
  registered extension match; mismatched opened bytes under an explicit `.usda`
  or `.usdc` extension are handled by the selected handler's validation
  diagnostics, not by redispatching to another handler
- when `usd-resource-protocol` exposes `file_backed_path` on the opened
  `ResourceReadResult`, the entrypoint forwards that path to the concrete
  handler for standalone resources so format-specific fast paths (e.g. Crate
  mmap) can run
- package-syntax inputs are split through `usd-resource-protocol.split_package`
  before any handler is invoked; `outer.usdz[inner]` reaches `usdz-layer-open`
  as opened outer package bytes plus the explicit inner entry
- `.usdz` local resources dispatch to `usdz-layer-open`; whole-package opens use
  the package default layer selected by `usdz-package-format`
- Uri-typed locations that no registered handler accepts must produce
  `UnsupportedScheme`, not `ResourceOpenFailed`
- reject unsupported resource schemes before parser state is emitted
- reject unsupported formats clearly
- preserve the handler's exact diagnostics for malformed USDA content after the
  resource has been opened
- all cases in `goldens/integration/usda-single-layer/basic.json`