feat(cli): add nemoclaw <sandbox> skill install command (#1844)

agents/hermes/plugin/__init__.py

@@ -3,8 +3,15 @@
 """
 NemoClaw plugin for Hermes Agent.
 
-Provides sandbox status tools and a startup banner when Hermes runs inside
-an OpenShell sandbox managed by NemoClaw.
+Provides sandbox status tools, skill hot-reload, and a startup banner when
+Hermes runs inside an OpenShell sandbox managed by NemoClaw.
+
+Skill hot-reload: Hermes caches its skill slash-command registry in a
+module-global dict on first scan. New skills dropped on disk are invisible
+until the cache is cleared. This plugin provides a nemoclaw_reload_skills
+tool that clears the cache and re-scans, letting the agent pick up new
+skills without a gateway restart. The on_session_start hook also refreshes
+skills automatically at session boundaries.
 """
 
 import json
@@ -104,6 +111,49 @@ def _handle_info(tool_input, context):
     return json.dumps(_get_sandbox_info(), indent=2)
 
 
+def _reload_skills():
+    """Clear the Hermes skill slash-command cache and re-scan skill directories.
+
+    Hermes's ``agent.skill_commands`` module caches discovered skills in a
+    module-global dict (``_skill_commands``).  ``get_skill_commands()`` only
+    scans on first call, so skills installed after gateway startup are
+    invisible.  We clear the dict and call ``scan_skill_commands()`` to force
+    a fresh scan.
+
+    Returns the dict of discovered skills, or None on failure.
+    """
+    try:
+        import agent.skill_commands as sc
+
+        sc._skill_commands.clear()
+        return sc.scan_skill_commands()
+    except ImportError:
+        return None
+    except Exception:
+        return None
+
+
+def _handle_reload_skills(tool_input, context):
+    """Handle the nemoclaw_reload_skills tool call."""
+    commands = _reload_skills()
+    if commands is None:
+        return (
+            "Failed to reload skills. The agent.skill_commands module may "
+            "not be available in this Hermes version."
+        )
+
+    if not commands:
+        return "Skill reload complete. No skills found in skill directories."
+
+    names = sorted(commands.keys())
+    lines = [f"Skill reload complete. {len(names)} skill(s) discovered:", ""]
+    for name in names:
+        info = commands[name]
+        desc = info.get("description", "no description")
+        lines.append(f"  {name}: {desc}")
+    return "\n".join(lines)
+
+
 def register(ctx):
     """Register NemoClaw tools and hooks with Hermes."""
 
@@ -142,8 +192,32 @@ def register(ctx):
         description="NemoClaw sandbox info (JSON)",
     )
 
+    # Register skill reload tool
+    ctx.register_tool(
+        name="nemoclaw_reload_skills",
+        toolset="nemoclaw",
+        schema={
+            "type": "function",
+            "function": {
+                "name": "nemoclaw_reload_skills",
+                "description": (
+                    "Reload and re-discover skills from the skill directories. "
+                    "Call this after new skills have been installed to make them "
+                    "available as slash commands without restarting the gateway."
+                ),
+                "parameters": {"type": "object", "properties": {}},
+            },
+        },
+        handler=_handle_reload_skills,
+        description="Reload skills from disk without gateway restart",
+    )
+
     # Startup banner on session start
     def _on_session_start(**kwargs):
+        # Refresh skill cache so skills installed since last session are
+        # immediately available as slash commands.
+        _reload_skills()
+
         info = _get_sandbox_info()
         banner = (
             "\n"
@@ -153,7 +227,8 @@ def _on_session_start(**kwargs):
             f"  \u2502  Model:     {info['model']:<40}\u2502\n"
             f"  \u2502  Provider:  {info['provider']:<40}\u2502\n"
             f"  \u2502  Gateway:   {info['gateway']:<40}\u2502\n"
-            "  \u2502  Tools:     nemoclaw_status, nemoclaw_info          \u2502\n"
+            "  \u2502  Tools:     nemoclaw_status, nemoclaw_info,         \u2502\n"
+            "  \u2502             nemoclaw_reload_skills                   \u2502\n"
             "  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n"
         )
         try:

agents/hermes/plugin/plugin.yaml

@@ -2,14 +2,15 @@
 # SPDX-License-Identifier: Apache-2.0
 
 name: nemoclaw
-version: "0.0.11"
+version: "0.0.12"
 description: "NemoClaw sandbox management for Hermes running inside OpenShell"
 author: "NVIDIA Corporation"
 manifest_version: 1
 
 provides_tools:
   - nemoclaw_status
   - nemoclaw_info
