Index of every page on this site: llms.txt
All skills
nvidia avatar

/update-docs

@c24fcd2
by NVIDIA Corporationnvidia/openshell22k stars
2,144
Run it yourself

Scan recent git commits for changes that affect user-facing behavior, then draft or update the corresponding documentation pages. Use when docs have fallen behind code changes, after a batch of features lands, or when preparing a release. Trigger keywords - update docs, draft docs, docs from commits, sync docs, catch up docs, doc debt, docs behind, docs drift.

  • 1 file
  • 9.4 KB
  • Updated 2 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/nvidia/openshell/update-docs

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈94 tokens for metadata: the name and description. ≈2.3k when used: this file.

Description uses 4.9% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈389 characters, or 4.9%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Update Docs from Commits

Scan recent git history for commits that affect user-facing behavior and draft documentation updates for each.

Prerequisites

  • You must be in the OpenShell git repository.
  • The published docs tree must exist under docs/.
  • Read docs/CONTRIBUTING.mdx before writing any content. It contains the current style guide and formatting rules.

When to Use

  • After a batch of features or fixes has landed and docs may be stale.
  • Before a release, to catch any doc gaps.
  • When a contributor asks "what docs need updating?"

Step 1: Identify Relevant Commits

Determine the commit range. The user may provide one explicitly (e.g., "since v0.2.0" or "last 30 commits"). If not, default to commits since the head of the main branch.

# Commits since a tag
git log v0.2.0..HEAD --oneline --no-merges

# Or last 50 commits
git log -50 --oneline --no-merges

Filter to commits that are likely to affect docs. Look for these signals:

  1. Commit type: feat, fix, refactor, perf commits often change behavior. docs commits are already doc changes. chore, ci, test commits rarely need doc updates.
  2. Files changed: Changes to crates/openshell-cli/, python/, proto/, deploy/, gateway config parsing, driver config structs, or policy-related code are high-signal.
  3. Ignore: Changes limited to tests/, e2e/, .github/, tasks/, or internal-only modules.
# Show files changed per commit to assess impact
git log v0.2.0..HEAD --oneline --no-merges --name-only

Step 2: Map Commits to Doc Pages

For each relevant commit, determine which doc page(s) it affects. Use this mapping as a starting point:

Code area Likely doc page(s)
crates/openshell-cli/ (gateway commands) docs/how-it-works/gateways/overview.mdx
crates/openshell-cli/ (sandbox commands) docs/how-it-works/sandboxes/overview.mdx
crates/openshell-cli/ (provider commands) docs/how-it-works/providers/overview.mdx
crates/openshell-cli/ (new top-level command) May need a new page or docs/reference/ entry
crates/openshell-server/src/config_file.rs or gateway TOML parsing docs/how-it-works/gateways/configuration.mdx
crates/openshell-server/src/cli.rs gateway config merge/default behavior docs/how-it-works/gateways/configuration.mdx
crates/openshell-driver-*/ config structs or driver defaults docs/how-it-works/gateways/configuration.mdx, docs/how-it-works/sandboxes/runtimes.mdx
deploy/helm/openshell/templates/gateway-config.yaml docs/how-it-works/gateways/configuration.mdx, docs/how-it-works/sandboxes/runtimes.mdx, Helm docs if values change
Proxy or policy code docs/how-it-works/policies/overview.mdx, docs/how-it-works/policies/schema.mdx
Inference code docs/inference/configure.mdx
python/ (SDK changes) docs/reference/ or docs/get-started/quickstart.mdx
proto/ (API changes) docs/reference/
deploy/ (Dockerfile, Helm) docs/how-it-works/gateways/overview.mdx, docs/about/architecture.mdx
Sandbox image behavior docs/how-it-works/sandboxes/overview.mdx

If a commit does not map to any existing page but introduces a user-visible concept, flag it as needing a new page.

Step 3: Read the Commit Details

For each commit that needs a doc update, read the full diff to understand the change:

git show <commit-hash> --stat
git show <commit-hash>

Extract:

  • What changed (new flag, renamed command, changed default, new feature).
  • Why it changed (from the commit message body, linked issue, or PR description).
  • Any breaking changes or migration steps.

Step 4: Read the Current Doc Page

Before editing, read the full target doc page to understand its current content and structure:

# Read the file

Identify where the new content should go. Follow the page's existing structure.

Step 5: Draft the Update

