chore(docs): add agent tooling guidelines#93
Open
coryrylan wants to merge 1 commit into
Open
Conversation
📝 WalkthroughWalkthroughAdds a new internal "Agent Tooling" documentation page with layered guidance and an interactive SVG diagram, and wires an "Agent Tooling" entry into the docs navigation tree. ChangesAgent Tooling Documentation and Navigation
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 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 `@projects/site/src/docs/internal/guidelines/agent-tooling.md`:
- Around line 39-58: The SVG layer groups (the <g> elements with
data-tooling-layer="metadata", "static-tools", "cli-skills", and "mcp") need
accessibility attributes and keyboard handlers: add role="button", tabindex="0"
and an appropriate aria-label to each <g>, and ensure focus styling is possible;
then update the JS that currently binds only to mouse events (click, mouseenter)
to also listen for keyboard events (keydown) and trigger the same handlers on
Enter and Space so keyboard and screen-reader users can activate the layers.
- Around line 245-248: The four consecutive list items in agent-tooling.md that
all start with "Do not" are repetitive; update the four bullets (“Do not hide
facts in prompts.”, “Do not make MCP the source of truth.”, “Do not ship
model-only validation.”, “Do not return raw dumps.”) to vary sentence openings
while keeping the same prohibitions and intent—for example change one or two to
affirmative guidance or passive constructions (e.g., “Avoid hiding facts in
prompts.”, “Treat MCP as an adapter rather than the source of truth.”, “Ensure
CI-enforceable validation rather than model-only checks.”, “Distill context
before returning dumps.”) so the wording satisfies Vale/Google style and
write-good rules and preserves the original meaning.
🪄 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: 5e8d7d8b-6277-4a3c-a3e8-b0768c081cf0
📒 Files selected for processing (2)
projects/site/src/_11ty/layouts/common.jsprojects/site/src/docs/internal/guidelines/agent-tooling.md
- Introduced a new internal author documentation page for 'Agent Tooling' detailing best practices for designing metadata, static checks, CLI tools, skills, apps, and MCP servers for agents. Signed-off-by: Cory Rylan <crylan@nvidia.com>
coryrylan
force-pushed
the
topic-tool-guidance
branch
from
c6ada7b to
4f4d1bd
Compare
There was a problem hiding this comment.
♻️ Duplicate comments (2)
projects/site/src/docs/internal/guidelines/agent-tooling.md (2)
245-248:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winVary sentence structure to improve readability.
Four consecutive list items begin with "Do not," which creates repetitive phrasing. As per coding guidelines, documentation files must follow Vale linting rules (Google style guide, write-good rules, and custom Element rules).
📝 Suggested rewording
- **Do not hide facts in prompts.** Prompts are runtime hints, not durable data. -- **Do not make MCP the source of truth.** Treat it as an adapter over services. -- **Do not ship model-only validation.** If CI cannot enforce it, the harness is incomplete. -- **Do not return raw dumps.** Distill context before it reaches the agent. + **Avoid making MCP the source of truth.** Treat it as an adapter over services. + **Ensure CI enforces all validation.** If CI cannot enforce it, the harness is incomplete. + **Distill outputs before returning them.** Never return raw dumps to agents.🤖 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 `@projects/site/src/docs/internal/guidelines/agent-tooling.md` around lines 245 - 248, The four consecutive list items beginning with "Do not" are repetitively phrased and violate the Vale linting/write-good style; revise the four bullets (the items currently reading "Do not hide facts in prompts.", "Do not make MCP the source of truth.", "Do not ship model-only validation.", "Do not return raw dumps.") to vary sentence structure while preserving intent—e.g., convert some to positive or alternative imperatives, combine related points, or rephrase to start with different verbs or noun phrases, ensuring the wording conforms to Google-style and Element lint rules and keeps the original meaning and emphasis.
39-58:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAdd keyboard navigation and ARIA attributes to interactive SVG layers.
The interactive SVG layer groups lack accessibility support:
- No
role="button"ortabindex="0"for keyboard focus- No ARIA labels describing each layer
- JavaScript event listeners (lines 205-215) handle only mouse events (click, mouseenter), not keyboard events (keydown)
Keyboard-only users and screen reader users cannot interact with the diagram. As per coding guidelines, documentation must follow accessibility best practices.
♿ Recommended accessibility fixes
Add accessibility attributes to each
<g>element:- <g data-tooling-layer="metadata" style="cursor:pointer"> + <g data-tooling-layer="metadata" role="button" tabindex="0" aria-label="Metadata layer - Source of Truth" style="cursor:pointer">Apply similar changes to all layer groups (static-tools, cli-skills, mcp).
Then update the JavaScript to handle keyboard events:
layerGroups.forEach(group => { group.addEventListener('click', () => { locked = true; setToolingLayer(group.getAttribute('data-tooling-layer')); }); + group.addEventListener('keydown', (e) => { + if (e.key === 'Enter' || e.key === ' ') { + e.preventDefault(); + locked = true; + setToolingLayer(group.getAttribute('data-tooling-layer')); + } + }); group.addEventListener('mouseenter', () => { if (!locked) { setToolingLayer(group.getAttribute('data-tooling-layer')); } }); });Also applies to: 205-215
🤖 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 `@projects/site/src/docs/internal/guidelines/agent-tooling.md` around lines 39 - 58, The SVG layer groups (e.g., elements with data-tooling-layer="metadata", "static-tools", "cli-skills", "mcp") are not keyboard- or screen-reader accessible; add role="button", tabindex="0", and an appropriate aria-label (e.g., aria-label="Metadata layer") to each <g> to make them focusable and identifiable, and update the event handling in the script that attaches listeners to these groups (the code that currently listens for click and mouseenter) to also handle keyboard activation (keydown/keyup or keypress) for Enter and Space so keyboard users can activate and hover-equivalent focus styles; ensure the same ARIA and keyboard handling is applied consistently to all tooling-layer groups referenced by data-tooling-layer attributes.
🤖 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.
Duplicate comments:
In `@projects/site/src/docs/internal/guidelines/agent-tooling.md`:
- Around line 245-248: The four consecutive list items beginning with "Do not"
are repetitively phrased and violate the Vale linting/write-good style; revise
the four bullets (the items currently reading "Do not hide facts in prompts.",
"Do not make MCP the source of truth.", "Do not ship model-only validation.",
"Do not return raw dumps.") to vary sentence structure while preserving
intent—e.g., convert some to positive or alternative imperatives, combine
related points, or rephrase to start with different verbs or noun phrases,
ensuring the wording conforms to Google-style and Element lint rules and keeps
the original meaning and emphasis.
- Around line 39-58: The SVG layer groups (e.g., elements with
data-tooling-layer="metadata", "static-tools", "cli-skills", "mcp") are not
keyboard- or screen-reader accessible; add role="button", tabindex="0", and an
appropriate aria-label (e.g., aria-label="Metadata layer") to each <g> to make
them focusable and identifiable, and update the event handling in the script
that attaches listeners to these groups (the code that currently listens for
click and mouseenter) to also handle keyboard activation (keydown/keyup or
keypress) for Enter and Space so keyboard users can activate and
hover-equivalent focus styles; ensure the same ARIA and keyboard handling is
applied consistently to all tooling-layer groups referenced by
data-tooling-layer attributes.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: f16af1cb-568c-4557-9959-db8f51747ca5
📒 Files selected for processing (2)
projects/site/src/_11ty/layouts/common.jsprojects/site/src/docs/internal/guidelines/agent-tooling.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary by CodeRabbit