NVIDIA · kristinapathak · Jul 21, 2026 · Jul 21, 2026
@@ -16,8 +16,7 @@ Useful pointers:
 - `BAZEL.md` for the contributor-facing Bazel build path
 - `docs/AGENTS.md` for in-repo user and developer documentation
 - `tools/AGENTS.md` for repo tooling
-- `imports.yaml` for subtree ownership and commit pins, an internal file not
-  present in this public snapshot
+- `imports.yaml` for subtree ownership and commit pins
 - `.cursor/skills/documentation-style/SKILL.md` for docs style
 - `.cursor/skills/` for root dev-skill symlink fanout
 - `ai-tooling/user/skills/` and `ai-tooling/dev/skills/` for public skills
@@ -87,15 +86,39 @@ to press a manual CI button or retrigger CI.
 
 ## Writing AGENTS.md Files
 
-Every subtree that an agent may work in should have its own `AGENTS.md` with build commands, test commands, code style, and any subtree-specific conventions. Keep each file under 400 lines; split into separate docs or skills when it grows past that.
+Every subtree that an agent may work in should have its own `AGENTS.md` with
+build commands, test commands, code style, and any subtree-specific conventions.
+Keep each file under 400 lines. Split long examples or workflow detail into
+separate docs or skills.
 
-`AGENTS.md` is the source of truth for agent guidance. Cursor and Codex read `AGENTS.md` directly. Claude Code reads `CLAUDE.md`, so every directory that has an `AGENTS.md` also has a sibling `CLAUDE.md` that is a regular file containing the single line `@AGENTS.md`. That import line tells Claude Code to load the adjacent `AGENTS.md`, so all three tools end up on the same content. When creating a new `AGENTS.md`, create the companion `CLAUDE.md` in the same commit: `printf '@AGENTS.md\n' > CLAUDE.md`. Do not use a symlink, and never put unique content in `CLAUDE.md`.
+Apply `documentation-style` whenever you create or edit `AGENTS.md` or
+`CLAUDE.md`. Keep the guidance short, public-safe, and command-focused.
+
+`AGENTS.md` is the source of truth for agent guidance. Cursor and Codex read it
+directly.
+
+Claude Code reads `CLAUDE.md`. Every directory with an `AGENTS.md` also has a
+sibling `CLAUDE.md` containing only `@AGENTS.md`. That import line tells Claude
+Code to load the adjacent `AGENTS.md`, so all three tools use the same content.
+
+When creating a new `AGENTS.md`, create the companion `CLAUDE.md` in the same
+commit: `printf '@AGENTS.md\n' > CLAUDE.md`. Do not use a symlink, and never put
+unique content in `CLAUDE.md`.
 
 ## Skills
 