Write the smallest update that tells users exactly what changed and what they need to do. Prefer updating one authoritative page and linking to it over repeating explanations across pages. Omit exhaustive internal details unless they directly affect a user decision or workflow. Follow docs/CONTRIBUTING.mdx. Key reminders:

  • Active voice, present tense, second person.
  • No unnecessary bold. Reserve bold for UI labels and parameter names.
  • No em dashes unless used sparingly. Prefer commas or separate sentences.
  • Start sections with an introductory sentence that orients the reader.
  • No superlatives. Say what the feature does, not how great it is.
  • Code examples use shell language for copyable commands, with no $ prompt prefix.
  • Use text fences for transcripts, logs, or shell sessions that should not be copied verbatim.
  • Include the SPDX header as YAML comments in frontmatter if creating a new page.
  • Match existing Fern frontmatter format if creating a new page, including sidebar-title, keywords, and position when they are relevant. Use frontmatter slug only for folder-discovered pages or absolute URL overrides.
  • Use sidebar-title for short nav labels. For explicit navigation entries, keep relative slug values in docs/index.yml instead of page frontmatter.
  • Keep explicit page: entries in docs/index.yml. Fern still requires them. If the page defines sidebar-title, set page: to that value. Otherwise set page: to the page frontmatter title.
  • Use skip-slug: true in docs/index.yml when a child page should live at the parent section path.
  • Keep each page URL equal to its file path under docs/. Rename the file when you rename a page, add a fern/docs.yml redirect for the old URL, and set a relative slug: when the nav label does not produce the file name. mise run docs runs docs:nav, which fails otherwise.
  • Use keywords as a comma-separated string.
  • Do not add a duplicate H1. Fern renders the page title from frontmatter.
  • Always write NVIDIA in all caps. Wrong: Nvidia, nvidia.
  • Always capitalize OpenShell correctly. Wrong: openshell, Openshell, openShell.
  • Do not number section titles. Wrong: "Section 1: Deploy a Gateway" or "Step 3: Verify." Use plain descriptive titles.
  • No colons in titles. Wrong: "Gateways: Deploy and Manage." Write "Deploy and Manage Gateways" instead.
  • Use colons only to introduce a list. Do not use colons as general-purpose punctuation between clauses.

When updating an existing page:

  • Add content in the logical place within the existing structure.
  • Do not reorganize sections unless the change requires it.
  • Update any cross-references or "Next Steps" links if relevant.
  • When moving published URLs, update fern/docs.yml redirects and run mise run test:docs-website. Redirects reach production through the owning channel's snapshot sync; changing source configuration alone does not republish existing snapshots. See fern/README.md for channel ownership and repair instructions.

When creating a new page:

  • Follow the frontmatter template from docs/CONTRIBUTING.mdx.
  • Add the page to the appropriate section in docs/index.yml.

Step 6: Present the Results

After drafting all updates, present a summary to the user:

## Doc Updates from Commits

### Updated pages
- `docs/how-it-works/gateways/overview.mdx`: Added `--gpu` flag documentation (from commit abc1234).
- `docs/how-it-works/policies/schema.mdx`: Updated network policy schema for new `tls_inspect` field (from commit def5678).

### New pages needed
- None (or list any new pages created).

### Commits with no doc impact
- `chore(deps): bump tokio` (abc1234) — internal dependency, no user-facing change.
- `test(e2e): add gateway timeout test` (def5678) — test-only change.

Step 7: Build and Verify

After making changes, validate the Fern docs locally:

mise run docs

If a human needs to inspect rendering while iterating, they can also run:

mise run docs:serve

Check for:

  • Validation warnings or errors.
  • Broken cross-references.
  • Correct rendering of new content in the PR preview when available.

Tips

  • When in doubt about whether a commit needs a doc update, check if the commit message references a CLI flag, config option, or user-visible behavior.
  • Group related commits that touch the same doc page into a single update rather than making multiple small edits.
  • If a commit is a breaking change, add a note at the top of the relevant section using a Fern <Warning> callout.
  • PRs that are purely internal refactors with no behavior change do not need doc updates, even if they touch high-signal directories.

Example Usage

User says: "Catch up the docs for everything merged since v0.2.0."

  1. Run git log v0.2.0..HEAD --oneline --no-merges --name-only.
  2. Filter to feat, fix, refactor, perf commits touching user-facing code.
  3. Map each to a doc page.
  4. Read the commit diffs and current doc pages.
  5. Draft updates following the style guide.
  6. Present the summary.
  7. Run mise run docs to verify.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at c24fcd2. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 months ago
metadata
{
  "internal": true
}

README badge

README badge for nvidia/openshell/update-docs