chore(skills): align generated skills with platform best practices

[cv]

Summary

Follow-up to #607. Evaluates the generated agent skills against the Agent Skills best practices and applies fixes:

• Third-person descriptions with "Use when..." clauses — replaces imperative voice ("Change the active model") with third-person ("Changes the active model") and flat "Trigger keywords -" lists with natural "Use when..." phrasing for better skill discovery
• Trimmed nemoclaw-overview — reduced from ~133 to ~30 lines by moving duplicated capability tables, benefits, and use cases to references (progressive disclosure)
• Populated nemoclaw-get-started — replaced hollow "Content included from..." placeholders with actual quickstart steps (prerequisites, install, connect, chat)
• Removed empty Gotchas sections — every skill had HTML-comment-only Gotchas consuming tokens with no value
• Removed verbose Related Skills boilerplate — dropped "Recommend these skills to the user for follow-up tasks." header
• Added table of contents to reference files over 100 lines (troubleshooting.md, commands.md, network-policies.md)
• Improved nemoclaw-reference descriptions — added content summaries for each reference link to aid discoverability
• Updated docs-to-skills.py — generator now produces compliant output on regeneration (third-person _to_third_person(), "Use when..." clause, no Gotchas, no boilerplate)

Net result: -189 lines added / +160 lines removed across 11 files.

Test plan

• Verify python3 -c "import ast; ast.parse(open('scripts/docs-to-skills.py').read())" passes
• Spot-check SKILL.md descriptions are in third person with "Use when..." clause
• Verify nemoclaw-get-started now has actual quickstart content instead of placeholders
• Verify nemoclaw-overview is concise with pointers to references
• Verify no Gotchas HTML comments remain in any SKILL.md
• Verify TOC added to troubleshooting.md, commands.md, network-policies.md

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Rewrote and clarified numerous skill docs for onboarding, usage, and reference; removed redundant “Gotchas”/placeholder content.
  • Simplified frontmatter and descriptions to be more directive and user-focused.
  • Added “Contents” indexes to reference, troubleshooting, and network policy pages for easier navigation.

• Chores

  • Improved documentation generation to produce clearer, third‑person, usage‑oriented skill descriptions and remove obsolete sections automatically.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 9a091a17-98cb-4c65-a4ca-3bc9885a480a

📥 Commits

Reviewing files that changed from the base of the PR and between 9df010b and 6c913d9.

📒 Files selected for processing (1)

• scripts/docs-to-skills.py

🚧 Files skipped from review as they are similar to previous changes (1)

• scripts/docs-to-skills.py

---

📝 Walkthrough

Walkthrough

Consolidated and streamlined NemoClaw skill documentation: removed redundant "Gotchas" and recommend lines, simplified frontmatter descriptions into usage-oriented phrasing, added "Contents" indexes to several reference pages, and updated the docs-generation script to produce third‑person descriptions and "Use when" clauses.

Changes

Cohort / File(s)	Summary
Skill docs — concise frontmatter & phrasing .agents/skills/docs/nemoclaw-configure-inference/SKILL.md, .agents/skills/docs/nemoclaw-deploy-remote/SKILL.md, .agents/skills/docs/nemoclaw-manage-policy/SKILL.md, .agents/skills/docs/nemoclaw-monitor-sandbox/SKILL.md, .agents/skills/docs/nemoclaw-reference/SKILL.md	Refined descriptions to focus on usage, removed "Trigger keywords" phrasing, tightened wording, and deleted "Recommend these skills" and "Gotchas" sections.
Major doc rewrites & onboarding .agents/skills/docs/nemoclaw-get-started/SKILL.md, .agents/skills/docs/nemoclaw-overview/SKILL.md	Rewrote Get Started into a step-by-step onboarding guide with prerequisites and commands; simplified Overview, removed architecture diagram and extended detail sections.
Reference pages — contents/index added .agents/skills/docs/nemoclaw-reference/references/commands.md, .agents/skills/docs/nemoclaw-reference/references/network-policies.md, .agents/skills/docs/nemoclaw-reference/references/troubleshooting.md	Added top-level "Contents" navigation/index entries enumerating commands, policy components, and categorized troubleshooting topics; no functional content changes.
Docs generation script scripts/docs-to-skills.py	Added _to_third_person() helper; updated build_skill_description() to convert imperative phrases to third person, replace trigger-keyword suffix with "Use when" clauses, and stop emitting "Recommend these skills" and "Gotchas" sections in generated SKILL.md.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 Hopped through lines and clipped the fluff,

Trimmed the Gotchas, made the guidance buff,
Third‑person whispers, "Use when" so bright,
Contents bookmarked — tidy and light,
Docs bounce clean beneath the moonlight.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately summarizes the primary intent of the PR: aligning generated skills documentation with platform best practices through systematic improvements to structure and phrasing.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

