From 3a14944a47f25caa1989f7a1935c9f6f17df07b9 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Thu, 2 Apr 2026 18:16:04 -0700 Subject: [PATCH] docs: update symlink references to new top-level directory pattern Co-Authored-By: Claude Opus 4.6 --- CHANGELOG.md | 4 ++++ CLAUDE.md | 12 +++++++----- CONTRIBUTING.md | 22 +++++++++++++--------- 3 files changed, 24 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 27d2c0c6..387c6d41 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/CLAUDE.md b/CLAUDE.md index 362b8f32..db9630fe 100644 --- a/CLAUDE.md +++ b/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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fcb9c279..96131ecf 100644 --- a/CONTRIBUTING.md +++ b/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