elliot-stack 1.0.22 → 1.0.24

package/README.md

@@ -11,7 +11,7 @@ A curated set of Claude Code skills by Elliot Drel. One command installs them al
 npx elliot-stack@latest
 ```
 
-This copies skills to `~/.claude/skills/` and registers a `SessionStart` hook so your skills stay up to date automatically.
+This installs skills to `~/.agents/skills/` and symlinks them into `~/.claude/skills/`, then registers a `SessionStart` hook so your skills stay up to date automatically.
 
 ## Skills
 
@@ -34,10 +34,11 @@ Hooks install to `~/.claude/hooks/` and are auto-registered in your `~/.claude/s
 
 ## How it works
 
-- Skills install to `~/.claude/skills/estack-*/`
+- Skills install to `~/.agents/skills/estack-*/` (symlinked from `~/.claude/skills/estack-*/`)
 - Hooks install to `~/.claude/hooks/` and are registered in `~/.claude/settings.json`
 - A `SessionStart` hook auto-updates both each time you open Claude Code
 - If you've made local edits to a skill or hook, the installer detects the conflict and lets you choose: overwrite, skip, or merge
+- Every skill carries its own semver (`version:` in SKILL.md frontmatter; hooks use a `// @version` comment), independent of the package version — update messages show exactly what moved, e.g. `estack-chris-voss (1.0.0 → 1.1.0)`. Under the hood, updates are detected by content hash, so a change can never be missed; a release-time check (`scripts/check-versions.cjs`) guarantees every content change ships with a version bump.
 
 ## Updating
 
@@ -62,10 +63,10 @@ Run the installer straight from your checkout to preview what a real install wou
 
 ```bash
 node bin/install.cjs            # dry run — previews changes, writes nothing
-node bin/install.cjs --install  # actually sync your local edits to ~/.claude/skills/
+node bin/install.cjs --install  # actually sync your local edits to ~/.agents/skills/ + ~/.claude/skills/
 ```
 
-Run from the repo, the installer **dry-runs by default** so testing never clobbers your live `~/.claude/skills/` install. Pass `--install` once the preview looks right. (`--dry-run` forces a preview even under `npx`.)
+Run from the repo, the installer **dry-runs by default** so testing never clobbers your live install. Pass `--install` once the preview looks right. (`--dry-run` forces a preview even under `npx`.)
 
 See [`docs/publishing.md`](docs/publishing.md) for the release flow and security model.
 

package/bin/install.cjs

@@ -11,6 +11,8 @@ const readline = require('readline');
 const HOME = os.homedir();
 const CLAUDE_DIR = path.join(HOME, '.claude');
 const SKILLS_DIR = path.join(CLAUDE_DIR, 'skills');
+const AGENTS_ROOT = path.join(HOME, '.agents');
+const AGENTS_DIR = path.join(AGENTS_ROOT, 'skills');
 const BACKUP_DIR = path.join(HOME, '.estack-backup');
 const CHECKSUMS_FILE = path.join(CLAUDE_DIR, '.estack-checksums.json');
 const SETTINGS_FILE = path.join(CLAUDE_DIR, 'settings.json');
@@ -60,6 +62,67 @@ const PACKAGE_HOOKS_DIR = path.join(__dirname, '..', 'hooks');
   }
 })();
 
