docs: clarify agent skill writing guidance

[kristinapathak]

TL;DR

• Extends documentation-style to cover AGENTS files, skills, GitHub issues, and Pull Request descriptions.
• Makes the root guide point at the shared Codex, Cursor, and Claude skill fanout.

Additional Details

• Keeps the public docs guidance in one skill instead of adding another docs skill.
• Adds GitHub-reader guidance for short, public-safe, actionable agent docs.
• Keeps AGENTS changes compatible with the GitHub issue-reference guidance in PR 287.

For the Reviewer

• Start with ai-tooling/dev/skills/documentation-style/SKILL.md for the updated scope.
• Check AGENTS.md for discoverability through .codex/skills/, .cursor/skills/, and .claude/skills/.

For QA

• python3 ai-tooling/dev/hooks/validate-skill-fanout.py
• git diff --check
• ASCII scan across touched files
• QA not needed. Docs-only change.

Issues

Closes #289

Checklist

• I am familiar with the Contributing Guidelines.
• I have signed off my commits for Developer Certificate of Origin (DCO) compliance.
• New or existing tests cover these changes.
• The documentation is up to date with these changes.

Summary by CodeRabbit

• Documentation
  • Updated agent/workflow guidance to tighten subtree/fanout handling and generated-artifact PR expectations.
  • Reworked Pull Request requirements, including Conventional Commit titles, stricter issue-linking rules, and a structured PR description with an explicit checklist.
  • Clarified cross-subtree impact guidance and refined hook/fanout behavior expectations.
  • Strengthened the documentation-style skill rules with stricter ASCII-only prose constraints, expanded exceptions, and clearer validation/editing guidance.
  • Updated the skills reference wording to reflect the expanded documentation-style scope.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 3073bd7e-8af4-4207-ac10-365ab9239f48

📥 Commits

Reviewing files that changed from the base of the PR and between abecfbe and f4f2b26.

📒 Files selected for processing (3)

• AGENTS.md
• ai-tooling/README.md
• ai-tooling/dev/skills/documentation-style/SKILL.md

---

📝 Walkthrough

Walkthrough

Updates the public documentation-style skill, AGENTS.md authoring and fanout guidance, generated-artifact rules, and repository contribution terminology from mixed merge-request wording to consistent Pull Request wording.

Changes

Documentation guidance

Layer / File(s)	Summary
Public documentation style guidance ai-tooling/README.md, ai-tooling/dev/skills/documentation-style/SKILL.md	Expands ASCII Markdown rules, supported documentation targets, validation procedures, editing scope, limitations, and exceptions.
Agent authoring and skill fanout AGENTS.md	Clarifies repository pointers, AGENTS.md and CLAUDE.md authoring rules, generated artifact handling, skill validation, and symlink-only fanout requirements.
Pull Request guidance and terminology AGENTS.md	Updates public issue-linkage requirements, structured Pull Request descriptions, related Pull Requests, test and style notes, observability, and issue tracking terminology.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• NVIDIA/nvcf#287: Updates related AGENTS.md guidance for valid public issue references and Pull Request requirements.

Suggested reviewers: famousdirector

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes match the linked issue goals for public skill guidance, cross-tool fanout, and clearer AGENTS/SKILL/PR wording.
Out of Scope Changes check	✅ Passed	The edits stay within documentation and agent-skill guidance scope without obvious unrelated code or product changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: clarifying documentation and agent skill writing guidance.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/open-documentation-skill

---

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

[coderabbitai]

Actionable comments posted: 3

🤖 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.md`:
- Around line 278-298: Update the contributor guidance in the Pull Requests
section to replace any remaining “MR” terminology in the PR template
instructions with “Pull Request,” preserving the existing meaning and
formatting.

In `@ai-tooling/dev/skills/documentation-style/SKILL.md`:
- Around line 43-49: Update the “When to use” list in the documentation-style
skill to remove the “when the user wants repo style” qualifier from GitHub issue
bodies, commit messages, and Pull Request descriptions, making the documented
scope unconditional for those targets.
- Around line 112-119: Add a language identifier to the fenced example in the
documentation guidance, using text or markdown after the opening fence to
satisfy markdownlint MD040 while preserving the example content.

🪄 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: CHILL

Plan: Enterprise

Run ID: 035fcb09-f5e1-47aa-8784-1307a3dbb809

📥 Commits

Reviewing files that changed from the base of the PR and between c292aa9 and 1f5715f.

📒 Files selected for processing (3)

• AGENTS.md
• ai-tooling/README.md
• ai-tooling/dev/skills/documentation-style/SKILL.md

[coderabbitai]

Actionable comments posted: 3

🤖 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.md`:
- Around line 270-280: Update the fallback Pull Request description requirements
in AGENTS.md to explicitly require testing results, dependency or prerequisite
changes, and relevant references alongside the existing problem, change,
connection, and link context. Preserve the instruction not to include a
test-plan checklist unless explicitly requested.
- Around line 204-209: Update the hook guidance in AGENTS.md to remove the
statement that tool-specific hook configs may be regular files, so it matches
validate-skill-fanout.py’s symlink-only enforcement for .cursor/hooks/,
.codex/hooks/, and .claude/hooks/.

In `@ai-tooling/dev/skills/documentation-style/SKILL.md`:
- Around line 110-113: Update the Before/After example in the
documentation-style guidance so it demonstrates replacing a literal Unicode
em-dash with a period; use an actual em-dash in the Before fixture while
preserving the existing After text.

🪄 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: CHILL

Plan: Enterprise

Run ID: a79cf021-79f3-48a8-aaaf-291bcda843da

📥 Commits

Reviewing files that changed from the base of the PR and between 1f5715f and abecfbe.

📒 Files selected for processing (3)

• AGENTS.md
• ai-tooling/README.md
• ai-tooling/dev/skills/documentation-style/SKILL.md

🚧 Files skipped from review as they are similar to previous changes (1)

• ai-tooling/README.md