nemoclaw-contributor-update-docs

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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 NemoClaw git repository (`NemoClaw`).
- The `docs/` directory must exist with the current doc set.

## 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.
- During daily release prep, before opening the docs refresh PR.
- When a contributor asks "what docs need updating?"

## Step 0: Load the Skip List

Before scanning commits, read `docs/.docs-skip` if it exists. This file lists features and commits that are merged but should not be documented yet (experimental, under review, etc.).

```bash
cat docs/.docs-skip
```

Parse these sections from the file:

- `skip-features:` — substring patterns matched against commit messages and changed file paths. Any commit whose message or file list contains a listed string is excluded.
- `skip-terms:` — terms that must never appear in generated documentation. Check all drafted content against this list before writing. If a drafted sentence contains a skip-term, remove that sentence or the entire section. This is a hard gate — no skip-term may appear in any doc output.

Ignore comment lines (starting with `#`) and inline comments (everything after ` # `).

Keep the loaded skip list in memory for use throughout the skill execution and the whole documentation process.

## Step 1: Identify Relevant Commits

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

```bash
# Commits since a tag
git log v0.1.0..HEAD --oneline --no-merges

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

Filter to commits that are likely to affect docs. Apply every rule below before proceeding. A commit excluded by any rule must not produce doc changes.

1. **Commit type**: `feat`, `fix`, `refactor`, `perf` commits often change behavior. `docs` commits are already doc changes, but still need a review pass when they fall in the scanned range.
2. **Files changed**: Changes to `nemoclaw/src/`, `nemoclaw-blueprint/`, `bin/`, `scripts/`, or policy-related code are high-signal.
3. **Ignore**: Changes limited to `test/`, `.github/`, or internal-only modules.
4. **Skip list**: Exclude any commit whose short hash appears in `skip-commits`, or whose commit message or changed file paths contain a `skip-features` substring. Report skipped commits in the final summary under a "Skipped (docs-skip)" heading.
5. **Agent support matrix**: Do not document agent support (e.g., Claude Code, OpenHands, Goose) unless the agent is listed in the tested agent support matrix in the quickstart or platform docs. Commits that add or modify agent integration code should only produce doc updates for agents already in the matrix. Report excluded agents under "Skipped (not in agent matrix)" in the summary.

```bash
# Show files changed per commit to assess impact
git log v0.1.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) |
|---|---|
| `nemoclaw/src/commands/` (launch, connect, status, logs) | `docs/reference/commands.mdx` |
| `nemoclaw/src/commands/` (new command) | May need a new page or entry in `docs/reference/commands.mdx` |
| `nemoclaw/src/blueprint/` | `docs/reference/architecture.mdx` |
| `nemoclaw/src/cli.ts` or `nemoclaw/src/index.ts` | `docs/reference/commands.mdx`, `docs/get-started/quickstart.mdx` |
| `nemoclaw-blueprint/orchestrator/` | `docs/reference/architecture.mdx` |
| `nemoclaw-blueprint/policies/` | `docs/reference/network-policies.mdx` |
| `nemoclaw-blueprint/blueprint.yaml` | `docs/reference/architecture.mdx`, `docs/inference/inference-options.mdx` |
| `scripts/` (setup, start) | `docs/get-started/quickstart.mdx` |
| `Dockerfile` | `docs/reference/architecture.mdx` |
| Inference-related changes | `docs/inference/inference-options.mdx` |

If a commit does not map to any existing page but introduces a user-visible concept, flag it as needing a new page.
If a commit already changes files under `docs/`, include those pages in the target page list and run a docs review or edit pass against them using the style guidance in Step 5.
Do not assume an existing doc change is complete, correctly placed, or style-compliant just because it landed with the source commit.

## Step 3: Read the Commit Details

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

```bash
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.
For target pages that were already changed by a scanned commit, compare the committed doc diff against the source behavior and the style guidance before deciding whether to edit further.

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

## Step 5: Draft the Update

Before writing, verify that the commit was not excluded in Step 1. Do not draft content for commits matched by the skip list or for agent integrations not in the tested agent support matrix. After drafting, scan the content for any `skip-terms` from `docs/.docs-skip`. Remove any sentence or section that contains a skip-term. If in doubt, skip the commit and report it.

Write the doc update following these conventions:

- **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.
- **Copyable code examples use language-specific fences** such as `bash`, `sh`, or `powershell`, without prompt markers.
- **Shared NemoClaw CLI examples use `$$nemoclaw`.** In shared OpenClaw/Hermes variant pages, write host CLI examples with the `$$nemoclaw` build-time placeholder so the docs build renders `nemoclaw` on OpenClaw pages and `nemohermes` on Hermes pages before Fern renders fenced code blocks.
- **Do not duplicate code blocks for binary-name-only differences.** Use one fenced block with `$$nemoclaw` when the only difference is `nemoclaw` versus `nemohermes`; keep `<AgentOnly>` only when the surrounding text, flags, behavior, or setup steps actually differ.
- **Use `console` only for terminal transcripts** that include prompts, output, or interactive sessions.
- **Include the SPDX header** if creating a new page.
- **Match existing frontmatter format** if creating a new page.
- **Always write NVIDIA in all caps.** Wrong: Nvidia, nvidia.

From YYC-Cube/YYC3-NemoClaw, Apache-2.0.

More from YYC-Cube/YYC3-NemoClaw