feat(skills): /reload-skills slash command + skills_reload agent tool

Adds a public reload path for the in-process skill caches so newly
installed (or removed) skills become visible mid-session without a
gateway restart. Mirrors the shape of /reload-mcp.

Three surfaces:
* /reload-skills slash command — CLI (cli.py) and gateway (gateway/run.py),
  with /reload_skills alias for Telegram autocomplete and an explicit
  Discord registration.
* skills_reload agent tool (tools/skills_tool.py) — lets agents/subagents
  pick up freshly-installed skills via tool call.
* agent.skill_commands.reload_skills() — shared helper that clears
  _skill_commands, _SKILLS_PROMPT_CACHE (in-process LRU), and the
  on-disk .skills_prompt_snapshot.json, then returns an added/removed
  diff plus the new total count.

Tested:
* tests/agent/test_skill_commands_reload.py (9 cases)
* tests/cli/test_cli_reload_skills.py       (3 cases)
* tests/gateway/test_reload_skills_command.py (4 cases)

Use case: NemoClaw / OpenShell-style sandboxed orchestrators that drop
skills into ~/.hermes/skills mid-session, plus agentic flows where the
agent itself installs a skill via the shell tool and needs it bound
without a gateway restart. The Python helper
clear_skills_system_prompt_cache(clear_snapshot=True) already exists
internally — this PR just exposes it via slash command and tool.

tests/agent/test_skill_commands_reload.py

