Skip to content

setup: Claude host installer drops review/qa/etc. runtime assets (only copies SKILL.md) #2454

Closed

Description

@BootCodex

Summary

./setup for the Claude host only copies each skill's SKILL.md (and a sections/ dir, if present) into ~/.claude/skills/<name>/. Skills whose SKILL.md reads sibling runtime files at a path like .claude/skills/<name>/<file> — review/, qa/, plan-devex-review/, gstack-upgrade/, careful/, freeze/ — end up broken after a clean install, because those files never get copied for the Claude host.

/review is the clearest case: its SKILL.md says "Read .claude/skills/review/checklist.md... If the file cannot be read, STOP and report the error," but that file is never installed for the Claude host, so /review cannot run its structured pipeline out of the box.

Root cause

link_claude_skill_dirs() in setup (around line 540) only handles SKILL.md and sections/:

# setup:566-579
_link_or_copy "$gstack_dir/$dir_name/SKILL.md" "$target/SKILL.md"
if [ -d "$gstack_dir/$dir_name/sections" ]; then
  ...
  _link_or_copy "$gstack_dir/$dir_name/sections" "$target/sections"
fi

Compare this to create_codex_runtime_root() (around line 808), create_factory_runtime_root() (~848), and create_opencode_runtime_root() (~890), which all explicitly copy review/'s runtime files:

# setup:808-816 (Codex host)
# Review runtime assets (individual files, NOT the whole review/ dir which has SKILL.md)
for f in checklist.md design-checklist.md greptile-triage.md TODOS-format.md; do
  if [ -f "$gstack_dir/review/$f" ]; then
    _link_or_copy "$gstack_dir/review/$f" "$codex_gstack/review/$f"
  fi
done

The Claude host (the primary target for most users) never got the equivalent treatment. This isn't Windows-specific — _link_or_copy falls back to cp there, but on macOS/Linux the same gap exists via ln -snf, since link_claude_skill_dirs simply never references these files at all for any platform.

Repro

cd ~/.claude/skills/gstack && ./setup   # default: --host claude
ls ~/.claude/skills/review/
# SKILL.md   <- only this. checklist.md, design-checklist.md,
#               greptile-triage.md, TODOS-format.md, specialists/ all missing

Then invoke /review in a project with a real diff: it hits Step 2 ("Read .claude/skills/review/checklist.md") and stops with "file cannot be read."

Affected skills (source has extra runtime files the Claude-host installer drops)

Skill Missing after ./setup
review checklist.md, design-checklist.md, greptile-triage.md, TODOS-format.md, specialists/
qa references/, templates/
plan-devex-review dx-hall-of-fame.md
gstack-upgrade migrations/
careful bin/
freeze bin/

(sections/ is handled correctly for cso, design-consultation, document-release, office-hours, plan-ceo-review, plan-design-review, plan-eng-review, ship, etc. — only non-sections/ extras are affected.)

Suggested fix

Generalize link_claude_skill_dirs() to copy any non-SKILL.md/SKILL.md.tmpl sibling (not just sections/), the way create_codex_runtime_root() already special-cases review/. Or extract the per-host "review runtime assets" list into a shared helper called from all five host installers (Claude, Codex, Factory, OpenCode, Kiro) instead of duplicating (and, in Claude's case, omitting) it per host.

Environment

  • gstack VERSION: 1.60.1.0
  • OS: Windows (MINGW64/Git Bash, MINGW64_NT-10.0-26200)
  • Host: claude (default, no --host flag)
  • ./setup run with no arguments

Activity

  1. added a commit that references this issue on Aug 17, 2026
    ae8914a
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions