feat: create agent skill for nemoclaw CLI usage and multi-step workflows

[johntmyers]

Problem Statement

LLMs do not know how to use the nemoclaw CLI by default. To enable agents to operate NemoClaw effectively — from basic provider management and sandbox creation through complex iterative policy refinement and BYOC workflows — we need a dedicated agent skill that teaches the CLI's command structure, guides multi-step workflows, and provides a fallback self-teaching mechanism via --help.

Additionally, the existing generate-sandbox-policy skill has drifted from the actual policy schema (critical: allowed_routing_hints vs allowed_routes field name mismatch that would cause agent-generated policies to fail parsing). Since the new CLI skill will delegate policy content authoring to generate-sandbox-policy, that skill must be fixed as part of this work.

Technical Context

The nemoclaw CLI (crates/navigator-cli) is a comprehensive tool with 30+ commands across 7 command groups (cluster, sandbox, provider, inference, policy, image, forward). The codebase already has 12 agent skills in .agents/skills/ following a well-established pattern: YAML frontmatter, numbered workflow steps, command reference tables, and concrete example scenarios. The new skill needs to cover basic CRUD operations, but more importantly, it must guide agents through multi-step workflows that involve coordinating across command groups (e.g., create providers → create sandbox with policy → monitor logs → pull policy → edit → push → verify reload).

The generate-sandbox-policy skill is a companion to the new CLI skill — the CLI skill handles command orchestration while generate-sandbox-policy handles policy content authoring. The CLI skill should cross-reference it at handoff points rather than duplicating policy semantics.

Affected Components

Component	Key Files	Role
New CLI skill	.agents/skills/nemoclaw-cli/SKILL.md (to create)	CLI workflow guidance for agents
Policy generation skill	.agents/skills/generate-sandbox-policy/SKILL.md, examples.md	Companion skill — needs schema drift fixes
Architecture docs	architecture/security-policy.md	Has same allowed_routing_hints error — fix alongside
Navigator CLI	crates/navigator-cli/src/main.rs, run.rs, ssh.rs	CLI command definitions (reference for skill content)
Policy system	crates/navigator-policy/src/lib.rs, dev-sandbox-policy.yaml	Authoritative schema (source of truth for fixes)

Proposed Approach

Part 1: Fix generate-sandbox-policy schema drift

• Fix allowed_routing_hints → allowed_routes in SKILL.md, examples.md, and architecture/security-policy.md
• Reconcile default read_only paths (decide whether skill should match dev-sandbox-policy.yaml or keep tighter defaults with a note)

Part 2: Create nemoclaw-cli agent skill

• Follow the multi-step workflow archetype (like build-from-issue and generate-sandbox-policy)
• Organize into tiered workflows: basic operations → intermediate → advanced multi-step
• Cross-reference generate-sandbox-policy at policy content handoff points
• Include --help fallback mechanism for self-teaching
• Consider supplementary reference file for full command tree

Key workflows to document:

1. Provider management (CRUD, auto-creation from local credentials)
2. Sandbox lifecycle (create, connect, sync, logs, delete)
3. Policy iteration loop (logs → pull policy → delegate to generate-sandbox-policy → push → verify reload)
4. BYOC pipeline (build image → push → create sandbox → port forward)
5. Agent-assisted sandbox session (parallel monitoring + policy refinement)

Scope Assessment

• Complexity: Medium — substantial content but follows established patterns; mostly documentation with a critical bug fix
• Confidence: High — 12 existing skills provide a proven template, CLI structure is well-defined, schema drift is clearly identified
• Estimated files to change: 4-6 (new SKILL.md + optional reference.md, fix SKILL.md + examples.md in generate-sandbox-policy, fix security-policy.md)
• Issue type: feat

Risks & Open Questions

• Skill length vs. context window: A comprehensive skill covering all workflows could be 600-800+ lines. Consider splitting into core SKILL.md with supplementary reference files.
• Trigger keyword collision: Need keywords that activate for CLI usage without colliding with generate-sandbox-policy (which triggers on policy generation/authoring).
• Provider auto-creation shortcut: Should the skill teach ncl sandbox create -- claude (auto-creates providers) or always use explicit provider management? Probably both, with the shortcut as the quick-start path.
• Dynamic vs static policy fields: Agents must understand which policy fields can be hot-reloaded (network_policies, inference) and which require sandbox recreation (filesystem_policy, landlock, process). Getting this wrong leads to confusing errors.
• read_only defaults decision: Should the generate-sandbox-policy skill match the actual reference file (/proc + /var/log) or keep its tighter defaults (/proc/self, no /var/log) with an explicit note?

