How the NVIDIA Skill Enforces a Strict Milestone Chain in OpenAI Plugins

The NVIDIA skill enforces a strict milestone chain through declarative phase definitions in SKILL.md, router-level upstream dependency checks in agents/openai.yaml, and runtime pre-flight scripts that validate the existence of predecessor marker files before allowing execution to proceed.

The openai/plugins repository hosts NVIDIA skills such as Physical-AI Neural Reconstruction and Omniverse USD Performance Tuning that rely on a strict milestone chain to ensure correct execution order. This architectural pattern guarantees that complex, multi-stage pipelines—spanning dataset preparation to final rendering—execute sequentially without allowing users to skip critical intermediate steps.

Declarative Milestone Definitions in SKILL.md

Each skill’s SKILL.md file serves as the source of truth for the ordered milestone workflow. In plugins/nvidia/skills/physical-ai-neural-reconstruction/SKILL.md, the required phases are explicitly sequenced: dataset preparation → NCore conversion → Asset Harvester → NuRec rendering → DiffusionHarmonizer.

The companion workflow documentation in plugins/nvidia/skills/physical-ai-neural-reconstruction/references/workflows.md reinforces this structure by providing a structured milestone list. These files assign symbolic names to each stage (e.g., profile-stage:baseline, so-run-validators) and explicitly warn against skipping phases, establishing the contractual requirements for the strict milestone chain.

Router Enforcement via Upstream Dependencies

The skill’s router implements the primary enforcement mechanism by declaring upstream dependencies for each downstream sibling skill. This configuration resides in the skill card and agent definitions.

The agents/openai.yaml Configuration

The agents/openai.yaml file contains an upstream field that specifies prerequisite skills and their corresponding marker files. The router checks the current environment for the presence of these required artifacts before permitting execution.

# plugins/nvidia/skills/physical-ai-neural-reconstruction/agents/openai.yaml

upstream:
  - repo: https://github.com/NVIDIA/nurec-skills
    skill: ncore
    required_marker: .milestone-ncore-done
  - repo: https://github.com/NVIDIA/nurec-skills
    skill: asset-harvester
    required_marker: .milestone-asset-harvester-done

If a prerequisite milestone’s artifact is missing, the router aborts with a clear error, preventing the user from jumping ahead in the pipeline.

Runtime Validation with Pre-Flight Scripts

Automated checks in pre-flight scripts provide a secondary layer of enforcement. These scripts perform runtime validation of GPU driver versions, Docker and NVIDIA Container Toolkit availability, and—critically—the existence of prior-stage containers and marker files.

Marker File Persistence

After a milestone finishes, the skill writes a marker file (e.g., .milestone-ncore-done) into the skill’s work directory. Subsequent steps read these markers to verify that the chain is intact. This persistence mechanism enforces strict ordering across separate invocations and container restarts.

The following excerpt from the infrastructure setup skill demonstrates how the script validates both system requirements and milestone prerequisites:

# plugins/nvidia/skills/physical-ai-infrastructure-setup-and-resilient-scaling/components/cluster-microk8s/scripts/preflight.sh

MIN_NVIDIA_DRIVER_VERSION="525"
if ! check_driver "${MIN_NVIDIA_DRIVER_VERSION}"; then
  echo "❌ NVIDIA driver version too low – previous milestones must be completed first."
  exit 1
fi

# look for marker from previous milestone

if [ ! -f "${WORKDIR}/.milestone-dataset-download-done" ]; then
  echo "❌ Dataset download milestone not finished – cannot start NCore conversion."
  exit 1
fi
echo "✅ All prerequisite milestones satisfied – proceeding with NCore conversion."

Workflow Documentation Guardrails

The strict milestone chain is further reinforced through documentation-driven guardrails. Files such as plugins/nvidia/skills/omniverse-usd-performance-tuning/references/workflow.md provide structured milestone lists for USD performance tuning, explicitly describing how each stage builds on the previous one. These references embed guardrails that automated tooling respects, refusing to launch downstream containers unless upstream milestones are flagged as completed.

Summary

• Declarative definitions: SKILL.md and references/workflows.md explicitly list the ordered phases of the strict milestone chain.
• Router validation: The upstream configuration in agents/openai.yaml blocks execution if required markers from previous milestones are absent.
• Runtime checks: Pre-flight scripts like preflight.sh verify system requirements and check for marker files (e.g., .milestone-dataset-download-done) before proceeding.
• State persistence: Marker files written to the work directory maintain milestone state across container restarts and separate invocations.
• Documentation enforcement: Reference files embed strict sequencing rules that automated tools consult before executing downstream stages.

Frequently Asked Questions

What happens if a prerequisite milestone is missing?

The router aborts execution immediately. In agents/openai.yaml, the upstream field defines required markers for each skill; if .milestone-ncore-done or similar files are not detected, the skill returns an error before initializing any downstream containers.

How does the router check for milestone completion?

The router inspects the skill’s work directory for specific marker files defined in the required_marker property of the upstream configuration. These files are created only when a milestone successfully completes, serving as immutable proof of progress.

Can the strict milestone chain be bypassed?

No. The enforcement operates at multiple levels: declarative configuration in SKILL.md, runtime checks in pre-flight scripts, and router-level upstream dependencies. Even if a user attempts manual execution, the preflight.sh scripts verify marker files and will exit with an error code if the chain is broken.

Where are milestone markers stored?

Markers are stored as hidden files in the skill’s work directory (e.g., ${WORKDIR}/.milestone-ncore-done). These files persist across container restarts and are tracked by both the validation scripts and the router’s upstream dependency checker.

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