fix(setup): namespace skill symlinks with gstack- prefix (#267, #284)

[LarHope]

Closes #267
Closes #284

The problem

gstack installs 27 skills as flat symlinks in ~/.claude/skills/ — names like review, ship, qa, browse. These are generic names that collide with other skill packs and make it impossible to tell which skills belong to gstack vs. something else.

Issue #267 (6 👍) and #284 (2 👍) have been asking for this — it's the #2 most-requested change by community reactions.

Every other skill pack uses namespaced names (superpowers:brainstorming, example-skills:pdf). gstack is the outlier dumping 27 generic names into the global namespace. As the ecosystem grows, this gets worse.

The fix (1 file, 51 lines)

The setup script now prefixes all Claude skill symlinks with gstack-:

Before: ~/.claude/skills/review    → gstack/review
After:  ~/.claude/skills/gstack-review → gstack/review

This matches what gstack already does for Codex via codexSkillName() — the Claude side was just missing the same treatment.

What's in the diff:

• link_claude_skill_dirs() applies gstack- prefix (skips gstack-upgrade to avoid double-prefix)
• New cleanup_old_claude_symlinks() removes stale flat symlinks on upgrade
• --no-prefix flag for users who want the old behavior

What's NOT in the diff: templates, docs, tests. Those come in a follow-up PR to keep this reviewable.

Backward compatibility

./setup	New default — prefixed names (gstack-review)
./setup --no-prefix	Opt-out — old flat names (review)
Upgrade path	Old symlinks auto-cleaned on re-run
Codex/Kiro	Unchanged (already prefixed)

How to test

cd ~/.claude/skills/gstack && ./setup
ls ~/.claude/skills/gstack-*     # ✓ gstack-review, gstack-ship, etc.
ls ~/.claude/skills/review 2>&1  # ✗ gone (cleaned up)

# Backward compat:
./setup --no-prefix
ls ~/.claude/skills/review       # ✓ restored

Follow-up

This is PR 1 of 2. A follow-up PR will update SKILL.md templates and docs to reference /gstack-review instead of /review. Kept separate to make each PR easy to review.

🤖 Generated with Claude Code

[n-scroggs]

Really clean approach to a problem I've been running into. I have a few custom skills alongside gstack and the flat namespace was causing me to second-guess which /review I was invoking. The gstack- prefix makes it immediately obvious.

The cleanup_old_claude_symlinks() migration is a nice touch — checking the symlink target with readlink before removing ensures it only cleans gstack's own links and won't accidentally nuke something else in the skills directory. Solid defensive coding.

One thing I noticed: the --no-prefix escape hatch is good for backward compat, but it might be worth documenting that in the main README too (not just the PR) so people upgrading from older installs know the option exists.

[s-neidert]

This is overdue. Managing a shared ~/.claude/skills/ namespace across multiple skill packs is exactly the kind of thing that causes subtle breakage at scale — you don't notice the collision until someone's /review triggers the wrong skill and they spend 30 minutes debugging it.

The fact that Codex already uses prefixed names via codexSkillName() makes this even more of a no-brainer — it's just bringing the Claude side to parity. Keeping the change to a single file also makes it easy to review and low-risk to merge.

👍 from me. Would be good to get the follow-up PR with the SKILL.md template updates soon so the slash command references stay in sync.

[LarHope]

I have a follow-up PR ready that updates all 28 SKILL.md templates, resolver TypeScript files, and documentation (README, docs/skills.md, CLAUDE.md, CONTRIBUTING.md, ARCHITECTURE.md) to use the new /gstack-review invocation format consistently.

Happy to submit it once this lands, or happy to let the team handle the alignment if you'd prefer to do it as part of a wave. Just let me know which you'd prefer.