# SPDX-License-Identifier: Apache-2.0 # Copyright (c) 2026 NVIDIA Corporation. All rights reserved. # # Sync skills from product repos into the nvidia/skills catalog. # Reads component definitions from components.d/*.yml (one file per # component) — teams onboard by adding their own file there, not by # editing this workflow or any shared file. # # Requires a PAT (SKILLS_SYNC_PAT) with read access to all product # repos, stored as a repository secret. name: Sync Skills from Product Repos on: schedule: # Hourly - cron: "0 * * * *" workflow_dispatch: # Allow manual trigger permissions: contents: write pull-requests: write issues: write concurrency: group: sync-skills cancel-in-progress: true jobs: sync: runs-on: ubuntu-latest steps: - name: Checkout skills catalog uses: actions/checkout@v4 with: ref: main - name: Verify yq is available run: yq --version - name: Sync skills from product repos env: GH_TOKEN: ${{ secrets.SKILLS_SYNC_PAT }} run: | set -euo pipefail truncate -s 0 /tmp/rsynced-components.txt truncate -s 0 /tmp/changed-components.txt truncate -s 0 /tmp/failed-components.txt truncate -s 0 /tmp/sync-versions.txt truncate -s 0 /tmp/rsynced-skill-dirs.txt # Aggregate per-component files into a single config so the # iteration loop below can index by position. The components.d/ # layout means concurrent onboarding PRs never touch a shared # file — see components.d/README.md for the schema. CONFIG=/tmp/components.aggregated.yml yq ea '[.] | {"components": .}' components.d/*.yml > "$CONFIG" # Configure git to use the token via credential helper # so it never appears in clone URLs or error output git config --global credential.helper '!f() { echo "username=x-access-token"; echo "password=${GH_TOKEN}"; }; f' component_count=$(yq '.components | length' "$CONFIG") for i in $(seq 0 $((component_count - 1))); do name=$(yq -r ".components[$i].name" "$CONFIG") repo=$(yq -r ".components[$i].repo" "$CONFIG") ref=$(yq -r ".components[$i].ref // \"main\"" "$CONFIG") echo "── $name ──" # Keep separate checkouts for components that share a source repo. tmp_dir=".tmp/${i}-$(echo "$repo" | tr '/' '-')" if ! git clone --depth 1 --filter=blob:none --sparse \ "https://github.com/${repo}.git" \ "$tmp_dir" -b "$ref" 2>/dev/null; then echo " ⚠ Clone failed for $repo — skipping" echo "- **$name** ($repo): clone failed" >> /tmp/failed-components.txt continue fi # Capture upstream HEAD info for the README Version column upstream_sha=$(git -C "$tmp_dir" rev-parse HEAD) upstream_short_sha=$(git -C "$tmp_dir" rev-parse --short HEAD) upstream_date=$(git -C "$tmp_dir" show -s --format=%cs HEAD) slug=$(echo "$name" | tr 'A-Z ' 'a-z-') echo "$slug|$upstream_short_sha|$upstream_sha|$upstream_date|$repo" >> /tmp/sync-versions.txt # Collect all skill paths for sparse checkout skill_count=$(yq -r ".components[$i].skills | length" "$CONFIG") sparse_paths="" for j in $(seq 0 $((skill_count - 1))); do path=$(yq -r ".components[$i].skills[$j].path" "$CONFIG") sparse_paths="$sparse_paths $path" done (cd "$tmp_dir" && git sparse-checkout set $sparse_paths 2>/dev/null) || true # Copy each skill path to its catalog directory synced=false for j in $(seq 0 $((skill_count - 1))); do path=$(yq -r ".components[$i].skills[$j].path" "$CONFIG") catalog_dir=$(yq -r ".components[$i].skills[$j].catalog_dir" "$CONFIG") src="$tmp_dir/$path" if [ -d "$src" ] && [ -n "$(ls -A "$src" 2>/dev/null)" ]; then mkdir -p "skills/$catalog_dir" rsync -a --delete "$src/" "skills/$catalog_dir/" synced=true # Exact rsynced destination — used by the drift-detection # step to scan only the dirs this run actually touched # (nesting-safe; not derived by awk-extracting paths). echo "skills/$catalog_dir" >> /tmp/rsynced-skill-dirs.txt echo " ✓ $path → skills/$catalog_dir/" else echo " ⚠ $path empty or missing — skipping to preserve existing catalog" echo "- **$name** ($repo): \`$path\` empty or missing" >> /tmp/failed-components.txt fi done # Record successful rsync (used by the "fail if nothing synced" # health check) separately from actual content changes (used # for the PR title and body) — a component can rsync cleanly # yet have no diff when upstream is unchanged. if $synced; then echo "- $name" >> /tmp/rsynced-components.txt for j in $(seq 0 $((skill_count - 1))); do catalog_dir=$(yq -r ".components[$i].skills[$j].catalog_dir" "$CONFIG") if [ -n "$(git status --porcelain "skills/$catalog_dir" 2>/dev/null)" ]; then echo "- $name" >> /tmp/changed-components.txt break fi done fi echo "" done rm -rf .tmp - name: Fail if nothing synced run: | if [ ! -s /tmp/rsynced-components.txt ]; then echo "::error::All component checkouts failed — no skills were synced" exit 1 fi - name: Detect signature drift in rsync run: | set -euo pipefail # Signature drift = the rsync changed files under skills// # but did NOT change skills//skill.oms.sig. The on-source # signature is therefore stale relative to the on-source content, # and landing it would break cryptographic verification on the # next "Verify Signed Skills" sweep. # # Recovery: # - Skill existed on main → revert the catalog dir to its # pre-rsync (signed) state. The signed version stays live; # the unsigned update is held until the source team runs # /nvskills-ci and the next sync picks up the fresh sig. # - New skill (no prior version on main) → drop outright. # # Both cases are recorded in /tmp/dropped-skills.txt with a # reason string starting with "sig drift", so the # "Track dropped skills" step surfaces them in the rolling # tracker issue alongside missing-artifact drops. dropped=/tmp/dropped-skills.txt touch "$dropped" # Scan the EXACT catalog dirs the rsync targeted this run, # recorded by the previous step into /tmp/rsynced-skill-dirs.txt. # This is nesting-safe (handles `skills//` as # well as the flat `skills/` layout) and avoids the # bugs of awk-extracting "skills/$1/$2" from git output — # that approach collapsed multi-skill products to one entry, # masking drift on sibling skills and misclassifying new # skills under existing products as "existing on main." # # If the file doesn't exist (extremely defensive — the rsync # step always creates it), exit cleanly with no drift found. if [ ! -f /tmp/rsynced-skill-dirs.txt ]; then echo " (no rsync targets recorded — nothing to scan for drift)" exit 0 fi sort -u -o /tmp/rsynced-skill-dirs.txt /tmp/rsynced-skill-dirs.txt # Newline-safe iteration — catalog dirs shouldn't contain # spaces but defensive against that ever changing. while IFS= read -r dir; do [ -z "$dir" ] && continue # Defense #1: rsynced dir has no skill.oms.sig at all (source # never carried one, or source-side sig got deleted). Compliance # would also drop these later, but compliance always rm -rf's — # it can't preserve a prior signed version. Handle it here so a # previously-signed catalog skill survives a source-side sig # deletion (revert to HEAD) rather than being wiped. if [ ! -f "$dir/skill.oms.sig" ]; then product=$(echo "$dir" | awk -F/ '{print $2}') if git ls-tree HEAD -- "$dir/skill.oms.sig" | grep -q .; then reason="sig missing: reverted (source has no skill.oms.sig; preserving prior signed version)" echo "$product|$dir|$reason" >> "$dropped" echo " ↩ $dir — $reason — reverting to HEAD" git checkout HEAD -- "$dir/" git clean -fdx -- "$dir/" >/dev/null else reason="sig missing: dropped (new skill, no skill.oms.sig in source)" echo "$product|$dir|$reason" >> "$dropped" echo " ✗ $dir — $reason" rm -rf "$dir" fi continue fi # Defense #2: classic drift — rsync changed files but did NOT # change skill.oms.sig. The on-source signature is stale # relative to its content; landing it would break crypto # verification on the next "Verify Signed Skills" sweep. # # NOTE on the deleted-sig-with-content-edit case: if rsync # deletes skill.oms.sig alongside content edits, the deletion # appears in `git diff` so sig_changed matches and drift is # NOT flagged here. That case lands as "no sig file" on the # next sync and is caught by Defense #1 above. modified=$(git diff --name-only HEAD -- "$dir/" 2>/dev/null || true) untracked=$(git ls-files --others --exclude-standard -- "$dir/" 2>/dev/null || true) changed=$(printf '%s\n%s\n' "$modified" "$untracked" | sed '/^$/d') if [ -z "$changed" ]; then continue fi # Match only the root sig at "$dir/skill.oms.sig" — a nested # file like "$dir/docs/skill.oms.sig" would not count as a # sig refresh, since compliance requires the root signature. sig_path="$dir/skill.oms.sig" sig_changed=$(echo "$changed" | grep -Fx -- "$sig_path" || true) non_sig_changed=$(echo "$changed" | grep -Fvx -- "$sig_path" || true) if [ -n "$non_sig_changed" ] && [ -z "$sig_changed" ]; then product=$(echo "$dir" | awk -F/ '{print $2}') file_count=$(echo "$non_sig_changed" | wc -l | tr -d ' ') if git ls-tree HEAD -- "$dir" | grep -q .; then reason="sig drift: reverted ($file_count file(s) changed without skill.oms.sig refresh)" echo "$product|$dir|$reason" >> "$dropped" echo " ↩ $dir — $reason — reverting to HEAD" git checkout HEAD -- "$dir/" # -x clears ignored files too so the dir matches HEAD exactly. git clean -fdx -- "$dir/" >/dev/null else reason="sig drift: dropped ($file_count file(s) without skill.oms.sig — new skill, no prior version)" echo "$product|$dir|$reason" >> "$dropped" echo " ✗ $dir — $reason" rm -rf "$dir" fi fi # Defense #3: signed-but-inconsistent — the rsync delivered a # sig refresh (with or without content edits), but the incoming # content does not hash-match the incoming signature. The source # repo itself is internally inconsistent (skill files edited # after the signing run, or a pipeline ordering fault). Landing # it would publish content that fails public signature # verification — and bot sync PRs run no CI, so this loop is # the only gate on the ingestion path. Verification mirrors # .github/scripts/verify_content_integrity.py (digest compare # of every signed resource; missing files count as mismatches). if [ -n "$sig_changed" ]; then mismatch=$(python3 - "$dir" <<'PYEOF' import base64, hashlib, json, sys from pathlib import Path d = Path(sys.argv[1]) try: bundle = json.loads((d / "skill.oms.sig").read_text()) stmt = json.loads(base64.b64decode(bundle["dsseEnvelope"]["payload"])) resources = stmt["predicate"]["resources"] except Exception: # Malformed bundle: treat as one mismatch so the skill is held # rather than published unverifiable. print(1) sys.exit(0) bad = 0 for res in resources: target = d / res["name"] if not target.is_file(): bad += 1 continue if hashlib.sha256(target.read_bytes()).hexdigest() != res["digest"]: bad += 1 print(bad if bad else "") PYEOF ) if [ -n "$mismatch" ]; then product=$(echo "$dir" | awk -F/ '{print $2}') if git ls-tree HEAD -- "$dir" | grep -q .; then reason="sig mismatch: reverted ($mismatch signed file(s) do not match the incoming skill.oms.sig; source repo is internally inconsistent — re-run signing at source)" echo "$product|$dir|$reason" >> "$dropped" echo " ↩ $dir — $reason — reverting to HEAD" git checkout HEAD -- "$dir/" git clean -fdx -- "$dir/" >/dev/null else reason="sig mismatch: dropped ($mismatch signed file(s) do not match skill.oms.sig — new skill, no prior version)" echo "$product|$dir|$reason" >> "$dropped" echo " ✗ $dir — $reason" rm -rf "$dir" fi fi fi done < /tmp/rsynced-skill-dirs.txt # Mark any product with a dropped skill as "changed" so the PR # opens (matches the pattern used by the compliance step). # `--` and `-F` are explicit so the leading "-" in the pattern # isn't parsed as a grep option. if [ -s "$dropped" ]; then while IFS='|' read -r product _ _; do if ! grep -Fqx -- "- $product" /tmp/changed-components.txt 2>/dev/null; then echo "- $product" >> /tmp/changed-components.txt fi done < "$dropped" fi - name: Enforce skill compliance (signature + card) env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} run: | set -euo pipefail # Every catalog skill (defined by SKILL.md) must ship with: # - skill.oms.sig (detached NVIDIA signature) # - skill-card.md (skill metadata card) # - eval data (Tier-3 evaluation dataset). Accepted in any # of these forms — semantic equivalence, # not literal-filename: # * evals.json anywhere in the skill dir # (canonical — recursive find) # * any *.json under skills//evals/ # * any *.json under skills//eval/ # This accepts multi-profile datasets like # eval/h100.json + eval/nvidia_hosted.json # (RAG Blueprint pattern), benchmark/evals.json # (cuopt-developer pattern), and the # canonical evals/evals.json layout. # Skills missing any of these are dropped from the catalog # before the PR is created — non-compliant skills do not merge. # # Append-only: the preceding "Detect signature drift" step # writes to the same /tmp/dropped-skills.txt with "sig drift:" # prefixed reasons. Do NOT truncate here — that would wipe # drift records. dropped=/tmp/dropped-skills.txt touch "$dropped" while IFS= read -r skill_md; do dir=$(dirname "$skill_md") missing="" [ -f "$dir/skill.oms.sig" ] || missing="$missing skill.oms.sig" [ -f "$dir/skill-card.md" ] || missing="$missing skill-card.md" # Eval dataset: accept canonical evals.json, OR any *.json # under eval/ or evals/ subdir (multi-profile datasets). has_eval="" if [ -n "$(find "$dir" -type f -name evals.json -print -quit 2>/dev/null)" ]; then has_eval=1 elif [ -d "$dir/evals" ] && \ [ -n "$(find "$dir/evals" -maxdepth 1 -type f -name '*.json' -print -quit 2>/dev/null)" ]; then has_eval=1 elif [ -d "$dir/eval" ] && \ [ -n "$(find "$dir/eval" -maxdepth 1 -type f -name '*.json' -print -quit 2>/dev/null)" ]; then has_eval=1 fi [ -n "$has_eval" ] || missing="$missing evals.json" if [ -n "$missing" ]; then product=$(echo "$dir" | awk -F/ '{print $2}') # Prefixed reason so the tracker-issue partition splits # cleanly into missing-artifacts / orphan / sig-drift. echo "$product|$dir|missing artifacts: $(echo "$missing" | xargs)" >> "$dropped" echo " ✗ Dropping $dir — missing:$missing" rm -rf "$dir" fi done < <(find skills -type f -name SKILL.md) # Drop top-level product directories with no SKILL.md anywhere # inside. These show up as misleading empty/helper-only folders # to anyone browsing the catalog (e.g. a product placeholder # with just a README, or a product whose every skill was just # dropped above). for product_dir in skills/*/; do product_dir="${product_dir%/}" if [ -z "$(find "$product_dir" -type f -name SKILL.md -print -quit 2>/dev/null)" ]; then product=$(basename "$product_dir") echo "$product|$product_dir|orphan: no SKILL.md inside" >> "$dropped" echo " ✗ Dropping orphan $product_dir — no SKILL.md inside" rm -rf "$product_dir" fi done # Mark any product with a dropped skill as "changed" so the PR # opens even when the only diff is a removed non-compliant skill. # `-F` literal, `--` to stop option parsing (pattern starts with "-"). if [ -s "$dropped" ]; then while IFS='|' read -r product _ _; do if ! grep -Fqx -- "- $product" /tmp/changed-components.txt 2>/dev/null; then echo "- $product" >> /tmp/changed-components.txt fi done < "$dropped" fi - name: Prune orphaned skill dirs # Remove skills/ dirs whose components.d registration was removed. # Teams consistently assume deregistering also removes the catalog # copy (Dynamo, TAO, cuOpt all hit this) — this step makes that # true. Capped + parse-guarded; see the script header for the # safety rails, and catalog-exceptions.yml for dirs # that are intentionally unregistered. run: | bash .github/scripts/prune-orphans.sh if [ -s /tmp/pruned-orphans.txt ]; then echo "- orphan pruning" >> /tmp/changed-components.txt fi - name: Resolve skill contacts # For each dropped/reverted skill, resolve the original onboarder # via git blame on the owning components.d/.yml and emit a # mapping (catalog_dir → @github-login) into /tmp/skill-contacts.txt. # Downstream steps (tracker issue body, sync PR body) read this # file and @-mention the contact so the source-team owner is # notified directly instead of via a manual catalog-PIC ping. # # Resolution rules: # - YML owner: first file matching `catalog_dir: ` under # components.d/*.yml (orphans without a YML are skipped with # a warning). # - Author email: `git log --diff-filter=A` on the YML — the # person who added the component is the canonical contact. # - Email → GH login: GitHub user search by email. The repo's # Verify Authors gate guarantees NVIDIA-issued emails, so the # lookup usually resolves. If it doesn't, we emit a loud # workflow warning rather than silently skipping the tag. # Lookups are cached in-memory across the run to keep API calls # well under the rate limit even on large drop batches. continue-on-error: true env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | set -euo pipefail dropped=/tmp/dropped-skills.txt contacts=/tmp/skill-contacts.txt : > "$contacts" if [ -s "$dropped" ]; then : else echo " (no dropped skills — nothing to resolve)" exit 0 fi # File-backed cache for email → GH login lookups so we make at # most one API call per unique email even on large drop batches. # File-backed rather than associative array so the step works # under any bash version. cache=/tmp/email-login-cache.txt : > "$cache" while IFS='|' read -r product dir reason; do [ -z "$dir" ] && continue cat_dir=$(basename "$dir") # Find owning YML. Multiple `catalog_dir:` matches across # components.d/ are not expected (uniqueness gate at PR time) # but if it happens we take the first deterministically. # Anchor the match to end-of-line so e.g. catalog_dir "rag" # doesn't false-positive on a line declaring "rag-blueprint". # YAML lines for components.d/*.yml don't carry trailing # comments/whitespace, so $ is a reliable anchor here. owner_yml=$(grep -l "catalog_dir: ${cat_dir}$" components.d/*.yml 2>/dev/null | sort | head -1) if [ -z "$owner_yml" ]; then echo "::warning::no YML owner found for $dir — cannot resolve contact (orphan or schema mismatch)" continue fi # Author of the first commit that added this YML = onboarder. # --diff-filter=A returns the "A"dded entry. tail -1 in case # the YML was added, deleted, and re-added (last A wins). author_email=$(git log --diff-filter=A --format='%ae' -- "$owner_yml" 2>/dev/null | tail -1 || true) if [ -z "$author_email" ]; then echo "::warning::no add-commit author for $owner_yml — cannot resolve contact for $cat_dir" continue fi # Email → GH login lookup. Check cache first. cached=$(awk -F'|' -v e="$author_email" '$1==e {print $2; exit}' "$cache") if [ -n "$cached" ]; then # Cache hit. Sentinel "-" means "tried, got empty" — don't retry. if [ "$cached" = "-" ]; then login="" else login="$cached" fi else # GitHub search by email; +in:email is the qualifier. login=$(gh api "search/users?q=${author_email}+in:email" \ --jq '.items[0].login // empty' 2>/dev/null || echo "") # Persist result (use "-" sentinel for empty so future # lookups hit the cache instead of re-querying). if [ -n "$login" ]; then echo "$author_email|$login" >> "$cache" else echo "$author_email|-" >> "$cache" fi fi if [ -z "$login" ]; then echo "::warning::could not resolve GitHub login for $author_email (onboarder of $owner_yml) — $cat_dir will land without contact tag" continue fi echo "$cat_dir|@$login|$author_email|$owner_yml" >> "$contacts" echo " $cat_dir → @$login (from $author_email via $(basename "$owner_yml"))" done < "$dropped" if [ -s "$contacts" ]; then resolved=$(wc -l < "$contacts" | tr -d ' ') total=$(wc -l < "$dropped" | tr -d ' ') echo "Resolved $resolved/$total contacts." fi - name: Snapshot existing drop-tracker state continue-on-error: true env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | # Save the pre-update issue body so "Ping skill owners" can # determine which drops are new this run vs already tracked. # Writes {} on any failure so downstream steps degrade gracefully. gh issue list --label missing-compliance --state open \ --json number,body --jq '.[0] // {}' --limit 1 \ > /tmp/pre-update-tracker.json 2>/dev/null \ || echo '{}' > /tmp/pre-update-tracker.json - name: Track dropped skills continue-on-error: true env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} run: | set -euo pipefail dropped=/tmp/dropped-skills.txt gh label create missing-compliance \ --color FFA500 \ --description "Catalog skills dropped or reverted by sync — missing artifacts or signature drift" \ --force >/dev/null existing=$(gh issue list --label missing-compliance --state open \ --json number --jq '.[0].number // empty' --limit 1) if [ ! -s "$dropped" ]; then if [ -n "$existing" ]; then gh issue close "$existing" \ --comment "All catalog skills now carry \`skill.oms.sig\`, \`skill-card.md\`, and \`evals.json\`, and no signature drift detected. Closing automatically." echo "All compliant — closed tracking issue #$existing" else echo "All compliant — nothing to track" fi exit 0 fi sort -t'|' -k1,1 -k2,2 -o "$dropped" "$dropped" count=$(wc -l < "$dropped" | tr -d ' ') # Partition by explicit reason prefix: "missing artifacts:" / # "orphan:" / "sig drift:" / "sig missing:". Anything that # doesn't match a known prefix is grouped under "Other" so # nothing is silently lost. missing_count=$(awk -F'|' '$3 ~ /^missing artifacts:/' "$dropped" | wc -l | tr -d ' ') orphan_count=$(awk -F'|' '$3 ~ /^orphan:/' "$dropped" | wc -l | tr -d ' ') drift_count=$(awk -F'|' '$3 ~ /^sig drift:/' "$dropped" | wc -l | tr -d ' ') mismatch_count=$(awk -F'|' '$3 ~ /^sig mismatch:/' "$dropped" | wc -l | tr -d ' ') nosig_count=$(awk -F'|' '$3 ~ /^sig missing:/' "$dropped" | wc -l | tr -d ' ') other_count=$(awk -F'|' '$3 !~ /^(missing artifacts:|orphan:|sig drift:|sig mismatch:|sig missing:)/' "$dropped" | wc -l | tr -d ' ') body=/tmp/missing-compliance-body.md { echo "Tracking catalog skills that were **dropped** or **reverted** by the last sync run. Failure modes surfaced here:" echo "" echo "1. **Missing artifacts** — \`SKILL.md\` exists on the source repo but one or more required companions don't:" echo " - \`skill.oms.sig\` (NVIDIA detached signature)" echo " - \`skill-card.md\` (skill metadata card)" echo " - \`evals.json\` (eval definitions — anywhere within the skill directory)" echo "2. **Signature drift** — files in the skill dir were updated on the source repo, but \`skill.oms.sig\` wasn't refreshed alongside. Loading this content would break crypto verification, so:" echo " - Skills that previously existed on \`main\` are **reverted** to their last-signed version (the signed copy stays live)." echo " - Brand-new skills with drift are **dropped** outright." echo " Recovery: comment \`/nvskills-ci\` on a follow-up PR on the source repo so the next sync picks up a fresh, content-aligned signature." echo "3. **Signature mismatch** — the source repo delivered a refreshed \`skill.oms.sig\`, but the skill's content does not hash-match it. The source repo is internally inconsistent (skill files edited after the signing run, or a pipeline ordering fault). Same revert/drop handling as drift." echo " Recovery: re-run \`/nvskills-ci\` at source and do not modify skill files after the generated signature commit lands." echo "4. **Signature missing** — source skill dir has no \`skill.oms.sig\` at all (never signed, or sig deleted upstream):" echo " - Previously-signed catalog skills are **reverted** to their last-signed version." echo " - New unsigned skills are **dropped** outright." echo " Recovery: run the signing flow on the source repo so \`skill.oms.sig\` lands alongside \`SKILL.md\`." echo "5. **Orphan product dirs** — product folder under \`skills/\` with no \`SKILL.md\` inside (e.g. every skill was dropped, leaving only helper files)." echo "" echo "**Last updated:** $(date -u +%Y-%m-%d) by [sync run #${{ github.run_id }}]($RUN_URL)" echo "" # Look up the resolved GitHub login (if any) for a catalog # dir from /tmp/skill-contacts.txt produced by the # "Resolve skill contacts" step. Empty result means the # contact resolver couldn't find a login — section emits # without a cc trailer in that case. contacts_file=/tmp/skill-contacts.txt lookup_contact() { local cat_dir="$1" [ -f "$contacts_file" ] || { echo ""; return; } awk -F'|' -v d="$cat_dir" '$1==d {print $2; exit}' "$contacts_file" } emit_section() { local heading="$1" filter_kind="$2" count="$3" [ "$count" -gt 0 ] || return 0 echo "## $heading ($count)" local current="" while IFS='|' read -r product dir reason; do case "$reason" in "missing artifacts: "*) kind="missing"; display="${reason#missing artifacts: }" ;; "orphan: "*) kind="orphan"; display="${reason#orphan: }" ;; "sig drift: "*) kind="drift"; display="${reason#sig drift: }" ;; "sig mismatch: "*) kind="mismatch"; display="${reason#sig mismatch: }" ;; "sig missing: "*) kind="nosig"; display="${reason#sig missing: }" ;; *) kind="other"; display="$reason" ;; esac [ "$kind" = "$filter_kind" ] || continue if [ "$product" != "$current" ]; then echo "" echo "### \`$product\`" current="$product" fi cat_dir=$(basename "$dir") contact=$(lookup_contact "$cat_dir") if [ -n "$contact" ]; then echo "- \`$dir\` — $display (cc: $contact)" else echo "- \`$dir\` — $display" fi done < "$dropped" echo "" } emit_section "Missing artifacts" "missing" "$missing_count" emit_section "Signature drift" "drift" "$drift_count" emit_section "Signature mismatch" "mismatch" "$mismatch_count" emit_section "Signature missing" "nosig" "$nosig_count" emit_section "Orphan product dirs" "orphan" "$orphan_count" emit_section "Other" "other" "$other_count" echo "---" echo "Owners: re-run \`/nvskills-ci\` on the source repo after editing skill content so the signature stays in sync. This issue auto-updates each sync and closes when all skills are compliant." } > "$body" # Title summarizes the active failure modes. Build it from # whichever buckets are non-empty so it stays accurate as # categories come and go. parts=() [ "$missing_count" -gt 0 ] && parts+=("$missing_count missing artifacts") [ "$drift_count" -gt 0 ] && parts+=("$drift_count sig drift") [ "$mismatch_count" -gt 0 ] && parts+=("$mismatch_count sig mismatch") [ "$nosig_count" -gt 0 ] && parts+=("$nosig_count sig missing") [ "$orphan_count" -gt 0 ] && parts+=("$orphan_count orphan") [ "$other_count" -gt 0 ] && parts+=("$other_count other") if [ ${#parts[@]} -eq 0 ]; then title="Skills dropped from sync" # shouldn't happen (we exit 0 above) else # Bash array expansion under custom IFS only uses the first # char as separator, so a comma-space IFS gives "a,b" not # "a, b". Build the join with printf + trailing strip instead. joined=$(printf '%s, ' "${parts[@]}") joined="${joined%, }" title="Skills dropped from sync — $joined" fi # Assign the rolling tracker to one or more catalog PIC(s) so # any drift change reliably reaches them via GitHub # notifications, independent of repo-watch settings. # CATALOG_TRACKER_ASSIGNEES is a comma-separated list of # **individual GitHub user handles** — GitHub does NOT accept # team handles as issue assignees, so a team rotation has to # be expressed as the explicit current owners in the secret. # If the secret is unset we skip assignment entirely and emit # a loud warning — no hardcoded personal fallback, because a # deactivated personal handle would silently mute notifications # (Sayali's review #3, refined by Codex's note that teams # aren't valid assignees). assignees="${{ secrets.CATALOG_TRACKER_ASSIGNEES }}" if [ -z "$assignees" ]; then echo "::warning title=Drift notifications inactive::CATALOG_TRACKER_ASSIGNEES secret is unset — the rolling drift-tracker issue will be created but no one will be auto-assigned. Set this secret to a comma-separated list of GitHub user handles (e.g. \"alice,bob\") to restore notifications." fi # Both branches assign in a tolerant loop so a bad/deactivated # handle in CATALOG_TRACKER_ASSIGNEES doesn't take down the # tracker step — even though the step is `continue-on-error`, # a failing `gh issue create` would still skip the tracker # update entirely, defeating the feature (Sayali's review #2, # refined by Codex's note that the step's continue-on-error # already prevents catastrophic sync failure). IFS=',' read -r -a assignee_arr <<< "$assignees" if [ -n "$existing" ]; then gh issue edit "$existing" --title "$title" --body-file "$body" # `--add-assignee` is idempotent — re-asserts assignment on # every run so a manual unassign doesn't permanently mute it. for a in "${assignee_arr[@]}"; do a=$(echo "$a" | xargs) # trim whitespace [ -n "$a" ] && (gh issue edit "$existing" --add-assignee "$a" || echo " warn: could not assign '$a' to issue #$existing") done echo "Updated tracking issue #$existing (assignees attempted: ${assignees:-})" else # Create first (no assignee), then add assignees in a # tolerant loop so a typo can't block issue creation. new_url=$(gh issue create --title "$title" --body-file "$body" --label missing-compliance) new_num=$(echo "$new_url" | grep -oE '[0-9]+$') echo "Opened new tracking issue #$new_num" for a in "${assignee_arr[@]}"; do a=$(echo "$a" | xargs) [ -n "$a" ] && (gh issue edit "$new_num" --add-assignee "$a" || echo " warn: could not assign '$a' to issue #$new_num") done fi - name: Ping skill owners for new drops continue-on-error: true env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | set -euo pipefail dropped=/tmp/dropped-skills.txt contacts=/tmp/skill-contacts.txt # Nothing to do if there are no drops or no resolved contacts. [ -s "$dropped" ] || exit 0 [ -s "$contacts" ] || exit 0 # Pre-update body tells us which skills were already in the issue # before this run. Only comment for first-time drops so owners # get one notification per incident, not one per sync cycle. pre_body=$(jq -r '.body // ""' /tmp/pre-update-tracker.json 2>/dev/null || true) # Get the current issue number (Track step just created/updated it). issue_num=$(gh issue list --label missing-compliance --state open \ --json number --jq '.[0].number // empty' --limit 1) [ -n "$issue_num" ] || exit 0 new_lines="" while IFS='|' read -r product dir reason; do # Orphan product dirs have no source skill — skip. case "$reason" in orphan:*) continue ;; esac # Already tracked in a prior run — skip to avoid repeat pings. if printf '%s' "$pre_body" | grep -qF "\`$dir\`"; then continue fi # Look up the resolved contact from "Resolve skill contacts". cat_dir=$(basename "$dir") contact=$(awk -F'|' -v d="$cat_dir" '$1==d {print $2; exit}' "$contacts") line="- \`$dir\` — ${reason#*: }" [ -n "$contact" ] && line="$line (cc: $contact)" new_lines="${new_lines}${line}"$'\n' done < "$dropped" [ -n "$new_lines" ] || exit 0 ping_body=/tmp/ping-comment-body.md { echo "### New skill drops this sync run — action required" echo "" echo "The following skills were dropped or reverted for the **first time** in this sync run:" echo "" printf '%s\n' "$new_lines" echo "**How to fix:** comment \`/nvskills-ci\` on a follow-up PR in the source repo after updating the skill content. The next sync will pick up the refreshed \`skill.oms.sig\` automatically." } > "$ping_body" gh issue comment "$issue_num" --body-file "$ping_body" echo "Posted owner-ping comment on issue #$issue_num" - name: Rebuild plugin catalog run: | set -euo pipefail # plugins//skills/ in copy mode duplicates content from # the canonical skills/ tree, so any sync that touched a # curated source path leaves those copies stale. Re-run the # plugin build here so the same sync PR ships a consistent # tree (skills/ + plugins/) and validate-plugins.yml --check # stays green. Symlink-mode plugins are a no-op for the build. # build-plugins.py soft-fails missing/dropped curated skills # so a rename or compliance drop does NOT block the sync PR. .github/scripts/build-plugins.sh # Mark the plugin catalog as a changed component if anything # under plugins/ or either marketplace.json moved, so the PR # summary surfaces it and the "has_changes" gate fires even # when the only diff is the auto-rebuild. 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 - name: Auto-bump plugin versions for materially-changed plugins run: | set -euo pipefail # Compare the freshly-rebuilt plugin tree against the pre-sync # commit (HEAD — the sync changes are still uncommitted at this # point) and auto-bump any plugin whose curated content moved: # z for in-place edits, y for structural changes (skill add/ # remove, capability change). Builders own x bumps explicitly. .github/scripts/version-plugins.sh --apply --base HEAD - name: Regenerate README tables run: .github/scripts/regenerate-readme.sh # The rsync loop records a component as changed the moment rsync # produces a diff, but the drift, compliance and prune steps that run # after it can revert those files. Nothing ever removed the component # from the list, so a component whose skills were all held came out # labelled "updated" — contradicting the held list printed directly # below it in the same PR body, and inflating the title that GitHub # rejects past 256 characters. Recompute from the working tree now # that every step which can mutate it has run. - name: Recompute changed components after reverts run: | set -euo pipefail CONFIG=/tmp/components.aggregated.yml recomputed=/tmp/changed-components.recomputed.txt : > "$recomputed" if [ -f "$CONFIG" ]; then component_count=$(yq -r '.components | length' "$CONFIG") for ((i = 0; i < component_count; i++)); do name=$(yq -r ".components[$i].name" "$CONFIG") skill_count=$(yq -r ".components[$i].skills | length" "$CONFIG") for ((j = 0; j < skill_count; j++)); do catalog_dir=$(yq -r ".components[$i].skills[$j].catalog_dir" "$CONFIG") if [ -n "$(git status --porcelain "skills/$catalog_dir" 2>/dev/null)" ]; then echo "- $name" >> "$recomputed" break fi done done fi # Entries that are not components describe changes outside # skills/, so they are re-established from their own evidence # rather than carried over from the pre-revert list. if [ -s /tmp/pruned-orphans.txt ]; then echo "- orphan pruning" >> "$recomputed" fi if [ -n "$(git status --porcelain plugins .agents/plugins .claude-plugin .cursor-plugin 2>/dev/null)" ]; then echo "- plugin catalog" >> "$recomputed" fi sort -u -o "$recomputed" "$recomputed" # A sync can legitimately change only README tables or generated # catalog files. Those still warrant a PR, so never let the # recompute turn a dirty tree into "no changes". if [ ! -s "$recomputed" ] && [ -n "$(git status --porcelain)" ]; then echo "- catalog maintenance" >> "$recomputed" fi before=$(wc -l < /tmp/changed-components.txt | tr -d ' ') after=$(wc -l < "$recomputed" | tr -d ' ') echo "changed components: ${before} recorded during rsync -> ${after} after reverts" if [ "${before}" -ne "${after}" ]; then echo "Dropped from the list (rsynced then reverted or removed):" comm -23 \ <(sort -u /tmp/changed-components.txt) \ <(sort -u "$recomputed") | sed 's/^/ /' fi mv "$recomputed" /tmp/changed-components.txt - name: Build sync summary id: summary run: | # Surface failure count regardless of whether anything changed — # a quiet sync can still have a misconfigured component to flag. if [ -s /tmp/failed-components.txt ]; then echo "has_failures=true" >> "$GITHUB_OUTPUT" else echo "has_failures=false" >> "$GITHUB_OUTPUT" fi if [ ! -s /tmp/changed-components.txt ]; then echo "has_changes=false" >> "$GITHUB_OUTPUT" echo "::notice::All components synced; no upstream content changes detected" exit 0 fi echo "has_changes=true" >> "$GITHUB_OUTPUT" # Dedupe before composing the title — the enforce step may have # re-added entries already present from the rsync loop. sort -u -o /tmp/changed-components.txt /tmp/changed-components.txt # GitHub rejects a pull request title over 256 characters, and it # rejects it on create as well as on update — so an over-long title # stops the sync PR from existing at all, stranding synced content on # the branch. Name as many components as fit and count the rest; the # complete list is always in the body below, which has no limit. sed 's/^- //' /tmp/changed-components.txt | sed '/^[[:space:]]*$/d' > /tmp/changed-names.txt total=$(wc -l < /tmp/changed-names.txt | tr -d ' ') title_limit=256 title_prefix="chore: sync skills (" names="" shown=0 while IFS= read -r name; do if [ -z "${names}" ]; then candidate="${name}"; else candidate="${names},${name}"; fi remaining=$((total - shown - 1)) if [ "${remaining}" -gt 0 ]; then more=" +${remaining} more"; else more=""; fi if [ $(( ${#title_prefix} + ${#candidate} + ${#more} + 1 )) -le "${title_limit}" ]; then names="${candidate}" shown=$((shown + 1)) else break fi done < /tmp/changed-names.txt if [ "${total}" -eq 1 ]; then count_label="1 component"; else count_label="${total} components"; fi omitted=$((total - shown)) if [ "${shown}" -eq 0 ]; then # Even one name does not fit; fall back to a bare count. title="chore: sync skills (${count_label})" elif [ "${omitted}" -gt 0 ]; then title="${title_prefix}${names} +${omitted} more)" else title="${title_prefix}${names})" fi # Belt and braces: never emit a title the API will reject. if [ "${#title}" -gt "${title_limit}" ]; then title="chore: sync skills (${count_label})" fi echo "title=${title}" >> "$GITHUB_OUTPUT" { echo 'body<` trailer per skill when /tmp/skill-contacts.txt # has a resolved entry, otherwise emit the line bare. contacts_file=/tmp/skill-contacts.txt emit_with_contact() { local dir="$1" display="$2" local cat_dir contact cat_dir=$(basename "$dir") if [ -f "$contacts_file" ]; then contact=$(awk -F'|' -v d="$cat_dir" '$1==d {print $2; exit}' "$contacts_file") else contact="" fi if [ -n "$contact" ]; then echo "- \`$dir\` — $display (cc: $contact)" else echo "- \`$dir\` — $display" fi } if [ -n "$missing_lines" ]; then echo "" echo "**Skills dropped — missing required artifacts (\`skill.oms.sig\`, \`skill-card.md\`, and/or \`evals.json\`):**" echo "$missing_lines" | while IFS='|' read -r _ dir reason; do emit_with_contact "$dir" "${reason#missing artifacts: }" done fi if [ -n "$drift_lines" ]; then echo "" echo "**Skills held — signature drift (content changed without \`skill.oms.sig\` refresh):**" echo "$drift_lines" | while IFS='|' read -r _ dir reason; do emit_with_contact "$dir" "${reason#sig drift: }" done fi if [ -n "$mismatch_lines" ]; then echo "" echo "**Skills held — signature mismatch (incoming content does not match its own \`skill.oms.sig\`):**" echo "$mismatch_lines" | while IFS='|' read -r _ dir reason; do emit_with_contact "$dir" "${reason#sig mismatch: }" done fi if [ -n "$nosig_lines" ]; then echo "" echo "**Skills held — no signature in source (\`skill.oms.sig\` absent upstream):**" echo "$nosig_lines" | while IFS='|' read -r _ dir reason; do emit_with_contact "$dir" "${reason#sig missing: }" done fi if [ -n "$orphan_lines" ]; then echo "" echo "**Orphan product dirs dropped (no SKILL.md inside):**" echo "$orphan_lines" | while IFS='|' read -r _ dir reason; do emit_with_contact "$dir" "${reason#orphan: }" done fi if [ -n "$other_lines" ]; then echo "" echo "**Other drops:**" echo "$other_lines" | while IFS='|' read -r _ dir reason; do emit_with_contact "$dir" "$reason" done fi fi if [ -s /tmp/pruned-orphans.txt ]; then echo "" echo "**Pruned — deregistered from components.d (dir removed from catalog):**" while read -r dir; do echo "- \`skills/$dir\`" done < /tmp/pruned-orphans.txt fi if [ -s /tmp/pruned-orphans-overflow.txt ]; then echo "" echo "**⚠ Orphan pruning skipped — count exceeds safety cap; needs human triage:**" while read -r dir; do echo "- \`skills/$dir\`" done < /tmp/pruned-orphans-overflow.txt fi if [ -s /tmp/failed-components.txt ]; then echo "" echo "**Components that failed to sync:**" cat /tmp/failed-components.txt fi echo "" echo "Triggered by: \`${{ github.event_name }}\`" echo 'EOFBODY' } >> "$GITHUB_OUTPUT" - name: Create pull request if: steps.summary.outputs.has_changes == 'true' uses: peter-evans/create-pull-request@v6 with: commit-message: ${{ steps.summary.outputs.title }} branch: automated/sync-skills title: ${{ steps.summary.outputs.title }} body: ${{ steps.summary.outputs.body }} delete-branch: true - name: Update sync-failure tracking issue (rolling) if: always() continue-on-error: true uses: actions/github-script@v7 with: script: | const fs = require('fs'); const hasFailures = '${{ steps.summary.outputs.has_failures }}' === 'true'; const jobFailed = '${{ job.status }}' === 'failure'; const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`; // Find the existing rolling tracker (if any). const { data: openIssues } = await github.rest.issues.listForRepo({ owner: context.repo.owner, repo: context.repo.repo, state: 'open', labels: 'sync-failure', }); const tracker = openIssues[0]; if (!hasFailures && !jobFailed) { // Clean run — close the rolling tracker if open, then exit. if (tracker) { await github.rest.issues.createComment({ owner: context.repo.owner, repo: context.repo.repo, issue_number: tracker.number, body: `Sync run [#${context.runId}](${runUrl}) completed cleanly — closing the rolling sync-failure tracker. A new tracker opens automatically if a future sync fails.`, }); await github.rest.issues.update({ owner: context.repo.owner, repo: context.repo.repo, issue_number: tracker.number, state: 'closed', }); console.log(`Clean run — closed tracker #${tracker.number}`); } else { console.log('Clean run — no tracker to close'); } return; } // There IS a failure to report. Build a single rolling body that // reflects the current state, not a historical run log. let title, bodyLines = []; const today = new Date().toISOString().slice(0, 10); if (jobFailed) { title = `Sync failure tracker — sync workflow run failed (${today})`; bodyLines.push( `The most recent sync workflow run failed entirely.`, ``, `**Most recent run:** [#${context.runId}](${runUrl})`, `**Trigger:** \`${context.eventName}\``, `**Last updated:** ${today}`, ``, `This issue auto-updates on every sync run and closes when sync runs cleanly again.`, ); } else { // Partial failure — read the failed components list. let failed = ''; try { failed = fs.readFileSync('/tmp/failed-components.txt', 'utf8').trim(); } catch (e) { failed = '(failed-components.txt not available)'; } const count = failed.split('\n').filter(l => l.trim()).length; title = `Sync failure tracker — ${count} component(s) currently failing (${today})`; bodyLines.push( `Components that failed to sync on the most recent run. This issue auto-updates each sync and closes when all components are syncing cleanly.`, ``, `**Currently failing components (${count}):**`, failed, ``, `**Most recent run:** [#${context.runId}](${runUrl})`, `**Trigger:** \`${context.eventName}\``, `**Last updated:** ${today}`, ``, `Failures usually mean the skill path in \`components.d/.yml\` doesn't match the actual directory in the source repo (e.g. symlink, renamed, removed, or moved branch).`, ); } const body = bodyLines.join('\n'); if (tracker) { await github.rest.issues.update({ owner: context.repo.owner, repo: context.repo.repo, issue_number: tracker.number, title, body, }); console.log(`Updated rolling tracker #${tracker.number}`); } else { await github.rest.issues.create({ owner: context.repo.owner, repo: context.repo.repo, title, body, labels: ['sync-failure'], }); console.log('Opened new rolling tracker'); }