hermes - 💡(How to fix) Fix Bug: productivity/maps SKILL.md script path is wrong twice — missing category prefix and uses ~/ which sandboxed subprocesses can't resolve [1 pull requests]

Summary

The bundled productivity/maps skill documents its script path as ~/.hermes/skills/maps/scripts/maps_client.py, but the agent cannot successfully invoke it via the terminal tool. Two stacked bugs:

1. Wrong subpath. The actual file is at ~/.hermes/skills/productivity/maps/scripts/maps_client.py (under the productivity category). The documented path omits productivity/. So even without sandboxing, the documented path would not exist.
2. ~ doesn't resolve to the user's home in subprocess shell commands. Per the intentional per-profile HOME isolation in tools/environments/local.py:295-301 (get_subprocess_home()), subprocess HOME is overridden to {HERMES_HOME}/home/ when that directory exists. So a SKILL.md that tells the agent to run python3 ~/.hermes/skills/... produces an absolute path inside the profile sandbox — not the real Hermes root.

This is distinct from #28456: that issue is about the gateway Python process's HOME being incorrectly overridden, breaking Path.expanduser() in read_file. The bug here is about a bundled SKILL.md being authored against assumptions that don't hold under the documented (and correctly-functioning) subprocess HOME sandbox.

Symptom

From a real session (Anthropic Sonnet 4.6, profile guide, HERMES_HOME=~/.hermes):

Agent ran:
  MAPS=~/.hermes/skills/maps/scripts/maps_client.py
  python3 $MAPS nearby --near "Jacobs Inn Dublin, Talbot Place" --category restaurant --radius 600 --limit 15

terminal tool returned:
  python3: can't open file
  '/home/joe/.hermes/profiles/guide/home/.hermes/skills/maps/scripts/maps_client.py':
  [Errno 2] No such file or directory

Walk-through of the resolution:

• bash expands ~ to subprocess $HOME = /home/joe/.hermes/profiles/guide/home (set by get_subprocess_home() because that dir exists)
• Result: /home/joe/.hermes/profiles/guide/home/.hermes/skills/maps/scripts/maps_client.py
• File does not exist there.
• Even if ~ had expanded to the real /home/joe, the documented path would still be wrong because of (1) — the actual file is under productivity/maps/, not maps/.

The agent then burned several tool calls debugging (find / -name 'maps_client.py'), eventually discovered the real path, and recovered by hard-coding an absolute path. Net cost: ~3–4 extra terminal calls per first-time invocation, plus model latency, before recovery.

Affected file

skills/productivity/maps/SKILL.md — four occurrences of ~/.hermes/skills/maps/scripts/maps_client.py (lines 42, 47, 190, 193 in v1.2.0).

Suggested fix

Replace all occurrences with the correct, sandbox-safe form:

$HERMES_HOME/skills/productivity/maps/scripts/maps_client.py

HERMES_HOME passes through the env blocklist in local.py:102-166 (confirmed) and is the documented anchor for the Hermes data tree, so this works regardless of profile HOME sandboxing or where the user has installed Hermes.

Other bundled skills that document ~/.hermes/skills/... paths in shell commands should be audited for the same pattern. A quick grep of skills/**/SKILL.md for ~/.hermes/skills would surface them.

Repro

1. python3 -m hermes_cli.main profile create test-profile && mkdir ~/.hermes/profiles/test-profile/home (any profile with a home/ directory triggers the sandbox)
2. Have the agent call skill_view("maps") and then run any of the documented examples, e.g. python3 $MAPS search "Eiffel Tower" where $MAPS is set from the SKILL.md line 47.
3. Observe: FileNotFoundError on {HERMES_HOME}/home/.hermes/skills/maps/scripts/maps_client.py.

Environment

• Hermes commit: 973f27e95631aaecbda5e32e3fa9e5d7f6a2e1d3 (HEAD as of 2026-05-16 — fix(run_agent): isolate background review fork from external memory plugins (#27190))
• Python: 3.11.x (Hermes venv)
• OS: Debian 13
• Provider: Anthropic Sonnet 4.6
• Profile: guide with profiles/guide/home/ directory present