Frontmatter Convention for NVIDIA Plugin Skills: YAML Schema and Metadata Standards

NVIDIA plugin skills in the openai/plugins repository use a strict YAML frontmatter block—delimited by triple dashes (---) at the top of each SKILL.md file—that defines metadata fields including name, version, tools, and a nested upstream object to enable Codex discovery and routing.

The openai/plugins repository hosts NVIDIA-specific automation skills that adhere to a standardized metadata convention. Every skill definition resides in a SKILL.md file (or skill-card.md for viewer components) that begins with a structured YAML frontmatter block. This standardized header provides the routing logic, versioning constraints, and dependency mapping required to deploy Physical AI, Omniverse, and neural reconstruction workflows without duplicating heavy logic in the router itself.

Required YAML Fields in the NVIDIA Plugin Frontmatter

The frontmatter convention for NVIDIA plugin skills follows a predictable top-level schema. While key order is not enforced, the typical layout observed in skills such as physical-ai-neural-reconstruction includes the following mandatory top-level keys:

Field	Type	Purpose
name	String	Short, snake-case identifier used for routing
description	String	One-sentence summary of functionality
license	String	SPDX-compatible license identifier
version	String	Semantic version string
tools	List	Array of required tool capabilities
compatibility	String	Free-form runtime requirements
metadata	Object	Nested block containing author, tags, and upstream linkage

Core Identifiers and Licensing

The name field provides the canonical snake-case identifier (e.g., physical-ai-neural-reconstruction) that Codex uses to route requests. The description field must contain a concise one-sentence summary clarifying the skill’s scope and explicit exclusions—such as "Do NOT use for SimReady or infra setup" observed in the NuRec router skill.

The license field accepts SPDX-compatible strings like Apache-2.0, while version typically mirrors the semantic version defined in the skill’s pyproject.toml.

Runtime Requirements

The tools field enumerates required capabilities as a YAML list:

tools:
  - Read
  - Shell

The compatibility field contains free-form text describing runtime prerequisites. For Physical AI skills, this typically specifies Docker, NVIDIA Container Toolkit, GPU availability, and NGC API key requirements.

The Metadata Block

The metadata object nests critical descriptive data:

• author: Human-readable attribution (e.g., "NVIDIA Physical AI")
• tags: Keyword array for discoverability (physical-ai, nurec, neural-reconstruction)
• upstream: Complex object linking to external implementation repositories

Deep Dive: The Upstream Repository Configuration

The upstream field within metadata distinguishes NVIDIA plugin skills from simple documentation files. This object ensures the thin router skill does not duplicate heavy logic, instead pointing to canonical implementations in NVIDIA’s own repositories.

The upstream object contains the following fields as implemented in plugins/nvidia/skills/physical-ai-neural-reconstruction/SKILL.md:

• repo: HTTPS URL of the upstream repository
• branch: Target Git branch (typically main)
• skills_dir: Path inside the upstream repo where skills live (e.g., .agents/skills/)
• skills_dir_alias: Alias used for path resolution (e.g., skills/)
• index_skill: Path to the upstream index skill file
• index_skill_name: Canonical name of the index skill (e.g., nurec-index)
• sibling_skills: Map of related downstream skills with folder paths and upstream URLs
• upstream_clone_path: Default local clone path using environment variable fallbacks
• upstream_override_env: Environment variable allowing path override (e.g., NUREC_SKILLS_UPSTREAM_ROOT)

The sibling_skills map is particularly critical for complex ecosystems like NuRec, defining relationships to skills such as physical-ai-datasets, ncore, nre, asset-harvester, and nurec-fixer, each with their own folder and upstream specifications.

Real-World Implementation Examples

The following example from plugins/nvidia/skills/physical-ai-neural-reconstruction/SKILL.md demonstrates a complete, valid NVIDIA frontmatter block:

---
name: physical-ai-neural-reconstruction
description: "Router for NVIDIA NuRec/NRE: USDZ rendering, NCore conversion, 3DGS, gRPC sensor sim, PhysicalAI HF datasets. Do NOT use for SimReady or infra setup."
license: Apache-2.0
version: "0.3.0"
tools:
  - Read
  - Shell
compatibility: >-
  Router skill; downstream sibling skills require Docker, NVIDIA Container Toolkit,
  GPU, NGC API key, Hugging Face token with PhysicalAI gated licenses, Python 3.10+.
