Agent-Skills.md

Agent Skills: NeMo Gym Docs Maintenance

'Maintain the NeMo Gym Fern docs site — add, update, move, or remove

UncategorizedID: autohandai/community-skills/nvidia-nemo-gym-docs

Repository

autohandai/community-skills
autohandaiLicense: Apache-2.0
103

Install this agent skill to your local

pnpm dlx add-skill https://github.com/autohandai/community-skills/tree/HEAD/nvidia-nemo-gym-docs

Skill Files

Browse the full folder contents for nvidia-nemo-gym-docs.

Download Skill

Loading file tree…

nvidia-nemo-gym-docs/SKILL.md

Skill Metadata

Name
nvidia-nemo-gym-docs
Description
'Maintain the NeMo Gym Fern docs site — add, update, move, or remove

NeMo Gym Docs Maintenance

Unified skill for adding, updating, moving, and removing pages on the NeMo Gym Fern documentation site.

Scope Rule

ALL docs edits happen under fern/. All new pages — including release notes and migration guides — belong under fern/.

Bleeding-edge tree + GA snapshots. Gym keeps one bleeding-edge content tree at fern/versions/latest/ (the folder name is historical — it's mounted under the main slug via main.yml) and one frozen GA snapshot per shipped release (currently fern/versions/v0.2.1/). All new edits land in fern/versions/latest/. The latest.yml file is a GA alias — a symlink to the current GA's yml — so /latest/... and /<current-ga>/... serve the same pages. Back-ports into a frozen GA snapshot are deliberate and rare; default to editing fern/versions/latest/ only.

Layout at a Glance

fern/
├── fern.config.json          # Org + Fern CLI version (currently 4.80.3)
├── package.json              # `npm run dev|check|generate` — wraps `npx -y fern-api@latest`
├── docs.yml                  # Site config: instances, versions, tabs, redirects, libraries
├── versions/
│   ├── latest.yml            # GA alias — symlink to the current GA's yml (currently v0.2.1.yml)
│   ├── main.yml              # Nav tree for the bleeding-edge train (mounts ./latest/pages)
│   ├── latest/pages/         # MDX content for the bleeding-edge train (slug: main)
│   ├── v0.2.1.yml            # Nav tree for the 0.2.1 GA snapshot
│   └── v0.2.1/pages/         # MDX content for the 0.2.1 GA snapshot
├── components/               # Custom TSX (CTAButtons, NavButton, CustomFooter)
├── assets/                   # Images, SVGs, favicon
├── main.css                  # Global theme overrides (NVIDIA green, badge spacing, etc.)
└── product-docs/             # GENERATED library reference (gitignored)

File system                                            Published URL
─────────────────────────────────────────────────────  ──────────────────────────────────
fern/versions/latest/pages/get-started/quickstart.mdx  docs.nvidia.com/nemo/gym/main/get-started/quickstart
fern/versions/v0.2.1/pages/get-started/quickstart.mdx  docs.nvidia.com/nemo/gym/v0.2.1/get-started/quickstart
                                                       docs.nvidia.com/nemo/gym/latest/get-started/quickstart  (GA alias)

Operations

Add a Page

  1. Gather: page title, target section, filename (kebab-case .mdx), subdirectory under fern/versions/latest/pages/.

  2. Create fern/versions/latest/pages/<subdirectory>/<filename>.mdx:

    ---
title: "<Page Title>"
description: "One-line SEO description (or empty string)"
position: 3
---

# <Page Title>

<content>

  3. If the parent folder is mounted in main.yml with title-source: frontmatter, the page is auto-discovered — no nav edit needed. Otherwise add a - page: entry under the right section: in fern/versions/main.yml.

  4. Do not mirror into the current GA snapshot folder (e.g., v0.2.1/) — frozen GA snapshots only get back-ports on explicit request.

Update a Page

  1. Locate by path, title, or keyword (grep -rn in fern/versions/latest/pages/).
  2. Content only — edit the MDX in fern/versions/latest/pages/. Don't touch v0.2.1/ unless this is an explicit back-port.
  3. Title change — update the frontmatter title: and (if the parent uses title-source: frontmatter) nothing else; otherwise update the nav - page: entry too.
  4. Section move — git mv the file, update its path: in main.yml, fix all incoming links inside fern/versions/latest/pages/.
  5. Slug change — folders use the page filename for the slug. Renaming the file changes the URL; add a redirect in fern/docs.yml so the old URL keeps working.

Remove a Page

  1. Find incoming links: grep -rn "<filename>" fern/versions/latest/pages --include="*.mdx".
  2. git rm the file from fern/versions/latest/pages/.
  3. Remove the matching - page: block from main.yml if it was a manual entry.
  4. Fix or remove all incoming links.
  5. Add a redirect in fern/docs.yml if the URL was public.

Back-port to a GA Snapshot

Only back-port when the user explicitly asks ("back-port to v0.2.1"). Apply the same change inside the GA snapshot's pages/ folder (e.g., fern/versions/v0.2.1/pages/) and update its yml if needed. latest.yml is a symlink to the current GA's yml, so nav changes propagate automatically.

Worked Example: Adding a Page

Request: "Add a how-to for collecting rollouts under Get Started."

  1. Create fern/versions/latest/pages/get-started/rollout-collection.mdx:

    ---
title: "Collect Rollouts"
description: "Run the agent against your dataset and write results to JSONL"
position: 4
---

# Collect Rollouts

<content>

  2. The get-started folder in main.yml uses title-source: frontmatter, so the page appears automatically. position: 4 controls ordering — it's optional; without it, pages sort alphabetically by filename.

  3. cd fern && npm run check && npm run dev, verify /main/get-started/rollout-collection renders.

Worked Example: Renaming a Slug (with Redirect)

Request: "Rename /main/get-started/setup to /main/get-started/detailed-setup."

  1. git mv fern/versions/latest/pages/get-started/setup.mdx fern/versions/latest/pages/get-started/detailed-setup.mdx.

  2. Add a redirect in fern/docs.yml:

    redirects:
  - source: "/main/get-started/setup"
    destination: "/main/get-started/detailed-setup"

  3. grep -rn "/get-started/setup" fern/versions/latest/ and update any incoming links.

Content Guidelines

NeMo Gym uses Fern-native MDX components directly. Do not use GitHub > [!NOTE] syntax — it will not render.

| Purpose | Component | |---|---| | Neutral aside | <Note>...</Note> | | Helpful tip | <Tip>...</Tip> | | Informational callout | <Info>...</Info> | | Warning | <Warning>...</Warning> | | Error / danger | <Error>...</Error> | | Card grid on index pages | <Cards> with <Card title="..." href="..."> children | | Status/scope tag inside a Card | <Badge minimal outlined>tag</Badge> (see below) |

Images live in fern/assets/ (shared) or under a version's pages/ (version-scoped). Reference with root-relative paths.

Cards and Badges

Index pages use a <Cards> grid. Each <Card> can carry one or more <Badge> tags to indicate scope, status, or read-time.

Valid intents: success, note, tip, warning, error, info, launch, check. Use <Badge minimal outlined>...</Badge> (no intent) for neutral tags.

Place badges as the last line inside the <Card>, separated by a blank line from the body text. The CSS in main.css (.fern-card .fern-docs-badge) handles spacing — do not add inline style= props.

<Cards>
  <Card title="Quickstart" href="/main/get-started/quickstart">
    Install, start servers, and collect your first rollouts in one page.

    <Badge intent="success" minimal outlined>start here</Badge> <Badge minimal outlined>5 min</Badge>
  </Card>
</Cards>

Frontmatter Fields

---
title: "<Page Title>"        # required — used for nav and <h1>
description: ""              # required (may be empty string) — SEO
position: 1                  # optional — orders auto-discovered pages within a folder
---

The MDX body should still open with # <Page Title> matching the frontmatter title. Folders using title-source: frontmatter in the version YAML pull the nav label from title:.

Validate

First-time setup: authenticate the CLI against the nvidia Fern org via Google SSO (one-time, browser flow):

npx -y fern-api@latest login    # opens browser → sign in with your @nvidia.com Google account

Run from fern/ (no install step — scripts shell out to npx -y fern-api@latest):

npm run check       # `fern check` — YAML + frontmatter validation
npm run dev         # `fern docs dev` — localhost:3000 hot-reload preview

fern check must pass before commit. The dev server's broken-link warnings for cross-version links like /latest/about are false positives — Fern's local validator does not resolve the version slug from docs.yml against latest.yml. The published site renders them correctly.

To regenerate the autodoc library reference (gitignored under product-docs/):

npm run generate:library    # `fern docs md generate`

Commit & Preview

git add fern/
git commit -s -m "docs: <add|update|remove> <page-title>"

PRs that touch fern/** get an automatic Fern preview URL posted as a comment by .github/workflows/fern-docs-preview-comment.yml. No manual step needed.

                    ┌─ fern-docs-ci.yml                  → fern check
PR (touches fern/) ─┼─ fern-docs-preview-build.yml       → upload fern/ artifact (no secrets)
                    └─ fern-docs-preview-comment.yml     → 🌿 preview URL comment

Push to main (touches docs/** or fern/**) → publish-fern-docs.yml → docs.nvidia.com/nemo/gym
Tag push (docs/v*)                        → publish-fern-docs.yml → docs.nvidia.com/nemo/gym
Manual dispatch                           → publish-fern-docs.yml → docs.nvidia.com/nemo/gym

The preview-comment + publish jobs require the DOCS_FERN_TOKEN repository or organization secret (from fern token).

Publishing to Production

Production publishes on three triggers (see .github/workflows/publish-fern-docs.yml):

  1. Push to main when docs/** or fern/** changes — continuous staging.
  2. Tag push matching docs/v* — versioned release.
  3. Manual dispatch from the Actions tab.

Tag format must be docs/v<MAJOR>.<MINOR>.<PATCH>. Do not push a tag unless the user asks.

git tag docs/v0.3.0
git push origin docs/v0.3.0

URL → version mapping:

docs.nvidia.com/nemo/gym/latest/...   → GA alias (currently mirrors v0.2.1)
docs.nvidia.com/nemo/gym/main/...     → bleeding-edge train (folder: ./latest/pages)
docs.nvidia.com/nemo/gym/v0.2.1/...   → 0.2.1 GA snapshot

Cutting a New Version Train

When the user ships a new version (e.g. v0.3.0):

  1. cp -r fern/versions/latest fern/versions/v0.3.0 — frozen snapshot of the bleeding-edge folder.
  2. cp fern/versions/main.yml fern/versions/v0.3.0.yml and rewrite ./latest/ path prefixes to ./v0.3.0/.
  3. Retarget the fern/versions/latest.yml symlink at the new GA's yml: cd fern/versions && ln -sfn v0.3.0.yml latest.yml.
  4. In fern/docs.yml versions:, add the new GA snapshot entry (display-name: "0.3.0", slug: v0.3.0, availability: stable) and demote/remove the previous GA snapshot per the support policy.
  5. fern/versions/latest/pages/ keeps moving forward as the bleeding-edge tree. main.yml is unchanged.
  6. Tag docs/v0.3.0 and push to publish.

Debugging

| Symptom | Fix | |---|---| | fern check YAML error | 2-space indent; - page: inside contents:; path: is relative to the version YAML file | | Page 404 in preview | slug: missing/duplicated in the same section; or position: collision in an auto-discovered folder | | Broken-link warning for /latest/... cross-version link | False positive in fern docs dev; works on published site | | JSX expressions must have one parent element | Wrap multi-element MDX content in <>...</> or a <div> | | Old URL breaks (page renamed/moved) | Add a redirects: entry in fern/docs.yml | | Library reference missing | npm run generate:library in fern/ | | Broken image | Path is relative to the MDX file; check fern/assets/ exists | | Card badges have no spacing | Don't add inline styles — main.css .fern-card .fern-docs-badge rules handle it | | /latest/<page> and /<current-ga>/<page> show different content | They shouldn't — latest.yml should mirror the current GA version's yml and point at the same ./<current-ga>/pages/... content. Sync them. |

Key References

| File | Purpose | |---|---| | fern/docs.yml | Site config, versions, redirects, libraries | | fern/versions/latest.yml | GA alias — symlink to the current GA's yml | | fern/versions/main.yml | Nav tree for the bleeding-edge train (mounts ./latest/pages) | | fern/versions/v0.2.1.yml | Nav tree for the 0.2.1 GA snapshot | | fern/versions/<ver>/pages/ | MDX content for a version | | fern/components/ | Custom TSX (CTAButtons, NavButton, CustomFooter) | | fern/assets/ | Shared images, SVGs, favicon | | fern/main.css | Global theme overrides — NVIDIA green, card/badge spacing | | fern/package.json | npm run check|dev|generate|generate:library — each wraps npx -y fern-api@latest | | .github/workflows/fern-docs-*.yml | CI: check, preview build, preview comment | | .github/workflows/publish-fern-docs.yml | CI: publish to docs.nvidia.com/nemo/gym |