docs: update symlink references to new top-level directory pattern

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CHANGELOG.md

@@ -9,6 +9,10 @@ You can now run `/design-html` without having to run `/design-shotgun` first. Th
 - **`/design-html` works from any starting point.** Three routing modes: (A) approved mockup from /design-shotgun, (B) CEO plan and/or design variants without formal approval, (C) clean slate with just a description. Each mode asks the right questions and proceeds accordingly.
 - **AskUserQuestion for missing context.** Instead of blocking with "no approved design found," the skill now offers choices: run the planning skills first, provide a PNG, or just describe what you want and design live.
 
+### Fixed
+
+- **Skills now discovered as top-level names.** Setup creates real directories with SKILL.md symlinks inside instead of directory symlinks. This fixes Claude auto-prefixing skill names with `gstack-` when using `--no-prefix` mode. `/qa` is now just `/qa`, not `/gstack-qa`.
+
 ## [0.15.0.0] - 2026-04-01 — Session Intelligence
 
 Your AI sessions now remember what happened. Plans, reviews, checkpoints, and health scores survive context compaction and compound across sessions. Every skill writes a timeline event, and the preamble reads recent artifacts on startup so the agent knows where you left off.

CLAUDE.md

@@ -181,11 +181,13 @@ symlink or a real copy. If it's a symlink to your working directory, be aware th
 - During large refactors, remove the symlink (`rm .claude/skills/gstack`) so the
   global install at `~/.claude/skills/gstack/` is used instead
 
-**Prefix setting:** Skill symlinks use either short names (`qa -> gstack/qa`) or
-namespaced (`gstack-qa -> gstack/qa`), controlled by `skill_prefix` in
-`~/.gstack/config.yaml`. When vendoring into a project, run `./setup` after
-symlinking to create the per-skill symlinks with your preferred naming. Pass
-`--no-prefix` or `--prefix` to skip the interactive prompt.
+**Prefix setting:** Setup creates real directories (not symlinks) at the top level
+with a SKILL.md symlink inside (e.g., `qa/SKILL.md -> gstack/qa/SKILL.md`). This
+ensures Claude discovers them as top-level skills, not nested under `gstack/`.
+Names are either short (`qa`) or namespaced (`gstack-qa`), controlled by
+`skill_prefix` in `~/.gstack/config.yaml`. When vendoring into a project, run
+`./setup` after symlinking to create the per-skill directories. Pass `--no-prefix`
+or `--prefix` to skip the interactive prompt.
 
 **For plan reviews:** When reviewing plans that modify skill templates or the
 gen-skill-docs pipeline, consider whether the changes should be tested in isolation

CONTRIBUTING.md

@@ -40,8 +40,8 @@ No setup needed. Learnings are logged automatically. View them with `/learn`.
    ln -sfn /path/to/your/gstack-fork .claude/skills/gstack
    cd .claude/skills/gstack && bun install && bun run build && ./setup
    ```
-   Setup creates the per-skill symlinks (`qa -> gstack/qa`, etc.) and asks your
-   prefix preference. Pass `--no-prefix` to skip the prompt and use short names.
+   Setup creates per-skill directories with SKILL.md symlinks inside (`qa/SKILL.md -> gstack/qa/SKILL.md`)
+   and asks your prefix preference. Pass `--no-prefix` to skip the prompt and use short names.
 5. **Fix the issue** — your changes are live immediately in this project
 6. **Test by actually using gstack** — do the thing that annoyed you, verify it's fixed
 7. **Open a PR from your fork**
@@ -64,9 +64,11 @@ your local edits instead of the global install.
 gstack/                          <- your working tree
 ├── .claude/skills/              <- created by dev-setup (gitignored)
 │   ├── gstack -> ../../         <- symlink back to repo root
-│   ├── review -> gstack/review  <- short names (default)
-│   ├── ship -> gstack/ship      <- or gstack-review, gstack-ship if --prefix
-│   └── ...                      <- one symlink per skill
+│   ├── review/                  <- real directory (short name, default)
+│   │   └── SKILL.md -> gstack/review/SKILL.md
+│   ├── ship/                    <- or gstack-review/, gstack-ship/ if --prefix
+│   │   └── SKILL.md -> gstack/ship/SKILL.md
+│   └── ...                      <- one directory per skill
 ├── review/
 │   └── SKILL.md                 <- edit this, test with /review
 ├── ship/
@@ -77,7 +79,9 @@ gstack/                          <- your working tree
 └── ...
 ```
 
-Skill symlink names depend on your prefix setting (`~/.gstack/config.yaml`).
+Setup creates real directories (not symlinks) at the top level with a SKILL.md
+symlink inside. This ensures Claude discovers them as top-level skills, not nested
+under `gstack/`. Names depend on your prefix setting (`~/.gstack/config.yaml`).
 Short names (`/review`, `/ship`) are the default. Run `./setup --prefix` if you
 prefer namespaced names (`/gstack-review`, `/gstack-ship`).
 
@@ -320,7 +324,7 @@ ln -sfn /path/to/your/gstack-checkout .claude/skills/gstack
 ### Step 2: Run setup to create per-skill symlinks
 
 The `gstack` symlink alone isn't enough. Claude Code discovers skills through
-individual symlinks (`qa -> gstack/qa`, `ship -> gstack/ship`, etc.), not through
+individual top-level directories (`qa/SKILL.md`, `ship/SKILL.md`, etc.), not through
 the `gstack/` directory itself. Run `./setup` to create them:
 
 ```bash
@@ -344,8 +348,8 @@ Remove the project-local symlink. Claude Code falls back to `~/.claude/skills/gs
 rm .claude/skills/gstack
 ```
 
-The per-skill symlinks (`qa`, `ship`, etc.) still point to `gstack/...`, so they'll
-resolve to the global install automatically.
+The per-skill directories (`qa/`, `ship/`, etc.) contain SKILL.md symlinks that point
+to `gstack/...`, so they'll resolve to the global install automatically.
 
 ### Switching prefix mode