docs(skills): document /skill-name slash invocation in slash-commands.md

[Miracle0530]

Summary

The hermes-agent skill's references/slash-commands.md listed /skills
(management), /bundles, /learn, and /reload-skills, but omitted the
primary way to load a specific skill into a session: /<skill-name> (e.g.,
/github-auth, /gif-search). Every installed skill is automatically
registered as a slash command at startup by agent/skill_commands.py, but
this was not documented in the in-skill reference the agent consults first.

This matches the behavior in cli.py:9620-9664 and the official user guide
(website/docs/user-guide/features/skills.md:52-85), which both document
the /<skill-name> form with examples.

Changes

1. Added /<skill-name> to the "Tools & Skills" section of
   slash-commands.md, with two concrete examples and the stacking note
   (up to 5: /skill-a /skill-b do XYZ).

2. Corrected the opening "Registry of record" note — it claimed every
   slash-command consumer derives from COMMAND_REGISTRY, but dynamically
   registered skill commands live in agent/skill_commands.py, not
   COMMAND_REGISTRY. The note now distinguishes the two sets and points
   to the registration source.

Impact

Without this line, the agent falls back to grepping cli.py source when
asked how to load a skill — a 8-API-call, 3-minute detour that should
be a single skill_view. Documenting it lets the agent answer from the
reference directly.

Verified by probing a fresh hermes chat -q session before and after the
patch (memory and sessions cleaned between runs):

Metric	Before patch	After patch
API calls	8	3
Duration	3m 07s	58s
Tool calls	7 (grep+read cli.py)	2 (skill_view only)
Source fallback	Yes	No

Type

docs — accuracy/completeness improvement, no behavior change.

[teknium1]

Thanks for filling a real gap in the in-skill slash-command reference: current main supports dynamic skill invocation (agent/skill_commands.py:374-482; CLI dispatch at cli.py:10159-10203), while this reference currently omits it (skills/autonomous-ai-agents/hermes-agent/references/slash-commands.md:55-75).

Problems

• The added registry note says skill commands are registered “at startup” by scanning ~/.hermes/skills/. Discovery is lazy (agent/skill_commands.py:470-482), profile-aware (tools/skills_tool.py:142-143), and also includes configured external directories (agent/skill_commands.py:390-415).

Suggested changes

• Describe /<skill-name> commands as dynamically discovered eligible skills, without a fixed default-profile path or startup-only timing claim.

Automated hermes-sweeper review.

[GottZ]

This was generated by AI during triage.

Summary

18 PRs address or reference this issue complex: seven modify the resolved-install-path versus unresolved-skills-root failure, while the remainder cover destination symlinks, one-shot CLI documentation, here-now metadata, or slash-command documentation. The visible diffs make #64954 the current-code-shape two-site symlink-root implementation, #70511 the merged slash-command reference implementation, and #71295 a distinct follow-up documenting dynamic skill invocation.

Related pull requests