metadata:
  author: NVIDIA Physical AI
  tags:
    - physical-ai
    - nurec
    - neural-reconstruction
    - router
    - sensor-sim
  upstream:
    repo: https://github.com/NVIDIA/nurec-skills
    branch: main
    skills_dir: .agents/skills/
    skills_dir_alias: skills/
    index_skill: .agents/skills/SKILL.md
    index_skill_name: nurec-index
    sibling_skills:
      physical-ai-datasets:
        folder: physical-ai-datasets/
        upstream: https://huggingface.co/nvidia
      ncore:
        folder: ncore/
        upstream: https://github.com/NVIDIA/ncore
      nre:
        folder: nre/
        upstream: nvcr.io/nvidia/nre/nre
      asset-harvester:
        folder: asset-harvester/
        upstream: https://github.com/NVIDIA/asset-harvester
      nurec-fixer:
        folder: nurec-fixer/
        upstream: https://github.com/NVIDIA/harmonizer
        hf_model: https://huggingface.co/nvidia/DiffusionHarmonizer
  upstream_clone_path: "${PHYSICAL_AI_SKILL_HUB_UPSTREAM_ROOT:-$HOME/.physical-ai-skill-hub/upstreams}/nurec-skills"
  upstream_override_env: NUREC_SKILLS_UPSTREAM_ROOT
---

A second implementation in plugins/nvidia/skills/omniverse-usd-performance-tuning/SKILL.md follows the identical schema, differing only in name, description, and sibling skill mappings:

---
name: omniverse-usd-performance-tuning
description: "Diagnose and optimize USD scene performance in NVIDIA Omniverse workflows."
license: Apache-2.0
version: "0.1.0"
tools:
  - Read
  - Shell
compatibility: >-
  Requires an NVIDIA GPU, Omniverse USD library, and the `usd-optimize` toolset.
metadata:
  author: NVIDIA Physical AI
  tags:
    - omniverse
    - usd
    - performance
  upstream:
    repo: https://github.com/NVIDIA-omniverse/usd-optimize
    branch: main
    skills_dir: .agents/skills/
    index_skill: .agents/skills/SKILL.md
    index_skill_name: usd-optimize-index
    sibling_skills:
      usd-validate:
        folder: validators/
        upstream: https://github.com/NVIDIA-omniverse/usd-optimize
      usd-optimize:
        folder: optimizers/
        upstream: https://github.com/NVIDIA-omniverse/usd-optimize
  upstream_clone_path: "${OMNIVERSE_SKILL_HUB_UPSTREAM_ROOT:-$HOME/.omniverse-skill-hub/upstreams}/usd-optimize"
  upstream_override_env: USD_OPTIMIZE_UPSTREAM_ROOT
---

Why the Frontmatter Convention Matters

The strict frontmatter convention for NVIDIA plugin skills serves four critical functions in the openai/plugins ecosystem:

• Discovery: Codex scans every SKILL.md file, extracts the frontmatter, and constructs an internal skill graph based on name and tags fields.
• Routing: The name field and upstream.sibling_skills mappings allow the model to match user intent (e.g., "render a NuRec scene") to the correct downstream implementation.
• Versioning and Compatibility: The version string and compatibility text prevent runtime errors by clarifying Docker, GPU, and API key requirements before execution.
• Upstream Linkage: The upstream object eliminates code duplication by maintaining router logic in the openai/plugins repository while heavy implementations remain in NVIDIA’s canonical repositories (e.g., https://github.com/NVIDIA/nurec-skills).

Summary

• NVIDIA plugin skills in the openai/plugins repository use YAML frontmatter enclosed in triple dashes at the start of SKILL.md files.
• Required top-level fields include name, description, license, version, tools, compatibility, and a nested metadata object.
• The metadata.upstream field contains repository URLs, branch specifications, sibling skill mappings, and environment variable overrides for local path configuration.
• Real-world implementations in paths such as plugins/nvidia/skills/physical-ai-neural-reconstruction/SKILL.md follow this exact schema to enable Codex routing and discovery.
• This convention ensures version control, runtime compatibility checking, and clean separation between routing logic and heavy implementation code.

Frequently Asked Questions

What file uses the frontmatter convention in NVIDIA plugin skills?

The frontmatter convention applies to SKILL.md files located within skill directories under plugins/nvidia/skills/. Some viewer-specific skills use skill-card.md instead, but both follow the identical YAML schema enclosed in triple dashes.

How does the upstream field handle sibling skills?

The upstream.sibling_skills field contains a map where each key represents a related skill name, and its value is an object specifying the folder path and upstream URL. This allows a single router skill to delegate tasks to specialized downstream skills such as ncore, nre, or asset-harvester without embedding their logic.

What is the purpose of the compatibility field?

The compatibility field provides free-form text describing runtime prerequisites such as Docker, NVIDIA Container Toolkit, GPU requirements, and necessary API keys. This field prevents execution failures by declaring environmental dependencies before Codex attempts to invoke the skill.

Can the upstream repository location be customized?

Yes. The upstream_clone_path field supports environment variable interpolation with fallbacks (e.g., ${PHYSICAL_AI_SKILL_HUB_UPSTREAM_ROOT:-$HOME/.physical-ai-skill-hub/upstreams}/nurec-skills), while upstream_override_env specifies an environment variable (such as NUREC_SKILLS_UPSTREAM_ROOT) that users can set to override the default clone location.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}