+// ── Migrate skills from ~/.agents/<name> (v1.0.23 layout) to ~/.agents/skills/ ──
+(function migrateAgentsLayout() {
+  let strays;
+  try {
+    // statSync guards against ~/.agents existing as a plain file
+    if (!fs.existsSync(AGENTS_ROOT) || !fs.statSync(AGENTS_ROOT).isDirectory()) return;
+    strays = fs.readdirSync(AGENTS_ROOT, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && e.name.startsWith('estack-'));
+  } catch (_) {
+    return; // unreadable — let main() surface a real error if it matters
+  }
+  if (strays.length === 0) return;
+  const silent = process.argv.includes('--silent');
+  const isDryRun = process.argv.includes('--dry-run') ||
+    (!__dirname.includes('node_modules') && !process.argv.includes('--install'));
+  if (isDryRun) {
+    if (!silent) {
+      process.stderr.write(
+        'estack: [dry run] Would move ' + strays.length + ' skill(s) from ~/.agents/ to ~/.agents/skills/\n'
+      );
+    }
+    return;
+  }
+  try {
+    fs.mkdirSync(AGENTS_DIR, { recursive: true });
+  } catch (err) {
+    process.stderr.write(
+      'estack: WARNING — could not create ~/.agents/skills/: ' + err.message + '\n'
+    );
+    return;
+  }
+  for (const e of strays) {
+    const oldPath = path.join(AGENTS_ROOT, e.name);
+    const newPath = path.join(AGENTS_DIR, e.name);
+    try {
+      if (fs.existsSync(newPath)) {
+        // already migrated — drop the stale copy at the old location
+        fs.rmSync(oldPath, { recursive: true, force: true });
+      } else {
+        try {
+          fs.renameSync(oldPath, newPath);
+        } catch (_) {
+          copyDirRaw(oldPath, newPath);
+          removeDirRaw(oldPath);
+        }
+      }
+      // re-point the live symlink — the old junction now dangles
+      ensureSymlink(newPath, path.join(SKILLS_DIR, e.name));
+    } catch (err) {
+      process.stderr.write(
+        'estack: WARNING — could not migrate ' + e.name + ' to ~/.agents/skills/: ' + err.message + '\n'
+      );
+    }
+  }
+  if (!silent) {
+    process.stderr.write(
+      'estack: moved ' + strays.length + ' skill(s) from ~/.agents/ to ~/.agents/skills/\n'
+    );
+  }
+})();
+
 function copyDirRaw(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
@@ -79,6 +142,38 @@ function removeDirRaw(dir) {
   fs.rmdirSync(dir);
 }
 
+function isSymlink(p) {
+  try { return fs.lstatSync(p).isSymbolicLink(); } catch (_) { return false; }
+}
+
+// True only for a real directory at p — not a symlink to one, not a file.
+function isRealDir(p) {
+  try {
+    const stat = fs.lstatSync(p);
+    return stat.isDirectory() && !stat.isSymbolicLink();
+  } catch (_) {
+    return false;
+  }
+}
+
+// Creates (or updates) a directory symlink at linkPath pointing to target.
+// On Windows uses 'junction' (no elevation required); on Unix uses 'dir'.
+function ensureSymlink(target, linkPath) {
+  try {
+    const stat = fs.lstatSync(linkPath);
+    if (stat.isSymbolicLink()) {
+      if (path.resolve(fs.readlinkSync(linkPath)) === path.resolve(target)) return;
+      fs.unlinkSync(linkPath);
+    } else {
+      // real dir, plain file, or anything else occupying the link path
+      fs.rmSync(linkPath, { recursive: true, force: true });
+    }
+  } catch (_) {}
+  fs.mkdirSync(path.dirname(linkPath), { recursive: true });
+  const type = process.platform === 'win32' ? 'junction' : 'dir';
+  fs.symlinkSync(target, linkPath, type);
+}
+
 // ── Flags ──────────────────────────────────────────────────────────────────
 const SILENT = process.argv.includes('--silent');
 const STARTUP = process.argv.includes('--startup');
@@ -127,7 +222,12 @@ function computeFileHash(filePath) {
 }
 
 function computeSkillHash(skillDir) {
-  if (!fs.existsSync(skillDir)) return null;
+  // statSync (not lstat) so symlinked dirs hash their contents; plain files → null
+  try {
+    if (!fs.statSync(skillDir).isDirectory()) return null;
+  } catch (_) {
+    return null;
+  }
   const hash = crypto.createHash('sha256');
   const files = walkDir(skillDir, skillDir);
   for (const relPath of files) {
@@ -147,7 +247,8 @@ function copyDir(src, dest) {
 }
 
 function backupSkill(name) {
-  const installedDir = path.join(SKILLS_DIR, name);
+  const agentsDir = path.join(AGENTS_DIR, name);
+  const installedDir = fs.existsSync(agentsDir) ? agentsDir : path.join(SKILLS_DIR, name);
   if (!fs.existsSync(installedDir)) return;
   fs.mkdirSync(BACKUP_DIR, { recursive: true });
   copyDir(installedDir, path.join(BACKUP_DIR, name));
@@ -201,18 +302,65 @@ function getSkillDescription(skillDir) {
   const skillMd = path.join(skillDir, 'SKILL.md');
   if (!fs.existsSync(skillMd)) return '';
   const content = fs.readFileSync(skillMd, 'utf8');
-  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
   if (!frontmatterMatch) return '';
   const fm = frontmatterMatch[1];
-  const singleLine = fm.match(/^description:\s*(.+)$/m);
-  if (singleLine) return singleLine[1].trim();
-  const multiLine = fm.match(/^description:\s*>\n((?:\s+.+\n?)+)/m);
+  const singleLine = fm.match(/^description:\s*(\S.*)$/m);
+  if (singleLine && !/^[>|]/.test(singleLine[1])) return singleLine[1].trim();
+  const multiLine = fm.match(/^description:\s*[>|][->+]?\r?\n((?:[ \t]+.*\r?\n?)+)/m);
   if (multiLine) {
     return multiLine[1].replace(/\s+/g, ' ').trim();
   }
   return '';
 }
 
+// Per-skill version from SKILL.md frontmatter (`version: x.y.z`).
+// Versions are the human-readable label; content hashes remain the
+// update-detection source of truth (scripts/check-versions.cjs keeps them in sync).
+function getSkillVersion(skillDir) {
+  const skillMd = path.join(skillDir, 'SKILL.md');
+  if (!fs.existsSync(skillMd)) return null;
+  const content = fs.readFileSync(skillMd, 'utf8');
+  const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!frontmatterMatch) return null;
+  const m = frontmatterMatch[1].match(/^version:\s*(\S+)\s*$/m);
+  return m ? m[1] : null;
+}
+
+// Version of the currently installed copy of a skill (agents dir, falling
+// back to the legacy skills dir for pre-migration installs).
+function getInstalledSkillVersion(name) {
+  const agentsDir = path.join(AGENTS_DIR, name);
+  if (fs.existsSync(agentsDir)) return getSkillVersion(agentsDir);
+  return getSkillVersion(path.join(SKILLS_DIR, name));
+}
+
+// Per-hook version from a `// @version x.y.z` comment near the top.
+function getHookVersion(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const m = fs.readFileSync(filePath, 'utf8').match(/^\/\/ @version\s+(\S+)\s*$/m);
+  return m ? m[1] : null;
+}
+
+// "name (1.0.0 → 1.1.0)" for updates, "name (v1.1.0)" for fresh installs.
+function withVersion(name, oldV, newV) {
+  if (oldV && newV && oldV !== newV) return name + ' (' + oldV + ' → ' + newV + ')';
+  if (newV) return name + ' (v' + newV + ')';
+  return name;
+}
+
+// Copies a skill to ~/.agents/skills/<name> and creates/updates the symlink at ~/.claude/skills/<name>.
+// If a real (non-symlink) directory already exists at the skills path, it is removed first.
+function installSkillFiles(name) {
+  const agentsSkillDir = path.join(AGENTS_DIR, name);
+  const skillsLinkDir = path.join(SKILLS_DIR, name);
+  if (!isSymlink(skillsLinkDir) && fs.existsSync(skillsLinkDir)) {
+    fs.rmSync(skillsLinkDir, { recursive: true, force: true });
+  }
+  copyDir(path.join(PACKAGE_SKILLS_DIR, name), agentsSkillDir);
+  ensureSymlink(agentsSkillDir, skillsLinkDir);
+}
+
 // ── Hook setup ─────────────────────────────────────────────────────────────
 
 // Returns true if the hook was added (or would be added in dryRun), false if
@@ -310,15 +458,26 @@ function setupRepoSearchNudgeHook(dryRun) {
 
 async function main() {
   // 0. Remove deprecated skills (renamed/deleted from the package)
-  if (fs.existsSync(SKILLS_DIR)) {
+  if (fs.existsSync(SKILLS_DIR) || fs.existsSync(AGENTS_DIR)) {
     const newChecksums0 = fs.existsSync(CHECKSUMS_FILE)
       ? (() => { try { return JSON.parse(fs.readFileSync(CHECKSUMS_FILE, 'utf8')); } catch (_) { return {}; } })()
       : {};
     let changed = false;
     for (const name of DEPRECATED_SKILLS) {
-      const dir = path.join(SKILLS_DIR, name);
-      if (fs.existsSync(dir)) {
-        if (!DRY_RUN) fs.rmSync(dir, { recursive: true, force: true });
+      const agentsDir = path.join(AGENTS_DIR, name);
+      const skillsDir = path.join(SKILLS_DIR, name);
+      let found = false;
+      if (fs.existsSync(agentsDir)) {
+        if (!DRY_RUN) fs.rmSync(agentsDir, { recursive: true, force: true });
+        found = true;
+      }
+      if (fs.existsSync(skillsDir) || isSymlink(skillsDir)) {
+        if (!DRY_RUN) {
+          try { fs.unlinkSync(skillsDir); } catch (_) { fs.rmSync(skillsDir, { recursive: true, force: true }); }
+        }
+        found = true;
+      }
+      if (found) {
         delete newChecksums0[name];
         changed = true;
         if (!SILENT && !STARTUP) {
@@ -329,7 +488,10 @@ async function main() {
         changed = true;
       }
     }
-    if (changed && !DRY_RUN) fs.writeFileSync(CHECKSUMS_FILE, JSON.stringify(newChecksums0, null, 2));
+    if (changed && !DRY_RUN) {
+      fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+      fs.writeFileSync(CHECKSUMS_FILE, JSON.stringify(newChecksums0, null, 2));
+    }
   }
 
   // 1. Scan package skills
@@ -377,11 +539,21 @@ async function main() {
   }
 
   // 4. Detect local modifications and needed updates
+  // Real files live in AGENTS_DIR; fall back to SKILLS_DIR for pre-migration installs.
   const modifiedSkills = [];
   const needsUpdate = [];
   for (const name of skillNames) {
-    const installedDir = path.join(SKILLS_DIR, name);
-    if (!fs.existsSync(installedDir)) {
+    const agentsSkillDir = path.join(AGENTS_DIR, name);
+    let installedDir = null;
+    if (fs.existsSync(agentsSkillDir)) {
+      installedDir = agentsSkillDir;
+    } else {
+      const legacyDir = path.join(SKILLS_DIR, name);
+      if (isRealDir(legacyDir)) {
+        installedDir = legacyDir; // old-style install, will be migrated on next write
+      }
+    }
+    if (!installedDir) {
       needsUpdate.push(name);
       continue;
     }
@@ -437,12 +609,13 @@ async function main() {
         hooksNeedingUpdate.length === 0 && modifiedHooks.length === 0) {
       process.exit(0);
     }
+    fs.mkdirSync(AGENTS_DIR, { recursive: true });
     fs.mkdirSync(SKILLS_DIR, { recursive: true });
     const newChecksums = Object.assign({}, storedChecksums);
     for (const name of skillNames) {
       if (modifiedSkills.includes(name)) continue;
-      if (!needsUpdate.includes(name) && fs.existsSync(path.join(SKILLS_DIR, name))) continue;
-      copyDir(path.join(PACKAGE_SKILLS_DIR, name), path.join(SKILLS_DIR, name));
+      if (!needsUpdate.includes(name) && fs.existsSync(path.join(AGENTS_DIR, name))) continue;
+      installSkillFiles(name);
       newChecksums[name] = packageHashes[name];
     }
     fs.mkdirSync(HOOKS_DIR, { recursive: true });
@@ -463,43 +636,54 @@ async function main() {
       process.exit(0);
     }
 
+    fs.mkdirSync(AGENTS_DIR, { recursive: true });
     fs.mkdirSync(SKILLS_DIR, { recursive: true });
     const newChecksums = Object.assign({}, storedChecksums);
-    const updated = [];
-    const mergeNeeded = [];
+    const updated = [];            // display labels with version transitions
+    const mergeNeeded = [];        // plain names (used in merge instructions)
+    const mergeNeededLabels = [];  // display labels with version transitions
 
     for (const name of skillNames) {
+      const newV = getSkillVersion(path.join(PACKAGE_SKILLS_DIR, name));
       if (modifiedSkills.includes(name)) {
         // Backup local version, install new version
+        const oldV = getInstalledSkillVersion(name);
         backupSkill(name);
-        copyDir(path.join(PACKAGE_SKILLS_DIR, name), path.join(SKILLS_DIR, name));
+        installSkillFiles(name);
         newChecksums[name] = packageHashes[name];
         mergeNeeded.push(name);
+        mergeNeededLabels.push(withVersion(name, oldV, newV));
         continue;
       }
-      if (!needsUpdate.includes(name) && fs.existsSync(path.join(SKILLS_DIR, name))) continue;
-      copyDir(path.join(PACKAGE_SKILLS_DIR, name), path.join(SKILLS_DIR, name));
+      if (!needsUpdate.includes(name) && fs.existsSync(path.join(AGENTS_DIR, name))) continue;
+      const oldV = getInstalledSkillVersion(name);
+      installSkillFiles(name);
       newChecksums[name] = packageHashes[name];
-      updated.push(name);
+      updated.push(withVersion(name, oldV, newV));
     }
 
     // Install hooks
     fs.mkdirSync(HOOKS_DIR, { recursive: true });
     const updatedHooks = [];
     const mergeNeededHooks = [];
+    const mergeNeededHookLabels = [];
 
     for (const filename of hookFilenames) {
+      const newV = getHookVersion(path.join(PACKAGE_HOOKS_DIR, filename));
       if (modifiedHooks.includes(filename)) {
+        const oldV = getHookVersion(path.join(HOOKS_DIR, filename));
         backupHook(filename);
         fs.copyFileSync(path.join(PACKAGE_HOOKS_DIR, filename), path.join(HOOKS_DIR, filename));
         newChecksums['hook:' + filename] = packageHookHashes[filename];
         mergeNeededHooks.push(filename);
+        mergeNeededHookLabels.push(withVersion(filename, oldV, newV));
         continue;
       }
       if (!hooksNeedingUpdate.includes(filename) && fs.existsSync(path.join(HOOKS_DIR, filename))) continue;
+      const oldV = getHookVersion(path.join(HOOKS_DIR, filename));
       fs.copyFileSync(path.join(PACKAGE_HOOKS_DIR, filename), path.join(HOOKS_DIR, filename));
       newChecksums['hook:' + filename] = packageHookHashes[filename];
-      updatedHooks.push(filename);
+      updatedHooks.push(withVersion(filename, oldV, newV));
     }
 
     setupRepoSearchNudgeHook();
@@ -521,14 +705,15 @@ async function main() {
     if (mergeNeeded.length > 0) {
       const backupPath = BACKUP_DIR.replace(HOME, '~');
       msgParts.push(
-        'estack: updated ' + mergeNeeded.join(', ') +
+        'estack: updated ' + mergeNeededLabels.join(', ') +
         ' (local changes backed up to ' + backupPath + ')'
       );
       output.additionalContext =
         'estack skills were updated but the user had local modifications to: ' +
         mergeNeeded.join(', ') + '. ' +
         'Their previous versions are saved at ' + BACKUP_DIR + '. ' +
-        'The new upstream versions are now installed at ' + SKILLS_DIR + '. ' +
+        'The new upstream versions are now installed at ' + AGENTS_DIR + ' ' +
+        '(symlinked from ' + SKILLS_DIR + '). ' +
         'Offer to merge their customizations from the backup into the updated versions. ' +
         'To merge: read both the backup version and the new version of each skill, ' +
         'identify the user\'s changes, and apply them to the new version where compatible.';
@@ -537,7 +722,7 @@ async function main() {
     if (mergeNeededHooks.length > 0) {
       const backupPath = BACKUP_DIR.replace(HOME, '~');
       msgParts.push(
-        'estack: updated hooks ' + mergeNeededHooks.join(', ') +
+        'estack: updated hooks ' + mergeNeededHookLabels.join(', ') +
         ' (local changes backed up to ' + backupPath + '/hooks/)'
       );
       const existingContext = output.additionalContext ? output.additionalContext + ' ' : '';
@@ -608,7 +793,10 @@ async function main() {
   }
 
   // 8. Install skills
-  if (!DRY_RUN) fs.mkdirSync(SKILLS_DIR, { recursive: true });
+  if (!DRY_RUN) {
+    fs.mkdirSync(AGENTS_DIR, { recursive: true });
+    fs.mkdirSync(SKILLS_DIR, { recursive: true });
+  }
   const newChecksums = Object.assign({}, storedChecksums);
   let installedCount = 0;
   const mergedSkills = [];
@@ -617,7 +805,8 @@ async function main() {
     if (modifiedSkills.includes(name)) {
       if (modifiedAction === 'skip') {
         console.log('  Skipped ' + name + ' (local modifications preserved)');
-        const currentHash = computeSkillHash(path.join(SKILLS_DIR, name));
+        const currentHash = computeSkillHash(path.join(AGENTS_DIR, name)) ||
+                            computeSkillHash(path.join(SKILLS_DIR, name));
         if (currentHash) newChecksums[name] = currentHash;
         continue;
       }
@@ -627,19 +816,23 @@ async function main() {
         console.log((DRY_RUN ? '  [dry run] Would back up ' : '  Backed up ') + name + ' → ~/.estack-backup/' + name);
       }
       // overwrite or merge — fall through to install
-    } else if (!needsUpdate.includes(name) && fs.existsSync(path.join(SKILLS_DIR, name))) {
+    } else if (!needsUpdate.includes(name) && fs.existsSync(path.join(AGENTS_DIR, name))) {
       // Already installed and up-to-date
       if (DRY_RUN) console.log('  [dry run] Up to date (no change): ' + name);
       continue;
     }
-    const isUpdate = fs.existsSync(path.join(SKILLS_DIR, name));
-    if (!DRY_RUN) copyDir(path.join(PACKAGE_SKILLS_DIR, name), path.join(SKILLS_DIR, name));
+    const isUpdate = fs.existsSync(path.join(AGENTS_DIR, name)) ||
+                     isRealDir(path.join(SKILLS_DIR, name));
+    const label = withVersion(name,
+      isUpdate ? getInstalledSkillVersion(name) : null,
+      getSkillVersion(path.join(PACKAGE_SKILLS_DIR, name)));
+    if (!DRY_RUN) installSkillFiles(name);
     newChecksums[name] = packageHashes[name];
     installedCount++;
     if (DRY_RUN) {
-      console.log('  [dry run] Would ' + (isUpdate ? 'update ' : 'install ') + name);
+      console.log('  [dry run] Would ' + (isUpdate ? 'update ' : 'install ') + label);
     } else {
-      console.log('  Installed ' + name);
+      console.log('  Installed ' + label);
     }
   }
 
@@ -668,13 +861,16 @@ async function main() {
       continue;
     }
     const isHookUpdate = fs.existsSync(path.join(HOOKS_DIR, filename));
+    const hookLabel = withVersion(filename,
+      isHookUpdate ? getHookVersion(path.join(HOOKS_DIR, filename)) : null,
+      getHookVersion(path.join(PACKAGE_HOOKS_DIR, filename)));
     if (!DRY_RUN) fs.copyFileSync(path.join(PACKAGE_HOOKS_DIR, filename), path.join(HOOKS_DIR, filename));
     newChecksums['hook:' + filename] = packageHookHashes[filename];
     installedHookCount++;
     if (DRY_RUN) {
-      console.log('  [dry run] Would ' + (isHookUpdate ? 'update hook ' : 'install hook ') + filename);
+      console.log('  [dry run] Would ' + (isHookUpdate ? 'update hook ' : 'install hook ') + hookLabel);
     } else {
-      console.log('  Installed hook ' + filename);
+      console.log('  Installed hook ' + hookLabel);
     }
   }
 
@@ -689,13 +885,13 @@ async function main() {
   // 11. Summary output
   if (DRY_RUN) {
     console.log('\n[dry run] No files were changed. Run with --install to apply.\n');
-    console.log('  ' + installedCount + ' skill' + (installedCount !== 1 ? 's' : '') + ' would be installed/updated in ~/.claude/skills/');
+    console.log('  ' + installedCount + ' skill' + (installedCount !== 1 ? 's' : '') + ' would be installed/updated in ~/.agents/skills/ (linked from ~/.claude/skills/)');
     if (installedHookCount > 0) {
       console.log('  ' + installedHookCount + ' hook' + (installedHookCount !== 1 ? 's' : '') + ' would be installed/updated in ~/.claude/hooks/');
     }
   } else {
     console.log('\nestack installed successfully!\n');
-    console.log('  ' + installedCount + ' skill' + (installedCount !== 1 ? 's' : '') + ' installed to ~/.claude/skills/');
+    console.log('  ' + installedCount + ' skill' + (installedCount !== 1 ? 's' : '') + ' installed to ~/.agents/skills/ (symlinked from ~/.claude/skills/)');
     if (installedHookCount > 0) {
       console.log('  ' + installedHookCount + ' hook' + (installedHookCount !== 1 ? 's' : '') + ' installed to ~/.claude/hooks/');
     }
@@ -705,7 +901,8 @@ async function main() {
 
   for (const name of skillNames) {
     const desc = getSkillDescription(path.join(PACKAGE_SKILLS_DIR, name));
-    console.log('  /' + name + (desc ? ' — ' + desc : ''));
+    const ver = getSkillVersion(path.join(PACKAGE_SKILLS_DIR, name));
+    console.log('  /' + name + (ver ? ' v' + ver : '') + (desc ? ' — ' + desc : ''));
   }
 
   if (mergedSkills.length > 0) {

package/hooks/repo-search-nudge.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// @version 1.0.0
 // PostToolUse hook: nudges toward the repo-search skill when GitHub is involved.
 // Fires on every WebFetch or WebSearch that touches a github.com URL.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elliot-stack",
-  "version": "1.0.22",
+  "version": "1.0.24",
   "description": "Elliot's skill stack for Claude Code — install via npx elliot-stack@latest",
   "bin": {
     "elliot-stack": "bin/install.cjs"

package/skills/estack-active-learning-tutor/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: estack-active-learning-tutor
+version: 1.0.0
 description: (active-learning-tutor) Tutors a student through exam preparation using active learning — questioning, gap diagnosis, and concept mastery tracking. Use when the student says they want to study, learn, prep for an exam, be quizzed on a chapter, work through a practice test together, or be taught a topic conceptually rather than lectured.
 disable-model-invocation: true
 ---

package/skills/estack-better-title/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: estack-better-title
+version: 1.0.0
 description: (better-title) Suggest better chat session titles and rename the session
 disable-model-invocation: true
 allowed-tools: Bash, AskUserQuestion

package/skills/estack-chris-voss/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: estack-chris-voss
+version: 1.0.0
 description: >
   (chris-voss) Applies Chris Voss negotiation principles from *Never Split the Difference* to any situation
   where understanding human psychology, persuasion, or influence would improve the output. Use

package/skills/estack-customer-discovery/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: estack-customer-discovery
+version: 1.0.0
 description: (customer-discovery) Guide users through customer discovery — validating business ideas, identifying target customers, crafting outreach, preparing interview questions, and analyzing interview results. Use this skill whenever the user mentions customer discovery, customer interviews, validating an idea, market research, finding product-market fit, talking to customers, outreach messages, interview guides, or analyzing customer feedback. Also use when someone says they have a business idea and want to test it, or when they're preparing to talk to potential customers.
 ---
 

package/skills/estack-flight-planner/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: estack-flight-planner
+version: 1.0.0
 description: (flight-planner) Find and rank flights between any two airports with config-driven preferences (budget, airlines, nonstop, time-of-day) and optional ground-shuttle pairing. Uses SerpAPI Google Flights (or WebSearch fallback). Saves preferences to `~/.flight-planner/config.json` and logs every search.
 disable-model-invocation: true
 ---

package/skills/estack-github-issue-tracker/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: estack-github-issue-tracker
+version: 1.0.0
 description: >
   (github-issue-tracker) GitHub issue tracker management. Checks all open issues the user is involved in,
   finds related/duplicate issues, reports what changed, and recommends next steps.

package/skills/estack-prompt-builder-coach/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: estack-prompt-builder-coach
+version: 1.0.0
 description: (prompt-builder-coach) Use whenever you or the user need to write, sharpen, audit, or scope a prompt or work request for an AI agent or model. This is a four-part kit covering shaping a fuzzy idea into a decided goal, building a prompt from scratch, auditing a draft request that feels vague, and defining what "done" looks like when the task is fuzzy. Trigger when the user says "help me write a prompt", "build me a prompt", "audit this prompt", "make this request better", "why is the AI giving me generic output", "I don't know what I want", "I have a rough idea", "what should done look like", or when handing a task to another agent and wanting it to land. Use it even when the user did not say the word "prompt" but is clearly trying to get an AI to do consequential work. Do not use for quick factual lookups or for executing an already well-defined task.
 ---
 

package/skills/estack-read-claude-session-history/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: estack-read-claude-session-history
+version: 1.0.0
 description: (read-claude-session-history) Invoke for ANY task involving Claude Code session history, transcripts, or .jsonl files — this is the only way to read, parse, or search them; do not attempt to use Bash or Read on .jsonl directly. Use for: recovering context after /compact ("what were we doing before compact"), advisor response retrieval ("what did the advisor say"), subagent output collection ("get all subagent finals"), cross-project session search by keyword, session listing and triage, UUID and title lookup, resume-command generation, file-edit and tool-call forensics, session diff between two sessions or subagents, weekly work journal, day timeline of activity blocks and idle gaps, engagement/attention-time accounting (active vs elapsed time, break detection, parallel-chat-safe totals), recovering from .claude-backups after data loss, session count queries, and reading the last agent message before a crash or interrupt. Trigger phrases: "session history", "before compact", "what did claude do", "what did I work on", "search my sessions", "find that session", "what did the advisor say", "what did the agent edit", "from the backup", "list my sessions", "subagent outputs", "session journal", "resume previous", "which files did claude touch", "go back and look", "what did I do yesterday", "where did my day go", "timeline of my day", "how much time on", "how long did that actually take", "how much did I actually work", "active time", "time I spent".
 ---
 

package/skills/estack-repo-search/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: estack-repo-search
+version: 1.0.0
 description: >-
   (repo-search) Clone and search external GitHub repositories to answer questions about their
   code. Use this skill whenever the user references a repo you don't have local