feat(plugins): YAML-driven plugin catalog + Claude/Codex marketplaces

[jasonnvidia]

Summary

Adds an NVIDIA-branded plugin layer on top of the existing skills/ catalog so the same skills can be installed via Claude marketplace (claude plugin install) and Codex marketplace (codex plugin add), without duplicating skill content or fragmenting curation.

The substantive change is infrastructure (~140 lines of Python in .github/scripts/build-plugins.py, ~30 lines added to sync-skills.yml, a new 78-line validate-plugins.yml workflow); the rest of the diff is the first plugin definition (plugins.d/nvidia-skills.yml) and its generated artifacts under plugins/nvidia-skills/.

The daily skills sync continues to be the only producer of skills/. Plugin trees are derived from skills/ plus per-plugin YAML, regenerated atomically inside the same sync run, and validated on every PR.

---

What this adds

1. plugins.d/ — plugin catalog YAML

One file per plugin, plus _defaults.yml for shared author/license/capability fields. The first plugin defined is nvidia-skills curating two cuopt skills.

plugins.d/
├── _defaults.yml         # shared defaults (skill_files: copy, license, brand color, …)
├── nvidia-skills.yml     # the NVIDIA-official plugin spec
└── README.md             # schema + onboarding instructions

Per-plugin YAML controls:

• identity (name, display_name, description, keywords)
• curation (include_skills: — list of paths under skills/)
• materialization mode (skill_files: copy | symlink — see below)
• per-marketplace opt-out (marketplace_enabled.{claude,codex}: false)

2. .github/scripts/build-plugins.py — derived-artifact generator

Idempotent build script that, from plugins.d/ and skills/, regenerates:

• plugins/<name>/skills/<skill>/ — curated subset, materialized as either real-dir copies (rsync) or relative symlinks
• plugins/<name>/.claude-plugin/plugin.json — Anthropic plugin manifest
• plugins/<name>/.codex-plugin/plugin.json — OpenAI Codex plugin manifest with interface block
• entries in .claude-plugin/marketplace.json and .agents/plugins/marketplace.json (top-level fields preserved; plugins: array rebuilt)

Modes:

skill_files:	What lands in plugins/<name>/skills/	Required when
copy (default)	rsync'd real directories	shipping to Codex (codex plugin add silently drops symlinks during install) — confirmed empirically against codex 0.132
symlink	relative symlinks → ../../../skills/<Product>/<skill>	Claude-only or npx skills add consumers; avoids duplicated SKILL.md

The current default (copy) keeps every consumer happy at the cost of duplicated SKILL.md content under plugins/. Plugins can opt into symlink per-file when Codex isn't a target.

3. .github/workflows/validate-plugins.yml — drift guard

Runs on PRs touching plugins.d/, skills/, plugins/, either marketplace.json, or the build script. Re-runs build-plugins.sh --check, which rebuilds into the working tree and exits non-zero if the committed plugin tree drifted from the YAML + skills sources.

4. .github/workflows/sync-skills.yml — one new step

Inserted between the existing Track dropped skills and Regenerate README tables steps:

      - name: Rebuild plugin catalog
        run: |
          set -euo pipefail
          .github/scripts/build-plugins.sh
          if ! git diff --quiet plugins/ \
              .claude-plugin/marketplace.json \
              .agents/plugins/marketplace.json; then
            if ! grep -qx "- plugin catalog" /tmp/changed-components.txt 2>/dev/null; then
              echo "- plugin catalog" >> /tmp/changed-components.txt
            fi
          fi

This regenerates copy-mode plugin trees atomically in the same PR as the upstream skills update, so validate-plugins.yml --check is never red on a sync PR.

---

How it all fits together

                 cron 06/18 UTC
                       │
         ┌─────────────▼─────────────┐
         │  sync-skills.yml          │
         │  ① rsync from product     │
         │     repos → skills/       │
         │  ② enforce sig+card,      │
         │     drop non-compliant    │
         │  ③ track dropped skills   │
         │  ④ rebuild plugin catalog │  ← NEW
         │     (build-plugins.sh)    │
         │  ⑤ regenerate-readme.sh   │
         │  ⑥ open PR                │
         └─────────────┬─────────────┘
                       │
                  PR opens
                       │
         ┌─────────────▼─────────────┐
         │  validate-plugins.yml     │  ← NEW
         │  build-plugins.sh --check │
         │     (drift guard)         │
         └───────────────────────────┘

skills/ remains the only source of truth that gets written — the build only derives plugins/, .claude-plugin/marketplace.json, and .agents/plugins/marketplace.json from it.

---

Why this design

A few decisions worth surfacing for review:

1. skills/ is canonical, plugins/ is derived. The build script never edits skills/ and never touches components.d/. This keeps the existing daily-sync invariant intact — no new authoritative directory the team has to remember.

2. Soft-fail policy. Curation references that the daily sync can legitimately invalidate (rename, removal, compliance-driven SKILL.md drop, basename collision) emit warnings and skip the entry instead of dying. The plugin ships with whatever resolved; the sync PR stays mergeable; a maintainer reconciles plugins.d/<plugin>.yml in a follow-up. We hit this empirically when upstream cuopt restructured its skill paths during testing.