+  - nemoclaw_reload_skills
 
 provides_hooks:
   - on_session_start

src/lib/skill-install.test.ts

@@ -0,0 +1,233 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, it, expect } from "vitest";
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+// Import from compiled dist/ so coverage is attributed correctly.
+import {
+  parseFrontmatter,
+  resolveSkillPaths,
+  collectFiles,
+  validateRelativePath,
+  shellQuote,
+} from "../../dist/lib/skill-install";
+
+describe("parseFrontmatter", () => {
+  it("extracts name from valid frontmatter", () => {
+    const result = parseFrontmatter("---\nname: my-skill\ndescription: test\n---\n# Body");
+    expect(result).toEqual({ name: "my-skill" });
+  });
+
+  it("handles quoted name values", () => {
+    expect(parseFrontmatter('---\nname: "my-tool"\n---\n').name).toBe("my-tool");
+    expect(parseFrontmatter("---\nname: 'demo.tool'\n---\n").name).toBe("demo.tool");
+  });
+
+  it("handles name with dots, hyphens, and underscores", () => {
+    expect(parseFrontmatter("---\nname: my_skill.v2-beta\n---\n").name).toBe("my_skill.v2-beta");
+  });
+
+  it("parses complex YAML metadata beyond name", () => {
+    const fm = parseFrontmatter(
+      '---\nname: rich-skill\ndescription: "A skill"\nmetadata: { "openclaw": { "emoji": "🔧" } }\n---\n',
+    );
+    expect(fm.name).toBe("rich-skill");
+  });
+
+  it("rejects malformed YAML", () => {
+    expect(() =>
+      parseFrontmatter("---\nname: ok\ndescription: [broken\n---\n"),
+    ).toThrow("not valid YAML");
+  });
+
+  it("rejects non-mapping frontmatter", () => {
+    expect(() => parseFrontmatter("---\n- just\n- a list\n---\n")).toThrow("must be a YAML mapping");
+  });
+
+  it("throws when frontmatter is missing entirely", () => {
+    expect(() => parseFrontmatter("# Just markdown\nNo frontmatter")).toThrow(
+      "missing YAML frontmatter",
+    );
+  });
+
+  it("throws when closing delimiter is missing", () => {
+    expect(() => parseFrontmatter("---\nname: broken\n# No closing")).toThrow(
+      "missing closing --- frontmatter delimiter",
+    );
+  });
+
+  it("throws when name field is absent", () => {
+    expect(() => parseFrontmatter("---\ndescription: no name here\n---\n")).toThrow(
+      "missing required 'name' field",
+    );
+  });
+
+  it("throws when name field is empty or null", () => {
+    expect(() => parseFrontmatter("---\nname:\n---\n")).toThrow("missing required 'name' field");
+    expect(() => parseFrontmatter('---\nname: ""\n---\n')).toThrow("missing required 'name' field");
+  });
+
+  it("rejects names with invalid characters", () => {
+    expect(() => parseFrontmatter("---\nname: my skill\n---\n")).toThrow("invalid characters");
+    expect(() => parseFrontmatter("---\nname: ../escape\n---\n")).toThrow("invalid characters");
+    expect(() => parseFrontmatter("---\nname: a/b\n---\n")).toThrow("invalid characters");
+  });
+});
+
+describe("validateRelativePath", () => {
+  it("accepts safe paths", () => {
+    expect(validateRelativePath("SKILL.md")).toBe(true);
+    expect(validateRelativePath("scripts/helper.js")).toBe(true);
+    expect(validateRelativePath("data/config-v2.yaml")).toBe(true);
+  });
+
+  it("rejects shell metacharacters", () => {
+    expect(validateRelativePath("$(touch /tmp/pwn).js")).toBe(false);
+    expect(validateRelativePath("a'b.txt")).toBe(false);
+    expect(validateRelativePath('a"b.txt')).toBe(false);
+    expect(validateRelativePath("a`b`.txt")).toBe(false);
+    expect(validateRelativePath("file name.txt")).toBe(false);
+    expect(validateRelativePath("a;rm -rf.txt")).toBe(false);
+  });
+
+  it("rejects directory traversal", () => {
+    expect(validateRelativePath("../escape")).toBe(false);
+    expect(validateRelativePath("foo/../../etc/passwd")).toBe(false);
+    expect(validateRelativePath("./current")).toBe(false);
+  });
+
+  it("rejects empty and degenerate paths", () => {
+    expect(validateRelativePath("")).toBe(false);
+    expect(validateRelativePath("/absolute")).toBe(false);
+    expect(validateRelativePath("foo//bar")).toBe(false);
+  });
+});
+
+describe("shellQuote", () => {
+  it("wraps simple strings in single quotes", () => {
+    expect(shellQuote("hello")).toBe("'hello'");
+  });
+
+  it("escapes embedded single quotes", () => {
+    expect(shellQuote("it's")).toBe("'it'\\''s'");
+  });
+});
+
+describe("collectFiles", () => {
+  let tmpDir: string;
+
+  function setup(files: Record<string, string>) {
+    tmpDir = mkdtempSync(join(tmpdir(), "skill-test-"));
+    for (const [rel, content] of Object.entries(files)) {
+      const full = join(tmpDir, rel);
+      mkdirSync(join(full, ".."), { recursive: true });
+      writeFileSync(full, content);
+    }
+  }
+
+  function cleanup() {
+    if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
+  }
+
+  it("collects a single SKILL.md", () => {
+    setup({ "SKILL.md": "---\nname: solo\n---\n" });
+    try {
+      const { files, skippedDotfiles, unsafePaths } = collectFiles(tmpDir);
+      expect(files).toEqual(["SKILL.md"]);
+      expect(skippedDotfiles).toEqual([]);
+      expect(unsafePaths).toEqual([]);
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("collects SKILL.md plus nested scripts, skips dotfiles", () => {
+    setup({
+      "SKILL.md": "---\nname: rich\n---\n",
+      "scripts/helper.js": "console.log('hi')",
+      ".env": "KEY=val",
+    });
+    try {
+      const { files, skippedDotfiles } = collectFiles(tmpDir);
+      expect(files.sort()).toEqual(["SKILL.md", "scripts/helper.js"]);
+      expect(skippedDotfiles).toEqual([".env"]);
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("flags files with unsafe characters", () => {
+    setup({
+      "SKILL.md": "---\nname: bad\n---\n",
+      "has space.txt": "content",
+    });
+    try {
+      const { files, unsafePaths } = collectFiles(tmpDir);
+      expect(files).toEqual(["SKILL.md"]);
+      expect(unsafePaths).toEqual(["has space.txt"]);
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("resolveSkillPaths", () => {
+  it("returns OpenClaw defaults when agent is null", () => {
+    const paths = resolveSkillPaths(null, "weather");
+    expect(paths.uploadDir).toBe("/sandbox/.openclaw/skills/weather");
+    expect(paths.mirrorDir).toBe("$HOME/.openclaw/skills/weather");
+    expect(paths.sessionFile).toBe(
+      "/sandbox/.openclaw-data/agents/main/sessions/sessions.json",
+    );
+    expect(paths.isOpenClaw).toBe(true);
+  });
+
+  it("returns OpenClaw paths when agent.name is 'openclaw'", () => {
+    const agent = {
+      name: "openclaw",
+      configPaths: {
+        immutableDir: "/sandbox/.openclaw",
+        writableDir: "/sandbox/.openclaw-data",
+      },
+    };
+    const paths = resolveSkillPaths(agent, "my-skill");
+    expect(paths.uploadDir).toBe("/sandbox/.openclaw/skills/my-skill");
+    expect(paths.mirrorDir).toBe("$HOME/.openclaw/skills/my-skill");
+    expect(paths.sessionFile).toBe(
+      "/sandbox/.openclaw-data/agents/main/sessions/sessions.json",
+    );
+    expect(paths.isOpenClaw).toBe(true);
+  });
+
+  it("returns Hermes paths without mirror or session refresh", () => {
+    const agent = {
+      name: "hermes",
+      configPaths: {
+        immutableDir: "/sandbox/.hermes",
+        writableDir: "/sandbox/.hermes-data",
+      },
+    };
+    const paths = resolveSkillPaths(agent, "demo-skill");
+    expect(paths.uploadDir).toBe("/sandbox/.hermes/skills/demo-skill");
+    expect(paths.mirrorDir).toBeNull();
+    expect(paths.sessionFile).toBeNull();
+    expect(paths.isOpenClaw).toBe(false);
+  });
+
+  it("returns generic paths for a hypothetical future agent", () => {
+    const agent = {
+      name: "future-agent",
+      configPaths: {
+        immutableDir: "/sandbox/.future",
+        writableDir: "/sandbox/.future-data",
+      },
+    };
+    const paths = resolveSkillPaths(agent, "test-skill");
+    expect(paths.uploadDir).toBe("/sandbox/.future/skills/test-skill");
+    expect(paths.mirrorDir).toBeNull();
+    expect(paths.sessionFile).toBeNull();
+    expect(paths.isOpenClaw).toBe(false);
+  });
+});