Summary

When the terminal backend bind-mounts the skill tree into a sandbox (Docker, Singularity, Modal), skill_view's response and the ${HERMES_SKILL_DIR} template substitution return the gateway-side host path (e.g. /opt/data/skills/nextcloud). The agent then references that path inside its execute_code sandbox, which mounts the same skill at /root/.hermes/skills/nextcloud — so any bundled-script invocation fails. This PR adds a runtime_skill_dir field that translates the host path through the active mount mapping, and uses the translated path for ${HERMES_SKILL_DIR} substitution.

Fixes #27491.

The bug

tools/skills_tool.py::skill_view() returns:

result = {
    ...
    "skill_dir": str(skill_dir) if skill_dir else None,
    ...
}

where skill_dir is the gateway-side absolute path (the gateway runs in Docker with HERMES_HOME=/opt/data, so this is /opt/data/skills/nextcloud). The reporter (#27491) describes the symptom precisely:

The agent searches for the script in skill_dir which points to /opt/data/skills/nextcloud, which does not exist in the sandbox.

The same path is fed into agent.skill_preprocessing.preprocess_skill_content, which substitutes it for every ${HERMES_SKILL_DIR} token in the rendered SKILL.md body — so a skill that documents bash ${HERMES_SKILL_DIR}/scripts/run.sh renders the wrong path in the message the agent sees.

The skill tree is actually mounted at /root/.hermes/skills/<name> inside the Podman-in-Docker sandbox (the canonical container_base used by tools/credential_files.get_skills_directory_mount() and consumed by tools/environments/docker.py, tools/environments/singularity.py, tools/environments/modal.py).

The fix

Add a small helper _to_runtime_skill_dir(skill_dir, backend) in tools/skills_tool.py that:

1. Returns skill_dir unchanged for the local backend.
2. For docker / singularity / modal backends, walks the get_skills_directory_mount() results, finds the mount whose host_path contains skill_dir, and rewrites the prefix to that mount's container_path (/root/.hermes/skills/... or /root/.hermes/external_skills/<idx>/... for skills.external_dirs entries).
3. Falls back to skill_dir when no mount matches — e.g. backends that use file_sync instead of bind mounts (ssh, daytona, vercel_sandbox), or when the skills mount registration hasn't run yet.

The skill_view result then exposes both fields:

"skill_dir": str(skill_dir) if skill_dir else None,                    # host path (unchanged)
"runtime_skill_dir": str(runtime_skill_dir) if runtime_skill_dir else None,  # sandbox path (or same for local)

…and the runtime path is the one passed into preprocess_skill_content, so ${HERMES_SKILL_DIR} substitution emits the path the agent actually needs at execute-code time.

skill_dir is intentionally left as the host path because agent.skill_commands._load_skill_payload reads it back as a Path to access the SKILL.md on the gateway-side filesystem (see PR #10587) — rewriting it to a sandbox path would break that caller.

Test plan

• New regression tests in tests/tools/test_skills_tool.py::TestSkillView:
  • test_skill_view_returns_host_skill_dir_for_local_backend — runtime_skill_dir == skill_dir == <host path> when TERMINAL_ENV=local.
  • test_skill_view_returns_sandbox_skill_dir_for_docker_backend — when TERMINAL_ENV=docker and get_skills_directory_mount() returns the canonical host_path → /root/.hermes/skills mapping, the response has skill_dir == <host path> and runtime_skill_dir == /root/.hermes/skills/nextcloud.
  • test_skill_view_template_substitution_uses_sandbox_path — ${HERMES_SKILL_DIR} inside SKILL.md substitutes the sandbox path under the same backend; the host path no longer appears in the rendered content.
  • test_skill_view_categorized_skill_keeps_subdirs_in_sandbox_path — categorized skill integration/nextcloud ends up at /root/.hermes/skills/integration/nextcloud (relative path preserved).
  • test_skill_view_runtime_path_falls_back_when_no_mount_matches — empty mount list ⇒ runtime_skill_dir == skill_dir; no confidently-wrong sandbox path is emitted.
• Regression guard: against pre-fix code, the four sandbox tests fail because runtime_skill_dir is absent from the response and ${HERMES_SKILL_DIR} substitutes the host path. With the fix, all five pass.
• Focused suite: uv run --with pytest --with pytest-xdist --with pytest-asyncio python3 -m pytest tests/tools/test_skills_tool.py::TestSkillView -v — 19 passed.
• Adjacent suites: tests/tools/test_skills_tool.py tests/agent/test_skill_commands.py tests/tools/test_credential_files.py — 160 passed.
• ${HERMES_SKILL_DIR} substitution under the default local backend is unchanged (existing test_skill_view_applies_template_vars still passes — runtime_skill_dir == skill_dir so the rendered string is byte-identical to before).

Related

• Fixes [Bug]: skill_dir returned from skill_view tool is incorrect when sandboxed #27491.
• Builds on #10587 (fix: use absolute skill_dir for external skills) — that PR added the absolute-host skill_dir field; this one adds a sandbox-aware sibling for the agent's runtime view.
• Mount mapping uses the same source of truth (tools/credential_files.get_skills_directory_mount) that tools/environments/docker.py already feeds to --volume flags — so the runtime path matches the actual bind mount.

Sibling code paths that may need the same fix: agent/skill_commands._build_skill_message also surfaces a [Skill directory: ...] line constructed from the host skill_dir, which has the same wrong-path problem when sandboxed. Intentionally left out of this PR's scope to keep the diff small — happy to widen to that callsite as well if preferred.