docs(skills): correct data-source registry example and clean up maintainer skill artifacts by zhongxuanwang-nv · Pull Request #281 · NVIDIA-AI-Blueprints/aiq

zhongxuanwang-nv · 2026-06-23T18:27:28Z

Overview

The maintainer skill set under .agents/skills/ (landed in #269 and #277) carried
a few documentation defects, found while auditing the skills against the live
AI-Q config schema and the sibling NeMo-Relay skill set. This PR fixes them.
Documentation-only — no skills are added or removed, and no product/runtime
code changes.

What changed:

aiq-add-data-source registry example (highest-impact). The YAML example in
references/registry-and-ui.md did not match DataSourceEntry /
DataSourceRegistryConfig or any working config: it used the data_source_registry
instance name (real configs use data_sources), included a non-existent
category field, and expressed tools as _type: mappings instead of the
schema's list[FunctionRef] (plain function-instance-name strings). Corrected to
match the schema and configs/config_web_frag.yml. Also added the missing
uv run ruff format --check to the validation block (its own references/validation.md
and the sibling aiq-add-tool already include it).
Dangling skill reference. registry-and-ui.md routed UI work to a
non-existent aiq-ui-change skill; replaced with a generic frontends/ui/ note.
Stray </content> artifacts removed from three files
(aiq-prepare-pr/SKILL.md, aiq-prepare-pr/references/pr-checklist.md,
aiq-release-qa/references/validation-matrix.md).
Inaccurate npm-scripts claim. aiq-release-qa stated only a handful of npm
scripts "exist" in frontends/ui/package.json, which defines ~16; reworded to
recommend the canonical checks without asserting exhaustiveness.
Stale skill lists. docs/source/integration/agent-skills.md and
.agents/skills/README.md listed only aiq-add-data-source as a maintainer
example; updated both to list all four maintainer skills and all four
.claude/skills maintainer symlinks.

Validation

All commands run from the repo root; output below is verbatim.

$ uv run python scripts/validate_skills.py .agents/skills
Skill validation passed: 6 skill(s) OK.

$ uv run pytest tests/test_agent_skills.py -q
4 passed in 0.06s

$ uv run pre-commit run --files $(git diff --name-only origin/develop..HEAD)
Detect secrets...........................................................Passed
Validate agent skills....................................................Passed
Markdown Link Check......................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed

$ grep -rn 'content>' .agents/skills
(no matches — stray tags removed)

I ran the relevant local checks or explained why they are not applicable.
I added or updated tests for behavior changes. (N/A — documentation-only; no behavior change. The existing scripts/validate_skills.py + tests/test_agent_skills.py gates already cover these skill files and pass.)
I updated documentation for user-facing or contributor-facing changes.
I confirmed this PR does not include secrets, credentials, or internal-only data.
I certify this contribution under the Developer Certificate of Origin (DCO) and signed my commits with git commit -s or an equivalent sign-off.

Where should reviewers start?

.agents/skills/aiq-add-data-source/references/registry-and-ui.md — the registry
YAML example is the highest-impact fix; compare it against DataSourceEntry in
src/aiq_agent/common/data_source_registry.py and the data_sources: block in
configs/config_web_frag.yml. The rest are small, self-evident cleanups.

Related Issues

Relates to feat(skills): complete maintainer skill set and extend aiq-research #277, feat(skills): add maintainer skill set foundation and first skill #269 (fixes documentation defects in the maintainer skill set those PRs introduced).

🤖 Generated with Claude Code

Summary by CodeRabbit

Documentation
- Updated data source registration examples and validation procedures for clarity.
- Clarified AI-Q skill guidance and development workflow documentation.
- Refined validation checklists and frontend QA script specifications.

copy-pr-bot · 2026-06-23T18:27:32Z

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

coderabbitai · 2026-06-23T18:27:41Z

Important

Review skipped

No new commits to review since the last review.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 014e1ef1-1876-47f0-8719-a01665c499c2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

Walkthrough

Documentation-only updates across the agent skills layer: the aiq-add-data-source registry YAML example is corrected (removes category, fixes tools to plain instance names) and a ruff format --check step is added to its validation sequence. The aiq-release-qa npm script list is narrowed to the four canonical scripts. Trailing lines are trimmed from aiq-prepare-pr docs, and skill index tables plus Claude Code symlinks are expanded with aiq-add-tool, aiq-release-qa, and aiq-prepare-pr.

Changes

Agent skills documentation updates

Layer / File(s)	Summary
aiq-add-data-source registry example and validation update `.agents/skills/aiq-add-data-source/references/registry-and-ui.md`, `.agents/skills/aiq-add-data-source/SKILL.md`	Registry YAML drops the `category` field, switches `tools` entries to plain function-instance name strings, and adds guidance to verify fields against `DataSourceEntry`/`DataSourceRegistryConfig`. Validation step adds `uv run ruff format --check` and updates the "Expected" text to require no lint or formatting failures. UI guidance sentence removes the `aiq-ui-change` label.
aiq-release-qa npm script guidance tightened `.agents/skills/aiq-release-qa/SKILL.md`, `.agents/skills/aiq-release-qa/references/validation-matrix.md`	Both the Common Mistakes bullet and the validation-matrix Web UI section now list exactly `lint`, `type-check`, `test:ci`, and `build`; the previously mentioned `test` script is removed from both locations.
aiq-prepare-pr trailing content removal `.agents/skills/aiq-prepare-pr/SKILL.md`, `.agents/skills/aiq-prepare-pr/references/pr-checklist.md`	Trailing newline removed after the Related Skills list in `SKILL.md`; Review loop checklist tail in `pr-checklist.md` trimmed by one line.
Skill index tables and Claude Code symlinks expanded `.agents/skills/README.md`, `docs/source/integration/agent-skills.md`	`aiq-add-tool` added to the maintainer-skills Examples row in the agents README. Integration docs table expanded with `aiq-add-tool`, `aiq-release-qa`, `aiq-prepare-pr`. Three new `.claude/skills/` symlink entries added pointing into `.agents/skills/`.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

NVIDIA-AI-Blueprints/aiq#269: Introduced the initial aiq-add-data-source skill and its SKILL.md/references/registry-and-ui.md, which are the exact files being corrected in this PR.
NVIDIA-AI-Blueprints/aiq#277: Added aiq-release-qa skill content including the validation-matrix npm script guidance that this PR further restricts and aligns with package.json.

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 error)