@@ -0,0 +1,178 @@
+"""Tests for ``agent.skill_commands.reload_skills`` and the ``skills_reload`` tool.
+
+Covers the helper that powers ``/reload-skills`` (CLI + gateway slash command)
+and the ``skills_reload`` agent tool — both clear in-process skill caches and
+return a diff of newly-visible / removed skill names.
+"""
+
+import json
+import shutil
+import tempfile
+import textwrap
+from pathlib import Path
+
+import pytest
+
+
+def _write_skill(skills_dir: Path, name: str, description: str = "") -> Path:
+    skill_dir = skills_dir / name
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    (skill_dir / "SKILL.md").write_text(
+        textwrap.dedent(
+            f"""\
+            ---
+            name: {name}
+            description: {description or f'{name} skill'}
+            ---
+            body
+            """
+        )
+    )
+    return skill_dir
+
+
+@pytest.fixture
+def hermes_home(monkeypatch):
+    """Isolate HERMES_HOME for ``reload_skills`` tests.
+
+    Rather than popping cache-bearing modules from ``sys.modules`` (which
+    races against pytest-xdist's parallel workers), we monkeypatch the
+    module-level ``HERMES_HOME`` / ``SKILLS_DIR`` constants in place so the
+    isolation is local to this fixture's scope.
+    """
+    td = tempfile.mkdtemp(prefix="hermes-reload-skills-")
+    monkeypatch.setenv("HERMES_HOME", td)
+    home = Path(td)
+    (home / "skills").mkdir(parents=True, exist_ok=True)
+
+    # Import lazily (inside fixture) so the modules are already resident,
+    # then redirect their captured paths at the new temp dir.
+    import tools.skills_tool as _st
+    import agent.skill_commands as _sc
+
+    monkeypatch.setattr(_st, "HERMES_HOME", home, raising=False)
+    monkeypatch.setattr(_st, "SKILLS_DIR", home / "skills", raising=False)
+    # Reset the in-process slash-command cache so each test starts from zero.
+    monkeypatch.setattr(_sc, "_skill_commands", {}, raising=False)
+
+    yield home
+
+    shutil.rmtree(td, ignore_errors=True)
+
+
+class TestReloadSkillsHelper:
+    """``agent.skill_commands.reload_skills``."""
+
+    def test_returns_expected_keys(self, hermes_home):
+        from agent.skill_commands import reload_skills
+
+        result = reload_skills()
+        assert set(result) == {"added", "removed", "unchanged", "total", "commands"}
+        assert result["total"] == 0
+        assert result["added"] == []
+        assert result["removed"] == []
+
+    def test_detects_newly_added_skill(self, hermes_home):
+        from agent.skill_commands import reload_skills, get_skill_commands
+
+        # Prime the cache so subsequent diff is meaningful
+        get_skill_commands()
+
+        _write_skill(hermes_home / "skills", "demo")
+        result = reload_skills()
+
+        assert result["added"] == ["demo"]
+        assert result["removed"] == []
+        assert result["total"] == 1
+        assert result["commands"] == 1
+
+    def test_detects_removed_skill(self, hermes_home):
+        from agent.skill_commands import reload_skills
+
+        skill_dir = _write_skill(hermes_home / "skills", "demo")
+        # First reload: demo present
+        first = reload_skills()
+        assert first["total"] == 1
+
+        # Remove and reload
+        shutil.rmtree(skill_dir)
+        second = reload_skills()
+
+        assert second["removed"] == ["demo"]
+        assert second["added"] == []
+        assert second["total"] == 0
+
+    def test_clears_prompt_cache_snapshot(self, hermes_home):
+        """The disk snapshot at ``.skills_prompt_snapshot.json`` must be removed."""
+        from agent.prompt_builder import _skills_prompt_snapshot_path
+        from agent.skill_commands import reload_skills
+
+        snapshot = _skills_prompt_snapshot_path()
+        snapshot.parent.mkdir(parents=True, exist_ok=True)
+        snapshot.write_text("{}")
+        assert snapshot.exists()
+
+        reload_skills()
+
+        assert not snapshot.exists(), "prompt cache snapshot should be removed"
+
+    def test_unchanged_skills_appear_in_unchanged_list(self, hermes_home):
+        from agent.skill_commands import reload_skills, get_skill_commands
+
+        _write_skill(hermes_home / "skills", "alpha")
+        # Prime cache
+        get_skill_commands()
+
+        # Call reload again with no FS changes
+        result = reload_skills()
+        assert "alpha" in result["unchanged"]
+        assert result["added"] == []
+        assert result["removed"] == []
+
+
+class TestSkillsReloadTool:
+    """``tools.skills_tool.skills_reload`` — the agent-facing tool."""
+
+    def test_tool_returns_json(self, hermes_home):
+        from tools.skills_tool import skills_reload
+
+        out = skills_reload()
+        result = json.loads(out)
+        assert result["success"] is True
+        assert set(result) == {
+            "success",
+            "added",
+            "removed",
+            "unchanged_count",
+            "total",
+            "commands",
+        }
+
+    def test_tool_reports_added_skill(self, hermes_home):
+        from agent.skill_commands import get_skill_commands
+        from tools.skills_tool import skills_reload
+
+        get_skill_commands()  # prime cache
+        _write_skill(hermes_home / "skills", "freshly-added", "fresh skill")
+
+        result = json.loads(skills_reload())
+        assert result["success"] is True
+        assert result["added"] == ["freshly-added"]
+        assert result["total"] == 1
+
+    def test_tool_is_registered_in_skills_toolset(self, hermes_home):
+        # Importing the module triggers registry.register
+        import tools.skills_tool  # noqa: F401
+        from tools.registry import registry
+
+        assert "skills_reload" in registry.get_tool_names_for_toolset("skills")
+        assert registry.get_toolset_for_tool("skills_reload") == "skills"
+
+    def test_tool_schema_has_no_required_args(self, hermes_home):
+        import tools.skills_tool  # noqa: F401
+        from tools.registry import registry
+
+        schema = registry.get_schema("skills_reload")
+        assert schema["name"] == "skills_reload"
+        # Caller invokes with no arguments; tool returns the diff verbatim.
+        assert schema["parameters"].get("required", []) == []

tests/cli/test_cli_reload_skills.py