Test Considerations

• Manual validation: have an agent use both skills to execute each documented workflow end-to-end
• Verify the --help fallback works for commands deliberately omitted from the skill
• Test that trigger keywords activate the correct skill and don't conflict
• Validate the policy iteration loop end-to-end: create sandbox → observe logs → pull policy → modify (via generate-sandbox-policy) → push → verify reload
• Verify the allowed_routes fix by generating a policy with inference config and confirming it parses

---

Created by spike investigation. Use build-from-issue to plan and implement.

[johntmyers]

🔬 spike-agent

Technical Investigation

Architecture Overview

The nemoclaw CLI is a Rust binary (crates/navigator-cli) built with clap-derive, containing 30+ commands across 7 command groups. It communicates with the NemoClaw gateway over gRPC (with mTLS) and provides SSH-based sandbox connectivity. The CLI manages client-side state under ~/.config/nemoclaw/ (cluster metadata, mTLS certs, active cluster, port forward PIDs).

Agent skills are convention-based at .agents/skills/<name>/SKILL.md — no registry file, just directory scanning. Each has YAML frontmatter with name and description (including trigger keywords), followed by structured workflow documentation. Complex workflow skills (like build-from-issue at 712 lines and generate-sandbox-policy at 549 lines) use numbered steps, ASCII decision trees, command reference tables, and concrete example scenarios.

Key design constraint: The generate-sandbox-policy skill already exists and handles all policy YAML semantics — schema structure, L4/L7 rule authoring, endpoint definitions, preset-based generation, and API doc translation. The new nemoclaw CLI skill should not duplicate policy content authoring. Instead, it should cover the CLI commands for the policy lifecycle (get/set/list, logs for observing activity) and cross-reference generate-sandbox-policy when the agent needs to create or modify policy YAML content.

Code References

Location	Description
crates/navigator-cli/src/main.rs:1-170	All clap derive structs defining the complete command tree
crates/navigator-cli/src/main.rs:236-261	CliProviderType enum — supported provider types: claude, opencode, codex, generic, nvidia, gitlab, github, outlook
crates/navigator-cli/src/main.rs:350-370	ClusterCommands — cluster status/use/list/admin subcommands
crates/navigator-cli/src/main.rs:474-637	SandboxCommands — create/get/list/delete/connect/sync/logs/ssh-config/forward/image/policy
crates/navigator-cli/src/main.rs:639-682	PolicyCommands — set/get/list for sandbox policies
crates/navigator-cli/src/main.rs:684-712	ForwardCommands — start/stop/list port forwards
crates/navigator-cli/src/main.rs:714-734	SandboxImageCommands — image push for BYOC
crates/navigator-cli/src/main.rs:736-797	InferenceCommands — create/update/delete/list inference routes
crates/navigator-cli/src/run.rs:1000-1283	sandbox_create() — full creation flow including auto-bootstrap, provider resolution, policy loading, watch-for-ready, sync, forward, connect/exec
crates/navigator-cli/src/run.rs:1834-1989	ensure_required_providers() — auto-creates providers from local credentials for known tools
crates/navigator-cli/src/run.rs:2753-2865	sandbox_policy_set() — policy update with no-op detection, --wait polling loop
crates/navigator-cli/src/run.rs:2867-2918	sandbox_policy_get() — fetch policy with --full YAML round-trip output
crates/navigator-cli/src/run.rs:2976-3107	sandbox_logs() — log retrieval with streaming, source/level filtering
crates/navigator-cli/src/run.rs:1711-1816	sandbox_image_push() — Docker build + containerd import for BYOC
crates/navigator-cli/src/ssh.rs:110-143	sandbox_connect() — SSH session creation and ProxyCommand setup
crates/navigator-cli/src/ssh.rs:150-199	sandbox_forward_start() — SSH tunnel port forwarding
crates/navigator-cli/src/ssh.rs:328-473	sandbox_sync_upload/download() — tar-over-SSH file transfer
crates/navigator-cli/src/bootstrap.rs:29-96	Auto-bootstrap detection and interactive cluster provisioning
crates/navigator-policy/src/lib.rs:214-241	parse_sandbox_policy() — YAML parsing to proto structs
dev-sandbox-policy.yaml	Reference policy file (167 lines) — complete real-world example
.agents/skills/generate-sandbox-policy/SKILL.md	Existing skill for policy YAML authoring — companion to the new skill
architecture/security-policy.md:102-141	Policy update validation rules (static vs dynamic fields)
architecture/security-policy.md:170-194	Policy reload mechanism (30s poll, atomic swap, last-known-good)
architecture/sandbox-custom-containers.md	BYOC architecture — supervisor bootstrap, init container, limitations
architecture/sandbox-connect.md:86-121	SSH connectivity architecture

