Skip to content

chore(compliance): add skill cards for sourced skills via compliance.d overlay - #25

Merged
ohadmo merged 2 commits into
mainfrom
chore/compliance-overlay
Aug 4, 2026
Merged

chore(compliance): add skill cards for sourced skills via compliance.d overlay#25
ohadmo merged 2 commits into
mainfrom
chore/compliance-overlay

Conversation

@trvachov

@trvachov trvachov commented Aug 4, 2026

Copy link
Copy Markdown
Contributor

Adds skill-card.md for all 14 sourced skills, in a way that survives the nightly sync and retires itself once upstream ships its own cards.

Companion to the three upstream PRs carrying the same card content:
KERMT#26 · Proteina-Complexa#60 · nvMolKit#248

The problem

sync-skills.yml runs rsync -a --delete "$src/" "$catalog_dir/". A skill-card.md committed into a sourced catalog dir is deleted on the next nightly run — not overwritten, deleted. Verified:

$ ls dst/            → SKILL.md  skill-card.md
$ rsync -a --delete src/ dst/
$ ls dst/            → SKILL.md

This is exactly what happened to the KERMT evals, recorded in docs/sync-findings.md. But we can't wait for three upstream PRs to merge before the catalog has cards.

The fix: overlay + backfill

Cards for sourced skills live in compliance.d/<catalog_path>/, outside every rsync target and every prune root. A new workflow step copies them in after the rsync, and only where the rsync left no card:

  • Immediate — cards present in the catalog on merge, surviving every sync
  • Upstream always wins — the moment a source repo ships its own card, rsync lands it and the backfill becomes a no-op. No flag to flip, no coordination
  • Self-retiring, with a signal — the sync PR body now reports both the outstanding debt (backfilled) and entries upstream has made redundant (retirable, i.e. delete them)

skill.oms.sig is deliberately NOT backfilled

A signature attests to specific bytes. Copying one over content it wasn't generated from publishes an artifact that fails verification — and NVIDIA/skills' sync has a dedicated defense that hash-checks exactly this case and reverts the skill. Signing stays a per-source-repo nvskills-ci task. Same reasoning for evals (SRC-10).

Scope

Catalog path Source repo Skills
open-models-skills/kermt/* NVIDIA-BioNeMo/KERMT 8
open-models-skills/proteina-complexa/* NVIDIA-BioNeMo/Proteina-Complexa 5
library-skills/nvMolKit NVIDIA-BioNeMo/nvMolKit 1

The other 17 skills are native and take cards directly in-tree — not in this PR.

Validation

No CI will run on this PR — neither plugin-sync.yml nor skill-security.yml has a path filter matching compliance.d/** or .github/workflows/sync-skills.yml, and sync-skills.yml itself only runs on schedule/dispatch. So the riskiest part of this change first executes unattended at 07:00 UTC. Verified by hand instead:

  • backfill logic simulated against a fixture for all three cases — absent → backfilled, already present → upstream wins, orphaned overlay entry → warned and skipped
  • bash -n on every run: block in the workflow → all pass
  • workflow parses as YAML; step ordering correct (after prune, before payload rebuild)
  • python3 scripts/plugin_sync.py --check → OK, 31 skills, payload matches source

That gap is worth closing separately — either extend plugin-sync.yml's path filter to cover the sync workflow, or add a small job that exercises the backfill against a fixture. Happy to follow up.

Heads-up on conflicts

⚠️ This touches .github/workflows/sync-skills.yml, which #15 also modifies. Worth sequencing with @ohadmo rather than merging blind.

Also noted while writing the Complexa cards: .gitignore in Proteina-Complexa ignores .claude/ wholesale while the skills inside are tracked, so new files added to a Complexa skill dir are silently dropped unless force-added. Fixed as a separable commit in Proteina-Complexa#60.

🤖 Generated with Claude Code

…d overlay

Sourced skills are rsynced with --delete, so a skill-card.md committed into a
catalog dir is deleted on the next nightly sync (this is what happened to the
KERMT evals, per docs/sync-findings.md). Cards for the 14 sourced skills
therefore live in compliance.d/<catalog_path>/, outside every rsync target and
prune root, and are copied in after the rsync by a new workflow step.

Upstream always wins: the backfill copies a card only where the rsync left none,
so a source repo shipping its own card supersedes the overlay automatically with
no flag to flip. The sync PR body reports both the outstanding debt (backfilled)
and entries that upstream has since made redundant (retirable).

skill.oms.sig is deliberately NOT backfilled — a signature attests to specific
bytes, and copying one over content it was not generated from publishes an
artifact that fails verification. Signing stays a per-source-repo nvskills-ci
task.

The same 14 cards are opened as PRs against KERMT, Proteina-Complexa, and
nvMolKit so the overlay is retired as those merge.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Timur Rvachov <trvachov@nvidia.com>
@ohadmo
ohadmo self-requested a review August 4, 2026 22:08
…repo

Signed-off-by: Ohad Mosafi <omosafi@nvidia.com>
@ohadmo
ohadmo merged commit b4aa179 into main Aug 4, 2026
1 check passed
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