@@ -0,0 +1,77 @@
+"""Tests for the ``/reload-skills`` CLI slash command (``HermesCLI._reload_skills``)."""
+
+from unittest.mock import MagicMock, patch
+
+
+def _make_cli():
+    """Build a minimal HermesCLI shell exposing ``_reload_skills``."""
+    import cli as cli_mod
+
+    obj = object.__new__(cli_mod.HermesCLI)
+    obj._command_running = False
+    obj.conversation_history = []
+    obj.agent = None
+    return obj
+
+
+class TestReloadSkillsCLI:
+    def test_reports_added_and_removed(self, capsys):
+        cli = _make_cli()
+        with patch(
+            "agent.skill_commands.reload_skills",
+            return_value={
+                "added": ["alpha", "beta"],
+                "removed": ["gamma"],
+                "unchanged": ["delta"],
+                "total": 3,
+                "commands": 3,
+            },
+        ):
+            cli._reload_skills()
+
+        out = capsys.readouterr().out
+        assert "Added: alpha, beta" in out
+        assert "Removed: gamma" in out
+        assert "3 skill(s) available" in out
+        # An informational message should be appended to the conversation
+        # so the model picks up the diff on the next turn.
+        assert len(cli.conversation_history) == 1
+        msg = cli.conversation_history[0]
+        assert msg["role"] == "user"
+        assert "Skills have been reloaded" in msg["content"]
+        assert "alpha" in msg["content"]
+        assert "gamma" in msg["content"]
+
+    def test_reports_no_changes(self, capsys):
+        cli = _make_cli()
+        with patch(
+            "agent.skill_commands.reload_skills",
+            return_value={
+                "added": [],
+                "removed": [],
+                "unchanged": ["alpha"],
+                "total": 1,
+                "commands": 1,
+            },
+        ):
+            cli._reload_skills()
+
+        out = capsys.readouterr().out
+        assert "No changes detected" in out
+        assert "1 skill(s) available" in out
+        # Nothing changed — don't pollute history.
+        assert cli.conversation_history == []
+
+    def test_handles_reload_failure_gracefully(self, capsys):
+        cli = _make_cli()
+        with patch(
+            "agent.skill_commands.reload_skills",
+            side_effect=RuntimeError("boom"),
+        ):
+            cli._reload_skills()
+
+        out = capsys.readouterr().out
+        assert "Skills reload failed" in out
+        assert "boom" in out
+        # Failure must not append a misleading "skills reloaded" note.
+        assert cli.conversation_history == []

tests/gateway/test_reload_skills_command.py