Complete Command Tree

nemoclaw (ncl)
  ├── cluster
  │   ├── status                    # Show server status & version
  │   ├── use <name>                # Set active cluster
  │   ├── list                      # List all clusters
  │   └── admin
  │       ├── deploy [opts]         # Provision/start cluster (local or remote)
  │       ├── stop [opts]           # Stop cluster (preserves state)
  │       ├── destroy [opts]        # Destroy cluster and all state
  │       ├── info [--name]         # Show deployment details
  │       └── tunnel [opts]         # SSH tunnel for kubectl access
  ├── sandbox
  │   ├── create [opts] [-- CMD]    # Create sandbox, wait, connect/exec
  │   ├── get <name>                # Show sandbox details
  │   ├── list [opts]               # List sandboxes
  │   ├── delete <name>...          # Delete sandboxes
  │   ├── connect <name>            # Interactive SSH shell
  │   ├── sync <name> --up/--down   # File sync via tar-over-SSH
  │   ├── logs <name> [opts]        # View/stream sandbox logs
  │   ├── ssh-config <name>         # Print SSH config block
  │   ├── forward
  │   │   ├── start <port> <name>   # Start SSH port forward
  │   │   ├── stop <port> <name>    # Stop port forward
  │   │   └── list                  # List active forwards
  │   ├── image
  │   │   └── push [opts]           # Build & push custom image
  │   └── policy
  │       ├── set <name> --policy   # Hot-reload policy on live sandbox
  │       ├── get <name> [--full]   # Fetch current policy (as YAML)
  │       └── list <name>           # Policy revision history
  ├── provider
  │   ├── create --name --type      # Create provider config
  │   ├── get <name>                # Show provider details
  │   ├── list                      # List providers
  │   ├── update <name>             # Update provider
  │   └── delete <name>...          # Delete providers
  ├── inference
  │   ├── create [opts]             # Create inference route
  │   ├── update <name> [opts]      # Update inference route
  │   ├── delete <name>...          # Delete inference routes
  │   └── list                      # List inference routes
  ├── gator                         # Launch interactive TUI
  ├── completions <shell>           # Generate shell completions
  └── ssh-proxy [opts]              # Internal SSH ProxyCommand

Workflow Analysis

The skill needs to guide agents through these workflows, ordered by complexity:

Tier 1: Basic Operations

• Provider CRUD: Create providers from local credentials (--from-existing) or explicit credentials. List, update, delete.
• Simple sandbox: ncl sandbox create with defaults (auto-bootstraps cluster, auto-creates providers for known tools).
• Sandbox lifecycle: List, get details, connect, delete.

Tier 2: Intermediate Operations

• Custom policy sandbox: Create with --policy flag pointing to a YAML file.
• File sync: Push local files into sandbox (--sync at creation, or ncl sandbox sync --up later).
• Port forwarding: Forward local ports to sandbox services (--forward at creation, or ncl sandbox forward start later).
• Inference routing: Create routes for model endpoints with auto-protocol detection.

Tier 3: Advanced Multi-Step Workflows

Policy iteration loop (the most critical workflow):

