Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
232 lines (169 loc) · 9.36 KB

CONTRIBUTING.md

File metadata and controls

232 lines (169 loc) · 9.36 KB
Raw

Contributing to NemoClaw Documentation

This guide covers how to write, edit, and review documentation for NemoClaw. If you change code that affects user-facing behavior, update the relevant docs in the same PR.

When to Update Docs

Update documentation when your change:

  • Adds, removes, or renames a CLI command or flag.
  • Changes default behavior or configuration.
  • Adds a new feature that users interact with.
  • Fixes a bug that the docs describe incorrectly.
  • Changes an API, protocol, or policy schema.

Update Docs with Agent Skills

If you use an AI coding agent (Cursor, Claude Code, Codex, etc.), the repo includes the update-docs skill that automates doc work. Use it before writing from scratch.

The skill scans recent commits for user-facing changes and drafts doc updates. Run it after landing features, before a release, or to find doc gaps. For example, ask your agent to "catch up the docs for everything merged since v0.2.0".

The skill lives in .agents/skills/update-docs/ and follows the style guide below automatically.

Doc-to-Skills Pipeline

The docs/ directory is the source of truth for user-facing documentation. The script scripts/docs-to-skills.py converts doc pages into agent skills under .agents/skills/. These generated skills let AI agents walk users through NemoClaw tasks (installation, inference configuration, policy management, monitoring, and more) without reading raw doc pages.

Always edit pages in docs/. Never edit generated skill files under .agents/skills/nemoclaw-*/. Your changes will be overwritten on the next run.

Generated skills

The current generated skills and their source pages are:

Skill Source docs
nemoclaw-overview docs/about/overview.md, docs/about/ecosystem.md, docs/about/how-it-works.md, docs/about/release-notes.md
nemoclaw-get-started docs/get-started/quickstart.md
nemoclaw-configure-inference docs/inference/inference-options.md, docs/inference/use-local-inference.md, docs/inference/switch-inference-providers.md
nemoclaw-manage-policy docs/network-policy/customize-network-policy.md, docs/network-policy/approve-network-requests.md
nemoclaw-monitor-sandbox docs/monitoring/monitor-sandbox-activity.md
nemoclaw-deploy-remote docs/deployment/deploy-to-remote-gpu.md, docs/deployment/set-up-telegram-bridge.md
nemoclaw-reference docs/reference/architecture.md, docs/reference/commands.md, docs/reference/network-policies.md, docs/reference/troubleshooting.md

Regenerating skills after doc changes

A pre-commit hook regenerates skills automatically whenever you commit changes to docs/**/*.md files. The hook runs scripts/docs-to-skills.py and stages the updated skills so they are included in the same commit. No manual step is needed for normal workflows.

To regenerate skills manually (for example, after rebasing or outside of a commit), run from the repo root:

python scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw

Always use this exact output path (.agents/skills/) and prefix (nemoclaw) so skill names and locations stay consistent.

Preview what would change before writing files:

python scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw --dry-run

Other useful flags:

Flag Purpose
--strategy <name> Grouping strategy: smart (default), grouped, or individual.
--name-map CAT=NAME Override a generated skill name (e.g. --name-map about=overview).
--exclude <file> Skip specific files (e.g. --exclude "release-notes.md").

How the Script Works

The script reads YAML frontmatter from each doc page to determine its content type (how_to, concept, reference, get_started), then groups pages into skills using the smart strategy by default. Procedure pages (how_to, get_started) become the main body of the skill. Concept pages become a ## Context section. Reference pages go into a references/ subdirectory for progressive disclosure, keeping the SKILL.md concise (under 500 lines).

Cross-references between doc pages are rewritten as skill-to-skill pointers so agents can navigate between skills. MyST/Sphinx directives are converted to standard markdown.

For full usage details and all flags, see the docstring at the top of scripts/docs-to-skills.py.

Building Docs Locally

Verify the docs are built correctly by building them and checking the output.

To build the docs, run:

make docs

To serve the docs locally and automatically rebuild on changes, run:

make docs-live

Writing Conventions