@@ -0,0 +1,174 @@
+"""Tests for the ``/reload-skills`` gateway slash command handler.
+
+Verifies the gateway path that mirrors ``/reload-mcp``:
+  * dispatcher routes ``/reload-skills`` to ``_handle_reload_skills_command``
+  * the underscored alias ``/reload_skills`` is not flagged as unknown
+  * the handler invokes ``agent.skill_commands.reload_skills`` and renders a
+    human-readable diff
+"""
+
+from datetime import datetime
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from gateway.config import GatewayConfig, Platform, PlatformConfig
+from gateway.platforms.base import MessageEvent
+from gateway.session import SessionEntry, SessionSource, build_session_key
+
+
+def _make_source() -> SessionSource:
+    return SessionSource(
+        platform=Platform.TELEGRAM,
+        user_id="u1",
+        chat_id="c1",
+        user_name="tester",
+        chat_type="dm",
+    )
+
+
+def _make_event(text: str) -> MessageEvent:
+    return MessageEvent(text=text, source=_make_source(), message_id="m1")
+
+
+def _make_runner():
+    from gateway.run import GatewayRunner
+
+    runner = object.__new__(GatewayRunner)
+    runner.config = GatewayConfig(
+        platforms={Platform.TELEGRAM: PlatformConfig(enabled=True, token="***")}
+    )
+    adapter = MagicMock()
+    adapter.send = AsyncMock()
+    runner.adapters = {Platform.TELEGRAM: adapter}
+    runner._voice_mode = {}
+    runner.hooks = SimpleNamespace(
+        emit=AsyncMock(),
+        emit_collect=AsyncMock(return_value=[]),
+        loaded_hooks=False,
+    )
+
+    session_entry = SessionEntry(
+        session_key=build_session_key(_make_source()),
+        session_id="sess-1",
+        created_at=datetime.now(),
+        updated_at=datetime.now(),
+        platform=Platform.TELEGRAM,
+        chat_type="dm",
+    )
+    runner.session_store = MagicMock()
+    runner.session_store.get_or_create_session.return_value = session_entry
+    runner.session_store.load_transcript.return_value = []
+    runner.session_store.has_any_sessions.return_value = True
+    runner.session_store.append_to_transcript = MagicMock()
+    runner.session_store.rewrite_transcript = MagicMock()
+    runner.session_store.update_session = MagicMock()
+    runner._running_agents = {}
+    runner._pending_messages = {}
+    runner._pending_approvals = {}
+    runner._session_db = None
+    runner._reasoning_config = None
+    runner._provider_routing = {}
+    runner._fallback_model = None
+    runner._show_reasoning = False
+    runner._is_user_authorized = lambda _source: True
+    runner._set_session_env = lambda _context: None
+    runner._should_send_voice_reply = lambda *_args, **_kwargs: False
+    return runner
+
+
+@pytest.mark.asyncio
+async def test_reload_skills_handler_renders_added_and_removed(monkeypatch):
+    """The handler should call ``reload_skills`` and surface the diff."""
+    import gateway.run as gateway_run
+
+    fake_result = {
+        "added": ["alpha", "beta"],
+        "removed": ["gamma"],
+        "unchanged": ["delta"],
+        "total": 3,
+        "commands": 3,
+    }
+
+    def _fake_reload_skills():
+        return fake_result
+
+    # Patch the symbol where ``_handle_reload_skills_command`` imports it from.
+    import agent.skill_commands as skill_commands_mod
+    monkeypatch.setattr(skill_commands_mod, "reload_skills", _fake_reload_skills)
+
+    runner = _make_runner()
+    out = await runner._handle_reload_skills_command(_make_event("/reload-skills"))
+
+    assert out is not None
+    assert "Skills Reloaded" in out
+    assert "alpha" in out and "beta" in out
+    assert "gamma" in out
+    assert "3 skill(s) available" in out
+
+    # A history note should be appended so the model sees the diff next turn.
+    runner.session_store.append_to_transcript.assert_called_once()
+    appended = runner.session_store.append_to_transcript.call_args[0][1]
+    assert appended["role"] == "user"
+    assert "Skills have been reloaded" in appended["content"]
+
+
+@pytest.mark.asyncio
+async def test_reload_skills_handler_reports_no_changes(monkeypatch):
+    """When nothing changed, the handler should say so without injecting a note."""
+    import agent.skill_commands as skill_commands_mod
+
+    monkeypatch.setattr(
+        skill_commands_mod,
+        "reload_skills",
+        lambda: {
+            "added": [],
+            "removed": [],
+            "unchanged": ["alpha"],
+            "total": 1,
+            "commands": 1,
+        },
+    )
+
+    runner = _make_runner()
+    out = await runner._handle_reload_skills_command(_make_event("/reload-skills"))
+
+    assert "No changes detected" in out
+    assert "1 skill(s) available" in out
+    # No history note when nothing changed — preserves prompt cache.
+    runner.session_store.append_to_transcript.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_dispatcher_routes_reload_skills(monkeypatch):
+    """``/reload-skills`` must reach ``_handle_reload_skills_command``."""
+    import gateway.run as gateway_run
+
+    runner = _make_runner()
+    sentinel = "reload-skills handler reached"
+    runner._handle_reload_skills_command = AsyncMock(return_value=sentinel)  # type: ignore[attr-defined]
+
+    monkeypatch.setattr(
+        gateway_run, "_resolve_runtime_agent_kwargs", lambda: {"api_key": "***"}
+    )
+
+    result = await runner._handle_message(_make_event("/reload-skills"))
+    assert result == sentinel
+
+
+@pytest.mark.asyncio
+async def test_underscored_alias_not_flagged_unknown(monkeypatch):
+    """Telegram autocomplete sends ``/reload_skills`` for ``/reload-skills``."""
+    import gateway.run as gateway_run
+
+    runner = _make_runner()
+    runner._handle_reload_skills_command = AsyncMock(return_value="ok")  # type: ignore[attr-defined]
+
+    monkeypatch.setattr(
+        gateway_run, "_resolve_runtime_agent_kwargs", lambda: {"api_key": "***"}
+    )
+
+    result = await runner._handle_message(_make_event("/reload_skills"))
+    if result is not None:
+        assert "Unknown command" not in result