diff --git a/.agents/skills/gstack-plan-ceo-review/SKILL.md b/.agents/skills/gstack-plan-ceo-review/SKILL.md
index 46e2e678..6878cb0d 100644
--- a/.agents/skills/gstack-plan-ceo-review/SKILL.md
+++ b/.agents/skills/gstack-plan-ceo-review/SKILL.md
@@ -711,7 +711,7 @@ Complete table of every method that can fail, every exception class, rescued sta
 Any row with RESCUED=N, TEST=N, USER SEES=Silent → **CRITICAL GAP**.
 
 ### TODOS.md updates
-Present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step. Follow the format in `.agents/skills/gstack-review/TODOS-format.md`.
+Present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step. Follow the format in `.agents/skills/gstack/review/TODOS-format.md`.
 
 For each TODO, describe:
 * **What:** One-line description of the work.
diff --git a/.agents/skills/gstack-plan-eng-review/SKILL.md b/.agents/skills/gstack-plan-eng-review/SKILL.md
index 367a51d2..77513680 100644
--- a/.agents/skills/gstack-plan-eng-review/SKILL.md
+++ b/.agents/skills/gstack-plan-eng-review/SKILL.md
@@ -333,7 +333,7 @@ Every plan review MUST produce a "NOT in scope" section listing work that was co
 List existing code/flows that already partially solve sub-problems in this plan, and whether the plan reuses them or unnecessarily rebuilds them.
 
 ### TODOS.md updates
-After all review sections are complete, present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step. Follow the format in `.agents/skills/gstack-review/TODOS-format.md`.
+After all review sections are complete, present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step. Follow the format in `.agents/skills/gstack/review/TODOS-format.md`.
 
 For each TODO, describe:
 * **What:** One-line description of the work.
diff --git a/.agents/skills/gstack-review/SKILL.md b/.agents/skills/gstack-review/SKILL.md
index 0584f558..6e4df188 100644
--- a/.agents/skills/gstack-review/SKILL.md
+++ b/.agents/skills/gstack-review/SKILL.md
@@ -214,7 +214,7 @@ Before reviewing code quality, check: **did they build what was requested — no
 
 ## Step 2: Read the checklist
 
-Read `.agents/skills/gstack-review/checklist.md`.
+Read `.agents/skills/gstack/review/checklist.md`.
 
 **If the file cannot be read, STOP and report the error.** Do not proceed without the checklist.
 
@@ -222,7 +222,7 @@ Read `.agents/skills/gstack-review/checklist.md`.
 
 ## Step 2.5: Check for Greptile review comments
 
-Read `.agents/skills/gstack-review/greptile-triage.md` and follow the fetch, filter, classify, and **escalation detection** steps.
+Read `.agents/skills/gstack/review/greptile-triage.md` and follow the fetch, filter, classify, and **escalation detection** steps.
 
 **If no PR exists, `gh` fails, API returns an error, or there are zero Greptile comments:** Skip this step silently. Greptile integration is additive — the review works without it.
 
@@ -271,7 +271,7 @@ eval $(~/.codex/skills/gstack/bin/gstack-diff-scope <base> 2>/dev/null)
 
 1. **Check for DESIGN.md.** If `DESIGN.md` or `design-system.md` exists in the repo root, read it. All design findings are calibrated against it — patterns blessed in DESIGN.md are not flagged. If not found, use universal design principles.
 
-2. **Read `.agents/skills/gstack-review/design-checklist.md`.** If the file cannot be read, skip design review with a note: "Design checklist not found — skipping design review."
+2. **Read `.agents/skills/gstack/review/design-checklist.md`.** If the file cannot be read, skip design review with a note: "Design checklist not found — skipping design review."
 
 3. **Read each changed frontend file** (full file, not just diff hunks). Frontend files are identified by the patterns listed in the checklist.
 
