elliot-stack 1.0.21 → 1.0.23

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/` and symlinks them into `~/.claude/skills/`, then registers a `SessionStart` hook so your skills stay up to date automatically.
 
 ## Skills
 
@@ -34,7 +34,7 @@ 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/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
@@ -62,10 +62,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/ + ~/.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,7 @@ 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_DIR = path.join(HOME, '.agents');
 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');
@@ -79,6 +80,26 @@ function removeDirRaw(dir) {
   fs.rmdirSync(dir);
 }
 
+function isSymlink(p) {
+  try { return fs.lstatSync(p).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 if (stat.isDirectory()) {
+      fs.rmSync(linkPath, { recursive: true, force: true });
+    }
+  } catch (_) {}
+  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');
@@ -98,6 +119,9 @@ const DEPRECATED_SKILLS = [
 
 // ── Helpers ────────────────────────────────────────────────────────────────
 
+const HASH_IGNORE_DIRS = new Set(['__pycache__', '.git', 'node_modules']);
+const HASH_IGNORE_EXTS = new Set(['.pyc', '.pyo']);
+
 function walkDir(dir, base) {
   base = base || dir;
   const entries = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) =>
@@ -107,8 +131,8 @@ function walkDir(dir, base) {
   for (const entry of entries) {
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
-      files.push(...walkDir(full, base));
-    } else {
+      if (!HASH_IGNORE_DIRS.has(entry.name)) files.push(...walkDir(full, base));
+    } else if (!HASH_IGNORE_EXTS.has(path.extname(entry.name))) {
       files.push(path.relative(base, full));
     }
   }
@@ -144,7 +168,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));
@@ -210,6 +235,18 @@ function getSkillDescription(skillDir) {
   return '';
 }
 
+// Copies a skill to ~/.agents/<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
@@ -307,15 +344,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) {
@@ -374,11 +422,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 (fs.existsSync(legacyDir) && !isSymlink(legacyDir)) {
+        installedDir = legacyDir; // old-style install, will be migrated on next write
+      }
+    }
+    if (!installedDir) {
       needsUpdate.push(name);
       continue;
     }
@@ -434,12 +492,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 });
@@ -460,6 +519,7 @@ 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 = [];
@@ -469,13 +529,13 @@ async function main() {
       if (modifiedSkills.includes(name)) {
         // Backup local version, install new version
         backupSkill(name);
-        copyDir(path.join(PACKAGE_SKILLS_DIR, name), path.join(SKILLS_DIR, name));
+        installSkillFiles(name);
         newChecksums[name] = packageHashes[name];
         mergeNeeded.push(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];
       updated.push(name);
     }
@@ -525,7 +585,8 @@ async function main() {
         '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.';
@@ -605,7 +666,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 = [];
@@ -614,7 +678,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;
       }
@@ -624,13 +689,15 @@ 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 skillsLegacyDir = path.join(SKILLS_DIR, name);
+    const isUpdate = fs.existsSync(path.join(AGENTS_DIR, name)) ||
+                     (fs.existsSync(skillsLegacyDir) && !isSymlink(skillsLegacyDir));
+    if (!DRY_RUN) installSkillFiles(name);
     newChecksums[name] = packageHashes[name];
     installedCount++;
     if (DRY_RUN) {
@@ -686,13 +753,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/ (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/ (symlinked from ~/.claude/skills/)');
     if (installedHookCount > 0) {
       console.log('  ' + installedHookCount + ' hook' + (installedHookCount !== 1 ? 's' : '') + ' installed to ~/.claude/hooks/');
     }

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.21",
+  "version": "1.0.23",
   "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