Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 0 additions & 40 deletions .agents/catalog-skills.yaml

This file was deleted.

1 change: 0 additions & 1 deletion .github/CODEOWNERS
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,6 @@
/spark-install.md @NVIDIA/nemoclaw-engineer

# ── Agent skills catalog ──
/.agents/catalog-skills.yaml @NVIDIA/nemoclaw-maintainer @NVIDIA/nemoclaw-engineer
/.agents/skills/ @NVIDIA/nemoclaw-maintainer @NVIDIA/nemoclaw-engineer
/skills/ @NVIDIA/nemoclaw-maintainer @NVIDIA/nemoclaw-engineer

Expand Down
100 changes: 36 additions & 64 deletions .github/catalog-skills-signing-flow.md
Original file line number Diff line number Diff line change
@@ -1,79 +1,51 @@
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

# NemoClaw catalog skills signing flow
# Publishing a NemoClaw skill to the NVIDIA Verified Skills catalog

This diagram shows the required sequence for publishing NemoClaw user-facing skills into the NVIDIA Verified Skills catalog through the generated `skills/` export.
The `skills/` directory at the repo root is the NVSkills CI watched location.
Whatever lives there is what gets signed and published. There is no
allowlist, manifest, or generator script — adding a skill to the catalog
means copying the source skill into `skills/` and pushing it through
NVSkills CI signing.