1. Create sandbox with initial policy
2. User works in sandbox (separate shell via ncl sandbox connect)
3. Agent monitors logs: ncl sandbox logs <name> --tail --source sandbox
4. Agent observes denied actions in logs
5. Agent pulls current policy: ncl sandbox policy get <name> --full > policy.yaml
6. Agent modifies policy YAML — delegates to generate-sandbox-policy skill for content authoring
7. Agent pushes updated policy: ncl sandbox policy set <name> --policy policy.yaml --wait
8. Agent verifies reload: ncl sandbox policy list <name> (check status = loaded)
9. Repeat steps 3-8

Key constraint: Only network_policies and inference sections are hot-reloadable. filesystem_policy, landlock, and process sections are immutable after creation. The agent must understand this boundary.

BYOC pipeline:

1. Write/modify Dockerfile
2. Build and push: ncl sandbox image push --dockerfile ./Dockerfile --tag my-app:latest
3. Create sandbox with custom image: ncl sandbox create --image my-app:latest --keep
4. Optionally forward ports: ncl sandbox forward start 8080 <name> -d
5. Connect or exec commands as needed
6. Iterate: modify code → rebuild → push → recreate sandbox

Agent-assisted sandbox session:

1. Create sandbox with providers and policy: ncl sandbox create --provider github --policy dev.yaml --keep -- claude
2. In parallel, agent monitors: ncl sandbox logs <name> --tail
3. Agent observes issues, pulls policy, suggests changes
4. Agent applies changes, verifies
5. User continues working with updated permissions

Skill Design Recommendations

Structure: Follow the multi-step workflow archetype (like build-from-issue). Organize into:

1. Overview + command tree quick reference
2. Prerequisites (cluster deployed, ncl on PATH)
3. Tiered workflows (basic → intermediate → advanced)
4. The --help self-teaching fallback section
5. Cross-references to companion skills

Companion skill delegation:

• Policy YAML content authoring → generate-sandbox-policy skill
• The nemoclaw skill covers: which CLI commands to run, in what order, with what flags, and how to interpret output
• Clear handoff points: "To create or modify the policy YAML content, use the generate-sandbox-policy skill. Once you have the YAML file, return here to push it to the sandbox."

--help fallback mechanism:

# Discover top-level commands
ncl --help

# Discover subcommands
ncl sandbox --help
ncl sandbox policy --help

# Discover flags for a specific command
ncl sandbox create --help

The skill should instruct the agent: "If you encounter a command or option not documented in this skill, walk the --help tree to discover it. Start from the relevant command group and drill down."

Supplementary files: Consider a reference.md with the full command tree and all flags, keeping SKILL.md focused on workflows. This mirrors how generate-sandbox-policy uses examples.md.

Patterns to Follow

The existing skill pattern is well-established:

1. YAML frontmatter with name and description (including trigger keywords)
2. ASCII workflow overview for complex multi-step flows
3. Numbered steps with concrete bash commands in fenced blocks
4. Decision points with explicit branching ("If X, do Y")
5. Cross-skill references ("use generate-sandbox-policy for policy content")
6. Useful Commands Reference table at the end
7. Example Usage section with 2-5 concrete scenarios

Trigger keywords should be chosen to avoid collision with generate-sandbox-policy. Suggested: nemoclaw, ncl, sandbox create, sandbox connect, sandbox logs, provider create, policy set, policy get, image push, port forward, BYOC, bring your own container, use nemoclaw, run nemoclaw, CLI usage.

Test Coverage Notes

• No automated tests exist for skills — they are documentation files
• Validation is manual: have an agent execute each workflow end-to-end
• Key test scenarios:
  1. Basic: create provider → create sandbox → connect → delete
  2. Policy iteration: create → logs → pull policy → modify → push → verify
  3. BYOC: build image → push → create sandbox with image → forward port
  4. Fallback: agent encounters undocumented command, uses --help to self-teach
  5. Cross-skill: agent transitions from nemoclaw CLI skill to generate-sandbox-policy and back

---

This investigation provides context for implementation. Next step: review the issue, refine if needed, then use build-from-issue to create a plan and implement.

[johntmyers]

🔬 spike-agent

Companion Task: Update generate-sandbox-policy Skill for Schema Drift

