docs(skills): refactor d2s script (#4549)

<!-- markdownlint-disable MD041 -->
## Summary

Refactors `scripts/docs-to-skills.py` to a simpler two-strategy
generator (`grouped` and `individual`) and regenerates
`.agents/skills/nemoclaw-user-*` output to match. The old `smart`
strategy, 11,500-character spill logic, and `*-details.md` deferral
files are removed; sibling pages now land in `references/` unchanged,
and procedure pages inline in full when they lead a group.

## Related Issue

None.

## Changes

**Generator (`scripts/docs-to-skills.py`)**
- Replace `smart` default with `grouped` (directory groups) and keep
`individual` (one skill per procedure page; concept/reference buckets).
- **Grouped lead selection:** highest-priority procedure page (`how_to`,
`get_started`, or `tutorial`) becomes `SKILL.md` body; all siblings go
to `references/`.
- **Reference-only hubs:** groups with no procedure page (for example
`overview`, `reference`, `configure-security`) emit a thin `SKILL.md`
with frontmatter + `## References` only; full content stays in
`references/`.
- Remove `MAX_SKILL_MD_CHARS`, section splitting/deferral, and generated
`*-details.md` spill files.
- Fix skill description ordering to follow the partitioned lead page.
- Fix markdownlint MD012 in generated hub skills
(`collapse_consecutive_blank_lines`, `append_markdown_section`).

**Docs source tweaks**
- `docs/about/overview.mdx`: add `skill.priority: 10` for overview
ordering in generated metadata.
- `docs/resources/agent-skills.mdx`: set `content.type` to `how_to` so
the single-page group inlines correctly.

**Regenerated user skills**
- Inline full procedure content where it leads: `get-started`
(quickstart + provider options), `configure-inference`, `manage-policy`,
`manage-sandboxes`, `deploy-remote`, `monitor-sandbox`, `agent-skills`.
- Convert heavy groups to reference hubs: `overview`, `reference`,
`configure-security`.
- Delete obsolete spill files: `quickstart-details.md`,
`use-local-inference-details.md`, `customize-network-policy-details.md`,
`lifecycle-details.md`, `agent-skills.md`.

**Docs pipeline docs**
- Update `docs/CONTRIBUTING.md` grouped-strategy description.

## Type of Change

- [ ] Code change (feature, bug fix, or refactor)
- [x] Code change with doc updates
- [ ] Doc only (prose changes, no code sample modifications)
- [ ] Doc only (includes code sample changes)

## Design notes (reviewer follow-ups)

- **Reference-only hub skills are intentional.** Concept/reference
directory groups defer all page bodies to `references/` so agents load
detail on demand (progressive disclosure). Routing text lives in
`SKILL.md` frontmatter + References bullets; full task coverage remains
in sibling reference files.
- **`resolve_includes()` path containment** is pre-existing MyST-only
behavior; this PR does not expand its surface. Follow-up hardening can
be a separate change if we want docs-root allowlisting.

## Verification

- [x] `npx prek run --all-files` passes (via CI `checks`)
- [x] `npm test` passes (via CI `unit-vitest-linux`)
- [ ] Tests added or updated for new or changed behavior
- [x] No secrets, API keys, or credentials committed
- [x] Docs updated for user-facing behavior changes
- [x] `npm run docs` builds without warnings (doc changes only; Fern
preview posted)
- [x] Doc pages follow the [style
guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md)
(doc changes only)
- [ ] New doc pages include SPDX header and frontmatter (new pages only)

**Local commands run:**
```bash
python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --doc-platform fern-mdx --dry-run
python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --doc-platform fern-mdx
```

---
Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>

Author: miyoungc

.agents/skills/nemoclaw-user-agent-skills/SKILL.md

@@ -9,6 +9,84 @@ license: "Apache-2.0"
 
 # NemoClaw Agent Skills for Your AI Coding Assistant
 
-## References
+NemoClaw ships agent skills that are generated directly from this documentation.
+Each skill is a converted version of one or more doc pages, structured so AI coding assistants can consume it as context.
+This means you can interact with the full NemoClaw documentation as skills inside your agent chat session, instead of reading the docs separately.
 
-- **Load [references/agent-skills.md](references/agent-skills.md)** when users ask about AI agent support, coding assistant integration, or the .agents/skills/ directory. Describes the agent skills shipped with NemoClaw and how to access them by cloning the repository.
+Ask your assistant a question about NemoClaw and it responds with the same guidance found in these docs, adapted to your current situation.
+Skills cover installation, inference configuration, network policy management, monitoring, deployment, security, workspace management, and the CLI reference.
+
+**Note:**
+
+If you are a contributor and have cloned the full NemoClaw repository, the full set of skills including contributor and maintainer skills are already available at the project root.
+Open the `NemoClaw` directory in your coding assistant and the skills load automatically.
+This page is for users who installed NemoClaw with the installer and do not have a local clone.
+
+## Get the Skills
+
+Fetch only the skills from the NemoClaw repository without downloading the full source tree.
+
+```console
+$ git clone --filter=blob:none --no-checkout https://github.com/NVIDIA/NemoClaw.git
+$ cd NemoClaw
+$ git sparse-checkout set --no-cone '/.agents/skills/nemoclaw-user-*/**' '/.agents/skills/nemoclaw-skills-guide/**' '/.claude/**' '/AGENTS.md' '/CLAUDE.md'
+$ git checkout
+```
+
+Open the `NemoClaw` directory in your AI coding assistant.
+The assistant discovers the skills in `.agents/skills/` and uses them to answer NemoClaw questions with project-specific guidance.
+
+You can keep the skills inside the cloned directory or copy `.agents/skills/` to a global location (such as `~/.cursor/skills/` or `~/.claude/skills/`) so they are available across all your projects.
+The choice depends on whether you want NemoClaw skills scoped to one workspace or accessible everywhere.
+
+## Update the Skills
+
+The sparse checkout filter is saved, so `git pull` fetches only updated skills without downloading the full source tree.
+Run `git pull` after each NemoClaw release to pick up new and updated skills.
+
+## Available Skills
+
+The following user skills ship with NemoClaw.
+
+| Skill | Summary |
+|-------|---------|
+| `nemoclaw-user-overview` | What NemoClaw is, ecosystem placement (OpenClaw + OpenShell + NemoClaw), how it works internally, and release notes. |
+| `nemoclaw-user-get-started` | Install NemoClaw, launch a sandbox, and run the first agent prompt. |
+| `nemoclaw-user-configure-inference` | Choose inference providers during onboarding, switch models without restarting, and set up local inference servers (Ollama, vLLM, TensorRT-LLM, NIM). |
+| `nemoclaw-user-manage-policy` | Approve or deny blocked egress requests in the TUI and customize the sandbox network policy (add, remove, or modify allowed endpoints). |
+| `nemoclaw-user-monitor-sandbox` | Check sandbox health, read logs, and trace agent behavior to diagnose problems. |
+| `nemoclaw-user-deploy-remote` | Deploy NemoClaw to a remote GPU instance, set up the Telegram bridge, and review sandbox container hardening. |
+| `nemoclaw-user-configure-security` | Review the risk framework for every configurable security control, understand credential storage, and assess posture trade-offs. |
+| `nemoclaw-user-manage-sandboxes` | Manage day-two sandbox operations, including status, logs, diagnostics, rebuilds, upgrades, messaging channels, workspace files, backup, and restore. |
+| `nemoclaw-user-reference` | CLI command reference, plugin and blueprint architecture, baseline network policies, and troubleshooting guide. |
+
+## Example Questions and Triggered Skills
+
+After opening the cloned repository in your coding assistant, ask a NemoClaw question in natural language.
+The assistant matches your question to the relevant skill and follows the guidance it contains.
+
+Examples of questions your assistant can answer with these skills:
+
+| Question | Skill triggered |
+|----------|-----------------|
+| "How do I install NemoClaw?" | `nemoclaw-user-get-started` |
+| "Switch my inference provider to Ollama." | `nemoclaw-user-configure-inference` |
+| "A network request was blocked. How do I approve it?" | `nemoclaw-user-manage-policy` |
+| "Show me the sandbox logs." | `nemoclaw-user-monitor-sandbox` |
+| "How do I deploy NemoClaw to a remote GPU?" | `nemoclaw-user-deploy-remote` |
+| "What security controls can I configure?" | `nemoclaw-user-configure-security` |
+| "Back up my agent workspace files." | `nemoclaw-user-manage-sandboxes` |
+| "What CLI commands are available?" | `nemoclaw-user-reference` |
+
+You can also reference a skill directly by name if you know which one you need.
+
+## AI Coding Assistants that You Can Use with NemoClaw Skills
+
+The NemoClaw agent skills follow the [Agent Skills best practices](https://agentskills.io/skill-creation/best-practices) and the [Claude Skills best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices).
+The following table shows how each AI coding assistant can use the NemoClaw skills.
+
+| Assistant | Skill discovery |
+|-----------|----------------|
+| Cursor | Reads `AGENTS.md` at the project root, which references `.agents/skills/`. |
+| Claude Code | Follows the `.claude/skills/` symlink, which points to `.agents/skills/`. |
+| Other assistants | Point the assistant to `.agents/skills/` if it supports project-level skill loading. |