```mermaid
sequenceDiagram
autonumber
actor Maintainer as Human maintainer
participant Source as NemoClaw source<br/>.agents/skills + .agents/catalog-skills.yaml
participant Exporter as scripts/export-catalog-skills.py
participant Export as Generated export<br/>skills
participant PRCI as PR workflow<br/>CI / Pull Request
participant Refresh as Skills / Catalog Refresh workflow
participant PR as Same-repo refresh PR
participant NVSkills as NVSkills CI signer
participant Main as NVIDIA/NemoClaw main
participant Target as NVIDIA/skills sync
## Add a skill to the catalog

Note over Source,Export: Implementation PR path added by issue #4282
Maintainer->>Source: Curate catalog-safe skills in .agents/catalog-skills.yaml
Maintainer->>Exporter: Run python3 scripts/export-catalog-skills.py
Exporter->>Export: Copy allowlisted skills as real files<br/>write catalog-metadata.json<br/>preserve skill.oms.sig + skill-card.md if present
Maintainer->>PRCI: Open implementation or content PR
PRCI->>Exporter: python3 scripts/export-catalog-skills.py --check --allow-missing
Exporter-->>PRCI: Pass before first export exists;<br/>after refresh PR, fail if skills is stale or hand-edited
Maintainer->>Main: Merge reviewed PR after checks pass

Note over Refresh,PR: Post-merge refresh automation added by this PR
Maintainer->>Refresh: Optional manual workflow_dispatch<br/>dry_run=true first
Refresh->>Exporter: Regenerate export and show diff only
Refresh-->>Maintainer: No branch or PR created in dry run
Maintainer->>Refresh: Run dry_run=false when ready<br/>optionally request_nvskills_ci=true
Refresh->>Exporter: Regenerate export
Exporter->>Export: Update generated files if source changed
Refresh->>PR: Create/update automation/catalog-skills-refresh PR<br/>with export diff

alt request_nvskills_ci=true and bot is accepted
Refresh->>PR: Comment /nvskills-ci
else bot rejected or manual process preferred
Maintainer->>PR: Comment /nvskills-ci manually
end

NVSkills->>PR: Push signing artifacts<br/>skill.oms.sig + skill-card.md
PRCI->>Exporter: Re-run --check; signer artifacts are preserved
Maintainer->>PR: Review generated export and signing artifacts
Maintainer->>Main: Merge signed refresh PR
Target->>Main: Sync configured NemoClaw catalog path
Target->>Target: Keep only skills with skill.oms.sig and skill-card.md
```bash
mkdir -p skills
cp -R .agents/skills/nemoclaw-user-<name> skills/
git add skills/nemoclaw-user-<name>
git commit -m "chore(skills): publish nemoclaw-user-<name>"
```

## Human handoff points
Open the PR, comment `/nvskills-ci`, wait for the signing job to push back
`skill.oms.sig` and `skill-card.md`, then merge. Repeat per skill — NVSkills
CI signs one at a time.

These are the manual review and approval points in the catalog signing flow.
## Update an already-published skill

- Curate `.agents/catalog-skills.yaml` when public skill scope changes.
- Review the generated `skills/` diff in the same PR as the allowlist/source update.
- Manually comment `/nvskills-ci` if the workflow bot cannot request signing.
- Review and merge the signer-updated PR before expecting `NVIDIA/skills` to sync the signed skills.
```bash
rm -rf skills/nemoclaw-user-<name>
cp -R .agents/skills/nemoclaw-user-<name> skills/
git add -A skills/nemoclaw-user-<name>
git commit -m "chore(skills): refresh nemoclaw-user-<name>"
```

## Workflow steps added in this PR
The `skill.oms.sig` from the previous signing is removed by the `rm -rf`,
so NVSkills CI will re-sign on the next `/nvskills-ci` comment. Use
`git add -A` so newly added files in the refreshed skill are staged
alongside removals tracked by `git commit -a`.

These checks and workflow steps automate export freshness while keeping signing under maintainer control.
## Spot-checking for drift

- `CI / Pull Request` runs `python3 scripts/export-catalog-skills.py --check --allow-missing` so this infrastructure PR can merge before the first generated export, while later export PRs still reject stale or hand-edited files.
- `Skills / Catalog Refresh` supports:
- `dry_run=true` to regenerate and report changes without pushing.
- `dry_run=false` to create or update `automation/catalog-skills-refresh`.
- `request_nvskills_ci=true` to attempt the `/nvskills-ci` comment after opening/updating the PR.
- scheduled no-op/refresh behavior using the same exporter.
Source (`/.agents/skills/`) and published (`/skills/`) can drift if a

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix path notation inconsistency.

Line 37 uses leading slashes (/.agents/skills/ and /skills/) while line 40 omits them (.agents/skills/). Use consistent notation throughout the document to avoid confusion about absolute vs. relative paths.

🔧 Proposed fix
-Source (`/.agents/skills/`) and published (`/skills/`) can drift if a
+Source (`.agents/skills/`) and published (`skills/`) can drift if a
 source-side edit lands without a corresponding refresh PR. To check, ask
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Source (`/.agents/skills/`) and published (`/skills/`) can drift if a
Source (`.agents/skills/`) and published (`skills/`) can drift if a
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/catalog-skills-signing-flow.md at line 37, Paths in the document are
inconsistent: some entries use leading slashes ("/.agents/skills/", "/skills/")
while others use no leading slash (".agents/skills/"); update all occurrences to
a single consistent notation — e.g., change "/.agents/skills/" and "/skills/" to
".agents/skills/" and "skills/" (or vice versa if you prefer absolute paths) so
every reference to the agent and published skill directories uses the same form
throughout the file.

source-side edit lands without a corresponding refresh PR. To check, ask
an agent to compare every subdirectory of `skills/` against its counterpart
under `.agents/skills/` and report any file content differences (ignoring
`skill.oms.sig` and `skill-card.md`).

## Next Steps
## What goes in the catalog

- Review the exporter implementation in [`scripts/export-catalog-skills.py`](../scripts/export-catalog-skills.py).
- Update the catalog allowlist in [`.agents/catalog-skills.yaml`](../.agents/catalog-skills.yaml) when public skill scope changes.
- Review generated export diffs under `skills/` in the refresh PR before requesting or accepting signing artifacts.
- Check the workflow definitions in [`.github/workflows/pr.yaml`](workflows/pr.yaml) and [`.github/workflows/catalog-skills-refresh.yaml`](workflows/catalog-skills-refresh.yaml).
Only customer-facing skills, identified by the `nemoclaw-user-*` naming
convention. Internal skills (`nemoclaw-maintainer-*`, `nemoclaw-contributor-*`)
must not be copied into `skills/`.
15 changes: 0 additions & 15 deletions .github/pr-bodies/catalog-skills-refresh.md

This file was deleted.

142 changes: 0 additions & 142 deletions .github/workflows/catalog-skills-refresh.yaml

This file was deleted.

3 changes: 0 additions & 3 deletions .github/workflows/pr.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -51,9 +51,6 @@ jobs:
- name: Verify platform matrix is in sync
run: python3 scripts/generate-platform-docs.py --check

- name: Verify catalog skills export is in sync
run: python3 scripts/export-catalog-skills.py --check --allow-missing

test-e2e-ollama-proxy:
needs: [checks, changes]
if: needs.changes.outputs.code == 'true'
Expand Down
8 changes: 0 additions & 8 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -160,14 +160,6 @@ repos:
pass_filenames: false
priority: 10

- id: catalog-skills-export
name: Verify catalog skills export
entry: python3 scripts/export-catalog-skills.py --check --allow-missing
language: system
files: ^(\.agents/catalog-skills\.yaml|\.agents/skills/.*|skills/.*|scripts/export-catalog-skills\.py)$
pass_filenames: false
priority: 10

- id: env-var-docs
name: NEMOCLAW_* env-var documentation gate
entry: npx tsx scripts/check-env-var-docs.ts
Expand Down
Loading
Loading