3. Two materialization modes, copy as default. Empirical testing showed codex plugin add (codex 0.132) silently drops symlinks during install, leaving the cached plugin's skills/ empty. To keep Codex consumers working out of the box, copy is the default. Plugins that won't ship to Codex can opt into symlink mode and avoid duplicated SKILL.md content.

4. Marketplace identity fields are preserved, not regenerated. The build only rewrites plugins: arrays in marketplace.json files. Top-level name, displayName, metadata.description, owner, etc. are hand-edited and left alone — so the marketplace identity isn't accidentally clobbered by a build run.

5. Curated plugins (plugins/<name>/.skills-manifest.yml) coexist. A plugin directory with a hand-edited manifest skips the catalog-build path entirely; only its skills/ tree is regenerated, and its marketplace.json entry is preserved verbatim. This leaves the door open for a non-NVIDIA-managed plugin that still wants the build system to refresh its skills tree.

---

Testing

Local testing exercised:

• Baseline: build-plugins.sh produces plugins/nvidia-skills/skills/cuopt-routing-api-python/ and cuopt-user-rules/ cleanly in copy mode (real directories with SKILL.md + skill-card.md + skill.oms.sig).
• Drift guard: build-plugins.sh --check is green on a clean working tree, red on hand-edits under plugins/.
• Soft-fail scenarios — each verified to log a clear error/warning and continue:
  • missing include_skills: path on disk (rename/removal)
  • include_skills: path is not a directory (rare upstream change)
  • no SKILL.md under a curated path (compliance enforcement dropped them all)
  • duplicate skill basename across include_skills: entries
  • malformed plugins.d/<x>.yml
  • skill_files: with an invalid value (falls back to copy)
  • bad plugin name (not kebab-case)
  • empty skills: list in a curated .skills-manifest.yml
  • missing name: field in plugins.d
  • duplicate plugin name across plugins.d files
• Symlink mode: confirmed produces relative symlinks resolving correctly through to ../../../skills/<Product>/<skill> and that claude plugin install follows them; confirmed codex plugin add silently drops them (motivating copy as default).
• Mode switch: flipped nvidia-skills.yml between copy and symlink and verified the build cleanly converts the on-disk tree both directions.
• Merge from upstream/main during development: catch'd a real-world skill-rename via the soft-fail path (cuopt skill restructure + NemoClaw removal during an in-flight sync).

CI integration tested:

• validate-plugins.yml --check on this branch → green.

What's not yet tested in production CI:

• The new Rebuild plugin catalog step inside sync-skills.yml running against a real product-repo clone. Recommend manually triggering sync-skills.yml via workflow_dispatch once after merge to validate end-to-end before the next cron tick.

---

Risk assessment

Concern	Likelihood	Impact	Mitigation
Build step fails on ubuntu-latest due to PyYAML install	low	sync fails	wrapper script handles --user then --break-system-packages fallback; same install pattern works in validate-plugins.yml today
Curated cuopt skill renamed/removed by an upstream-product sync	moderate over time	warning logged; plugin ships fewer skills	soft-fail policy — no PR block
First production run hits an environment quirk	low	sync fails on first cron tick	workflow_dispatch smoke-test recommended after merge
PR title slightly longer (now includes "plugin catalog" when applicable)	certain	cosmetic only	accurate summary of what changed

What stays guaranteed-safe:

• No existing step in sync-skills.yml was modified or removed; one step was inserted.
• skills/ is still the only catalog-source written by sync.
• All other workflows (dco, verify-authors, team-request, request-nvskills-ci) untouched.
• Hard-fail still applies to genuine config disasters: missing _defaults.yml, missing marketplace.json, drift-check fail.

---

Follow-up work (deliberately out of scope)

Captured as a TODO comment block in validate-plugins.yml:

• claude plugin validate per generated plugin manifest + claude plugin validate .claude-plugin/marketplace.json (verified locally against @anthropic-ai/claude-code@2.1.145; deferred to keep this PR lean).
• A Codex-side validator. The codex CLI has no plugin validate subcommand; options are an install-as-validator dry-run, a hand-rolled JSON schema check, or skipping (relying on the build's schema parity).

Other follow-ups, not required for this PR:

• Open a plugins-curation-debt tracking issue (mirroring the existing missing-compliance pattern) when soft-fail warnings fire, so curation gaps don't get lost in workflow logs.
• Future plugins (NemoClaw, RAG, VSS, etc.) once those teams' skills stabilize.

---

Test plan

• build-plugins.sh produces clean output in copy mode
• build-plugins.sh produces clean output in symlink mode
• build-plugins.sh --check green on clean tree, red on hand-edits
• All 10 soft-fail scenarios log warnings/errors and continue
• Drift check green after the sync's auto-rebuild step
• workflow_dispatch run of sync-skills.yml after merge confirms the new step works end-to-end against real product repos
• First scheduled sync after merge produces a clean PR

[sayalinvidia]

LGTM! approved workflows to run!

[sayalinvidia]

lgtm! merging