gen:skill-docs --host hermes: directory is gstack-<skill>, frontmatter name is <skill> — Hermes indexes by frontmatter
- Dominant language
- TypeScript
- Stars
- 133k
- Forks
- 19.9k
- Avg merge
- 18h 46m
- Merged PRs (30d)
- 26
Description
## What happens
`bun run gen:skill-docs --host hermes` writes each skill to `.hermes/skills/gstack-/SKILL.md` — `externalSkillName()` in `scripts/gen-skill-docs.ts:190-198` adds the `gstack-` prefix to the directory. The frontmatter inside keeps the bare name:
```
$ grep -m1 '^name:' .hermes/skills/gstack-retro/SKILL.md
name: retro
$ grep -m1 '^name:' .hermes/skills/gstack-review/SKILL.md
name: review
```
Hermes indexes and de-duplicates skills by frontmatter `name`, not by directory (`tools/skills_tool.py`, first match wins across project → local → external tiers). So the prefix the generator computes never reaches the skill list: a seat sees `retro`, `review`, `health`, `benchmark`, and any other skill with one of those generic names shadows gstack's silently — no second row, no warning.
The Claude install path already solves this: `setup --prefix` rewrites the frontmatter `name:` to `gstack-` (`~/.claude/skills/gstack-retro/SKILL.md` carries `name: gstack-retro`).
## Ask
Have the Hermes render (and the other `.agents`-layout hosts, if they index by frontmatter too) write the same name into frontmatter that `externalSkillName()` gives the directory — or take a `--prefix` flag on `gen:skill-docs` mirroring `setup --prefix`.
## Measured on
gstack 1.68.2 at `51932ec`, Hermes 0.21.0 (`skills.external_dirs` pointing at individual render directories), macOS arm64. We currently carry the prefix across with a post-generation rewrite of the `name:` line; it would become a no-op with this change.
Contributor guide
Research direction
Start in scripts/gen-skill-docs.ts around externalSkillName() at lines 190-198, then read the indexing behavior in tools/skills_tool.py. Run bun run gen:skill-docs --host hermes and inspect the generated .hermes/skills directories and SKILL.md files. Done means the frontmatter name matches the generated directory name so gstack skills are not silently shadowed.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- bun, python, typescript
- Domain
- tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 74/100