garrytan / garrytan/gstack

gen:skill-docs --host hermes: directory is gstack-<skill>, frontmatter name is <skill> — Hermes indexes by frontmatter

Open
#2,825 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.