Investigation uncovered that the generate-sandbox-policy skill has drifted from the actual policy schema. This must be fixed as a prerequisite or parallel task, since the new nemoclaw CLI skill will delegate policy content authoring to it.

Critical Fix: inference Field Name

The skill documents allowed_routing_hints but the actual code expects allowed_routes. This is a breaking error — any agent-generated policy with inference config would fail YAML parsing due to deny_unknown_fields on the serde struct.

Source	Field Name Used
Proto (sandbox.proto)	allowed_routes
Rust serde (navigator-policy/src/lib.rs)	allowed_routes
Actual YAML (dev-sandbox-policy.yaml)	allowed_routes
OPA conversion (opa.rs)	allowed_routes
security-policy.md (architecture doc)	allowed_routing_hints (WRONG)
Skill SKILL.md line 414-416	allowed_routing_hints (WRONG)
Skill examples.md line 870	allowed_routing_hints (WRONG)

Files to fix:

1. .agents/skills/generate-sandbox-policy/SKILL.md — change allowed_routing_hints → allowed_routes
2. .agents/skills/generate-sandbox-policy/examples.md — change allowed_routing_hints → allowed_routes
3. architecture/security-policy.md — change allowed_routing_hints → allowed_routes (the architecture doc has the same error, which is likely where the skill picked it up from)

Minor: Default read_only Paths Differ

The skill's "Create New File" template uses /proc/self and omits /var/log, while the actual dev-sandbox-policy.yaml uses /proc (broader) and includes /var/log. Decide whether to:

• Update the skill to match the reference file, or
• Keep the tighter defaults and add a note explaining the intentional difference

Affected locations:

• .agents/skills/generate-sandbox-policy/SKILL.md line 391-397
• .agents/skills/generate-sandbox-policy/examples.md line 823-831

Low Priority: InferenceApiPattern (proto-only)

