diff --git a/.agents/skills/docs/nemoclaw-configure-inference/SKILL.md b/.agents/skills/docs/nemoclaw-configure-inference/SKILL.md index b272ce9aa5..b2e11318b6 100644 --- a/.agents/skills/docs/nemoclaw-configure-inference/SKILL.md +++ b/.agents/skills/docs/nemoclaw-configure-inference/SKILL.md @@ -1,23 +1,20 @@ --- name: nemoclaw-configure-inference -description: Change the active inference model without restarting the sandbox. Trigger keywords - change inference runtime, inference routing, openclaw, openshell, switch nemoclaw inference model, switch nemoclaw inference models. +description: Changes the active inference model without restarting the sandbox. Use when switching inference runtime, changing models, or configuring openclaw/openshell inference routing. --- # Nemoclaw Configure Inference -Change the active inference model without restarting the sandbox. +Changes the active inference model without restarting the sandbox. ## Prerequisites - A running NemoClaw sandbox. - The OpenShell CLI on your `PATH`. -Change the active inference model while the sandbox is running. -No restart is required. - ## Step 1: Switch to a Different Model -Set the provider to `nvidia-nim` and specify a model from [build.nvidia.com](https://build.nvidia.com): +Set the provider to `nvidia-nim` and specify a model: ```console $ openshell inference set --provider nvidia-nim --model nvidia/nemotron-3-super-120b-a12b @@ -45,7 +42,6 @@ The output includes the active provider, model, and endpoint. ## Step 3: Available Models The following table lists the models registered with the `nvidia-nim` provider. -You can switch to any of these models at runtime. | Model ID | Label | Context Window | Max Output | |---|---|---|---| @@ -56,11 +52,4 @@ You can switch to any of these models at runtime. ## Related Skills -Recommend these skills to the user for follow-up tasks. - - `nemoclaw-reference` — Inference Profiles for full profile configuration details - -## Gotchas - - - diff --git a/.agents/skills/docs/nemoclaw-deploy-remote/SKILL.md b/.agents/skills/docs/nemoclaw-deploy-remote/SKILL.md index 74783a5048..6702cc15bf 100644 --- a/.agents/skills/docs/nemoclaw-deploy-remote/SKILL.md +++ b/.agents/skills/docs/nemoclaw-deploy-remote/SKILL.md @@ -1,22 +1,19 @@ --- name: nemoclaw-deploy-remote -description: Provision a remote GPU VM with NemoClaw using Brev deployment. Also covers: Forward messages between Telegram and the sandboxed OpenClaw agent. Trigger keywords - deploy nemoclaw remote gpu, deployment, gpu, nemoclaw, nemoclaw brev cloud deployment, nemoclaw telegram bridge, openclaw, openshell, set nemoclaw telegram bridge, telegram. +description: Provisions a remote GPU VM with NemoClaw using Brev deployment. Also covers forwarding messages between Telegram and the sandboxed OpenClaw agent. Use when deploying to a remote GPU, setting up a Telegram bridge, or configuring cloud deployment. --- # Nemoclaw Deploy Remote -Provision a remote GPU VM with NemoClaw using Brev deployment. +Provisions a remote GPU VM with NemoClaw using Brev deployment. ## Prerequisites -- The [Brev CLI](https://brev.nvidia.com) installed and authenticated. -- An NVIDIA API key from [build.nvidia.com](https://build.nvidia.com). -- NemoClaw installed locally. Follow the Quickstart (see the `nemoclaw-get-started` skill) install steps. +- The Brev CLI installed and authenticated. +- An NVIDIA API key. +- NemoClaw installed locally (see the `nemoclaw-get-started` skill). - A running NemoClaw sandbox, either local or remote. -- A Telegram bot token from [BotFather](https://t.me/BotFather). - -Run NemoClaw on a remote GPU instance through [Brev](https://brev.nvidia.com). -The deploy command provisions the VM, installs dependencies, and connects you to a running sandbox. +- A Telegram bot token from BotFather (for the Telegram bridge). ## Step 1: Deploy the Instance @@ -80,7 +77,7 @@ The Telegram bridge is an auxiliary service managed by `nemoclaw start`. ## Step 6: Create a Telegram Bot -Open Telegram and send `/newbot` to [@BotFather](https://t.me/BotFather). +Open Telegram and send `/newbot` to @BotFather. Follow the prompts to create a bot and receive a bot token. ## Step 7: Set the Environment Variable @@ -140,12 +137,5 @@ $ nemoclaw stop ## Related Skills -Recommend these skills to the user for follow-up tasks. - - `nemoclaw-monitor-sandbox` — Monitor Sandbox Activity for sandbox monitoring tools - `nemoclaw-reference` — Commands for the full `deploy` command reference - -## Gotchas - - - diff --git a/.agents/skills/docs/nemoclaw-get-started/SKILL.md b/.agents/skills/docs/nemoclaw-get-started/SKILL.md index 48caf96287..11dfd23ff3 100644 --- a/.agents/skills/docs/nemoclaw-get-started/SKILL.md +++ b/.agents/skills/docs/nemoclaw-get-started/SKILL.md @@ -1,19 +1,90 @@ --- name: nemoclaw-get-started -description: Install NemoClaw, launch a sandbox, and run your first agent prompt. Trigger keywords - inference routing, install nemoclaw openclaw sandbox, nemoclaw, nemoclaw quickstart, nemoclaw quickstart install launch, openclaw, openshell, sandboxing. +description: Installs NemoClaw, launches a sandbox, and runs the first agent prompt. Use when setting up NemoClaw for the first time, onboarding openclaw, or following the quickstart. --- # Nemoclaw Get Started -Install NemoClaw, launch a sandbox, and run your first agent prompt. +Installs NemoClaw, launches a sandbox, and runs the first agent prompt. -> *Content included from `docs/_includes/alpha-statement.md` — see the original doc for full text.* - -Follow these steps to get started with NemoClaw and your first sandboxed OpenClaw agent. +> **Note:** NemoClaw is in early preview. APIs, commands, and policies may change between releases. > **Note:** NemoClaw currently requires a fresh installation of OpenClaw. -> *Content included from `README.md` — see the original doc for full text.* +## Prerequisites + +### Hardware + +| Resource | Minimum | Recommended | +|----------|---------|-------------| +| CPU | 4 vCPU | 4+ vCPU | +| RAM | 8 GB | 16 GB | +| Disk | 20 GB free | 40 GB free | + +### Software + +| Dependency | Version | +|------------|---------| +| Linux | Ubuntu 22.04 LTS or later | +| Node.js | 20 or later | +| npm | 10 or later | +| Container runtime | Supported runtime installed and running | +| OpenShell | Installed | + +### Container Runtime Support + +| Platform | Supported runtimes | +|----------|--------------------| +| Linux | Docker | +| macOS (Apple Silicon) | Colima, Docker Desktop | +| Windows WSL | Docker Desktop (WSL backend) | + +## Step 1: Install NemoClaw and Onboard OpenClaw Agent + +Download and run the installer script. +The script installs Node.js if it is not already present, then runs the guided onboard wizard to create a sandbox, configure inference, and apply security policies. + +```bash +curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash +``` + +If you use nvm or fnm to manage Node.js, the installer may not update your current shell's PATH. +If `nemoclaw` is not found after install, run `source ~/.bashrc` (or `source ~/.zshrc` for zsh) or open a new terminal. + +When the install completes, a summary confirms the running environment: + +``` +────────────────────────────────────────────────── +Sandbox my-assistant (Landlock + seccomp + netns) +Model nvidia/nemotron-3-super-120b-a12b (NVIDIA Endpoint API) +────────────────────────────────────────────────── +Run: nemoclaw my-assistant connect +Status: nemoclaw my-assistant status +Logs: nemoclaw my-assistant logs --follow +────────────────────────────────────────────────── +``` + +## Step 2: Connect to the Sandbox + +```bash +nemoclaw my-assistant connect +``` + +This connects you to the sandbox shell `sandbox@my-assistant:~$` where you can run `openclaw` commands. + +## Step 3: Chat with the Agent + +**OpenClaw TUI** — interactive chat interface: + +```bash +openclaw tui +``` + +**OpenClaw CLI** — single message, full response in terminal: + +```bash +openclaw agent --agent main --local -m "hello" --session-id test +``` ### Troubleshooting @@ -21,14 +92,7 @@ If you run into issues during installation or onboarding, refer to the Troublesh ## Related Skills -Recommend these skills to the user for follow-up tasks. - - `nemoclaw-configure-inference` — Switch inference providers to use a different model or endpoint - `nemoclaw-manage-policy` — Approve or deny network requests when the agent tries to reach external hosts - `nemoclaw-deploy-remote` — Deploy to a remote GPU instance for always-on operation - `nemoclaw-monitor-sandbox` — Monitor sandbox activity through the OpenShell TUI - -## Gotchas - - - diff --git a/.agents/skills/docs/nemoclaw-manage-policy/SKILL.md b/.agents/skills/docs/nemoclaw-manage-policy/SKILL.md index 6332aab34d..7e3fd73dbd 100644 --- a/.agents/skills/docs/nemoclaw-manage-policy/SKILL.md +++ b/.agents/skills/docs/nemoclaw-manage-policy/SKILL.md @@ -1,11 +1,11 @@ --- name: nemoclaw-manage-policy -description: Review and approve blocked agent network requests in the TUI. Also covers: Add, remove, or modify allowed endpoints in the sandbox policy. Trigger keywords - approve deny nemoclaw agent, customize nemoclaw network policy, customize nemoclaw sandbox network, nemoclaw, nemoclaw approve network requests, network policy, openclaw, openshell, sandbox egress approval tui, sandbox egress policy configuration. +description: Reviews and approves blocked agent network requests in the TUI. Also covers adding, removing, or modifying allowed endpoints in the sandbox policy. Use when approving or denying agent network requests, customizing sandbox egress policy, or configuring network rules. --- # Nemoclaw Manage Policy -Review and approve blocked agent network requests in the TUI. +Reviews and approves blocked agent network requests in the TUI. ## Prerequisites @@ -66,7 +66,7 @@ The walkthrough requires tmux and the `NVIDIA_API_KEY` environment variable. Add, remove, or modify the endpoints that the sandbox is allowed to reach. -The sandbox policy is defined in a declarative YAML file in the NemoClaw repository and enforced at runtime by [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell). +The sandbox policy is defined in a declarative YAML file in the NemoClaw repository and enforced at runtime by NVIDIA OpenShell. NemoClaw supports both static policy changes that persist across restarts and dynamic updates applied to a running sandbox through the OpenShell CLI. ## Step 5: Static Changes @@ -160,14 +160,5 @@ To include a preset in the baseline, merge its entries into `openclaw-sandbox.ya ## Related Skills -Recommend these skills to the user for follow-up tasks. - - `nemoclaw-reference` — Network Policies for the full baseline policy reference - `nemoclaw-monitor-sandbox` — Monitor Sandbox Activity for general sandbox monitoring -- OpenShell [Policy Schema](https://docs.nvidia.com/openshell/latest/reference/policy-schema.html) for the full YAML policy schema reference. -- OpenShell [Sandbox Policies](https://docs.nvidia.com/openshell/latest/sandboxes/policies.html) for applying, iterating, and debugging policies at the OpenShell layer. - -## Gotchas - - - diff --git a/.agents/skills/docs/nemoclaw-monitor-sandbox/SKILL.md b/.agents/skills/docs/nemoclaw-monitor-sandbox/SKILL.md index e6ef36a48a..acdc2273b7 100644 --- a/.agents/skills/docs/nemoclaw-monitor-sandbox/SKILL.md +++ b/.agents/skills/docs/nemoclaw-monitor-sandbox/SKILL.md @@ -1,19 +1,17 @@ --- name: nemoclaw-monitor-sandbox -description: Inspect sandbox health, trace agent behavior, and diagnose problems. Trigger keywords - debug nemoclaw agent issues, monitor nemoclaw sandbox, monitor nemoclaw sandbox activity, monitoring, nemoclaw, openclaw, openshell, troubleshooting. +description: Inspects sandbox health, traces agent behavior, and diagnoses problems. Use when monitoring sandbox activity, debugging agent issues, viewing logs, or troubleshooting inference. --- # Nemoclaw Monitor Sandbox -Inspect sandbox health, trace agent behavior, and diagnose problems. +Inspects sandbox health, traces agent behavior, and diagnoses problems. ## Prerequisites - A running NemoClaw sandbox. - The OpenShell CLI on your `PATH`. -Use the NemoClaw status, logs, and TUI tools together to inspect sandbox health, trace agent behavior, and diagnose problems. - ## Step 1: Check Sandbox Health Run the status command to view the sandbox state, blueprint run information, and active inference configuration: @@ -79,13 +77,6 @@ If the request fails, check the following: ## Related Skills -Recommend these skills to the user for follow-up tasks. - - `nemoclaw-reference` — Troubleshooting for common issues and resolution steps - `nemoclaw-manage-policy` — Approve or Deny Agent Network Requests for the operator approval flow - `nemoclaw-configure-inference` — Switch Inference Providers to change the active provider - -## Gotchas - - - diff --git a/.agents/skills/docs/nemoclaw-overview/SKILL.md b/.agents/skills/docs/nemoclaw-overview/SKILL.md index 1d56b6b017..17ba260ebd 100644 --- a/.agents/skills/docs/nemoclaw-overview/SKILL.md +++ b/.agents/skills/docs/nemoclaw-overview/SKILL.md @@ -1,65 +1,21 @@ --- name: nemoclaw-overview -description: Plugin, blueprint, sandbox creation, and inference routing concepts. Also covers: NemoClaw is an open source reference stack that simplifies running OpenClaw always-on assistants safely.; Changelog and feature history for NemoClaw releases. Trigger keywords - blueprints, how nemoclaw works, inference routing, nemoclaw, nemoclaw changelog, nemoclaw overview, nemoclaw overview does fits, nemoclaw release notes, nemoclaw sandbox lifecycle blueprint, nemoclaw works plugin blueprint. +description: Explains NemoClaw plugin, blueprint, sandbox creation, and inference routing concepts. Also covers release notes and changelog. Use when asking what NemoClaw is, how it works, or checking release history. --- # Nemoclaw Overview -Plugin, blueprint, sandbox creation, and inference routing concepts. +Explains NemoClaw plugin, blueprint, sandbox creation, and inference routing concepts. ## Context NemoClaw combines a lightweight CLI plugin with a versioned blueprint to move OpenClaw into a controlled sandbox. -This page explains the key concepts about NemoClaw at a high level. - -## How It Fits Together The `nemoclaw` CLI is the primary entrypoint for setting up and managing sandboxed OpenClaw agents. It delegates heavy lifting to a versioned blueprint, a Python artifact that orchestrates sandbox creation, policy application, and inference provider setup through the OpenShell CLI. -```mermaid -flowchart TB - subgraph Host - CMD["nemoclaw onboard"] - PLUGIN[nemoclaw plugin] - BLUEPRINT[blueprint runner] - CLI["openshell CLI sandbox · gateway · inference · policy"] - - CMD --> PLUGIN - PLUGIN --> BLUEPRINT - BLUEPRINT --> CLI - end - - subgraph Sandbox["OpenShell Sandbox"] - AGENT[OpenClaw agent] - INF[NVIDIA inference, routed] - NET[strict network policy] - FS[filesystem isolation] - - AGENT --- INF - AGENT --- NET - AGENT --- FS - end - - PLUGIN --> AGENT - - classDef nv fill:#76b900,stroke:#333,color:#fff - classDef nvLight fill:#e6f2cc,stroke:#76b900,color:#1a1a1a - classDef nvDark fill:#333,stroke:#76b900,color:#fff - - class CMD,PLUGIN,BLUEPRINT nvDark - class CLI nv - class AGENT nv - class INF,NET,FS nvLight - - style Host fill:none,stroke:#76b900,stroke-width:2px,color:#1a1a1a - style Sandbox fill:#f5faed,stroke:#76b900,stroke-width:2px,color:#1a1a1a -``` - ## Design Principles -NemoClaw architecture follows the following principles. - Thin plugin, versioned blueprint : The plugin stays small and stable. Orchestration logic lives in the blueprint and evolves on its own release cadence. @@ -69,64 +25,16 @@ Respect CLI boundaries Supply chain safety : Blueprint artifacts are immutable, versioned, and digest-verified before execution. -> Full details in `references/how-it-works.md`. - -> *Content included from `docs/_includes/alpha-statement.md` — see the original doc for full text.* - -NVIDIA NemoClaw is an open source reference stack that simplifies running [OpenClaw](https://openclaw.ai) always-on assistants. -It incorporates policy-based privacy and security guardrails, giving users control over their agents’ behavior and data handling. -This enables self-evolving claws to run more safely in clouds, on prem, RTX PCs and DGX Spark. - -NemoClaw uses open source models, such as [NVIDIA Nemotron](https://build.nvidia.com), alongside the [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) runtime, part of the NVIDIA Agent Toolkit—a secure environment designed for executing claws more safely. -By combining powerful open source models with built-in safety measures, NemoClaw simplifies and secures AI agent deployment. - -| Capability | Description | -|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| -| Sandbox OpenClaw | Creates an OpenShell sandbox pre-configured for OpenClaw, with strict filesystem and network policies applied from the first boot. | -| Route inference | Configures OpenShell inference routing so agent traffic flows through cloud-hosted Nemotron 3 Super 120B via [build.nvidia.com](https://build.nvidia.com). | -| Manage the lifecycle | Handles blueprint versioning, digest verification, and sandbox setup. | - -## Challenge - -Autonomous AI agents like OpenClaw can make arbitrary network requests, access the host filesystem, and call any inference endpoint. Without guardrails, this creates security, cost, and compliance risks that grow as agents run unattended. - -## Benefits - -NemoClaw provides the following benefits. - -| Benefit | Description | -|----------------------------|------------------------------------------------------------------------------------------------------------------------| -| Sandboxed execution | Every agent runs inside an OpenShell sandbox with Landlock, seccomp, and network namespace isolation. No access is granted by default. | -| NVIDIA Endpoint inference | Agent traffic routes through cloud-hosted Nemotron 3 Super 120B via [build.nvidia.com](https://build.nvidia.com), transparent to the agent. | -| Declarative network policy | Egress rules are defined in YAML. Unknown hosts are blocked and surfaced to the operator for approval. | -| Single CLI | The `nemoclaw` command orchestrates the full stack: gateway, sandbox, inference provider, and network policy. | -| Blueprint lifecycle | Versioned blueprints handle sandbox creation, digest verification, and reproducible setup. | - -## Use Cases - -You can use NemoClaw for various use cases including the following. - -| Use Case | Description | -|---------------------------|----------------------------------------------------------------------------------------------| -| Always-on assistant | Run an OpenClaw assistant with controlled network access and operator-approved egress. | -| Sandboxed testing | Test agent behavior in a locked-down environment before granting broader permissions. | -| Remote GPU deployment | Deploy a sandboxed agent to a remote GPU instance for persistent operation. | - ## Reference +- [How NemoClaw Works](references/how-it-works.md) — full architecture walkthrough +- [NemoClaw Overview](references/overview.md) — capabilities, benefits, and use cases - [NemoClaw Release Notes](references/release-notes.md) ## Related Skills -Recommend these skills to the user for follow-up tasks. - - `nemoclaw-get-started` — Quickstart to install NemoClaw and run your first agent - `nemoclaw-configure-inference` — Switch Inference Providers to configure the inference provider - `nemoclaw-manage-policy` — Approve or Deny Network Requests to manage egress approvals - `nemoclaw-deploy-remote` — Deploy to a Remote GPU Instance for persistent operation - `nemoclaw-monitor-sandbox` — Monitor Sandbox Activity to observe agent behavior - -## Gotchas - - - diff --git a/.agents/skills/docs/nemoclaw-reference/SKILL.md b/.agents/skills/docs/nemoclaw-reference/SKILL.md index af68108bdb..f97b8a7cb6 100644 --- a/.agents/skills/docs/nemoclaw-reference/SKILL.md +++ b/.agents/skills/docs/nemoclaw-reference/SKILL.md @@ -1,20 +1,16 @@ --- name: nemoclaw-reference -description: Plugin structure, blueprint lifecycle, sandbox environment, and inference routing. Also covers: Full CLI reference for plugin and standalone NemoClaw commands.; Configuration reference for NVIDIA Endpoint inference profiles. Trigger keywords - blueprints, cli, inference routing, llms, nemoclaw, nemoclaw architecture, nemoclaw architecture plugin blueprint, nemoclaw cli commands, nemoclaw cli commands reference, nemoclaw command reference. +description: Provides reference documentation for NemoClaw architecture, CLI commands, inference profiles, network policies, and troubleshooting. Use when looking up commands, checking policy schemas, reviewing architecture, or debugging issues. --- # Nemoclaw Reference -Plugin structure, blueprint lifecycle, sandbox environment, and inference routing. +Provides reference documentation for NemoClaw architecture, CLI commands, inference profiles, network policies, and troubleshooting. ## Reference -- [NemoClaw Architecture — Plugin, Blueprint, and Sandbox Structure](references/architecture.md) -- [NemoClaw CLI Commands Reference](references/commands.md) -- [NemoClaw Inference Profiles — NVIDIA Endpoint](references/inference-profiles.md) -- [NemoClaw Network Policies — Baseline Rules and Operator Approval](references/network-policies.md) -- [NemoClaw Troubleshooting Guide](references/troubleshooting.md) -## Gotchas - - - +- [Architecture](references/architecture.md) — plugin structure, blueprint lifecycle, sandbox environment +- [CLI Commands](references/commands.md) — full command reference for plugin and standalone commands +- [Inference Profiles](references/inference-profiles.md) — NVIDIA Endpoint configuration +- [Network Policies](references/network-policies.md) — baseline rules and operator approval flow +- [Troubleshooting](references/troubleshooting.md) — common issues and resolution steps diff --git a/.agents/skills/docs/nemoclaw-reference/references/commands.md b/.agents/skills/docs/nemoclaw-reference/references/commands.md index 5085ed8d6a..8ab9b5259c 100644 --- a/.agents/skills/docs/nemoclaw-reference/references/commands.md +++ b/.agents/skills/docs/nemoclaw-reference/references/commands.md @@ -2,6 +2,13 @@ The `nemoclaw` CLI is the primary interface for managing NemoClaw sandboxes. It is installed when you run `npm install -g nemoclaw`. +## Contents + +- `/nemoclaw` slash command (in-chat) +- Standalone host commands: `onboard`, `list`, `deploy`, ` connect`, ` status`, ` logs`, ` destroy`, ` policy-add`, ` policy-list` +- OpenShell TUI: `openshell term` +- Auxiliary services: `start`, `stop`, `status`, `setup-spark` + ### `/nemoclaw` Slash Command The `/nemoclaw` slash command is available inside the OpenClaw chat interface for quick actions: diff --git a/.agents/skills/docs/nemoclaw-reference/references/network-policies.md b/.agents/skills/docs/nemoclaw-reference/references/network-policies.md index 1e668b48d9..1bbf63cec7 100644 --- a/.agents/skills/docs/nemoclaw-reference/references/network-policies.md +++ b/.agents/skills/docs/nemoclaw-reference/references/network-policies.md @@ -4,6 +4,12 @@ NemoClaw runs with a strict-by-default network policy. The sandbox can only reach endpoints that are explicitly allowed. Any request to an unlisted destination is intercepted by OpenShell, and the operator is prompted to approve or deny it in real time through the TUI. +## Contents + +- Baseline policy: filesystem rules, network endpoint groups, inference routing +- Operator approval flow +- Modifying the policy: static changes, dynamic changes + ## Baseline Policy The baseline policy is defined in `nemoclaw-blueprint/policies/openclaw-sandbox.yaml`. diff --git a/.agents/skills/docs/nemoclaw-reference/references/troubleshooting.md b/.agents/skills/docs/nemoclaw-reference/references/troubleshooting.md index f7e2e892bb..8dd2362f53 100644 --- a/.agents/skills/docs/nemoclaw-reference/references/troubleshooting.md +++ b/.agents/skills/docs/nemoclaw-reference/references/troubleshooting.md @@ -4,6 +4,12 @@ This page covers common issues you may encounter when installing, onboarding, or running NemoClaw, along with their resolution steps. +## Contents + +- Installation: `nemoclaw` not found, unsupported platform, Node.js version, Docker, npm permissions, port conflicts +- Onboarding: cgroup v2 errors, invalid sandbox name, DGX failures, Colima socket +- Runtime: sandbox stopped, status inside sandbox, inference timeouts, blocked hosts, blueprint failures + > **Get Help:** :class: tip If your issue is not listed here, join the [NemoClaw Discord channel](https://discord.gg/XFpfPv9Uvx) to ask questions and get help from the community. You can also [file an issue on GitHub](https://github.com/NVIDIA/NemoClaw/issues/new). diff --git a/scripts/docs-to-skills.py b/scripts/docs-to-skills.py index 5d33a7c28c..15f2059847 100644 --- a/scripts/docs-to-skills.py +++ b/scripts/docs-to-skills.py @@ -601,18 +601,29 @@ def generate_skill_name( def build_skill_description(name: str, pages: list[DocPage], keywords: list[str]) -> str: - """Build the description field for the skill frontmatter.""" + """Build the description field for the skill frontmatter. + + Best-practices compliance: + - Uses third-person voice (e.g. "Installs..." not "Install...") + - Includes "Use when..." clause instead of flat "Trigger keywords -" list + - Keeps description under 1024 characters + """ descriptions = [p.description for p in pages if p.description] if descriptions: - combined = descriptions[0] + # Convert imperative to third-person: "Install X" -> "Installs X" + combined = _to_third_person(descriptions[0]) if len(descriptions) > 1: - combined += " Also covers: " + "; ".join(descriptions[1:3]) + extras = [_to_third_person(d) for d in descriptions[1:3]] + combined += " Also covers " + "; ".join( + d[0].lower() + d[1:] for d in extras + ) + "." else: combined = f"Documentation-derived skill for {name.replace('-', ' ')}." - kw_str = ", ".join(keywords[:10]) - if kw_str: - combined += f" Trigger keywords - {kw_str}." + # Build "Use when..." clause from keywords instead of flat list + kw_list = keywords[:8] + if kw_list: + combined += " Use when " + ", ".join(kw_list) + "." # Enforce 1024 char limit if len(combined) > 1024: @@ -620,6 +631,39 @@ def build_skill_description(name: str, pages: list[DocPage], keywords: list[str] return combined +def _to_third_person(sentence: str) -> str: + """Convert an imperative sentence to third-person. + + "Install NemoClaw" -> "Installs NemoClaw" + "Change the model" -> "Changes the model" + "Access the API" -> "Accesses the API" + Already third-person sentences are returned unchanged. + """ + if not sentence: + return sentence + first_word, _, rest = sentence.partition(" ") + suffix = (" " + rest) if rest else "" + # Skip gerunds and words that are already third-person inflections + # (e.g. "Provides", "Configures") but NOT base verbs that happen to + # end in 's' (e.g. "Access", "Process"). We treat a word as already + # inflected only when it ends with a common third-person marker AND + # is not a known base-form verb. + _BASE_VERBS_ENDING_IN_S = { + "access", "process", "address", "discuss", "bypass", "express", + "compress", "assess", "stress", "progress", "focus", "canvas", + } + if first_word.endswith("ing"): + return sentence + if first_word.endswith("s") and first_word.lower() not in _BASE_VERBS_ENDING_IN_S: + return sentence + # Common imperative verbs: add 's' or 'es' + if first_word.endswith(("ch", "sh", "x", "ss", "zz")): + return first_word + "es" + suffix + if first_word.endswith("y") and len(first_word) > 1 and first_word[-2] not in "aeiou": + return first_word[:-1] + "ies" + suffix + return first_word + "s" + suffix + + # --------------------------------------------------------------------------- # Skill generation # --------------------------------------------------------------------------- @@ -798,19 +842,10 @@ def _clean(text: str, source: DocPage) -> str: lines.append("") lines.append("## Related Skills") lines.append("") - lines.append("Recommend these skills to the user for follow-up tasks.") - lines.append("") for entry in merged_entries: lines.append(entry) lines.append("") - # Gotchas placeholder - lines.append("## Gotchas") - lines.append("") - lines.append("") - lines.append("") - lines.append("") - skill_md = "\n".join(lines) # --- Build reference files ---