diff --git a/.agents/skills/gstack-ship/SKILL.md b/.agents/skills/gstack-ship/SKILL.md
index 33270a07..814c27b0 100644
--- a/.agents/skills/gstack-ship/SKILL.md
+++ b/.agents/skills/gstack-ship/SKILL.md
@@ -660,7 +660,7 @@ Coverage line: `Test Coverage Audit: N new code paths. M covered (X%). K tests g
 
 Review the diff for structural issues that tests don't catch.
 
-1. Read `.agents/skills/gstack-review/checklist.md`. If the file cannot be read, **STOP** and report the error.
+1. Read `.agents/skills/gstack/review/checklist.md`. If the file cannot be read, **STOP** and report the error.
 
 2. Run `git diff origin/<base>` to get the full diff (scoped to feature changes against the freshly-fetched base branch).
 
@@ -682,7 +682,7 @@ eval $(~/.codex/skills/gstack/bin/gstack-diff-scope <base> 2>/dev/null)
 
 1. **Check for DESIGN.md.** If `DESIGN.md` or `design-system.md` exists in the repo root, read it. All design findings are calibrated against it — patterns blessed in DESIGN.md are not flagged. If not found, use universal design principles.
 
-2. **Read `.agents/skills/gstack-review/design-checklist.md`.** If the file cannot be read, skip design review with a note: "Design checklist not found — skipping design review."
+2. **Read `.agents/skills/gstack/review/design-checklist.md`.** If the file cannot be read, skip design review with a note: "Design checklist not found — skipping design review."
 
 3. **Read each changed frontend file** (full file, not just diff hunks). Frontend files are identified by the patterns listed in the checklist.
 
@@ -731,7 +731,7 @@ Save the review output — it goes into the PR body in Step 8.
 
 ## Step 3.75: Address Greptile review comments (if PR exists)
 
-Read `.agents/skills/gstack-review/greptile-triage.md` and follow the fetch, filter, classify, and **escalation detection** steps.
+Read `.agents/skills/gstack/review/greptile-triage.md` and follow the fetch, filter, classify, and **escalation detection** steps.
 
 **If no PR exists, `gh` fails, API returns an error, or there are zero Greptile comments:** Skip this step silently. Continue to Step 4.
 
@@ -854,7 +854,7 @@ If Codex is not available, skip silently. Continue to Step 4.
 
 Cross-reference the project's TODOS.md against the changes being shipped. Mark completed items automatically; prompt only if the file is missing or disorganized.
 
-Read `.agents/skills/gstack-review/TODOS-format.md` for the canonical format reference.
+Read `.agents/skills/gstack/review/TODOS-format.md` for the canonical format reference.
 
 **1. Check if TODOS.md exists** in the repository root.
 
diff --git a/scripts/gen-skill-docs.ts b/scripts/gen-skill-docs.ts
index 73fc6df6..ec667198 100644
--- a/scripts/gen-skill-docs.ts
+++ b/scripts/gen-skill-docs.ts
@@ -1355,7 +1355,7 @@ function processTemplate(tmplPath: string, host: Host = 'claude'): { outputPath:
     // Replace remaining hardcoded Claude paths with host-appropriate paths
     content = content.replace(/~\/\.claude\/skills\/gstack/g, ctx.paths.skillRoot);
     content = content.replace(/\.claude\/skills\/gstack/g, ctx.paths.localSkillRoot);
-    content = content.replace(/\.claude\/skills\/review/g, '.agents/skills/gstack-review');
+    content = content.replace(/\.claude\/skills\/review/g, '.agents/skills/gstack/review');
     content = content.replace(/\.claude\/skills/g, '.agents/skills');
   }
 
diff --git a/setup b/setup
index 10fd6742..66a38412 100755
--- a/setup
+++ b/setup
@@ -91,8 +91,8 @@ fi
 # 3. Ensure ~/.gstack global state directory exists
 mkdir -p "$HOME/.gstack/projects"
 
-# ─── Helper: link skill subdirectories into a skills parent directory ──
-link_skill_dirs() {
+# ─── Helper: link Claude skill subdirectories into a skills parent directory ──
+link_claude_skill_dirs() {
   local gstack_dir="$1"
   local skills_dir="$2"
   local linked=()
@@ -114,6 +114,36 @@ link_skill_dirs() {
   fi
 }
 
+# ─── Helper: link generated Codex skills into a skills parent directory ──
+# Installs from .agents/skills/gstack-* (the generated Codex-format skills)
+# instead of source dirs (which have Claude paths).
+link_codex_skill_dirs() {
+  local gstack_dir="$1"
+  local skills_dir="$2"
+  local agents_dir="$gstack_dir/.agents/skills"
+  local linked=()
+
+  if [ ! -d "$agents_dir" ]; then
+    echo "  warning: no .agents/skills/ directory found — run 'bun run build' first" >&2
+    return 1
+  fi
+
+  for skill_dir in "$agents_dir"/gstack*/; do
+    if [ -f "$skill_dir/SKILL.md" ]; then
+      skill_name="$(basename "$skill_dir")"
+      target="$skills_dir/$skill_name"
+      # Create or update symlink
+      if [ -L "$target" ] || [ ! -e "$target" ]; then
+        ln -snf "$skill_dir" "$target"
+        linked+=("$skill_name")
+      fi
+    fi
+  done
+  if [ ${#linked[@]} -gt 0 ]; then
+    echo "  linked skills: ${linked[*]}"
+  fi
+}
+
 # ─── Helper: create .agents/skills/gstack/ sidecar symlinks ──────────
 # Codex/Gemini/Cursor read skills from .agents/skills/. We link runtime
 # assets (bin/, browse/dist/, review/, qa/, etc.) so skill templates can
@@ -139,7 +169,7 @@ create_agents_sidecar() {
 SKILLS_BASENAME="$(basename "$SKILLS_DIR")"
 if [ "$INSTALL_CLAUDE" -eq 1 ]; then
   if [ "$SKILLS_BASENAME" = "skills" ]; then
-    link_skill_dirs "$GSTACK_DIR" "$SKILLS_DIR"
+    link_claude_skill_dirs "$GSTACK_DIR" "$SKILLS_DIR"
     echo "gstack ready (claude)."
     echo "  browse: $BROWSE_BIN"
   else
@@ -155,11 +185,12 @@ if [ "$INSTALL_CODEX" -eq 1 ]; then
   CODEX_GSTACK="$CODEX_SKILLS/gstack"
   mkdir -p "$CODEX_SKILLS"
 
-  # Symlink or copy gstack into ~/.codex/skills/gstack
+  # Symlink gstack source for runtime assets (bin/, browse/dist/)
   if [ -L "$CODEX_GSTACK" ] || [ ! -e "$CODEX_GSTACK" ]; then
     ln -snf "$GSTACK_DIR" "$CODEX_GSTACK"
   fi
-  link_skill_dirs "$GSTACK_DIR" "$CODEX_SKILLS"
+  # Install generated Codex-format skills (not Claude source dirs)
+  link_codex_skill_dirs "$GSTACK_DIR" "$CODEX_SKILLS"
 
   echo "gstack ready (codex)."
   echo "  browse: $BROWSE_BIN"