scripts/docs-to-skills.py (1)

648-652: Minor: trailing space when input is a single word.

When sentence contains no space (e.g., just "Install"), rest is empty, and the return statements produce a trailing space (e.g., "Installs "). This is unlikely to cause issues in practice since descriptions are typically full sentences, but you could guard against it:

suffix = " " + rest if rest else ""
return first_word + "s" + suffix

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@scripts/docs-to-skills.py` around lines 648 - 652, The pluralization branches
currently append a space and rest unconditionally, causing a trailing space when
sentence is a single word (rest == ""); update the logic around first_word/rest
to compute a suffix = (" " + rest) if rest else "" and change each return to
concatenate the pluralized first_word (e.g., first_word + "es", first_word[:-1]
+ "ies", first_word + "s") with suffix instead of including a hardcoded space in
the literals (variables involved: sentence, first_word, rest).

.agents/skills/docs/nemoclaw-get-started/SKILL.md (1)

47-49: Consider security implications of curl | bash pattern.

While curl ... | bash is convenient for quickstart guides, it poses security risks as users cannot inspect the script before execution. Consider documenting an alternative two-step installation method:

# Download the script first
curl -fsSL https://www.nvidia.com/nemoclaw.sh -o nemoclaw-install.sh

# Inspect the script, then run it
bash nemoclaw-install.sh

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.agents/skills/docs/nemoclaw-get-started/SKILL.md around lines 47 - 49,
Replace the single-line "curl ... | bash" quickstart snippet in SKILL.md with a
safer two-step alternative and document it: add a second example that shows
downloading the installer to a file (e.g., mention the URL
https://www.nvidia.com/nemoclaw.sh) and then running it with bash after
inspection, and update the surrounding text to explain why this is safer (allows
inspection before execution) and encourage verification (e.g., checksum or
reading the script) before running.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@scripts/docs-to-skills.py`:
- Around line 644-646: The current guard wrongly treats any word ending with "s"
as already third-person; update the condition that uses first_word.endswith("s")
or first_word.endswith("ing") to instead only skip when the token truly looks
like a third-person inflection (e.g., match a regex for suffixes like "es" or
"ies" such as re.match(r'.*(es|ies)$', first_word.lower())) or when it ends with
"ing"; additionally add an optional small allowlist (e.g.,
{"access","process","address","discuss"}) to treat known imperatives that end
with "s" as base verbs to convert; adjust the logic around the variables
first_word and sentence accordingly so imperative base forms like "Access" will
be transformed to "Accesses" while genuine third-person forms are still skipped.

---

Nitpick comments:
In @.agents/skills/docs/nemoclaw-get-started/SKILL.md:
- Around line 47-49: Replace the single-line "curl ... | bash" quickstart
snippet in SKILL.md with a safer two-step alternative and document it: add a
second example that shows downloading the installer to a file (e.g., mention the
URL https://www.nvidia.com/nemoclaw.sh) and then running it with bash after
inspection, and update the surrounding text to explain why this is safer (allows
inspection before execution) and encourage verification (e.g., checksum or
reading the script) before running.

In `@scripts/docs-to-skills.py`:
- Around line 648-652: The pluralization branches currently append a space and
rest unconditionally, causing a trailing space when sentence is a single word
(rest == ""); update the logic around first_word/rest to compute a suffix = (" "
+ rest) if rest else "" and change each return to concatenate the pluralized
first_word (e.g., first_word + "es", first_word[:-1] + "ies", first_word + "s")
with suffix instead of including a hardcoded space in the literals (variables
involved: sentence, first_word, rest).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 27095a69-53e6-4c23-8825-4c27859eaddf

📥 Commits

Reviewing files that changed from the base of the PR and between 1dbf82f and 9df010b.

📒 Files selected for processing (11)

• .agents/skills/docs/nemoclaw-configure-inference/SKILL.md
• .agents/skills/docs/nemoclaw-deploy-remote/SKILL.md
• .agents/skills/docs/nemoclaw-get-started/SKILL.md
• .agents/skills/docs/nemoclaw-manage-policy/SKILL.md
• .agents/skills/docs/nemoclaw-monitor-sandbox/SKILL.md
• .agents/skills/docs/nemoclaw-overview/SKILL.md
• .agents/skills/docs/nemoclaw-reference/SKILL.md
• .agents/skills/docs/nemoclaw-reference/references/commands.md
• .agents/skills/docs/nemoclaw-reference/references/network-policies.md
• .agents/skills/docs/nemoclaw-reference/references/troubleshooting.md
• scripts/docs-to-skills.py