The proto defines InferenceApiPattern with method, path_glob, protocol, and kind fields on InferencePolicy.api_patterns, but this is not exposed in the YAML parsing path (the Rust InferenceDef struct doesn't include it). No action needed for the skill — just noting for awareness.

Overall Assessment

The skill is ~97% accurate. The allowed_routes fix is the only critical item. Everything else — network policy structure, endpoint fields, L7 rules, access presets, validation rules, enforcement modes, TLS behavior, binary matching, private IP handling — is correct and up-to-date.

[johntmyers]

🔬 spike-agent

Design Decisions (from review)

read_only defaults: Update generate-sandbox-policy to match dev-sandbox-policy.yaml — use /proc (not /proc/self) and include /var/log. These are good defaults.

Supplementary reference file: Yes, include one for quick-reference of common commands. But the skill's primary self-sufficiency mechanism is --help navigation — the agent should always be able to walk ncl --help → ncl <group> --help → ncl <group> <cmd> --help to discover commands and flags. The reference file is an optimization to reduce round-trips, not a replacement for CLI self-teaching. This makes the skill resilient to CLI evolution without constant updates.

[johntmyers]

🏗️ build-plan

Implementation Plan

Issue type: feat
Complexity: Medium
Confidence: High — clear path, established patterns, mechanical fixes + content authoring

Summary

Fix the generate-sandbox-policy skill's schema drift (critical allowed_routing_hints → allowed_routes rename + default path reconciliation) across 3 files (7 occurrences of the field name, 2 occurrences of /proc/self). Then create a new nemoclaw-cli agent skill with a SKILL.md (workflow guidance) and cli-reference.md (full command tree), following established skill patterns. The new skill cross-references generate-sandbox-policy for policy content authoring.

Scope

• .agents/skills/generate-sandbox-policy/SKILL.md: Fix allowed_routing_hints → allowed_routes (line 414), fix /proc/self → /proc + add /var/log (line 394)
• .agents/skills/generate-sandbox-policy/examples.md: Fix allowed_routing_hints → allowed_routes (line 870), fix /proc/self → /proc + add /var/log (line 828)
• architecture/security-policy.md: Fix allowed_routing_hints → allowed_routes (lines 289, 475, 479, 990, 1019 — 5 occurrences; line 1019 is the proto-to-YAML mapping table where the proto column should stay as the proto field name but the YAML column must change)
• .agents/skills/nemoclaw-cli/SKILL.md (new): Main skill file with workflow guidance
• .agents/skills/nemoclaw-cli/cli-reference.md (new): Supplementary command reference

Implementation Steps

Step 1: Fix generate-sandbox-policy/SKILL.md

• Replace allowed_routing_hints → allowed_routes at line 414
• Replace /proc/self → /proc at line 394, add /var/log to the read_only list

Step 2: Fix generate-sandbox-policy/examples.md

• Replace allowed_routing_hints → allowed_routes at line 870
• Replace /proc/self → /proc at line 828, add /var/log to the read_only list

Step 3: Fix architecture/security-policy.md

• Replace allowed_routing_hints → allowed_routes at lines 289, 475, 479, 990
• Line 1019 (proto-to-YAML mapping table): update the YAML column from inference.allowed_routing_hints to inference.allowed_routes; keep the proto column as allowed_routing_hints since that's the actual proto field name

Step 4: Create .agents/skills/nemoclaw-cli/cli-reference.md
Supplementary reference file with the full command tree and flag details. Structure:

• Complete command tree (ASCII art)
• Per-group command tables with flags/descriptions
• Environment variables reference
• Global options

Step 5: Create .agents/skills/nemoclaw-cli/SKILL.md
Main skill file. Structure:

1. YAML frontmatter (name: nemoclaw-cli, description with trigger keywords)
2. H1 title + one-line summary
3. Overview: what nemoclaw is, skill's relationship to generate-sandbox-policy
4. Prerequisites
5. --help Self-Teaching (the fallback mechanism — how to walk the help tree)
6. Workflow 1: Getting Started (cluster bootstrap, first sandbox)
7. Workflow 2: Provider Management (CRUD, auto-creation)
8. Workflow 3: Sandbox Lifecycle (create, connect, sync, logs, delete)
9. Workflow 4: Policy Iteration Loop (the tight feedback cycle — logs → pull → delegate to generate-sandbox-policy → push → verify)
10. Workflow 5: BYOC Pipeline (build image → push → create sandbox → port forward)
11. Workflow 6: Agent-Assisted Sandbox Session (parallel monitoring + policy refinement while user works)
12. Workflow 7: Inference Routing (create/manage inference routes)
13. Quick Reference table
14. Cross-references to companion skills

Step 6: Run pre-commit checks

Test Plan

• Unit tests: N/A — all changes are Markdown documentation/skill files
• Integration tests: N/A
• E2E tests: N/A
• Manual validation: Verify the allowed_routes fix matches dev-sandbox-policy.yaml; verify the new skill's command references match ncl --help output

Risks & Open Questions

• Skill length: The SKILL.md will likely be 500-700 lines. The cli-reference.md offloads the full command tree details, keeping the main file focused on workflows. This is consistent with how generate-sandbox-policy uses examples.md.
• Trigger keywords: Proposed: nemoclaw, ncl, sandbox create, sandbox connect, sandbox logs, provider create, policy set, policy get, image push, port forward, BYOC, CLI usage, use nemoclaw. These should not collide with generate-sandbox-policy which triggers on policy generation/authoring.
• Proto field name on line 1019: The proto column in the mapping table should keep allowed_routing_hints since that's the actual proto field name — only the YAML mapping column changes to allowed_routes.

Documentation Impact

• architecture/security-policy.md: Fixed as part of the schema drift repair (Step 3)
• No other architecture docs need updating — this issue creates agent skills, not code changes

---

Revision 1 — initial plan

[johntmyers]

🏗️ build-from-issue-agent

Implementation Complete

PR: #85

What was built

Created the nemoclaw-cli agent skill with 8 tiered workflows (getting started through cluster management), a supplementary CLI reference file, and --help self-teaching as the primary fallback mechanism. Fixed critical schema drift in generate-sandbox-policy (allowed_routing_hints → allowed_routes) and updated default read_only paths to match dev-sandbox-policy.yaml.

Tests

• Unit: N/A (documentation-only changes)
• Integration: N/A
• E2E: N/A

Docs updated

• architecture/security-policy.md — fixed allowed_routing_hints → allowed_routes (5 occurrences)

The issue will auto-close when the PR is merged.