Check name	Status	Explanation	Resolution
Title check	❌ Error	Title exceeds 72-character limit at 90 characters and violates Conventional Commits format requirement.	Shorten to ≤72 characters, e.g., 'docs(skills): fix data-source registry example' or 'docs: correct maintainer skill documentation'.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description check	✅ Passed	Description is comprehensive with all required sections completed, validation evidence provided, and DCO certification confirmed.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

_{Comment @coderabbitai help to get the list of available commands.}

…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>

zhongxuanwang-nv · 2026-06-23T20:53:35Z

@coderabbitai review

coderabbitai · 2026-06-23T20:54:37Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

cdgamarose-nv · 2026-06-23T22:15:18Z

/ok to test 606a903

cdgamarose-nv

Lgtm!

…intainer skills DEVSKILLS-8 (under epic AIQ-3362) tracks later maintainer skills until their surfaces stabilize or become active release work. Two of those gates have now opened, so these skills move from the backlog into the set: - aiq-customize-prompts-models: prompt/model customization became active release work in 2.2 (per-agent LLM role fields orchestrator_llm/source_router_llm/ researcher_llm/planner_llm/writer_llm via NVIDIA-AI-Blueprints#267, plus the documented Jinja2 prompt templates and swapping-models guide). Routes editing src/aiq_agent/agents/*/prompts/*.j2 and assigning LLMs per role in the llms section and agent config. - aiq-maintain-ci: CI/governance became active release work (4 workflows, contributor governance setup, the skill-eval regression gate, copy-pr-bot mirroring, and an expanded pre-commit hook set). Routes changes to .github/workflows, .pre-commit-config.yaml, CODEOWNERS, .coderabbit.yaml, and the .github/skill-eval harness. Each skill is a SKILL.md plus two references and a .claude/skills compatibility symlink, following the existing maintainer-skill conventions. The other two DEVSKILLS-8 skills stay deferred: aiq-auth-data-source-integration (protected- source UX/API deferred to 2.2/2.3 per PR NVIDIA-AI-Blueprints#212) and aiq-ui-change (2.2 UI auth controls not yet settled). Doc example listings (agent-skills.md table, README) that enumerate maintainer skills are reworked in the separate PR NVIDIA-AI-Blueprints#281; kept disjoint here. Validation: scripts/validate_skills.py (8 skills OK), pytest tests/test_agent_skills.py (4 passed), and pre-commit (detect-secrets, validate-skills, markdown-link-check) on the new files all pass. Signed-off-by: Zhongxuan Wang <daniewang@nvidia.com>

Now that NVIDIA-AI-Blueprints#281 has merged, enumerate aiq-customize-prompts-models and aiq-maintain-ci alongside the other four maintainer skills in the .agents/skills/README.md and docs/source/integration/agent-skills.md examples tables, and add their .claude/skills symlinks to the documented symlink block. Signed-off-by: Zhongxuan Wang <daniewang@nvidia.com>

) * feat(skills): add aiq-customize-prompts-models and aiq-maintain-ci maintainer skills DEVSKILLS-8 (under epic AIQ-3362) tracks later maintainer skills until their surfaces stabilize or become active release work. Two of those gates have now opened, so these skills move from the backlog into the set: - aiq-customize-prompts-models: prompt/model customization became active release work in 2.2 (per-agent LLM role fields orchestrator_llm/source_router_llm/ researcher_llm/planner_llm/writer_llm via #267, plus the documented Jinja2 prompt templates and swapping-models guide). Routes editing src/aiq_agent/agents/*/prompts/*.j2 and assigning LLMs per role in the llms section and agent config. - aiq-maintain-ci: CI/governance became active release work (4 workflows, contributor governance setup, the skill-eval regression gate, copy-pr-bot mirroring, and an expanded pre-commit hook set). Routes changes to .github/workflows, .pre-commit-config.yaml, CODEOWNERS, .coderabbit.yaml, and the .github/skill-eval harness. Each skill is a SKILL.md plus two references and a .claude/skills compatibility symlink, following the existing maintainer-skill conventions. The other two DEVSKILLS-8 skills stay deferred: aiq-auth-data-source-integration (protected- source UX/API deferred to 2.2/2.3 per PR #212) and aiq-ui-change (2.2 UI auth controls not yet settled). Doc example listings (agent-skills.md table, README) that enumerate maintainer skills are reworked in the separate PR #281; kept disjoint here. Validation: scripts/validate_skills.py (8 skills OK), pytest tests/test_agent_skills.py (4 passed), and pre-commit (detect-secrets, validate-skills, markdown-link-check) on the new files all pass. Signed-off-by: Zhongxuan Wang <daniewang@nvidia.com> * docs(skills): fix accuracy issues in the two new maintainer skills Address PR #282 review feedback; every change verified against the repo. aiq-maintain-ci: - pytest and helm-lint are pre-commit `stages: [push]`, so `pre-commit run --all-files` does NOT run them (the prior "can be heavier than expected" note was backwards). Document `--hook-stage push` and that CI runs them as the dedicated test/helm-lint jobs; note the pre-commit job's SKIP= set. - Correct ui.yml job ids (install/lint/type-check/unit-test/build); name the skills-eval stages (detect-changes -> generate-datasets, which is creds-free -> harbor-eval); drop the tangential aiq-add-tool from Related Skills. aiq-customize-prompts-models: - The LLMProvider.configure(LLMRole.X) role binding is the deep-researcher pattern (add a field->role table: ORCHESTRATOR/ROUTER/RESEARCHER/PLANNER/ REPORT_WRITER); the clarifier passes planner_llm to its constructor instead. Unset deep-research roles fall back to orchestrator_llm (no generic `llm` field). Add source_router_llm to the example. - Adding a NEW template needs a one-line load_prompt wiring in the agent (prompts.md Step 3); soften "without changing agent code". Note prompts.md does not document every template's variables (source_router/writer/ source_registry) -- the .j2 files are authoritative. both: - Validation smoke must pass `--config_file <your config>` (a bare start_cli.sh runs the fixed default config); scope pytest to the agent's test dir. Validation: validate_skills.py (8 OK), pytest tests/test_agent_skills.py (4 passed), pre-commit (detect-secrets, validate-skills, markdown-link-check) on the changed files all pass. Signed-off-by: Zhongxuan Wang <daniewang@nvidia.com> * docs(skills): list the two new skills in the maintainer skill tables Now that #281 has merged, enumerate aiq-customize-prompts-models and aiq-maintain-ci alongside the other four maintainer skills in the .agents/skills/README.md and docs/source/integration/agent-skills.md examples tables, and add their .claude/skills symlinks to the documented symlink block. Signed-off-by: Zhongxuan Wang <daniewang@nvidia.com> * docs(skills): warn against hardcoding queries/domains in prompts Address review feedback on aiq-customize-prompts-models: add guidance that prompt templates must stay task-agnostic and not hard-code specific queries, domains, or source/tool names, since source/domain selection is data-driven via the data_source_registry and source_router.j2. Signed-off-by: Zhongxuan Wang <daniewang@nvidia.com> --------- Signed-off-by: Zhongxuan Wang <daniewang@nvidia.com> Co-authored-by: Chantal D Gama Rose <cdgamarose@nvidia.com>

zhongxuanwang-nv marked this pull request as ready for review June 23, 2026 18:28

zhongxuanwang-nv force-pushed the docs/maintainer-skill-accuracy-fixes branch from ce3d980 to 606a903 Compare June 23, 2026 18:30

zhongxuanwang-nv marked this pull request as draft June 23, 2026 18:31

zhongxuanwang-nv marked this pull request as ready for review June 23, 2026 18:31

zhongxuanwang-nv marked this pull request as draft June 23, 2026 18:51

zhongxuanwang-nv marked this pull request as ready for review June 23, 2026 20:53

zhongxuanwang-nv mentioned this pull request Jun 23, 2026

feat(skills): add aiq-customize-prompts-models and aiq-maintain-ci #282

Merged

5 tasks

cdgamarose-nv requested a review from a team June 23, 2026 22:16

cdgamarose-nv approved these changes Jun 23, 2026

View reviewed changes

cdgamarose-nv merged commit 3f02d59 into NVIDIA-AI-Blueprints:develop Jun 23, 2026
10 checks passed

AjayThorve added this to the v2.2 milestone Jul 7, 2026

This was referenced Jul 9, 2026

feat(mcp): add public AI-Q MCP server #319

Merged

docs: document AI-Q 2.2 candidate scope #322

Merged

Navigation Menu

Uh oh!

docs(skills): correct data-source registry example and clean up maintainer skill artifacts - #281

docs(skills): correct data-source registry example and clean up maintainer skill artifacts#281
cdgamarose-nv merged 1 commit into
NVIDIA-AI-Blueprints:developfrom
zhongxuanwang-nv:docs/maintainer-skill-accuracy-fixes

zhongxuanwang-nv commented Jun 23, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

copy-pr-bot Bot commented Jun 23, 2026

Uh oh!

coderabbitai Bot commented Jun 23, 2026 •

edited

Loading

Review skipped

Pre-merge checks failed

Uh oh!

zhongxuanwang-nv commented Jun 23, 2026

Uh oh!

coderabbitai Bot commented Jun 23, 2026 •

edited

Loading

Uh oh!

cdgamarose-nv commented Jun 23, 2026

Uh oh!

cdgamarose-nv left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

zhongxuanwang-nv commented Jun 23, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Validation

Where should reviewers start?

Related Issues

Summary by CodeRabbit

Uh oh!

copy-pr-bot Bot commented Jun 23, 2026

Uh oh!

coderabbitai Bot commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Pre-merge checks failed

❌ Failed checks (1 error)

Uh oh!

zhongxuanwang-nv commented Jun 23, 2026

Uh oh!

coderabbitai Bot commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cdgamarose-nv commented Jun 23, 2026

Uh oh!

cdgamarose-nv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

zhongxuanwang-nv commented Jun 23, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 23, 2026 •

edited

Loading

coderabbitai Bot commented Jun 23, 2026 •

edited

Loading