Skip to content

Agent-friendly conventions for openusd-cheatsheet.md - #72

Merged
asluk merged 3 commits into
NVIDIA-Omniverse:mainfrom
asluk:agent-friendly-cheatsheet
Apr 29, 2026
Merged

Agent-friendly conventions for openusd-cheatsheet.md#72
asluk merged 3 commits into
NVIDIA-Omniverse:mainfrom
asluk:agent-friendly-cheatsheet

Conversation

@asluk

@asluk asluk commented Apr 29, 2026

Copy link
Copy Markdown
Contributor

Initial pass at agent-friendly conventions. Adds metadata, source/scope tags, recast Agents section, plus folded-in framing/factual fixes. Follow-up commits welcome on the items in Out of scope below.

Why

#71 added docs/openusd-cheatsheet.md as a human-readable single-page entrypoint. Real-world consumption is mixed — humans skim it, agents (LLMs, MCP servers, RAG pipelines) ingest it. Agents need signals humans infer from context: vendor scope (OpenUSD vs NVIDIA), renderer scope (Kit vs OVRTX), freshness, validation-layer disambiguation, decision rubrics over flat lists.

This PR makes those signals explicit and machine-readable without bloating the page for humans.

What's in this PR

Front-matter metadata (HTML comment)

Invisible in rendered view; parseable by anything reading the markdown source.

<!--
agent-readable metadata:
  last_verified: 2026-04-29
  openusd_version_target: "25.05+"
  maintained_by: NVIDIA-Omniverse
  audience: [humans, agents]
  tag_vocabulary: ...
-->

Source/scope tags on every link

Tag vocabulary: [OpenUSD], [NVIDIA], [Kit], [OVRTX], [Isaac], [Community]. Multiple tags allowed.

Example:

- [Maximizing USD Performance](https://openusd.org/release/maxperf.html) `[OpenUSD]`
- [Kit Scene Optimizer](https://docs.omniverse.nvidia.com/extensions/latest/ext_scene-optimizer.html) `[NVIDIA, Kit]`

Quick visual scan for humans; structural metadata for agents; vendor-neutrality becomes grep-able.

Recast ## Agents section — instructions for agents, not about them

Drops the "Current models (GPT 5, Opus 4)" snapshot (which dates fast). Replaces with:

  • Routing guidance (prefer [OpenUSD] first, then [NVIDIA])
  • Renderer scope reminder (distinguish [OVRTX] from [Kit])
  • Layer disambiguation pointer (match user intent to validation layer)
  • Freshness verification (last_verified in metadata)
  • A list of NVIDIA OpenUSD-related MCP servers (kit-dev, usd-code, isaac-sim, omni-ui) alongside Kit USD Agents

Folded-in framing / factual fixes

  • Glossary link: /22.08//release/ (always-latest)
  • SimReady framing: rewritten to be honest about current status while clear on direction. Was: "a standard and ecosystem for physically accurate 3D assets..." Now: "a specification and ecosystem for physically accurate 3D assets... Currently NVIDIA-led, designed to evolve toward multi-vendor adoption and shared industry standards. The intent: simulation-vertical requirements that are shared and validatable across the ecosystem, not vendor-private." Second paragraph keeps the physical-AI direction.
  • USDA description: "ASCII-formatted USD" → "human-readable USD" (USDA accepts UTF-8; "human-readable" captures the format's intent more directly).

Out of scope (next iteration)

Saved for follow-up PRs to keep this one focused:

  • Section restructure of ## How Do I Optimize? and ## Best Practices into decision rubrics (file-format / composition / runtime / asset-structure layers)
  • Common Pitfalls subsection consolidating scattered anti-patterns as DON'T → DO → because triples
  • Top-N code snippets (lift-and-paste examples for usdchecker invocation, opening a stage, USDRT prim query, point-instancer creation, assetInfo read/write)
  • Companion docs/openusd-cheatsheet.json — same content as structured data, ingestible by MCP servers / RAG pipelines without parsing markdown
  • MCP server URLs — listed by name only in the Agents section; need verified GitHub or docs URLs

Implementation notes

  • Tag vocabulary lives in the HTML comment metadata at the top of the file; intro paragraph mentions tags briefly so casual readers don't ignore them.
  • Tags are intentionally short, bracketed, and backticked to stay grep-able and stable across renderers (GitHub, Sphinx, internal docs builds).

asluk and others added 3 commits April 29, 2026 14:06
…gents

The cheatsheet is consumed by agents (LLMs, MCP servers, RAG pipelines)
as well as humans. Agents need signals humans infer from context: vendor
scope, renderer scope, freshness, and validation-layer disambiguation.
This commit adds those signals without bloating the page for humans.

Changes:

* Add agent-readable metadata block (HTML comment with last_verified,
  openusd_version_target, audience, tag vocabulary). Invisible in
  rendered view; parseable by anything reading the markdown source.
* Note the tag convention briefly in the intro paragraph.
* Append source/scope tags to every link: [OpenUSD], [NVIDIA], [Kit],
  [OVRTX], [Isaac]. Multiple tags allowed (e.g. [NVIDIA, Kit]).
* Recast `## Agents` from "instructions about agents" to "For Agents
  Consuming This Page" — orient the agent toward primary sources, layer
  disambiguation, and freshness verification. Drops the volatile
  "Current models (GPT 5, Opus 4)" snapshot.
* List NVIDIA OpenUSD-related MCP servers (kit-dev, usd-code, isaac-sim,
  omni-ui) alongside Kit USD Agents. URLs pending — listed by name.
* Soften SimReady framing from "a standard and ecosystem" to "NVIDIA's
  specification and ecosystem" — accurate to current status.
* Update glossary link from /22.08/ (outdated) to /release/
  (always-latest).
* Tag bullets in Kit Runtime Performance per scope ([NVIDIA, Kit] vs
  [NVIDIA, OVRTX] for renderer-specific items like Geometry Streaming).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
USDA is text-based USD intended for humans to read and edit. "Human-
readable" captures that intent more directly than "ASCII-formatted"
(USDA also accepts UTF-8, so ASCII understates the format).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…irection

Earlier framing ("a standard and ecosystem") overstated current status.
Subsequent framing ("NVIDIA's specification and ecosystem") understated
the multi-vendor intent — SimReady is currently NVIDIA-led but explicitly
designed to evolve toward shared industry standards rather than stay
vendor-private. This rewrites the intro to be honest about today and
clear about where it's going.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@asluk
asluk marked this pull request as ready for review April 29, 2026 21:14
@asluk
asluk requested a review from jshrake-nvidia April 29, 2026 21:15

@jshrake-nvidia jshrake-nvidia left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks good to me. I audited all the tags against the links and everything makes sense.

@asluk
asluk merged commit 72d348d into NVIDIA-Omniverse:main Apr 29, 2026
2 checks passed
@asluk
asluk deleted the agent-friendly-cheatsheet branch April 29, 2026 22:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants