hermes - 💡(How to fix) Fix Docs: bundled-skill notes (gateway notify-interval, sudo secure-PATH, mcp --args quoting, repo-context-before-auth-diagnosis)

Summary

Two bundled skills could carry a few small, generic troubleshooting/usage notes that recur in real operation. Proposing them as documentation additions so they ship in the bundled skills rather than living as local edits (which mark the skill user-modified and stop it receiving future bundled updates). All items below are verified against current source.

1. skills/autonomous-ai-agents/hermes-agent/SKILL.md

(a) Gateway "Still working…" progress pings are configurable. Long-running-turn notifications are emitted by the gateway, not authored by the agent, and are controlled by agent.gateway_notify_interval (default 180, bridged to env HERMES_AGENT_NOTIFY_INTERVAL); 0 disables them. Persona/memory instructions do not suppress the gateway notifier. Suggested troubleshooting bullet:

Gateway-generated "Still working…" pings: these are emitted by the gateway, not the agent. They are controlled by agent.gateway_notify_interval (default 180s, bridged to HERMES_AGENT_NOTIFY_INTERVAL). Set hermes -p <profile> config set agent.gateway_notify_interval 0 and restart that profile's gateway to disable heartbeat pings. Prompt/memory instructions alone do not suppress them.

(Refs: hermes_cli/config.py default gateway_notify_interval: 180; gateway/run.py bridges it to HERMES_AGENT_NOTIFY_INTERVAL and treats 0 as disabled.)

(b) sudo hermes … → command not found. When Hermes is installed under a user-local bin (e.g. ~/.local/bin), sudo's secure PATH does not include it. Suggested bullet:

sudo hermes … says sudo: hermes: command not found: Hermes may be installed under a user-local bin (e.g. ~/.local/bin/hermes) that is not on sudo's secure PATH. Use the absolute path, e.g. sudo /home/<user>/.local/bin/hermes gateway restart --system, or operate the unit directly: sudo systemctl restart hermes-gateway.service. Inspect first with command -v hermes.

(c) hermes mcp add --args and leading-dash arguments. --args is nargs="*", so a value beginning with - can be parsed as a top-level option rather than as an argument to the MCP command. Prefer the = form. Suggested note:

When an MCP server argument begins with -, use the equals form for --args:

hermes mcp add example-server \
  --command /path/to/server \
  --args=--transport=stdio

The space form (--args "--transport=stdio") can be misparsed because --args is nargs="*" and argparse treats a --leading token as an option.

(Ref: hermes_cli/main.py — mcp add parser defines --args nargs="*".)

(d) Invoking installed skills in a session. A generic /skill <name> form is not reliable on all CLI/gateway paths; installed skills expose a dynamic slash command named after the skill, and can also be preloaded with --skills/-s. Suggested note for the session-command list:

Installed skills are invoked by their own dynamic slash command (named after the skill), or preloaded via the CLI --skills / -s flag.

2. skills/github/github-auth/SKILL.md — establish repo context before diagnosing auth

A very common false negative: a gh/git command fails because the shell is not inside the intended repository, and that gets misread as "GitHub is not authenticated." Suggested section:

Repository context before auth diagnosis

A GitHub command failing in the current directory does not prove GitHub is unauthenticated. Establish repository context first:

pwd
git rev-parse --show-toplevel 2>/dev/null || echo "not in a git repository"
gh auth status 2>/dev/null || true

• If gh auth status succeeds but git rev-parse reports "not in a git repository", the fix is cwd/repo selection, not authentication.
• Run repo-scoped commands from the owning checkout (set the tool's working directory, or cd /abs/path && …).
• For gh commands that support it, use -R OWNER/REPO when no local checkout is needed.
• Only conclude an auth failure after both a repo-context check and gh auth status / token check fail.

Notes

Happy to open a PR with the exact diffs if a documentation PR is preferred over an issue — wanted to confirm direction and wording first. All four hermes-agent items and the github-auth item are generic; no environment-specific content.