• fix(skills): replace symlink install destinations #21739 [closed] best fix — (+57/-2) — n/a: Replaces an existing destination symlink without touching its target, directly addressing hermes skills install crashes with OSError when install destination is a symlink #21735's rmtree crash; although closed, it remains recorded best-fix prior art, while main instead blocks this path via 3b9b9a7.
• fix(skills): replace force-install symlink destinations #23251 [closed] fixes — (+55/-1) — n/a: Implements the same destination-symlink replacement as fix(skills): replace symlink install destinations #21739; although closed, it remains relevant as an explicit duplicate of fix(skills): replace symlink install destinations #21739 and as prior work superseded by main commit 3b9b9a7.
• docs(cli): clarify hermes -z version boundary and one-shot timeout behavior #25501 [closed] partial — (+25/-1) — n/a: Documents the -z version boundary, chat -q fallback, and absent one-shot timeout option; although closed after a keep_open review, its unqualified GNU timeout example conflicts with its platform-independent framing and the corrected guidance is covered more cleanly by docs: fix small skill and cli references #54444.
• [codex] fix(skills): resolve installed path aliases under symlinked HERMES_HOME #35630 partial — (+55/-2) — n/a: Resolves both lock-recording and Installed: roots and adds a symlink-root regression, but despite its keep_open verdict the visible backend diff uses obsolete SKILLS_DIR while fix(skills): resolve the skills root before computing the lock install path #64954 carries the current-main _skills_dir() form and both production changes.
• fix(skills): install_from_quarantine fails when HERMES_HOME is a symlink #49885 partial — (+87/-1) — n/a: Resolves only the lock-recording root and tests that path, leaving the matching CLI display failure; despite its keep_open verdict, its obsolete SKILLS_DIR hunk is a backend-only subset of fix(skills): resolve the skills root before computing the lock install path #64954.
• fix(skills): remove phantom slash commands from hermes-agent SKILL.md #50608 [closed] best fix — (+2/-3) — n/a: Removes the phantom /skill guidance and incorrect /q quit alias; although closed after a keep_open review, it remains the earliest recorded fix credited in merged fix(skills): accuracy + concision pass over the hermes-agent hub references #70511, which superseded its moved documentation.
• docs: fix hermes-agent skill slash command references #50613 [closed] partial — (+30/-2) — n/a: Makes the two primary slash-command corrections but leaves the troubleshooting /skill reference and adds a source-shape test; although closed after a keep_open review, its corrections landed through fix(skills): accuracy + concision pass over the hermes-agent hub references #70511 while the test was explicitly omitted.
• fix(skills): resolve paths before computing relative install path #53409 partial — (+33/-4) — n/a: Changes both symlink-sensitive production sites but uses obsolete SKILLS_DIR and bundles unrelated slash-command edits plus source-text tests; despite its keep_open verdict, fix(skills): resolve the skills root before computing the lock install path #64954 provides the focused current-main implementation and behavioral coverage.
• fix(skills): change here-now skill frontmatter name from dotted to hyphenated (#53382) #53447 best fix — (+24/-1) — n/a: Renames here.now to here-now and validates it through the production parser and validator, preserving its recorded best-fix status for the validator aspect; its keep_open salvage path must not claim to fix the non-reproducing official load premise or fix(skills): preserve official optional-skill frontmatter names #27471's separate identity mismatch.
• fix(skills): handle symlinked skills install paths #53493 partial — (+60/-3) — n/a: Uses a shared helper at both symlink-sensitive sites and adds backend coverage, but despite its keep_open verdict the helper uses obsolete SKILLS_DIR and the CLI completion path is untested, both addressed more completely by fix(skills): resolve the skills root before computing the lock install path #64954.
• fix(skills): resolve symlinks before relative_to in skill install #53541 partial — (+1/-1) — n/a: Applies the older backend-only resolved-root change without a regression or CLI-display repair; despite its keep_open verdict, the visible diff is subsumed by fix(skills): resolve the skills root before computing the lock install path #64954's current-main two-site implementation.
• docs: fix small skill and cli references #54444 best fix — (+8/-4) — n/a: Combines the recorded best existing Docs/compat: clarify hermes -z version boundary and timeout support for one-shot/chat CLI #25121 guidance with the here-now rename and slash-command corrections; its keep_open verdict supports salvage, but the Docs: hermes-agent SKILL.md documents phantom slash commands (/skill, /q) #50605 portion is already represented by merged fix(skills): accuracy + concision pass over the hermes-agent hub references #70511 and the independent CLI-compatibility portion should be split out.
• docs(cli): remove phantom slash commands #62933 [closed] fixes — (+2/-3) — n/a: Corrects all three phantom /skill and /q references; although closed, it remains relevant as an explicit duplicate of fix(skills): remove phantom slash commands from hermes-agent SKILL.md #50608 whose substantive outcome is now represented by merged fix(skills): accuracy + concision pass over the hermes-agent hub references #70511.
• fix(docs): remove phantom /skill and /q alias from hermes-agent SKILL.md #63451 [closed] fixes — (+134/-3) — n/a: Repeats the fix(skills): remove phantom slash commands from hermes-agent SKILL.md #50608 documentation correction with a large registry-oriented regression test; although closed, it remains relevant as voluntarily superseded duplicate work now represented by fix(skills): accuracy + concision pass over the hermes-agent hub references #70511.
• fix(skills): resolve the skills root before computing the lock install path #64954 best fix — (+98/-2) — n/a: The recorded best existing fix for Bug: skill install crashes with ValueError when SKILLS_DIR or install path contains a symlink #53403/[Bug]: skills install fails with false "Installation blocked" and orphans files when HERMES_HOME is a symlink #64953 uses current-main _skills_dir().resolve() for lock recording, resolves the CLI display root, and tests successful lock creation plus escape rejection, consistent with its keep_open verdict and reported 13-case rebase check.
• fix: resolve _skills_dir() for symlinked HERMES_HOME install paths (#64953) #65050 partial — (+1/-1) — n/a: Correctly changes current-main lock recording to _skills_dir().resolve() but leaves the CLI Installed: comparison and regressions untouched; despite its keep_open verdict, its visible diff is a strict backend-only subset of fix(skills): resolve the skills root before computing the lock install path #64954.
• fix(skills): accuracy + concision pass over the hermes-agent hub references #70511 [merged] best fix — (+280/-306) — n/a: Rebuilds the command references from the live registry, removes phantom /skill guidance, and assigns /q to /queue; although merged, it remains the reference implementation that supersedes the Docs: hermes-agent SKILL.md documents phantom slash commands (/skill, /q) #50605 documentation PRs.
• docs(skills): document /skill-name slash invocation in slash-commands.md #71295 related — (+11/-3) — n/a: Documents / invocation and distinguishes dynamic skill commands from COMMAND_REGISTRY; consistent with its keep_open verdict, the shown diff now addresses the contributor's objection by describing discovery as lazy, profile-aware, and inclusive of configured external directories.

Duplicates

#23251 duplicates #21739. For the symlink-root cause, #35630, #53409, #53493, and #64954 overlap at both production sites; #49885 and #53541 are older backend-only variants, and #65050 is the current-main backend-only subset of #64954. #50608, #50613, #62933, and #63451 substantially duplicate the correction delivered by #70511; #25501 overlaps the CLI-compatibility portion of #54444, and #53447 overlaps its here-now portion.

Suggested consolidation

Keep #71295 open with a salvage path preserving its corrected lazy, profile-aware dynamic-discovery wording; keep #64954 open with its current-main two-site fix and regressions, and keep #53447 only for the narrowly stated frontmatter-normalization path. Author action on #54444: split out the #25121 compatibility documentation; close #65050 as duplicate of #64954, and despite their keep_open reviews close #35630, #49885, #53409, #53493, and #53541 as duplicate or superseded variants because their visible diffs use obsolete path APIs, omit an affected site or equivalent coverage, or bundle unrelated work.

Cross-PR triage: Reviewed 18 pull requests and 7 issues in this complex. Each diff was read against this issue; Assessment working set: 97 kB of PR diffs, 49 kB of issue/PR text, 35 kB of discussion (51 comments), 36 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.