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

> Learn the NVIDIA plugin skills frontmatter convention using YAML schema and metadata standards. Discover how to define name, version, tools, and upstream objects for Codex discovery and routing.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: best-practices
- Published: 2026-09-13

---

**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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md) file (or [`skill-card.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/pyproject.toml).

### Runtime Requirements

The `tools` field enumerates required capabilities as a YAML list:

```yaml
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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/nvidia/skills/physical-ai-neural-reconstruction/SKILL.md) demonstrates a complete, valid NVIDIA frontmatter block:

```yaml
---
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`](https://github.com/openai/plugins/blob/main/plugins/nvidia/skills/omniverse-usd-performance-tuning/SKILL.md) follows the identical schema, differing only in `name`, `description`, and sibling skill mappings:

```yaml
---
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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md) files located within skill directories under `plugins/nvidia/skills/`. Some viewer-specific skills use [`skill-card.md`](https://github.com/openai/plugins/blob/main/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.