review skill: `./setup` linker only mirrors SKILL.md into ~/.claude/skills/review/ — supporting files (checklist.md, specialists/, greptile-triage.md) unreachable via Step 2 path

[erikgunawans]

Summary

On the Claude host, ./setup creates ~/.claude/skills/review/ and symlinks SKILL.md into it — but does NOT mirror the sibling support files (checklist.md, greptile-triage.md, specialists/, design-checklist.md). The SKILL.md's Step 2 instructs reading \.claude/skills/review/checklist.md`` which resolves to a path that doesn't exist. The skill hits its own STOP point on a clean global install:

Read .claude/skills/review/checklist.md.
If the file cannot be read, STOP and report the error. Do not proceed without the checklist.

Repro

Tested on gstack v1.35.0.0 global-git install at ~/.claude/skills/gstack, post-upgrade from v1.15.0.0.

# Fresh post-./setup state:
$ ls -la ~/.claude/skills/review/
total 0
drwxr-xr-x@   3 user  staff    96 ...
drwxr-xr-x  174 user  staff  5568 ...
lrwx------@   1 user  staff    65 ... SKILL.md -> /Users/.../.claude/skills/gstack/review/SKILL.md

# The supporting files referenced by SKILL.md live ONLY under gstack/:
$ ls ~/.claude/skills/gstack/review/
SKILL.md  SKILL.md.tmpl  TODOS-format.md  checklist.md  design-checklist.md  greptile-triage.md  specialists/

So when SKILL.md Step 2 says Read \.claude/skills/review/checklist.md``:

• Project-relative resolution → <project>/.claude/skills/review/checklist.md — doesn't exist for global-install users
• Tilde-relative → ~/.claude/skills/review/checklist.md — doesn't exist (only SKILL.md symlink is there)

The skill hits STOP and either bails or falls back to inline categories (the categories happen to be inlined in SKILL.md Step 4, so the skill still produces useful output — but Step 2's discipline is bypassed and the fallback isn't documented as intended).

Inconsistency inside the same SKILL.md

Step 2 uses the unprefixed path:

Read `.claude/skills/review/checklist.md`.

Step 4.5 uses the gstack-prefixed path and DOES resolve correctly:

Read `~/.claude/skills/gstack/review/specialists/testing.md`.

Both reference the same on-disk layout. Step 2 doesn't work; Step 4.5 does. Greptile triage (Step 2.5) and design-checklist (Step 4.5 design specialist) have the same Step-2-style problem if they're referenced via the unprefixed path.

Suggested fix

Two reasonable paths, both small:

Option A (smallest patch — fix SKILL.md only)

Rewrite Step 2's reference to match Step 4.5's style:

-Read `.claude/skills/review/checklist.md`.
+Read `~/.claude/skills/gstack/review/checklist.md`.

Same change for any other Step that uses the unprefixed surface (greptile-triage.md in Step 2.5).

Pro: one-line patch, no ./setup changes.
Con: doesn't help any other skill that may have similar sibling-asset references.

Option B (durable — fix the linker)

Teach ./setup's Claude-host linker to mirror sibling files into the linked-skills surface alongside SKILL.md. Specifically: for any directory in the linked skills set that has files other than SKILL.md, symlink them into the corresponding ~/.claude/skills/<skill>/ directory.

Pro: future-proof — works for any skill with multi-file layout.
Con: larger change; need to decide which files to mirror (everything? globbed allowlist? exclude *.tmpl?).

A hybrid is reasonable: ship Option A now to unblock global-install users immediately, file Option B as a follow-up.

Local workaround

For anyone hitting this before a fix lands:

ln -s ~/.claude/skills/gstack/review/checklist.md       ~/.claude/skills/review/checklist.md
ln -s ~/.claude/skills/gstack/review/greptile-triage.md ~/.claude/skills/review/greptile-triage.md
ln -s ~/.claude/skills/gstack/review/specialists        ~/.claude/skills/review/specialists

This may be wiped on the next ./setup run; re-applying is mechanical.

Environment

• gstack: v1.35.0.0 (HEAD 40e34deb)
• host: Claude Code (global-git install at ~/.claude/skills/gstack)
• Upgraded from: v1.15.0.0 (so this isn't a 1.15 regression — the path bug persists across the 20 releases since)
• macOS, bash 3.2 system shell

Related

Issue #1077 is a sibling concern on the Hermes host (prefix-mode path rewrites). This issue is specifically the Claude-host linker gap; the surface-paths and fix shape are different.