feat(skills): add maintainer skill set foundation and first skill - #269
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Enterprise Run ID: 📒 Files selected for processing (2)
📜 Recent review details🧰 Additional context used📓 Path-based instructions (3){docs/**,README.md,CONTRIBUTING.md,SECURITY.md,CODE-OF-CONDUCT.md}⚙️ CodeRabbit configuration file
Files:
**⚙️ CodeRabbit configuration file
Files:
{skills/**,.agents/skills/**,.claude/skills/**,.github/skill-eval/**}⚙️ CodeRabbit configuration file
Files:
🧠 Learnings (1)📓 Common learnings🔇 Additional comments (4)
WalkthroughAdds a repo-local maintainer skills system with documentation, authoring template, and a validator CLI that enforces SKILL.md structure; integrates validation into pre-commit and tests; provides a concrete aiq-add-data-source skill with package layout, registry wiring, and validation guidance; and clarifies API-consumer vs maintainer skill concepts in updated docs. ChangesMaintainer Skills System & Validation Infrastructure
Sequence DiagramsequenceDiagram
participant Test as tests/test_agent_skills.py
participant Validator as scripts/validate_skills.py
participant FS as FileSystem
participant Frontmatter as parse_frontmatter
participant LinkCheck as check_bundle_links
Test->>Validator: validate_roots([.agents/skills])
Validator->>FS: iter_skill_dirs(root)
loop Each skill directory
Validator->>FS: read SKILL.md
Validator->>Frontmatter: extract YAML frontmatter
Validator->>Frontmatter: validate name/description
Validator->>LinkCheck: validate markdown links
LinkCheck->>FS: resolve relative link targets
end
Validator-->>Test: Report(errors, skills_checked)
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with 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.
Inline comments:
In @.agents/skills/aiq-add-data-source/references/package-layout.md:
- Around line 10-22: Update the markdown code fence that displays the directory
tree (the block starting with "sources/my_data_source/" and listing
pyproject.toml, README.md, src/, tests/, etc.) to include a language specifier
by replacing the opening ``` with ```text or ```plaintext so markdownlint MD040
is satisfied.
In @.agents/skills/README.md:
- Around line 41-58: The layout section in .agents/skills/README.md omits the
optional assets/ subdirectory; update the SKILL bundle layout list to include an
"assets/" entry (e.g., add a line describing assets/ as optional
images/binaries/other bundled assets) so it matches the validator's BUNDLE_DIRS
and the Naming/frontmatter rules; ensure the new entry appears alongside
references/, scripts/, and templates/ in the same block and that any example
tree or explanatory text mentions assets/ as optional.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 63cd3469-5536-4668-acd9-f7502ad3cb36
📒 Files selected for processing (12)
.agents/skills/README.md.agents/skills/TEMPLATE.md.agents/skills/aiq-add-data-source/SKILL.md.agents/skills/aiq-add-data-source/references/package-layout.md.agents/skills/aiq-add-data-source/references/registry-and-ui.md.agents/skills/aiq-add-data-source/references/validation.md.claude/skills/aiq-add-data-source.pre-commit-config.yamlAGENTS.mdCLAUDE.mdscripts/validate_skills.pytests/test_agent_skills.py
📜 Review details
🧰 Additional context used
📓 Path-based instructions (7)
{skills/**,.agents/skills/**,.claude/skills/**,.github/skill-eval/**}
⚙️ CodeRabbit configuration file
{skills/**,.agents/skills/**,.claude/skills/**,.github/skill-eval/**}: Review Agent Skill and skill-eval changes for valid skill metadata, deterministic eval specs, safe handling of
credentials, and clear generated-output boundaries. Do not flag SKILL.md files for missing SPDX headers when the
entrypoint intentionally starts with YAML frontmatter.
Files:
.claude/skills/aiq-add-data-source.agents/skills/README.md.agents/skills/aiq-add-data-source/references/validation.md.agents/skills/TEMPLATE.md.agents/skills/aiq-add-data-source/SKILL.md.agents/skills/aiq-add-data-source/references/registry-and-ui.md.agents/skills/aiq-add-data-source/references/package-layout.md
{.github/**,ci/**,.pre-commit-config.yaml,pyproject.toml,uv.lock}
⚙️ CodeRabbit configuration file
{.github/**,ci/**,.pre-commit-config.yaml,pyproject.toml,uv.lock}: Review automation and packaging changes for least-privilege permissions, pinned versions where appropriate,
copy-pr-bot pull-request/ branch behavior, reproducible uv/npm setup, secret handling, and consistency with
the documented validation matrix.
Files:
.pre-commit-config.yaml
**/*AGENTS*.md
📄 CodeRabbit inference engine (CLAUDE.md)
**/*AGENTS*.md: Document agent responsibilities, capabilities, and interactions in markdown files
Include clear descriptions of agent roles, inputs, outputs, and dependencies in agent documentation
Files:
AGENTS.md
**
⚙️ CodeRabbit configuration file
**: # Contributing GuidelinesWe welcome contributions to the NVIDIA AI-Q blueprint. This repository uses a maintainer-reviewed pull request workflow with DCO sign-off, code-owner review, copy-pr-bot mirroring, and GitHub Actions validation.
Before You Start
- Search existing issues and pull requests before opening new work.
- Open an issue or discussion before large design changes, public APIs, deployment changes, or contributor workflow changes.
- Do not include secrets, credentials, private hostnames, internal-only logs, customer data, or generated local artifacts.
- Target the
developbranch unless a maintainer asks you to use a release branch.Pull Requests
- Fork the repository and create a focused branch from
develop.- Make the smallest coherent change and add or update tests for behavior changes.
- Sign off every commit with
git commit -s.- Run the relevant local validation before opening the PR.
- Open a pull request into
developand fill out the PR template with exact validation evidence.- Address review feedback until required checks and code-owner review pass.
Local Validation
Use the narrowest command that covers your change, then include the exact output or workflow link in the PR.
uv sync --group dev uv run ruff check . uv run ruff format --check . uv run pytestFor UI changes:
cd frontends/ui npm ci npm run lint npm run type-check npm run test:ci npm run buildFor deployment changes, run the relevant Helm or compose validation and describe the environment used.
CI and Bot Workflow
AI-Q uses push-triggered GitHub Actions. Pull requests are mirrored by copy-pr-bot to
pull-request/<PR number>branches after a maintainer or configured vetter comments/ok to test, and CI runs on those mirrored branches.Repository owners, organization members, and collaborators can request NVSkills validation by commenting:
/nvskills-ciMaintainers can request bot-driven merge with:
``...
Files:
AGENTS.mdCLAUDE.mdtests/test_agent_skills.pyscripts/validate_skills.py
**/*.py
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run ruff check and ruff format validation for Python code changes
**/*.py: Lint Python code with Ruff using line length 120, target Python 3.11, rule sets E,F,W,I,PL,UP
Format Python code with Ruff and match existing import and formatting style; do not hand-reformat unrelated code
Configure Ruff isort with force-single-line for import organization
Files:
tests/test_agent_skills.pyscripts/validate_skills.py
**/*test*.py
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run pytest for all behavior changes in Python code
Files:
tests/test_agent_skills.py
{**/*.py,frontends/**/*.{ts,tsx}}
📄 CodeRabbit inference engine (AGENTS.md)
Never print or log secret values, including in tool output or error messages
Files:
tests/test_agent_skills.pyscripts/validate_skills.py
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T01:22:51.912Z
Learning: Never commit secrets, tokens, or environment-specific hostnames; use environment variables and SecretStr; resolve API keys at runtime
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T01:22:51.912Z
Learning: Missing-secret paths must degrade gracefully (stub/skip), not crash or leak
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T01:22:51.912Z
Learning: Keep docs canonical; do not duplicate full doc pages into skill text
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T01:22:51.912Z
Learning: Every commit must include DCO sign-off with 'git commit -s -m' containing Signed-off-by trailer
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T01:22:51.912Z
Learning: Keep PRs scoped: no unrelated files, no accidental generated artifacts, no secrets; provide validation evidence
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T01:22:51.912Z
Learning: Stay inside this repository; if workspace contains adjacent repos, do not edit them as part of an AI-Q change
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T01:22:51.912Z
Learning: Run the narrowest relevant build/test command first; broaden to full suite only when a change crosses shared boundaries
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T01:22:51.912Z
Learning: Install and use pre-commit to enforce linting, secret detection, link checking, and skill validation before pushing
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T01:22:55.501Z
Learning: Define agents for specific domain responsibilities and capabilities following the agent-based architecture pattern
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T01:22:55.501Z
Learning: Maintain consistency in agent naming and interaction patterns across the system
🪛 ast-grep (0.43.0)
scripts/validate_skills.py
[warning] 87-87: Do not make http calls without encryption
Context: "http://"
Note: [CWE-319].
(requests-http)
🪛 markdownlint-cli2 (0.22.1)
.agents/skills/README.md
[warning] 38-38: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 67-67: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 69-69: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 71-71: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
.agents/skills/TEMPLATE.md
[warning] 90-90: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 90-90: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
AGENTS.md
[warning] 137-137: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 139-139: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
.agents/skills/aiq-add-data-source/references/package-layout.md
[warning] 10-10: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (10)
.agents/skills/aiq-add-data-source/SKILL.md (1)
1-94: LGTM!.agents/skills/aiq-add-data-source/references/registry-and-ui.md (1)
1-62: LGTM!.agents/skills/aiq-add-data-source/references/validation.md (1)
1-57: LGTM!.claude/skills/aiq-add-data-source (1)
1-1: LGTM!.pre-commit-config.yaml (1)
51-57: LGTM!scripts/validate_skills.py (1)
1-174: Verify Ruff compliance for the Python files in this changeset. The prior Ruff command couldn’t run here becauseuvisn’t available (/bin/bash: uv: command not found), so Ruff’s E,F,W,I,PL,UP checks (line length 120, target py311) andruff format --checkstill need to be executed forscripts/validate_skills.pyandtests/test_agent_skills.pybefore merge..agents/skills/README.md (1)
67-73: 💤 Low valueAdd blank lines around bash code blocks (Markdown style).
Lines 67–73 show a bash code block without blank lines before and after. Markdown linting (markdownlint-cli2) expects blank lines around fenced code blocks (MD031).
.agents/skills/TEMPLATE.md (1)
1-105: LGTM!AGENTS.md (1)
1-157: LGTM!CLAUDE.md (1)
1-1: LGTM!
efajardo-nv
changed the title
… aiq-add-data-source Adds repo-local maintainer Agent Skills under .agents/skills/: root AGENTS.md (CLAUDE.md symlink), skill index README, authoring TEMPLATE, a skill validator wired into pre-commit and pytest, and the aiq-add-data-source exemplar skill. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Eli Fajardo <efajardo@nvidia.com>
…package-layout.md Signed-off-by: Eli Fajardo <efajardo@nvidia.com>
…tor's BUNDLE_DIRS Signed-off-by: Eli Fajardo <efajardo@nvidia.com>
5489a4b to
34dd4c0
Compare
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Eli Fajardo <efajardo@nvidia.com>
There was a problem hiding this comment.
Actionable comments posted: 9
🤖 Prompt for all review comments with 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.
Inline comments:
In @.agents/skills/aiq-add-data-source/references/package-layout.md:
- Around line 63-95: The example uses os.environ inside the my_data_source
function but never imports os; add an import os at the top of the module so
my_data_source (and the stub logic that reads MY_API_KEY) can access os.environ.
Locate the module header where other imports (e.g., from pydantic,
nat.builder.builder) are declared and add the os import alongside them to fix
the NameError.
In @.agents/skills/aiq-add-data-source/references/validation.md:
- Around line 29-36: Update the Lint step in the validation runbook to run both
style checks and formatting checks: amend the "Lint" section (the commands shown
in .agents/skills/aiq-add-data-source/references/validation.md) to include `ruff
format --check` in addition to `ruff check` (keeping the same Ruff settings:
line length 120, target 3.11) so the validation enforces both linting and format
consistency.
In @.agents/skills/README.md:
- Around line 38-45: Add a language label to the top tree fence (e.g., ```text
or ```bash) in .agents/skills/README.md and ensure every fenced shell block in
the numbered list has a blank line before and after the fence; also add a blank
line before and after the `git commit` fenced example in AGENTS.md so all fenced
code blocks follow markdownlint rules. Locate the block that lists SKILL.md,
references/, scripts/, templates/, assets/ and update the opening ``` to include
a language tag, then scan the numbered list and AGENTS.md for fenced shell
examples and insert single blank lines immediately above and below each fenced
block.
In @.agents/skills/TEMPLATE.md:
- Around line 69-79: Update the "Validation" checklist in TEMPLATE.md to include
the Ruff formatting check by adding the command `ruff format --check
<path/to/changed/code>` alongside the existing `uv run ruff check` entry so
authors run both lint and format validation; ensure the expected result text is
updated to require both tests passing and no Ruff lint/format failures for the
changed code.
In @.pre-commit-config.yaml:
- Line 55: The pre-commit hook configuration for the validate-skills hook
currently uses a floating dependency via additional_dependencies: ["pyyaml"];
update that entry to pin pyyaml to the resolved version (e.g., pyyaml==6.0.3) so
pre-commit runs are reproducible—edit the validate-skills hook's
additional_dependencies to use the exact version string instead of the unpinned
package.
In `@scripts/validate_skills.py`:
- Around line 110-114: Wrap the call to skill_md.read_text(encoding="utf-8") in
a try/except that catches UnicodeDecodeError and OSError, so a bad/unreadable
SKILL.md doesn't crash the validator; on exception call report.fail(dir_name,
f"Unable to read SKILL.md: {err}") (or similar message including the exception)
and return early for that skill, then continue processing other skills; keep the
existing frontmatter parsing via _parse_frontmatter and its report.fail path
unchanged.
- Around line 90-97: The link validation currently uses first_segment and
.exists() which allows path traversal like "references/../../README.md"; change
to resolve the candidate path and verify it stays inside the intended bundle
directory before accepting it. Concretely, build candidate = (skill_md.parent /
path_part).resolve(strict=False), compute bundle_root = (skill_md.parent /
first_segment).resolve(strict=False) (or use a commonpath check), then fail via
report.fail(dir_name, ...) if not candidate.exists() or if candidate is not
under bundle_root (i.e., not candidate.is_relative_to(bundle_root) / commonpath
mismatch). This prevents "../" escapes while preserving normal in-bundle links.
- Line 54: FRONTMATTER_RE currently only accepts LF delimiters and rejects CRLF
files; update the regular expression FRONTMATTER_RE so the opening and closing
frontmatter delimiters accept optional CR (use \r?\n) — e.g. change the pattern
from matching "^---\n(.*?)\n---" to a pattern that allows CRLF and still uses
re.DOTALL so YAML body can span lines; ensure the symbol FRONTMATTER_RE is
updated accordingly so CRLF-authored SKILL.md files parse correctly.
In `@tests/test_agent_skills.py`:
- Around line 31-37: Add explicit guards after creating the dynamic import spec
to fail fast with a helpful error: check that spec is not None and that
spec.loader is not None before using them (the variables named spec and
spec.loader in this block), and raise an AssertionError or RuntimeError with a
clear message like "failed to create import spec for VALIDATOR" or "import spec
loader missing for VALIDATOR" instead of letting spec.loader.exec_module raise
an unclear exception; then proceed to register module in sys.modules and call
spec.loader.exec_module(module) as before.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 312e32f7-e0b4-48f5-a52a-c0cfba4aba29
📒 Files selected for processing (12)
.agents/skills/README.md.agents/skills/TEMPLATE.md.agents/skills/aiq-add-data-source/SKILL.md.agents/skills/aiq-add-data-source/references/package-layout.md.agents/skills/aiq-add-data-source/references/registry-and-ui.md.agents/skills/aiq-add-data-source/references/validation.md.claude/skills/aiq-add-data-source.pre-commit-config.yamlAGENTS.mdCLAUDE.mdscripts/validate_skills.pytests/test_agent_skills.py
📜 Review details
🧰 Additional context used
📓 Path-based instructions (6)
**
⚙️ CodeRabbit configuration file
**: # Contributing GuidelinesWe welcome contributions to the NVIDIA AI-Q blueprint. This repository uses a maintainer-reviewed pull request workflow with DCO sign-off, code-owner review, copy-pr-bot mirroring, and GitHub Actions validation.
Before You Start
- Search existing issues and pull requests before opening new work.
- Open an issue or discussion before large design changes, public APIs, deployment changes, or contributor workflow changes.
- Do not include secrets, credentials, private hostnames, internal-only logs, customer data, or generated local artifacts.
- Target the
developbranch unless a maintainer asks you to use a release branch.Pull Requests
- Fork the repository and create a focused branch from
develop.- Make the smallest coherent change and add or update tests for behavior changes.
- Sign off every commit with
git commit -s.- Run the relevant local validation before opening the PR.
- Open a pull request into
developand fill out the PR template with exact validation evidence.- Address review feedback until required checks and code-owner review pass.
Local Validation
Use the narrowest command that covers your change, then include the exact output or workflow link in the PR.
uv sync --group dev uv run ruff check . uv run ruff format --check . uv run pytestFor UI changes:
cd frontends/ui npm ci npm run lint npm run type-check npm run test:ci npm run buildFor deployment changes, run the relevant Helm or compose validation and describe the environment used.
CI and Bot Workflow
AI-Q uses push-triggered GitHub Actions. Pull requests are mirrored by copy-pr-bot to
pull-request/<PR number>branches after a maintainer or configured vetter comments/ok to test, and CI runs on those mirrored branches.Repository owners, organization members, and collaborators can request NVSkills validation by commenting:
/nvskills-ciMaintainers can request bot-driven merge with:
``...
Files:
CLAUDE.mdAGENTS.mdtests/test_agent_skills.pyscripts/validate_skills.py
{.github/**,ci/**,.pre-commit-config.yaml,pyproject.toml,uv.lock}
⚙️ CodeRabbit configuration file
{.github/**,ci/**,.pre-commit-config.yaml,pyproject.toml,uv.lock}: Review automation and packaging changes for least-privilege permissions, pinned versions where appropriate,
copy-pr-bot pull-request/ branch behavior, reproducible uv/npm setup, secret handling, and consistency with
the documented validation matrix.
Files:
.pre-commit-config.yaml
{skills/**,.agents/skills/**,.claude/skills/**,.github/skill-eval/**}
⚙️ CodeRabbit configuration file
{skills/**,.agents/skills/**,.claude/skills/**,.github/skill-eval/**}: Review Agent Skill and skill-eval changes for valid skill metadata, deterministic eval specs, safe handling of
credentials, and clear generated-output boundaries. Do not flag SKILL.md files for missing SPDX headers when the
entrypoint intentionally starts with YAML frontmatter.
Files:
.claude/skills/aiq-add-data-source.agents/skills/aiq-add-data-source/references/validation.md.agents/skills/README.md.agents/skills/aiq-add-data-source/SKILL.md.agents/skills/TEMPLATE.md.agents/skills/aiq-add-data-source/references/registry-and-ui.md.agents/skills/aiq-add-data-source/references/package-layout.md
AGENTS.md
📄 CodeRabbit inference engine (CLAUDE.md)
Document agents in AGENTS.md file with their purpose, capabilities, and usage
Files:
AGENTS.md
**/*.py
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run ruff check and ruff format validation for Python code changes
**/*.py: Python code must be linted and formatted with Ruff using line length 120, target Python 3.11, and rule sets E,F,W,I,PL,UP with isort force-single-line import style
Match the existing import and formatting style in Python; do not hand-reformat unrelated code
Files:
tests/test_agent_skills.pyscripts/validate_skills.py
**/*test*.py
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run pytest for all behavior changes in Python code
Files:
tests/test_agent_skills.py
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T02:19:05.974Z
Learning: pre-commit enforces linting, formatting, secret detection, link checking, and skill validation; install it and let it run before pushing
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T02:19:05.974Z
Learning: Use a maintainer-reviewed PR workflow with DCO sign-off; every commit must be signed off with git commit -s
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T02:19:05.974Z
Learning: Keep PRs scoped with no unrelated files, no accidental generated artifacts, and no secrets; provide validation evidence with commands run and results
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T02:19:05.974Z
Learning: Stay inside this repository; if the workspace contains adjacent repos, do not edit them as part of an AI-Q change
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T02:19:05.974Z
Learning: Treat sources/* as independent packages; prefer the smallest change scoped to the package you are touching
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T02:19:05.974Z
Learning: For substantial behavior, auth, UI, or architecture changes, open a design discussion before coding rather than landing a large unreviewed change
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T02:19:05.974Z
Learning: Repository-global rules live in AGENTS.md; task-specific runbooks live in .agents/skills/; API-consumer skills live in skills/
🪛 ast-grep (0.43.0)
scripts/validate_skills.py
[warning] 87-87: Do not make http calls without encryption
Context: "http://"
Note: [CWE-319].
(requests-http)
🪛 markdownlint-cli2 (0.22.1)
.agents/skills/README.md
[warning] 38-38: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 68-68: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 70-70: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 72-72: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
AGENTS.md
[warning] 137-137: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 139-139: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
.agents/skills/TEMPLATE.md
[warning] 90-90: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 90-90: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (2)
CLAUDE.md (1)
1-1: LGTM!.agents/skills/aiq-add-data-source/SKILL.md (1)
1-94: LGTM!
…mple Signed-off-by: Eli Fajardo <efajardo@nvidia.com>
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
tests/test_agent_skills.py (1)
41-46: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winAdd negative-path coverage for the validator.
This test only proves the current repo skills pass the happy path. It would not catch the validator regressions above, such as CRLF frontmatter, bundle-link traversal, or unreadable
SKILL.mdhandling. Add tempdir-based cases that callvalidate_roots()on intentionally malformed bundles. As per coding guidelines, "Run pytest for all behavior changes in Python code" and "Make the smallest coherent change and add or update tests for behavior changes."🤖 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 `@tests/test_agent_skills.py` around lines 41 - 46, Extend test_agent_skills_are_valid by adding tmpdir-based negative-path cases that call the same _load_validator().validate_roots(...) (use tmp_path or tmpdir to create ephemeral skill bundles) and assert the validator reports errors for malformed bundles; specifically create separate temp bundles to test: (1) CRLF frontmatter in SKILL.md, (2) a bundle-link that traverses out of the bundle, and (3) an unreadable SKILL.md (change file permissions) — for each bundle call validate_roots([temp_bundle_path]) and assert report.errors is not empty and contains an expected substring, keeping existing SKILLS_ROOT happy-path check intact.Source: Coding guidelines
🤖 Prompt for all review comments with 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.
Outside diff comments:
In `@tests/test_agent_skills.py`:
- Around line 41-46: Extend test_agent_skills_are_valid by adding tmpdir-based
negative-path cases that call the same _load_validator().validate_roots(...)
(use tmp_path or tmpdir to create ephemeral skill bundles) and assert the
validator reports errors for malformed bundles; specifically create separate
temp bundles to test: (1) CRLF frontmatter in SKILL.md, (2) a bundle-link that
traverses out of the bundle, and (3) an unreadable SKILL.md (change file
permissions) — for each bundle call validate_roots([temp_bundle_path]) and
assert report.errors is not empty and contains an expected substring, keeping
existing SKILLS_ROOT happy-path check intact.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 837c7825-c647-4616-a9ca-239be54cd535
📒 Files selected for processing (2)
scripts/validate_skills.pytests/test_agent_skills.py
📜 Review details
🧰 Additional context used
📓 Path-based instructions (4)
**/*.py
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run ruff check and ruff format validation for Python code changes
**/*.py: Python code must be linted and formatted with Ruff using line length 120, target Python 3.11, rule sets E,F,W,I,PL,UP, and isort with force-single-line
Never print or log secret values, including in tool output or error messages
Missing-secret paths must degrade gracefully (stub/skip), not crash or leak
Files:
tests/test_agent_skills.pyscripts/validate_skills.py
**/*test*.py
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run pytest for all behavior changes in Python code
Files:
tests/test_agent_skills.py
**/*.{py,js,ts,tsx,yml,yaml}
📄 CodeRabbit inference engine (AGENTS.md)
Never commit secrets, tokens, or environment-specific hostnames; use environment variables and SecretStr; resolve API keys at runtime
Files:
tests/test_agent_skills.pyscripts/validate_skills.py
**
⚙️ CodeRabbit configuration file
**: # Contributing GuidelinesWe welcome contributions to the NVIDIA AI-Q blueprint. This repository uses a maintainer-reviewed pull request workflow with DCO sign-off, code-owner review, copy-pr-bot mirroring, and GitHub Actions validation.
Before You Start
- Search existing issues and pull requests before opening new work.
- Open an issue or discussion before large design changes, public APIs, deployment changes, or contributor workflow changes.
- Do not include secrets, credentials, private hostnames, internal-only logs, customer data, or generated local artifacts.
- Target the
developbranch unless a maintainer asks you to use a release branch.Pull Requests
- Fork the repository and create a focused branch from
develop.- Make the smallest coherent change and add or update tests for behavior changes.
- Sign off every commit with
git commit -s.- Run the relevant local validation before opening the PR.
- Open a pull request into
developand fill out the PR template with exact validation evidence.- Address review feedback until required checks and code-owner review pass.
Local Validation
Use the narrowest command that covers your change, then include the exact output or workflow link in the PR.
uv sync --group dev uv run ruff check . uv run ruff format --check . uv run pytestFor UI changes:
cd frontends/ui npm ci npm run lint npm run type-check npm run test:ci npm run buildFor deployment changes, run the relevant Helm or compose validation and describe the environment used.
CI and Bot Workflow
AI-Q uses push-triggered GitHub Actions. Pull requests are mirrored by copy-pr-bot to
pull-request/<PR number>branches after a maintainer or configured vetter comments/ok to test, and CI runs on those mirrored branches.Repository owners, organization members, and collaborators can request NVSkills validation by commenting:
/nvskills-ciMaintainers can request bot-driven merge with:
``...
Files:
tests/test_agent_skills.pyscripts/validate_skills.py
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T02:26:27.927Z
Learning: Do not hand-reformat unrelated code when making changes
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T02:26:27.927Z
Learning: For substantial behavior, auth, UI, or architecture changes, open a design discussion before coding rather than landing a large unreviewed change
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T02:26:27.927Z
Learning: Every commit must be signed off with git commit -s and contain a Signed-off-by trailer; commits without sign-off may be rejected
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T02:26:27.927Z
Learning: Keep PRs scoped: no unrelated files, no accidental generated artifacts, no secrets; provide validation evidence
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T02:26:27.927Z
Learning: Do not edit adjacent repositories (e.g., sibling NeMo-Relay checkout) as part of an AI-Q change
🔇 Additional comments (5)
scripts/validate_skills.py (4)
54-54: Keep frontmatter parsing CRLF-safe.
FRONTMATTER_REstill matches LF-only delimiters, so a Windows-authoredSKILL.mdwith valid YAML frontmatter can still be rejected.
90-97: Reject bundle-link escapes before checking existence.
references/../../README.mdstill passes thefirst_segmentgate and.exists()check here, which lets links escape the skill bundle while still satisfying the current validator.
110-114: Do not let one unreadableSKILL.mdabort the whole run.
read_text()can still raiseOSErrororUnicodeDecodeErrorhere and terminate validation before the remaining skills are checked. As per coding guidelines, "Missing-secret paths must degrade gracefully (stub/skip), not crash or leak."Source: Coding guidelines
151-171: LGTM!tests/test_agent_skills.py (1)
32-37: Fail fast when dynamic import spec resolution fails.
spec_from_file_location()can still returnNone, andspec.loadercan still beNone; the current path turns that into a less-diagnostic failure inmodule_from_spec()orexec_module().
Signed-off-by: Eli Fajardo <efajardo@nvidia.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Eli Fajardo <efajardo@nvidia.com>
Cover bundle-link escape and unreadable SKILL.md error paths, plus a positive guard that CRLF frontmatter stays accepted. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Eli Fajardo <efajardo@nvidia.com>
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
.agents/skills/aiq-add-data-source/references/validation.md (1)
11-17:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winMake the validation steps actually fail when registration is broken.
Step 1 only installs the package; it does not assert that the
nat.pluginsentry point exists. Step 4 only curls the endpoint; it does not fail on HTTP errors or verify thatmy_data_sourceappears in the response. As written, both checks can pass even when registration is wrong.Also applies to: 40-47
🤖 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 @.agents/skills/aiq-add-data-source/references/validation.md around lines 11 - 17, Update the validation steps so they assert plugin registration: after step 1 (package install) add a check that the `nat.plugins` entry point for `my_data_source` is present (e.g., run Python code or `pkg_resources`/`importlib.metadata` lookup and fail non-zero if missing), and update step 4 to curl the service endpoint but exit non-zero on HTTP errors and assert the response body contains `my_data_source`; reference `nat.plugins`, `my_data_source`, the installation step and the curl endpoint in the checks so the validation fails when registration is broken..agents/skills/README.md (1)
8-17:⚠️ Potential issue | 🟠 Major | ⚡ Quick winUpdate the canonical docs to match this new skill-location contract.
This README now tells contributors to author maintainer skills under
.agents/skills/and symlink.claude/skills/*into that tree, but the supplieddocs/source/integration/agent-skills.mdsnippets still document.agents/skills -> ../skillsand.claude/skills/* -> ../../skills/*. That leavesdocs/source/contradicting the workflow defined here.As per coding guidelines, “Update the docs under
docs/source/when behavior, configuration, or workflows change. Keep the docs canonical; do not duplicate full doc pages into skill text.”Also applies to: 65-80
🤖 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 @.agents/skills/README.md around lines 8 - 17, The docs under docs/source/integration/agent-skills.md are out of sync with the new skill-location contract described in .agents/skills/README.md; update the documentation text and any example symlink commands in agent-skills.md so they show maintainer skills living in .agents/skills/ with contributors creating symlinks from .claude/skills/* into .agents/skills/ (not the old .agents/skills -> ../skills or .claude/skills/* -> ../../skills/* paths), and make the same correction for the other referenced snippet range (lines referenced as 65-80) so the canonical docs in docs/source/ match the README workflow exactly.Sources: Coding guidelines, Learnings
.pre-commit-config.yaml (1)
51-57:⚠️ Potential issue | 🟠 MajorPin
validate-skillsto Python 3.11 to match the repo target.
.pre-commit-config.yamlsetsdefault_language_version: python: python3for the localvalidate-skillshook (nolanguage_versionoverride), butpyproject.tomltargetsrequires-python >=3.11,<3.14andscripts/validate_skills.pyuses Python-3.10+ syntax (dict | None) andPath.is_relative_to. If a contributor’spython3is <3.11, the hook may crash before validation. Addlanguage_version: python3.11to thevalidate-skillshook (or bump the global default).🤖 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 @.pre-commit-config.yaml around lines 51 - 57, The pre-commit hook entry with id "validate-skills" invokes the script validate_skills.py but relies on the repo default python which may be older than 3.11; add language_version: python3.11 to the validate-skills hook in .pre-commit-config.yaml so the hook runs under Python 3.11 (or alternatively bump the global default_language_version) to match pyproject.toml and the script's Python-3.11+ syntax.Source: Coding guidelines
🤖 Prompt for all review comments with 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.
Inline comments:
In `@scripts/validate_skills.py`:
- Line 54: The FRONTMATTER_RE pattern allows the closing '---' to be part of a
longer token (e.g. '----' or '---oops'); update the FRONTMATTER_RE regex to
require the closing fence to be a full line by adding an end-of-line or EOF
anchor (e.g. change the pattern used in FRONTMATTER_RE to require the closing
'---' to be followed by either a newline or end-of-file using a non-capturing
group like (?:\r?\n|$) while preserving DOTALL).
---
Outside diff comments:
In @.agents/skills/aiq-add-data-source/references/validation.md:
- Around line 11-17: Update the validation steps so they assert plugin
registration: after step 1 (package install) add a check that the `nat.plugins`
entry point for `my_data_source` is present (e.g., run Python code or
`pkg_resources`/`importlib.metadata` lookup and fail non-zero if missing), and
update step 4 to curl the service endpoint but exit non-zero on HTTP errors and
assert the response body contains `my_data_source`; reference `nat.plugins`,
`my_data_source`, the installation step and the curl endpoint in the checks so
the validation fails when registration is broken.
In @.agents/skills/README.md:
- Around line 8-17: The docs under docs/source/integration/agent-skills.md are
out of sync with the new skill-location contract described in
.agents/skills/README.md; update the documentation text and any example symlink
commands in agent-skills.md so they show maintainer skills living in
.agents/skills/ with contributors creating symlinks from .claude/skills/* into
.agents/skills/ (not the old .agents/skills -> ../skills or .claude/skills/* ->
../../skills/* paths), and make the same correction for the other referenced
snippet range (lines referenced as 65-80) so the canonical docs in docs/source/
match the README workflow exactly.
In @.pre-commit-config.yaml:
- Around line 51-57: The pre-commit hook entry with id "validate-skills" invokes
the script validate_skills.py but relies on the repo default python which may be
older than 3.11; add language_version: python3.11 to the validate-skills hook in
.pre-commit-config.yaml so the hook runs under Python 3.11 (or alternatively
bump the global default_language_version) to match pyproject.toml and the
script's Python-3.11+ syntax.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 8ca85dbd-46ff-460a-811a-b3862d35eb17
📒 Files selected for processing (8)
.agents/skills/README.md.agents/skills/TEMPLATE.md.agents/skills/aiq-add-data-source/references/package-layout.md.agents/skills/aiq-add-data-source/references/validation.md.pre-commit-config.yamlAGENTS.mdscripts/validate_skills.pytests/test_agent_skills.py
📜 Review details
🧰 Additional context used
📓 Path-based instructions (5)
{.github/**,ci/**,.pre-commit-config.yaml,pyproject.toml,uv.lock}
⚙️ CodeRabbit configuration file
{.github/**,ci/**,.pre-commit-config.yaml,pyproject.toml,uv.lock}: Review automation and packaging changes for least-privilege permissions, pinned versions where appropriate,
copy-pr-bot pull-request/ branch behavior, reproducible uv/npm setup, secret handling, and consistency with
the documented validation matrix.
Files:
.pre-commit-config.yaml
{skills/**,.agents/skills/**,.claude/skills/**,.github/skill-eval/**}
⚙️ CodeRabbit configuration file
{skills/**,.agents/skills/**,.claude/skills/**,.github/skill-eval/**}: Review Agent Skill and skill-eval changes for valid skill metadata, deterministic eval specs, safe handling of
credentials, and clear generated-output boundaries. Do not flag SKILL.md files for missing SPDX headers when the
entrypoint intentionally starts with YAML frontmatter.
Files:
.agents/skills/aiq-add-data-source/references/validation.md.agents/skills/aiq-add-data-source/references/package-layout.md.agents/skills/TEMPLATE.md.agents/skills/README.md
**/*.py
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run ruff check and ruff format validation for Python code changes
**/*.py: Lint Python code with Ruff (line length 120, target Python 3.11, rule sets E,F,W,I,PL,UP; isort force-single-line). Match existing import and formatting style; do not hand-reformat unrelated code.
Format Python code check with Ruff usinguv run ruff format --check .
Never print or log secret values, including in tool output or error messages.
Files:
tests/test_agent_skills.pyscripts/validate_skills.py
**/*test*.py
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run pytest for all behavior changes in Python code
Files:
tests/test_agent_skills.py
**
⚙️ CodeRabbit configuration file
**: # Contributing GuidelinesWe welcome contributions to the NVIDIA AI-Q blueprint. This repository uses a maintainer-reviewed pull request workflow with DCO sign-off, code-owner review, copy-pr-bot mirroring, and GitHub Actions validation.
Before You Start
- Search existing issues and pull requests before opening new work.
- Open an issue or discussion before large design changes, public APIs, deployment changes, or contributor workflow changes.
- Do not include secrets, credentials, private hostnames, internal-only logs, customer data, or generated local artifacts.
- Target the
developbranch unless a maintainer asks you to use a release branch.Pull Requests
- Fork the repository and create a focused branch from
develop.- Make the smallest coherent change and add or update tests for behavior changes.
- Sign off every commit with
git commit -s.- Run the relevant local validation before opening the PR.
- Open a pull request into
developand fill out the PR template with exact validation evidence.- Address review feedback until required checks and code-owner review pass.
Local Validation
Use the narrowest command that covers your change, then include the exact output or workflow link in the PR.
uv sync --group dev uv run ruff check . uv run ruff format --check . uv run pytestFor UI changes:
cd frontends/ui npm ci npm run lint npm run type-check npm run test:ci npm run buildFor deployment changes, run the relevant Helm or compose validation and describe the environment used.
CI and Bot Workflow
AI-Q uses push-triggered GitHub Actions. Pull requests are mirrored by copy-pr-bot to
pull-request/<PR number>branches after a maintainer or configured vetter comments/ok to test, and CI runs on those mirrored branches.Repository owners, organization members, and collaborators can request NVSkills validation by commenting:
/nvskills-ciMaintainers can request bot-driven merge with:
``...
Files:
tests/test_agent_skills.pyAGENTS.mdscripts/validate_skills.py
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T03:06:31.294Z
Learning: Never commit secrets, tokens, or environment-specific hostnames. Use environment variables and `SecretStr`; resolve API keys at runtime.
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T03:06:31.294Z
Learning: Missing-secret paths must degrade gracefully (stub/skip), not crash or leak.
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T03:06:31.294Z
Learning: Respect authenticated data sources: honor `requires_auth`, per-user token pass-through, and backend token validators. Apply owner guardrails before loading protected report or artifact context into an agent.
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T03:06:31.294Z
Learning: Do not weaken or bypass `AuthMiddleware`, validators, or auth gating without a prior design discussion.
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T03:06:31.294Z
Learning: Update the docs under `docs/source/` when behavior, configuration, or workflows change. Keep the docs canonical; do not duplicate full doc pages into skill text.
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T03:06:31.294Z
Learning: Every commit must be signed off with DCO: `git commit -s -m "Concise, scoped change"`. The commit must contain a `Signed-off-by: Your Name <youremail.com>` trailer.
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T03:06:31.294Z
Learning: Keep PRs scoped: no unrelated files, no accidental generated artifacts, no secrets. Provide validation evidence (commands run and results).
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T03:06:31.294Z
Learning: Do not edit adjacent repositories (e.g., sibling NeMo-Relay checkout) as part of an AI-Q change. Stay inside this repository and treat `sources/*` as independent packages: prefer the smallest change scoped to the package you are touching.
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T03:06:31.294Z
Learning: Backend Python package code should reside in `src/aiq_agent/`. Data-source and tool packages should reside in `sources/`. Frontends and tooling should reside in `frontends/`. Configs, deployment, and docs should reside in `configs/`, `deploy/`, and `docs/` respectively.
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T03:06:41.562Z
Learning: Define agent capabilities and responsibilities in a structured format with clear sections for purpose, actions, and dependencies
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T03:06:41.562Z
Learning: Document agent interfaces and communication protocols when defining agents
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-12T03:06:41.562Z
Learning: Maintain consistency in agent naming conventions across the codebase
Require the closing '---' to be a full line (newline or EOF) so tokens like '----' or '---oops' are not accepted as a valid frontmatter close. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Eli Fajardo <efajardo@nvidia.com>
|
/ok to test 8681926 |
AjayThorve
left a comment
AjayThorve
left a comment
There was a problem hiding this comment.
One blocking docs-consistency issue from my review.
AjayThorve
left a comment
AjayThorve
left a comment
There was a problem hiding this comment.
approving, pending one requested change
|
/nvskills-ci |
…on page Signed-off-by: Eli Fajardo <efajardo@nvidia.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with 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.
Inline comments:
In `@docs/source/integration/agent-skills.md`:
- Around line 20-21: Remove all references to the non-existent aiq-add-tool
skill from the documentation. In docs/source/integration/agent-skills.md, remove
aiq-add-tool from the table examples at lines 20-21 (replace it with only
aiq-add-data-source in the second column) and remove it from the symlink targets
section at lines 110-111. Additionally, check .agents/skills/README.md and
remove any references to aiq-add-tool listed as an example maintainer skill,
since only aiq-add-data-source actually exists in the .agents/skills/ directory.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 035957d3-bf43-43b8-a690-5869a6a9618b
📒 Files selected for processing (1)
docs/source/integration/agent-skills.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (3)
docs/source/**
📄 CodeRabbit inference engine (AGENTS.md)
Update the docs under docs/source/ when behavior, configuration, or workflows change. Keep docs canonical; do not duplicate full doc pages into skill text.
Files:
docs/source/integration/agent-skills.md
{docs/**,README.md,CONTRIBUTING.md,SECURITY.md,CODE-OF-CONDUCT.md}
⚙️ CodeRabbit configuration file
{docs/**,README.md,CONTRIBUTING.md,SECURITY.md,CODE-OF-CONDUCT.md}: Review documentation for command accuracy, branch-name consistency, current CI and copy-pr-bot behavior, public
vs internal boundary clarity, stale examples, and links that no longer match the repository layout.
Files:
docs/source/integration/agent-skills.md
**
⚙️ CodeRabbit configuration file
**: # Contributing GuidelinesWe welcome contributions to the NVIDIA AI-Q blueprint. This repository uses a maintainer-reviewed pull request workflow with DCO sign-off, code-owner review, copy-pr-bot mirroring, and GitHub Actions validation.
Before You Start
- Search existing issues and pull requests before opening new work.
- Open an issue or discussion before large design changes, public APIs, deployment changes, or contributor workflow changes.
- Do not include secrets, credentials, private hostnames, internal-only logs, customer data, or generated local artifacts.
- Target the
developbranch unless a maintainer asks you to use a release branch.Pull Requests
- Fork the repository and create a focused branch from
develop.- Make the smallest coherent change and add or update tests for behavior changes.
- Sign off every commit with
git commit -s.- Run the relevant local validation before opening the PR.
- Open a pull request into
developand fill out the PR template with exact validation evidence.- Address review feedback until required checks and code-owner review pass.
Local Validation
Use the narrowest command that covers your change, then include the exact output or workflow link in the PR.
uv sync --group dev uv run ruff check . uv run ruff format --check . uv run pytestFor UI changes:
cd frontends/ui npm ci npm run lint npm run type-check npm run test:ci npm run buildFor deployment changes, run the relevant Helm or compose validation and describe the environment used.
CI and Bot Workflow
AI-Q uses push-triggered GitHub Actions. Pull requests are mirrored by copy-pr-bot to
pull-request/<PR number>branches after a maintainer or configured vetter comments/ok to test, and CI runs on those mirrored branches.Repository owners, organization members, and collaborators can request NVSkills validation by commenting:
/nvskills-ciMaintainers can request bot-driven merge with:
``...
Files:
docs/source/integration/agent-skills.md
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-15T18:27:26.711Z
Learning: For substantial behavior, auth, UI, or architecture changes, open a design discussion before coding rather than landing a large unreviewed change.
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-15T18:27:26.711Z
Learning: Every commit must be signed off with git commit -s -m and include a Signed-off-by: Your Name <youremail.com> trailer. Commits without sign-off may be rejected.
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-15T18:27:26.711Z
Learning: Keep PRs scoped: no unrelated files, no accidental generated artifacts, no secrets. Provide validation evidence (commands run and results).
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-15T18:27:26.711Z
Learning: pre-commit enforces linting, formatting, secret detection, link checking, and skill validation. Install it and let it run before pushing.
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-15T18:27:26.711Z
Learning: Stay within the AI-Q repository. Do not edit adjacent repositories (e.g., NeMo-Relay) as part of AI-Q changes. Treat sources/* as independent packages: prefer the smallest change scoped to the package being touched.
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-15T18:27:26.711Z
Learning: Backend code should be organized under src/aiq_agent/. Data-source and tool packages should be under sources/. Frontends and tooling under frontends/. Configs, deployment, and docs under configs/, deploy/, and docs/.
Learnt from: CR
Repo: NVIDIA-AI-Blueprints/aiq
Timestamp: 2026-06-15T18:27:29.501Z
Learning: Maintain comprehensive documentation of all agent implementations with their capabilities and integration patterns
@AjayThorve, there was an error processing your request: See the following link for more information: https://docs.gha-runners.nvidia.com/cpr/e/1/ |
|
/nvskills-ci |
Signed-off-by: Eli Fajardo <efajardo@nvidia.com>
|
/ok to test d6055ee |
1dbed5d
into
NVIDIA-AI-Blueprints:develop
…ainer skill artifacts The maintainer skill set (.agents/skills/) shipped in NVIDIA-AI-Blueprints#269/NVIDIA-AI-Blueprints#277 carried a few documentation defects found while auditing it against the live AI-Q config schema and the sibling NeMo-Relay skill set. Documentation-only; no skills are added or removed. - aiq-add-data-source: correct the data_source_registry YAML example to match DataSourceEntry / DataSourceRegistryConfig and the working configs -- use the `data_sources` instance name, drop the non-existent `category` field, and list `tools` as plain function-instance-name strings (not `_type:` mappings). Add the missing `ruff format --check` to the validation block. - aiq-add-data-source: replace the dangling `aiq-ui-change` reference (no such skill) with a generic frontends/ui note. - aiq-prepare-pr, aiq-release-qa: remove stray `</content>` artifacts left at the end of three skill files. - aiq-release-qa: the npm "only these scripts exist" claim was inaccurate (package.json defines many more); reword to recommend the canonical checks without asserting exhaustiveness. - docs/integration/agent-skills.md, .agents/skills/README.md: list all four maintainer skills and all four .claude/skills maintainer symlinks. Validation: scripts/validate_skills.py (6 skills OK), pytest tests/test_agent_skills.py (4 passed), and pre-commit (detect-secrets, validate-skills, markdown-link-check) on the changed files all pass. Signed-off-by: Zhongxuan Wang <daniewang@nvidia.com>
…ainer skill artifacts (#281) The maintainer skill set (.agents/skills/) shipped in #269/#277 carried a few documentation defects found while auditing it against the live AI-Q config schema and the sibling NeMo-Relay skill set. Documentation-only; no skills are added or removed. - aiq-add-data-source: correct the data_source_registry YAML example to match DataSourceEntry / DataSourceRegistryConfig and the working configs -- use the `data_sources` instance name, drop the non-existent `category` field, and list `tools` as plain function-instance-name strings (not `_type:` mappings). Add the missing `ruff format --check` to the validation block. - aiq-add-data-source: replace the dangling `aiq-ui-change` reference (no such skill) with a generic frontends/ui note. - aiq-prepare-pr, aiq-release-qa: remove stray `</content>` artifacts left at the end of three skill files. - aiq-release-qa: the npm "only these scripts exist" claim was inaccurate (package.json defines many more); reword to recommend the canonical checks without asserting exhaustiveness. - docs/integration/agent-skills.md, .agents/skills/README.md: list all four maintainer skills and all four .claude/skills maintainer symlinks. Validation: scripts/validate_skills.py (6 skills OK), pytest tests/test_agent_skills.py (4 passed), and pre-commit (detect-secrets, validate-skills, markdown-link-check) on the changed files all pass. Signed-off-by: Zhongxuan Wang <daniewang@nvidia.com>
2 participants
Overview
Adds the first repo-local maintainer Agent Skills to AI-Q, mirroring the
NeMo Relay split between repo guidance, maintainer skills, and consumer skills.
This is the foundation slice of the DEVSKILLS work: repo guidance +
authoring scaffolding + a validator + one exemplar skill. It intentionally adds
no in-product skill runtime — these are static guidance bundles that coding
agents (Claude Code, Codex, Cursor, OpenCode) load while working in this repo.
What's included:
AGENTS.md(+CLAUDE.mdsymlink) — repository-global contract for codingagents: structure, build/test/eval commands, coding style, security/auth rules,
frontend conventions, docs expectations, and DCO/PR hygiene.
.agents/skills/README.md— maintainer skill index; explains maintainerskills (
.agents/skills/) vs. API-consumer skills (skills/:aiq-deploy,aiq-research)..agents/skills/TEMPLATE.md— canonical authoring template and frontmattercontract for new skills.
scripts/validate_skills.py— offline validator (frontmatter, naming, name↔ directory match, description length, in-bundle link existence), wired into
pre-commit and a pytest gate. This is the sole automated gate for
.agents/skills/, since the existingskills-evalworkflow is scoped toskills/only..agents/skills/aiq-add-data-source/— exemplar skill (SKILL.md + 3references) covering the full data-source workflow: package layout,
FunctionBaseConfig+@register_function, missing-secret stub,data_source_registrywiring, and validation commands. Surfaced to agents viaa
.claude/skills/symlink.Validation
Summary by CodeRabbit
AGENTS.mdand aCLAUDE.mdlink