Repository navigation
feat: create agent skill for nemoclaw CLI usage and multi-step workflows #83
Description
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_routesin SKILL.md, examples.md, andarchitecture/security-policy.md - Reconcile default
read_onlypaths (decide whether skill should matchdev-sandbox-policy.yamlor keep tighter defaults with a note)
Part 2: Create nemoclaw-cli agent skill
- Follow the multi-step workflow archetype (like
build-from-issueandgenerate-sandbox-policy) - Organize into tiered workflows: basic operations → intermediate → advanced multi-step
- Cross-reference
generate-sandbox-policyat policy content handoff points - Include
--helpfallback mechanism for self-teaching - Consider supplementary reference file for full command tree
Key workflows to document:
- Provider management (CRUD, auto-creation from local credentials)
- Sandbox lifecycle (create, connect, sync, logs, delete)
- Policy iteration loop (logs → pull policy → delegate to generate-sandbox-policy → push → verify reload)
- BYOC pipeline (build image → push → create sandbox → port forward)
- 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_onlydefaults decision: Should thegenerate-sandbox-policyskill 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
--helpfallback 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_routesfix by generating a policy with inference config and confirming it parses
Created by spike investigation. Use build-from-issue to plan and implement.
Activity
johntmyers commentedon Mar 4, 2026
Technical Investigation
Architecture Overview
The
nemoclawCLI 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 withnameanddescription(including trigger keywords), followed by structured workflow documentation. Complex workflow skills (likebuild-from-issueat 712 lines andgenerate-sandbox-policyat 549 lines) use numbered steps, ASCII decision trees, command reference tables, and concrete example scenarios.Key design constraint: The
generate-sandbox-policyskill 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-referencegenerate-sandbox-policywhen the agent needs to create or modify policy YAML content.Code References
crates/navigator-cli/src/main.rs:1-170crates/navigator-cli/src/main.rs:236-261CliProviderTypeenum — supported provider types: claude, opencode, codex, generic, nvidia, gitlab, github, outlookcrates/navigator-cli/src/main.rs:350-370ClusterCommands— cluster status/use/list/admin subcommandscrates/navigator-cli/src/main.rs:474-637SandboxCommands— create/get/list/delete/connect/sync/logs/ssh-config/forward/image/policycrates/navigator-cli/src/main.rs:639-682PolicyCommands— set/get/list for sandbox policiescrates/navigator-cli/src/main.rs:684-712ForwardCommands— start/stop/list port forwardscrates/navigator-cli/src/main.rs:714-734SandboxImageCommands— image push for BYOCcrates/navigator-cli/src/main.rs:736-797InferenceCommands— create/update/delete/list inference routescrates/navigator-cli/src/run.rs:1000-1283sandbox_create()— full creation flow including auto-bootstrap, provider resolution, policy loading, watch-for-ready, sync, forward, connect/execcrates/navigator-cli/src/run.rs:1834-1989ensure_required_providers()— auto-creates providers from local credentials for known toolscrates/navigator-cli/src/run.rs:2753-2865sandbox_policy_set()— policy update with no-op detection,--waitpolling loopcrates/navigator-cli/src/run.rs:2867-2918sandbox_policy_get()— fetch policy with--fullYAML round-trip outputcrates/navigator-cli/src/run.rs:2976-3107sandbox_logs()— log retrieval with streaming, source/level filteringcrates/navigator-cli/src/run.rs:1711-1816sandbox_image_push()— Docker build + containerd import for BYOCcrates/navigator-cli/src/ssh.rs:110-143sandbox_connect()— SSH session creation and ProxyCommand setupcrates/navigator-cli/src/ssh.rs:150-199sandbox_forward_start()— SSH tunnel port forwardingcrates/navigator-cli/src/ssh.rs:328-473sandbox_sync_upload/download()— tar-over-SSH file transfercrates/navigator-cli/src/bootstrap.rs:29-96crates/navigator-policy/src/lib.rs:214-241parse_sandbox_policy()— YAML parsing to proto structsdev-sandbox-policy.yaml.agents/skills/generate-sandbox-policy/SKILL.mdarchitecture/security-policy.md:102-141architecture/security-policy.md:170-194architecture/sandbox-custom-containers.mdarchitecture/sandbox-connect.md:86-121Complete Command Tree
Workflow Analysis
The skill needs to guide agents through these workflows, ordered by complexity:
Tier 1: Basic Operations
--from-existing) or explicit credentials. List, update, delete.ncl sandbox createwith defaults (auto-bootstraps cluster, auto-creates providers for known tools).Tier 2: Intermediate Operations
--policyflag pointing to a YAML file.--syncat creation, orncl sandbox sync --uplater).--forwardat creation, orncl sandbox forward startlater).Tier 3: Advanced Multi-Step Workflows
Policy iteration loop (the most critical workflow):
ncl sandbox connect)ncl sandbox logs <name> --tail --source sandboxncl sandbox policy get <name> --full > policy.yamlgenerate-sandbox-policyskill for content authoringncl sandbox policy set <name> --policy policy.yaml --waitncl sandbox policy list <name>(check status =loaded)Key constraint: Only
network_policiesandinferencesections are hot-reloadable.filesystem_policy,landlock, andprocesssections are immutable after creation. The agent must understand this boundary.BYOC pipeline:
ncl sandbox image push --dockerfile ./Dockerfile --tag my-app:latestncl sandbox create --image my-app:latest --keepncl sandbox forward start 8080 <name> -dAgent-assisted sandbox session:
ncl sandbox create --provider github --policy dev.yaml --keep -- claudencl sandbox logs <name> --tailSkill Design Recommendations
Structure: Follow the multi-step workflow archetype (like
build-from-issue). Organize into:nclon PATH)--helpself-teaching fallback sectionCompanion skill delegation:
generate-sandbox-policyskillgenerate-sandbox-policyskill. Once you have the YAML file, return here to push it to the sandbox."--helpfallback mechanism:The skill should instruct the agent: "If you encounter a command or option not documented in this skill, walk the
--helptree to discover it. Start from the relevant command group and drill down."Supplementary files: Consider a
reference.mdwith the full command tree and all flags, keepingSKILL.mdfocused on workflows. This mirrors howgenerate-sandbox-policyusesexamples.md.Patterns to Follow
The existing skill pattern is well-established:
nameanddescription(including trigger keywords)generate-sandbox-policyfor policy content")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
--helpto self-teachgenerate-sandbox-policyand backThis investigation provides context for implementation. Next step: review the issue, refine if needed, then use
build-from-issueto create a plan and implement.johntmyers commentedon Mar 4, 2026
Companion Task: Update
generate-sandbox-policySkill for Schema DriftInvestigation uncovered that the
generate-sandbox-policyskill 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:
inferenceField NameThe skill documents
allowed_routing_hintsbut the actual code expectsallowed_routes. This is a breaking error — any agent-generated policy with inference config would fail YAML parsing due todeny_unknown_fieldson the serde struct.sandbox.proto)allowed_routesnavigator-policy/src/lib.rs)allowed_routesdev-sandbox-policy.yaml)allowed_routesopa.rs)allowed_routessecurity-policy.md(architecture doc)allowed_routing_hints(WRONG)SKILL.mdline 414-416allowed_routing_hints(WRONG)examples.mdline 870allowed_routing_hints(WRONG)Files to fix:
.agents/skills/generate-sandbox-policy/SKILL.md— changeallowed_routing_hints→allowed_routes.agents/skills/generate-sandbox-policy/examples.md— changeallowed_routing_hints→allowed_routesarchitecture/security-policy.md— changeallowed_routing_hints→allowed_routes(the architecture doc has the same error, which is likely where the skill picked it up from)Minor: Default
read_onlyPaths DifferThe skill's "Create New File" template uses
/proc/selfand omits/var/log, while the actualdev-sandbox-policy.yamluses/proc(broader) and includes/var/log. Decide whether to:Affected locations:
.agents/skills/generate-sandbox-policy/SKILL.mdline 391-397.agents/skills/generate-sandbox-policy/examples.mdline 823-831Low Priority:
InferenceApiPattern(proto-only)The proto defines
InferenceApiPatternwithmethod,path_glob,protocol, andkindfields onInferencePolicy.api_patterns, but this is not exposed in the YAML parsing path (the RustInferenceDefstruct doesn't include it). No action needed for the skill — just noting for awareness.Overall Assessment
The skill is ~97% accurate. The
allowed_routesfix 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 commentedon Mar 4, 2026
Design Decisions (from review)
read_onlydefaults: Updategenerate-sandbox-policyto matchdev-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
--helpnavigation — the agent should always be able to walkncl --help→ncl <group> --help→ncl <group> <cmd> --helpto 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 commentedon Mar 4, 2026
Implementation Plan
Issue type:
featComplexity: Medium
Confidence: High — clear path, established patterns, mechanical fixes + content authoring
Summary
Fix the
generate-sandbox-policyskill's schema drift (criticalallowed_routing_hints→allowed_routesrename + default path reconciliation) across 3 files (7 occurrences of the field name, 2 occurrences of/proc/self). Then create a newnemoclaw-cliagent skill with a SKILL.md (workflow guidance) and cli-reference.md (full command tree), following established skill patterns. The new skill cross-referencesgenerate-sandbox-policyfor policy content authoring.Scope
.agents/skills/generate-sandbox-policy/SKILL.md: Fixallowed_routing_hints→allowed_routes(line 414), fix/proc/self→/proc+ add/var/log(line 394).agents/skills/generate-sandbox-policy/examples.md: Fixallowed_routing_hints→allowed_routes(line 870), fix/proc/self→/proc+ add/var/log(line 828)architecture/security-policy.md: Fixallowed_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 referenceImplementation Steps
Step 1: Fix
generate-sandbox-policy/SKILL.mdallowed_routing_hints→allowed_routesat line 414/proc/self→/procat line 394, add/var/logto theread_onlylistStep 2: Fix
generate-sandbox-policy/examples.mdallowed_routing_hints→allowed_routesat line 870/proc/self→/procat line 828, add/var/logto theread_onlylistStep 3: Fix
architecture/security-policy.mdallowed_routing_hints→allowed_routesat lines 289, 475, 479, 990inference.allowed_routing_hintstoinference.allowed_routes; keep the proto column asallowed_routing_hintssince that's the actual proto field nameStep 4: Create
.agents/skills/nemoclaw-cli/cli-reference.mdSupplementary reference file with the full command tree and flag details. Structure:
Step 5: Create
.agents/skills/nemoclaw-cli/SKILL.mdMain skill file. Structure:
nemoclaw-cli, description with trigger keywords)generate-sandbox-policy--helpSelf-Teaching (the fallback mechanism — how to walk the help tree)Step 6: Run pre-commit checks
Test Plan
allowed_routesfix matchesdev-sandbox-policy.yaml; verify the new skill's command references matchncl --helpoutputRisks & Open Questions
generate-sandbox-policyusesexamples.md.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 withgenerate-sandbox-policywhich triggers on policy generation/authoring.allowed_routing_hintssince that's the actual proto field name — only the YAML mapping column changes toallowed_routes.Documentation Impact
architecture/security-policy.md: Fixed as part of the schema drift repair (Step 3)Revision 1 — initial plan
feat(skills): create nemoclaw-cli agent skill and fix generate-sandbo…
johntmyers commentedon Mar 4, 2026
Implementation Complete
PR: #85
What was built
Created the
nemoclaw-cliagent skill with 8 tiered workflows (getting started through cluster management), a supplementary CLI reference file, and--helpself-teaching as the primary fallback mechanism. Fixed critical schema drift ingenerate-sandbox-policy(allowed_routing_hints→allowed_routes) and updated defaultread_onlypaths to matchdev-sandbox-policy.yaml.Tests
Docs updated
architecture/security-policy.md— fixedallowed_routing_hints→allowed_routes(5 occurrences)The issue will auto-close when the PR is merged.
feat(cli): add dynamic shell completion support (!59)
feat(skills): create nemoclaw-cli agent skill (#85)
feat(cli): add dynamic shell completion support (!59)
feat(skills): create nemoclaw-cli agent skill (#85)
Merge pull request NVIDIA#83 from opendatahub-io/carry/openclaw-image…