-Skills are reusable, on-demand agent instructions for specific workflows. They follow the [Agent Skills specification](https://agentskills.io/specification) and are compatible with the [Vercel Skills CLI](https://github.com/vercel-labs/skills). Skills are invoked when relevant, not auto-applied (auto-applied guidance belongs in rules, not skills).
+Skills are reusable, on-demand agent instructions for specific workflows. They
+follow the [Agent Skills specification](https://agentskills.io/specification)
+and are compatible with the [Vercel Skills CLI](https://github.com/vercel-labs/skills).
+
+Skills are invoked when relevant, not auto-applied. Auto-applied guidance
+belongs in rules, not skills.
 
-Keep durable skills focused on current behavior, stable prerequisites, and reusable workflows. Do not put in-progress Merge Request/Pull Request tables, merge-order checklists, branch-specific references, or temporary cross-repo coordination status in skills. Put that information in Merge Request/Pull Request descriptions, comments on the ticket, or temporary runbooks instead.
+Keep durable skills focused on current behavior, stable prerequisites, and
+reusable workflows. Do not put in-progress Pull Request tables, merge-order
+checklists, branch-specific references, or temporary cross-repo coordination
+status in skills. Put that information in Pull Request descriptions, comments
+on the ticket, or temporary runbooks instead.
 
 ### Skill structure
 
@@ -151,7 +174,9 @@ fanout directories (`.cursor/skills/`, `.codex/skills/`, `.claude/skills/`)
 must contain symlinks only, never source skill directories or regular skill
 files.
 
-The project hook `.cursor/hooks/validate-skill-fanout.py` audits this before an agent finishes. If it reports a fanout error, fix the symlinks or source placement before responding.
+The project hook `.cursor/hooks/validate-skill-fanout.py` audits this before an
+agent finishes. If it reports a fanout error, fix the symlinks or source
+placement before responding.
 
 When adding a skill:
 1. Decide visibility (public or private) and audience (`user/skills` or `dev/skills`).
@@ -163,7 +188,7 @@ When adding a skill:
 
 When editing source files under `ai-tooling/user/skills/nvcf-self-managed-cli/**` or
 `ai-tooling/user/skills/nvcf-self-managed-installation/**`, regenerate the embedded CLI
-data and commit the result in the same MR:
+data and commit the result in the same Pull Request:
 
 ```sh
 cd src/clis/nvcf-cli
@@ -179,15 +204,15 @@ is stale. Do not edit this file by hand.
 Hooks follow the same source-and-fanout pattern as root dev skills.
 Implementation scripts live in `ai-tooling/dev/hooks/`; `.cursor/hooks/`,
 `.codex/hooks/`, and `.claude/hooks/` are symlink fanouts only. Tool-specific
-hook configs may be regular files. Internal-only stop hooks and private
-snapshot hygiene checks live outside this public snapshot; still follow OSS
-Snapshot Hygiene manually before finishing.
+hook config files outside those fanout directories may be regular files.
+Internal-only stop hooks and private snapshot hygiene checks live outside this
+public snapshot; still follow OSS Snapshot Hygiene manually before finishing.
 
 ### Public skills
 
 | Skill | Location | Purpose |
 |-------|----------|---------|
-| `documentation-style` | `ai-tooling/dev/skills/` | NVCF documentation conventions (no bold, no emojis, no em-dash) |
+| `documentation-style` | `ai-tooling/dev/skills/` | Public docs, AGENTS, and skill-writing style |
 | `nvcf-explore-stack` | `ai-tooling/dev/skills/` | Navigate the self-hosted stack topology and dependency graph |
 | `nvcf-self-managed-cli` | `ai-tooling/user/skills/` | Install, operate, and manage self-managed NVCF through `nvcf-cli` |
 | `nvcf-self-managed-installation` | `ai-tooling/user/skills/` | Install and deploy the self-managed NVCF stack |
@@ -230,29 +255,31 @@ Foundational types (not in release notes): `docs`, `build`, `test`, `refactor`,
 
 When a commit adds or updates a third-party dependency, call out the dependency name and version in the body so reviewers can assess license and security impact.
 
-## Merge Requests/Pull Requests
+## Pull Requests
 
-Use Conventional Commit format for Merge Request/Pull Request titles, as
-described in the Commit Messages section. Release automation depends on this
-format. Examples: `feat:`, `fix:`, `chore:`, `docs:`.
+Use Conventional Commit format for Pull Request titles, as described in the
+Commit Messages section. Release automation depends on this format. Examples:
+`feat:`, `fix:`, `chore:`, `docs:`.
 
 For GitHub PRs, agents must create or link a public `NVIDIA/nvcf` issue in
 `## Issues` using `Closes #123`, `Fixes #123`, `Resolves NVIDIA/nvcf#123`, or
 `Relates to #123`. If context is private, create a generic public issue. Do not
 use `NO-REF`, Jira keys, private tracker or bug IDs, private URLs, title-only
 refs, other-repo issues, or invented issue numbers for agent-authored PRs.
 
-Use a structured Merge Request/Pull Request description. Subtree repos may define
-their own Merge Request/Pull Request template; fall back to this shape when none
-exists. Do not include a test plan checklist unless explicitly requested.
+Use a structured Pull Request description. Start from the root Pull Request
+template. Fall back to this shape only when that template is unavailable. Do
+not include a test plan checklist unless explicitly requested.
 
-Every Merge Request/Pull Request description must explain why the change is
-needed, not only what changed. Include enough context that a reviewer can
-understand the motivation without doing detective work. Always include:
+Every Pull Request description must explain why the change is needed, not only
+what changed. Include enough context that a reviewer can understand the
+motivation without doing detective work. Always include:
 - the problem, requirement, review comment, or CI blocker driving the change
 - what changed and how the changed pieces connect
-- links to upstream Merge Requests/Pull Requests, tickets, bugs, or related
-  reviews when relevant
+- links to upstream Pull Requests, tickets, bugs, or related reviews when
+  relevant
+- tests run, skipped tests, and whether QA is needed
+- dependency changes, license review status, and NOTICE impact
 
 ```
 ## Why
@@ -279,7 +306,7 @@ understand the motivation without doing detective work. Always include:
 ## References
 <bug, issue, or ticket links at the bottom, or "None">
 
-## Related Merge Requests/Pull Requests
+## Related Pull Requests
 <links or "None">
 
 ## Dependencies
@@ -288,19 +315,28 @@ understand the motivation without doing detective work. Always include:
 
 ## Cross-subtree impact
 
-NVCF clients in this repo (notably `src/clis/nvcf-cli`) are hand-written against control-plane and invocation-plane APIs. When changing public API surfaces (request/response shapes, auth flow, new endpoints, removed fields), evaluate whether `src/clis/nvcf-cli` needs a matching change, and list affected clients in the Merge Request/Pull Request "Related Merge Requests/Pull Requests" section. If the CLI needs an update, file a follow-up issue.
+NVCF clients in this repo (notably `src/clis/nvcf-cli`) are hand-written against
+control-plane and invocation-plane APIs. When changing public API surfaces
+(request/response shapes, auth flow, new endpoints, removed fields), evaluate
+whether `src/clis/nvcf-cli` needs a matching change, and list affected clients
+in the Pull Request "Related Pull Requests" section. If the CLI needs an
+update, file a follow-up issue.
 
 ## Tests
 
-Code changes must include tests. If a change does not include tests, explain why in the Merge Request/Pull Request description (for example: pure documentation, CI-only change, or refactor with full existing coverage).
+Code changes must include tests. If a change does not include tests, explain why
+in the Pull Request description (for example: pure documentation, CI-only
+change, or refactor with full existing coverage).
 
 Prefer the repo-native test runner (`make test`, `go test`, `cargo test`, etc.). Run tests before committing. Check coverage requirements in the subtree `AGENTS.md` or CI config.
 
 ## Code Style
 
 Write self-documenting code. Add comments only when the logic is non-obvious. Match the existing package structure, naming, and error-handling conventions of each subtree instead of imposing a new framework.
 
-Follow the documentation style rules in `.cursor/skills/documentation-style/SKILL.md`:
+Follow the documentation style rules in `.codex/skills/documentation-style/SKILL.md`
+(same source as `.cursor/skills/documentation-style/SKILL.md` and
+`.claude/skills/documentation-style/SKILL.md`):
 - No markdown bold for emphasis.
 - No emojis.
 - No em-dash (U+2014).
@@ -381,12 +417,14 @@ When a change affects observability, verify:
 - New spans propagate context and set error attributes on failure.
 - New metrics follow the naming convention and are pre-initialized.
 - Existing dashboards and alerts are not broken by renamed or removed metrics/spans.
-- The Merge Request/Pull Request description calls out the observability impact if dashboards or alerts may need updating.
+- The Pull Request description calls out the observability impact if dashboards
+  or alerts may need updating.
 
 ## Diagrams
 
 When a change modifies runtime behavior, data flow, or component interactions, ask whether architecture or sequence diagrams need updating. If the change modifies an existing documented flow, update that diagram instead of creating a conflicting copy. Prefer ASCII or Mermaid; avoid binary image formats when text is sufficient.
 
 ## Issue Tracking
 
-Reference related issues in commits and Merge Request/Pull Request descriptions. When creating follow-up work, file a ticket rather than leaving a TODO in code.
+Reference related issues in commits and Pull Request descriptions. When
+creating follow-up work, file a ticket rather than leaving a TODO in code.
@@ -6,7 +6,7 @@ Public agent skills for users and developers working with NVIDIA Cloud Functions
 
 | Skill | Description |
 |-------|-------------|
-| [documentation-style](dev/skills/documentation-style/SKILL.md) | NVCF documentation conventions for public repo prose |
+| [documentation-style](dev/skills/documentation-style/SKILL.md) | Public docs, AGENTS, and skill-writing style |
 | [nvcf-explore-stack](dev/skills/nvcf-explore-stack/SKILL.md) | Navigate the self-hosted stack topology, helmfile dependency graph, chart ownership, and deployment order |
 | [nvcf-self-managed-installation](user/skills/nvcf-self-managed-installation/SKILL.md) | Install and deploy the nvcf-self-managed-stack helmfile bundle: installation, teardown, values overrides, pull secrets, debugging |
 | [nvcf-self-managed-cli](user/skills/nvcf-self-managed-cli/SKILL.md) | Standalone NVCF CLI (`nvcf-cli`) for self-managed/self-hosted deployments: install, status, add compute plane, teardown, function lifecycle, invocation, and API keys |

@@ -1,8 +1,9 @@
 ---
 name: documentation-style
 description: >-
-  NVCF docs style: no bold, no emojis, no em-dash or en-dash, ASCII-only prose.
-  Use when editing markdown, READMEs, AGENTS.md, plans, or PR descriptions.
+  NVCF public docs style: short, plain, ASCII Markdown with no bold, emojis,
+  em-dash, or en-dash. Use when editing public docs, READMEs, AGENTS.md, agent
+  skills, plans, GitHub issues, or GitHub Pull Request descriptions.
 license: Apache-2.0
 compatibility: Requires an NVCF documentation or repository checkout
 author: "nvcf-core-eng <nvcf-core-eng@exchange.nvidia.com>"
@@ -34,40 +35,68 @@ metadata:
 
 ## Purpose
 
-Keep NVCF documentation plain, consistent, and agent-friendly. Avoid typographic Unicode that breaks grep and diff tools, and avoid emphasis patterns that encourage noisy, marketing-flavored prose.
+Keep NVCF documentation plain, consistent, and useful for external readers.
+Write short docs an agent or contributor can act on without private context.
+Avoid typographic Unicode that breaks grep and diff tools, and avoid emphasis
+patterns that make docs noisy.
 
 ## When to use
 
-- Any new or edited markdown in this repo (root docs, `dependencies-plan.md`, skills, comments in guides).
-- User-facing explanations, commit messages, or PR bodies when the user wants repo style.
-- Refactors of existing docs where you are already changing the file.
+- Any new or edited public Markdown in this repo.
+- `AGENTS.md`, `CLAUDE.md`, `SKILL.md`, READMEs, plans, and guides.
+- GitHub issue bodies, commit messages, and Pull Request descriptions.
+- Existing docs you are changing for another reason.
 
 ## Instructions
 
-1. No markdown bold for emphasis. Do not use `**...**` or `__...__`, and do not reach for raw HTML `<b>` or `<strong>`. Use structure (headings, lists, tables) and `backticks` for paths, commands, env vars, and identifiers. Let the wording carry emphasis.
+1. No markdown bold for emphasis. Do not use `**...**`, `__...__`, raw HTML
+`<b>`, or `<strong>`. Use headings, lists, and `backticks` for paths, commands,
+env vars, and identifiers.
 
 2. No emojis in documentation or user-facing prose.
 
-3. No em-dash (Unicode U+2014) or en-dash (U+2013). Split the thought into two sentences, or use a comma, parenthesis, or colon when you need a break.
+3. No em-dash (Unicode U+2014) or en-dash (U+2013). Split the thought into two
+sentences, or use a comma, semicolon, parenthesis, or colon.
 
-4. ASCII only in committed prose. Avoid smart quotes, ellipsis characters, non-breaking spaces, arrows, and other typographic Unicode. Prefer `->` over an arrow glyph and `...` over a single-character ellipsis. Code blocks and quoted fixtures are exempt.
+4. ASCII only in committed prose. Avoid smart quotes, ellipsis characters,
+non-breaking spaces, arrows, and other typographic Unicode. Prefer `->` over an
+arrow glyph and `...` over a single-character ellipsis. Code blocks and quoted
+fixtures are exempt.
 
-5. Be succinct. Prefer short sentences and direct wording. Cut filler and repetition. Keep one idea per sentence when possible.
+5. Be succinct. Prefer short sentences and direct wording. Cut filler and
+repetition. Keep one idea per sentence when possible.
 
-6. Be easy to understand. Define acronyms on first use if the audience is broad. Prefer concrete examples over abstract jargon.
+6. Prefer lists for short, scan-friendly structure. Use bullets for unordered
+items and numbered lists when sequence, priority, or stable rule references
+matter. Use tables only when columns make comparison, status, option tradeoffs,
+or matrix decisions easier. Do not turn a short list into a table.
+
+7. Be easy to understand. Define acronyms on first use if the audience is broad.
+Prefer concrete examples over abstract jargon.
+
+8. Write for GitHub readers. Use public names, public paths, and public
+behavior. Replace private evidence with the user-visible reason for the change.
+
+9. Keep agent guidance actionable. Say when to use a skill, what to inspect
+first, what command to run, and what done means. Do not add temporary branch
+status, Pull Request queues, merge-order notes, or private routing details.
+
+10. Avoid vague agent language. Remove filler such as "ensure", "leverage",
+"robust", "comprehensive", "where applicable", and "as needed" unless the term
+adds a concrete condition.
 
 ## Examples
 
 Inline bold label, replaced with a plain prefix:
 
-```
+```text
 Before: **Note:** restart after edit.
 After:  Note: restart after edit.
 ```
 
 Bold section header, replaced with a real heading:
 
-```
+```text
 Before: **Prerequisites**
 
         - Repository access to github.com/NVIDIA/nvcf.
@@ -77,25 +106,40 @@ After:  ## Prerequisites
         - Repository access to github.com/NVIDIA/nvcf.
 ```
 
-Em-dash, replaced with a period:
+Double hyphen used as a dash, replaced with a period:
 
-```
+```text
 Before: Services live upstream -- this repo mirrors them.
 After:  Services live upstream. This repo mirrors them.
 ```
 
+Long agent guidance, replaced with commands and durable criteria:
+
+```text
+Before: Ensure agents comprehensively verify symlink fanout where applicable.
+
+After:  Run `python3 ai-tooling/dev/hooks/validate-skill-fanout.py` after
+        changing root skills. Fix every reported path before finishing.
+```
+
 ## Editing existing files
 
-If a file already uses bold, emojis, em-dashes, en-dashes, or non-ASCII punctuation, normalize it when you touch that file for another reason, or when the user asks for a style pass. Do not expand scope into unrelated trees just to fix style.
+If a file already uses bold, emojis, em-dashes, en-dashes, or non-ASCII
+punctuation, normalize it when you touch that file for another reason, or when
+the user asks for a style pass. Do not expand scope into unrelated trees just to
+fix style.
 
 ## Limitations
 
 - The rules target agent-edited prose in this repo. Upstream documentation
   keeps its own style until merged natively.
-- There is no automated linter today. Enforcement happens during review.
+- There is no automated linter for prose today. Review catches style issues.
 
 ## Exceptions
 
-- Content you are quoting verbatim (upstream LICENSE text, cited errors, user paste).
-- Generated files (for example output from `go run ./tools/collect-dependencies`) where the generator controls formatting; fix style in the generator if needed.
-- Auto-generated changelogs or release notes assembled from external commit messages; fix the source commits, not the rolled-up file.
+- Content you are quoting verbatim, such as upstream LICENSE text, cited errors,
+  or user paste.
+- Generated files where the generator controls formatting. Fix style in the
+  generator if needed.
+- Auto-generated changelogs or release notes assembled from external commit
+  messages. Fix the source commits, not the rolled-up file.