Format

  • Docs use MyST Markdown, a Sphinx-compatible superset of CommonMark.

  • Every page starts with YAML frontmatter (title, description.main, description.agent, topics, tags, content type).

  • Include the SPDX license header after frontmatter:

    <!--
  SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
  SPDX-License-Identifier: Apache-2.0
-->

Frontmatter Template

---
title:
  page: "NemoClaw Page Title: Subtitle with Context"
  nav: "Short Nav Title"
description:
  main: "One-sentence summary for readers, SEO, and doc search snippets."
  agent: "Third-person verb summary for agent routing. Add 'Use when...' with trigger phrases."
keywords: ["primary keyword", "secondary keyword phrase"]
topics: ["generative_ai", "ai_agents"]
tags: ["openclaw", "openshell", "relevant", "tags"]
content:
  type: concept | how_to | get_started | tutorial | reference
  difficulty: technical_beginner | technical_intermediate | technical_advanced
  audience: ["developer", "engineer"]
status: published
---

Page Structure

  1. H1 heading matching the title.page value.
  2. A one- or two-sentence introduction stating what the page covers.
  3. Sections organized by task or concept, using H2 and H3. Start each section with an introductory sentence that orients the reader.
  4. A "Next Steps" section at the bottom linking to related pages.

Style Guide

Write like you are explaining something to a colleague. Be direct, specific, and concise.

Voice and Tone

  • Use active voice. "The CLI creates a gateway" not "A gateway is created by the CLI."
  • Use second person ("you") when addressing the reader.
  • Use present tense. "The command returns an error" not "The command will return an error."
  • State facts. Do not hedge with "simply," "just," "easily," or "of course."

Things to Avoid

These patterns are common in LLM-generated text and erode trust with technical readers. Remove them during review.

Pattern Problem Fix
Unnecessary bold "This is a critical step" on routine instructions. Reserve bold for UI labels, parameter names, and genuine warnings.
Em dashes "The gateway, which runs in Docker, creates sandboxes." Do not use em dashes. Prefer commas, colons, or separate sentences.
Superlatives "OpenShell provides a powerful, robust, seamless experience." Say what it does, not how great it is.
Hedge words "Simply run the command" or "You can easily configure..." Drop the adverb. "Run the command."
Emoji in prose "Let's get started!" No emoji in documentation prose.
Rhetorical questions "Want to secure your agents? Look no further!" State the purpose directly.

Formatting Rules

  • End every sentence with a period.

  • One sentence per line in the source file (makes diffs readable).

  • Use code formatting for CLI commands, file paths, flags, parameter names, and values.

  • Use code blocks with the console language for CLI examples. Prefix commands with $:

    $ nemoclaw onboard

  • Use tables for structured comparisons. Keep tables simple (no nested formatting).

  • Use MyST admonitions (:::{tip}, :::{note}, :::{warning}) for callouts, not bold text.

  • Avoid nested admonitions.

  • Do not number section titles. Write "Deploy a Gateway" not "Section 1: Deploy a Gateway" or "Step 3: Verify."

  • Do not use colons in titles. Write "Deploy and Manage Gateways" not "Gateways: Deploy and Manage."

  • Use colons only to introduce a list. Do not use colons as general-purpose punctuation between clauses.

Word List

Use these consistently:

Use Do not use
gateway Gateway (unless starting a sentence)
sandbox Sandbox (unless starting a sentence)
CLI cli, Cli
API key api key, API Key
NVIDIA Nvidia, nvidia
NemoClaw nemoclaw (in prose), Nemoclaw
OpenClaw openclaw (in prose), Openclaw
OpenShell Open Shell, openShell, Openshell, openshell
mTLS MTLS, mtls
YAML yaml, Yaml

Submitting Doc Changes

  1. Create a branch following the project convention.
  2. Make your changes.
  3. Build locally with make docs and verify the output.
  4. Open a PR with docs: as the conventional commit type.
docs: update quickstart for new onboard wizard

If your doc change accompanies a code change, include both in the same PR and use the code change's commit type:

feat(cli): add policy-add command

Reviewing Doc PRs

When reviewing documentation:

  • Check that the style guide rules above are followed.
  • Watch for LLM-generated patterns (excessive bold, em dashes, filler).
  • Verify code examples are accurate and runnable.
  • Confirm cross-references and links are not broken.
  • Build locally to check rendering.