@iceinvein/agent-skills 0.1.27 → 0.1.29

package/README.md

@@ -126,6 +126,29 @@ bunx @iceinvein/agent-skills info <skill>
 | `--activation <mode>` | For skills that support it: `session` (manual `/skill`) or `global` (auto via `SessionStart` hook). Claude Code only. |
 | `-g, --global` | Install to home directory (available in all projects) |
 
+## Updating Skills
+
+Each skill is versioned independently (see `skill.json` inside each skill). The CLI tracks what you installed in `.agent-skills.lock` and can pull newer versions from GitHub.
+
+```bash
+bunx @iceinvein/agent-skills update <skill>     # update one skill
+bunx @iceinvein/agent-skills update --all       # update everything in the lockfile
+bunx @iceinvein/agent-skills list               # show installed versions
+```
+
+`update` re-fetches the latest manifest and files from this repo, removes the old install, and re-installs cleanly. Your chosen activation mode (session vs. global) is preserved across updates, as is the set of tools you installed for. Use `-g` to update globally-installed skills.
+
+After any command other than `update`, the CLI runs a background freshness check (at most once every 24 hours) and prints a one-line notice if anything is out of date:
+
+```
+some-skill (v0.2.0 → v0.3.0)
+  Run: agent-skills update --all
+```
+
+The check is best-effort: it silently skips on network failure and only hits GitHub once per day per project. To force a re-check sooner, delete the `lastUpdateCheck` field in `.agent-skills.lock` (or just run any command after 24 hours have elapsed).
+
+To pin to the current version, do nothing: skills are not auto-updated. `update` is opt-in.
+
 ## Activation Modes (Claude Code)
 
 Some skills — like `terse` — support activation modes. Pick one at install time:
@@ -159,7 +182,7 @@ Skills install to the **current project** by default. Use `-g` to install to you
 
 ## Contributing
 
-- [Releasing](docs/RELEASING.md) — how versions are bumped, tagged, and published to npm
+- [Releasing](docs/RELEASING.md): how versions are bumped, tagged, and published to npm
 
 ## License
 

package/dist/cli/index.js

@@ -248,6 +248,30 @@ function validateManifest(data) {
   if (typeof d.install !== "object" || d.install === null) {
     return { ok: false, error: "Missing 'install' configuration" };
   }
+  if (d.bundle !== undefined) {
+    if (typeof d.bundle !== "object" || d.bundle === null) {
+      return { ok: false, error: "'bundle' must be an object" };
+    }
+    const b = d.bundle;
+    if (!Array.isArray(b.include) || b.include.length === 0) {
+      return { ok: false, error: "'bundle.include' must be a non-empty array" };
+    }
+    for (const p of b.include) {
+      if (typeof p !== "string") {
+        return { ok: false, error: "'bundle.include' entries must be strings" };
+      }
+    }
+    if (b.exclude !== undefined) {
+      if (!Array.isArray(b.exclude)) {
+        return { ok: false, error: "'bundle.exclude' must be an array" };
+      }
+      for (const p of b.exclude) {
+        if (typeof p !== "string") {
+          return { ok: false, error: "'bundle.exclude' entries must be strings" };
+        }
+      }
+    }
+  }
   if (d.activation !== undefined) {
     if (typeof d.activation !== "object" || d.activation === null) {
       return { ok: false, error: "'activation' must be an object" };
@@ -318,12 +342,87 @@ async function fetchAllSkillFiles(skillName, manifest) {
       files.set(supportFile, result.content);
     }
   }
+  if (manifest.bundle) {
+    const treeResult = await fetchSkillTree(skillName);
+    if (!treeResult.ok)
+      return { error: treeResult.error };
+    const bundlePaths = resolveBundlePaths(treeResult.entries, manifest.bundle);
+    for (const relPath of bundlePaths) {
+      if (files.has(relPath))
+        continue;
+      const result = await fetchSkillFile(skillName, relPath);
+      if (!result.ok)
+        return { error: result.error };
+      files.set(relPath, result.content);
+    }
+  }
   return files;
 }
+async function fetchSkillTree(skillName) {
+  const url = `https://api.github.com/repos/${REPO}/git/trees/${BRANCH}?recursive=1`;
+  const res = await fetch(url, {
+    headers: { Accept: "application/vnd.github+json" }
+  });
+  if (!res.ok) {
+    return { ok: false, error: `Failed to fetch repo tree: HTTP ${res.status}` };
+  }
+  const data = await res.json();
+  if (data.truncated) {
+    return { ok: false, error: "GitHub tree response was truncated; skill bundle too large to enumerate" };
+  }
+  const prefix = `skills/${skillName}/`;
+  const entries = data.tree.filter((e) => e.path.startsWith(prefix) && (e.type === "blob" || e.type === "tree")).map((e) => ({ path: e.path.slice(prefix.length), type: e.type }));
+  return { ok: true, entries };
+}
+function resolveBundlePaths(entries, bundle) {
+  const excludes = bundle.exclude ?? [];
+  const isExcluded = (p) => excludes.some((ex) => p === ex || p.startsWith(ex));
+  const dirs = new Set;
+  const files = new Set;
+  for (const entry of entries) {
+    if (entry.type === "tree")
+      dirs.add(entry.path);
+    else
+      files.add(entry.path);
+  }
+  const result = new Set;
+  for (const include of bundle.include) {
+    if (dirs.has(include)) {
+      const prefix = include.endsWith("/") ? include : include + "/";
+      for (const f of files) {
+        if (f.startsWith(prefix) && !isExcluded(f))
+          result.add(f);
+      }
+    } else if (files.has(include)) {
+      if (!isExcluded(include))
+        result.add(include);
+    }
+  }
+  return [...result].sort();
+}
 
 // src/cli/adapters/claude.ts
-import { existsSync as existsSync2, mkdirSync, rmSync, unlinkSync } from "node:fs";
+import { chmodSync, existsSync as existsSync2, mkdirSync, rmSync, statSync, unlinkSync } from "node:fs";
 import { dirname, join as join2 } from "node:path";
+function shouldBeExecutable(relPath, content) {
+  if (relPath.endsWith(".sh"))
+    return true;
+  if (relPath.startsWith("bin/") || relPath.includes("/bin/"))
+    return true;
+  if (content.startsWith("#!"))
+    return true;
+  return false;
+}
+function runScript(scriptPath, cwd) {
+  if (!existsSync2(scriptPath))
+    return { ok: true, code: 0 };
+  const result = Bun.spawnSync(["bash", scriptPath], {
+    cwd,
+    stdout: "inherit",
+    stderr: "inherit"
+  });
+  return { ok: result.exitCode === 0, code: result.exitCode ?? 1 };
+}
 function matchesSkillDirective(command, skillName) {
   return command.includes(`Activate ${skillName} skill`);
 }
@@ -394,6 +493,21 @@ var claudeAdapter = {
         }
       }
     }
+    if (config.bundleRoot && manifest.bundle) {
+      const promptPath = manifest.files?.prompt;
+      for (const [relPath, content] of files) {
+        if (relPath === promptPath)
+          continue;
+        const targetRel = join2(config.bundleRoot, relPath);
+        const targetPath = join2(cwd, targetRel);
+        mkdirSync(dirname(targetPath), { recursive: true });
+        await Bun.write(targetPath, content);
+        if (shouldBeExecutable(relPath, content)) {
+          chmodSync(targetPath, 493);
+        }
+        installed.push(targetRel);
+      }
+    }
     if (config.mcpServers) {
       const settingsPath = join2(cwd, ".claude/settings.json");
       let settings = {};
@@ -416,22 +530,49 @@ var claudeAdapter = {
         installed.push(".claude/settings.json");
       }
     }
+    if (config.postinstall && config.bundleRoot) {
+      const scriptPath = join2(cwd, config.bundleRoot, config.postinstall);
+      const result = runScript(scriptPath, join2(cwd, config.bundleRoot));
+      if (!result.ok) {
+        console.error(`postinstall script '${config.postinstall}' exited with code ${result.code}`);
+      }
+    }
     return installed;
   },
   async remove(cwd, manifest, installedFiles) {
     const config = manifest.install.claude;
     if (!config)
       return;
+    if (config.postremove && config.bundleRoot) {
+      const scriptPath = join2(cwd, config.bundleRoot, config.postremove);
+      const result = runScript(scriptPath, join2(cwd, config.bundleRoot));
+      if (!result.ok) {
+        console.error(`postremove script '${config.postremove}' exited with code ${result.code}`);
+      }
+    }
     for (const file of installedFiles) {
       if (file === ".claude/settings.json")
         continue;
       const fullPath = join2(cwd, file);
       if (existsSync2(fullPath)) {
-        unlinkSync(fullPath);
-        const dir = dirname(fullPath);
         try {
-          rmSync(dir, { recursive: false });
+          const stat = statSync(fullPath);
+          if (stat.isDirectory()) {
+            rmSync(fullPath, { recursive: true, force: true });
+          } else {
+            unlinkSync(fullPath);
+          }
         } catch {}
+        let dir = dirname(fullPath);
+        const stopAt = config.bundleRoot ? join2(cwd, config.bundleRoot, "..") : cwd;
+        while (dir !== stopAt && dir !== "/" && dir.startsWith(cwd)) {
+          try {
+            rmSync(dir, { recursive: false });
+          } catch {
+            break;
+          }
+          dir = dirname(dir);
+        }
       }
     }
     if (config.mcpServers) {
@@ -768,8 +909,64 @@ async function fetchAllSkillFiles2(skillName, manifest) {
       files.set(supportFile, result.content);
     }
   }
+  if (manifest.bundle) {
+    const treeResult = await fetchSkillTree2(skillName);
+    if (!treeResult.ok)
+      return { error: treeResult.error };
+    const bundlePaths = resolveBundlePaths2(treeResult.entries, manifest.bundle);
+    for (const relPath of bundlePaths) {
+      if (files.has(relPath))
+        continue;
+      const result = await fetchSkillFile2(skillName, relPath);
+      if (!result.ok)
+        return { error: result.error };
+      files.set(relPath, result.content);
+    }
+  }
   return files;
 }
+async function fetchSkillTree2(skillName) {
+  const url = `https://api.github.com/repos/${REPO2}/git/trees/${BRANCH2}?recursive=1`;
+  const res = await fetch(url, {
+    headers: { Accept: "application/vnd.github+json" }
+  });
+  if (!res.ok) {
+    return { ok: false, error: `Failed to fetch repo tree: HTTP ${res.status}` };
+  }
+  const data = await res.json();
+  if (data.truncated) {
+    return { ok: false, error: "GitHub tree response was truncated; skill bundle too large to enumerate" };
+  }
+  const prefix = `skills/${skillName}/`;
+  const entries = data.tree.filter((e) => e.path.startsWith(prefix) && (e.type === "blob" || e.type === "tree")).map((e) => ({ path: e.path.slice(prefix.length), type: e.type }));
+  return { ok: true, entries };
+}
+function resolveBundlePaths2(entries, bundle) {
+  const excludes = bundle.exclude ?? [];
+  const isExcluded = (p) => excludes.some((ex) => p === ex || p.startsWith(ex));
+  const dirs = new Set;
+  const files = new Set;
+  for (const entry of entries) {
+    if (entry.type === "tree")
+      dirs.add(entry.path);
+    else
+      files.add(entry.path);
+  }
+  const result = new Set;
+  for (const include of bundle.include) {
+    if (dirs.has(include)) {
+      const prefix = include.endsWith("/") ? include : include + "/";
+      for (const f of files) {
+        if (f.startsWith(prefix) && !isExcluded(f))
+          result.add(f);
+      }
+    } else if (files.has(include)) {
+      if (!isExcluded(include))
+        result.add(include);
+    }
+  }
+  return [...result].sort();
+}
 
 // src/cli/commands/remove.ts
 async function removeSkill(cwd, skillName) {
@@ -1081,6 +1278,18 @@ async function checkForUpdates(cwd) {
   }
 }
 
+// src/cli/lockfile.ts
+import { join as join8 } from "node:path";
+var LOCKFILE_NAME2 = ".agent-skills.lock";
+async function readLockfile2(cwd) {
+  const path = join8(cwd, LOCKFILE_NAME2);
+  const file = Bun.file(path);
+  if (!await file.exists()) {
+    return { skills: {} };
+  }
+  return file.json();
+}
+
 // src/cli/types.ts
 var TOOL_NAMES2 = ["claude", "cursor", "codex", "gemini"];
 
@@ -2953,8 +3162,19 @@ async function pickActivation(skillName, modes) {
 
 // src/cli/index.ts
 import { mkdirSync as mkdirSync4 } from "fs";
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 import { homedir } from "os";
+async function otherScopeSkillCount(currentDir) {
+  const home = homedir();
+  const otherDir = currentDir === home ? process.cwd() : home;
+  if (otherDir === currentDir)
+    return { scope: "global", count: 0 };
+  const lockfile = await readLockfile2(otherDir);
+  return {
+    scope: otherDir === home ? "global" : "local",
+    count: Object.keys(lockfile.skills).length
+  };
+}
 function resolveInstallDir(flags) {
   if (flags.global !== undefined || flags.g !== undefined) {
     return homedir();
@@ -3046,7 +3266,7 @@ async function resolveTargetTools(installDir, isGlobal, flags) {
   for (const tool of picked) {
     const dir = TOOL_DIRS[tool];
     if (dir)
-      mkdirSync4(join8(installDir, dir), { recursive: true });
+      mkdirSync4(join9(installDir, dir), { recursive: true });
   }
   return picked;
 }
@@ -3160,18 +3380,25 @@ Installing ${names.length} skills...
 `);
         const results = await updateAllSkills(updateDir);
         if (results.length === 0) {
-          console.log("No skills installed.");
-          break;
-        }
-        for (const r of results) {
-          if (!r.ok) {
-            console.error(`  \u2717 ${r.name}: ${r.error}`);
-          } else if (r.from === r.to) {
-            console.log(`  \u2298 ${r.name} already up to date (v${r.to})`);
-          } else {
-            console.log(`  \u2713 ${r.name} v${r.from} \u2192 v${r.to}`);
+          console.log("No skills installed in this scope.");
+        } else {
+          for (const r of results) {
+            if (!r.ok) {
+              console.error(`  \u2717 ${r.name}: ${r.error}`);
+            } else if (r.from === r.to) {
+              console.log(`  \u2298 ${r.name} already up to date (v${r.to})`);
+            } else {
+              console.log(`  \u2713 ${r.name} v${r.from} \u2192 v${r.to}`);
+            }
           }
         }
+        const other = await otherScopeSkillCount(updateDir);
+        if (other.count > 0) {
+          const command2 = other.scope === "global" ? "agent-skills update --all -g" : "agent-skills update --all";
+          const noun = other.count === 1 ? "skill" : "skills";
+          console.log(`
+Note: ${other.count} ${noun} installed in the ${other.scope} scope. Run \`${command2}\` to update those too.`);
+        }
         break;
       }
       const skillName = args[0];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iceinvein/agent-skills",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "description": "Install agent skills into AI coding tools",
   "author": "iceinvein",
   "license": "MIT",
@@ -19,6 +19,7 @@
     "skill:bump": "bun run src/cli/index.ts bump",
     "skill:bump:all": "bun run src/cli/index.ts bump --all",
     "skill:bump:check": "bun run src/cli/index.ts bump --all --dry-run",
+    "build:index": "bun run scripts/build-index.ts",
     "release": "bash scripts/release.sh"
   },
   "keywords": [

package/skills/index.json

@@ -1,18 +1,12 @@
 [
   {
-    "name": "design-review",
-    "description": "Brooks-inspired design integrity review — tests conceptual integrity, constraint exploitation, removal discipline, and scope control",
-    "type": "prompt",
-    "version": "1.0.0",
-    "applies": ["any"],
-    "quick": false
-  },
-  {
-    "name": "codebase-architecture",
-    "description": "Architecture review for existing codebases or structured design for new projects, with patterns reference",
+    "name": "bounded-context-auditor",
+    "description": "Evans-inspired bounded context analysis — detect linguistic fractures, draw context maps, identify leaking language and shared model pollution",
     "type": "prompt",
     "version": "1.0.0",
-    "applies": ["any", "architecture"],
+    "applies": [
+      "domain"
+    ],
     "quick": false
   },
   {
@@ -22,107 +16,124 @@
     "version": "1.0.0"
   },
   {
-    "name": "contract-enforcer",
-    "description": "Meyer-inspired Design by Contract — preconditions, postconditions, invariants, and failure contracts for non-trivial functions",
+    "name": "codebase-architecture",
+    "description": "Architecture review for existing codebases or structured design for new projects, with patterns reference",
     "type": "prompt",
     "version": "1.0.0",
-    "applies": ["any"],
+    "applies": [
+      "any",
+      "architecture"
+    ],
     "quick": false
   },
   {
-    "name": "complexity-accountant",
-    "description": "Ousterhout-inspired complexity analysis — deep vs shallow modules, complexity budget, justified abstractions",
+    "name": "cognitive-load-auditor",
+    "description": "Jeff Johnson-inspired cognitive load analysis — evaluate UI against Miller's Law, Hick's Law, Fitts's Law, and working memory limits",
     "type": "prompt",
     "version": "1.0.0",
-    "applies": ["any"],
+    "applies": [
+      "ui"
+    ],
     "quick": false
   },
   {
-    "name": "module-secret-auditor",
-    "description": "Parnas-inspired information hiding analysis — module boundaries drawn by change-reason, not by noun or technical layer",
-    "type": "prompt",
-    "version": "1.0.0",
-    "applies": ["architecture"],
-    "quick": true
-  },
-  {
-    "name": "seam-finder",
-    "description": "Feathers-inspired legacy code modification — find seams, make minimal incisions, preserve existing behavior",
+    "name": "cohesion-analyzer",
+    "description": "Constantine & Yourdon-inspired cohesion analysis — classify module focus on the 7-level spectrum, find split lines, reduce mixed responsibilities",
     "type": "prompt",
     "version": "1.0.0",
-    "applies": ["legacy"],
+    "applies": [
+      "architecture"
+    ],
     "quick": true
   },
   {
-    "name": "simplicity-razor",
-    "description": "Hickey-inspired simplicity analysis — simple vs easy, complecting detection, strand decomposition",
+    "name": "complexity-accountant",
+    "description": "Ousterhout-inspired complexity analysis — deep vs shallow modules, complexity budget, justified abstractions",
     "type": "prompt",
     "version": "1.0.0",
-    "applies": ["any"],
+    "applies": [
+      "any"
+    ],
     "quick": false
   },
   {
-    "name": "coupling-auditor",
-    "description": "Constantine & Yourdon-inspired coupling analysis — classify, measure, and reduce interdependence between modules",
+    "name": "composability-auditor",
+    "description": "Unix Philosophy-inspired composability analysis — identify reuse blockers, decompose self-sufficient units into composable pieces with standard interfaces",
     "type": "prompt",
     "version": "1.0.0",
-    "applies": ["architecture"],
-    "quick": true
+    "applies": [
+      "any"
+    ],
+    "quick": false
   },
   {
-    "name": "evolution-analyzer",
-    "description": "Lehman-inspired software evolution analysis — trajectory assessment, debt visibility, and change impact on system health",
+    "name": "contract-enforcer",
+    "description": "Meyer-inspired Design by Contract — preconditions, postconditions, invariants, and failure contracts for non-trivial functions",
     "type": "prompt",
     "version": "1.0.0",
-    "applies": ["any"],
+    "applies": [
+      "any"
+    ],
     "quick": false
   },
   {
-    "name": "error-strategist",
-    "description": "Duffy & Abrahams-inspired error handling — classify errors (bug/recoverable/fatal), assign safety guarantees, design recovery boundaries",
+    "name": "coupling-auditor",
+    "description": "Constantine & Yourdon-inspired coupling analysis — classify, measure, and reduce interdependence between modules",
     "type": "prompt",
     "version": "1.0.0",
-    "applies": ["errors"],
-    "quick": false
+    "applies": [
+      "architecture"
+    ],
+    "quick": true
   },
   {
-    "name": "rams-design-audit",
-    "description": "Dieter Rams-inspired design audit — every visual element must earn its presence, less but better, clarity through restraint",
+    "name": "cqs-auditor",
+    "description": "Meyer-inspired Command-Query Separation — classify functions as commands or queries, detect mixed violations, separate side effects from return values",
     "type": "prompt",
     "version": "1.0.0",
-    "applies": ["ui"],
+    "applies": [
+      "architecture"
+    ],
     "quick": true
   },
   {
-    "name": "cognitive-load-auditor",
-    "description": "Jeff Johnson-inspired cognitive load analysis — evaluate UI against Miller's Law, Hick's Law, Fitts's Law, and working memory limits",
+    "name": "demeter-enforcer",
+    "description": "Lieberherr-inspired Law of Demeter analysis — detect chain violations, parameter drilling, and hidden traversal; fix with tell-don't-ask or parameter narrowing",
     "type": "prompt",
     "version": "1.0.0",
-    "applies": ["ui"],
-    "quick": false
+    "applies": [
+      "architecture"
+    ],
+    "quick": true
   },
   {
-    "name": "gestalt-reviewer",
-    "description": "Gestalt-inspired visual perception audit — proximity, similarity, closure, continuity, and figure-ground analysis for UI layouts",
+    "name": "dependency-direction-auditor",
+    "description": "Martin-inspired dependency direction analysis — trace imports across layers, classify violations by severity, recommend inversion",
     "type": "prompt",
     "version": "1.0.0",
-    "applies": ["ui"],
+    "applies": [
+      "architecture"
+    ],
     "quick": true
   },
   {
-    "name": "integration-pattern-auditor",
-    "description": "Hohpe & Woolf-inspired messaging analysis — name the integration pattern, verify delivery guarantees, identify missing infrastructure",
+    "name": "design-review",
+    "description": "Brooks-inspired design integrity review — tests conceptual integrity, constraint exploitation, removal discipline, and scope control",
     "type": "prompt",
     "version": "1.0.0",
-    "applies": ["integration"],
+    "applies": [
+      "any"
+    ],
     "quick": false
   },
   {
-    "name": "unidirectional-flow-enforcer",
-    "description": "Elm Architecture-inspired data flow analysis — enforce unidirectional state flow, detect bidirectional mutations, trace state lifecycle in UI applications",
+    "name": "error-strategist",
+    "description": "Duffy & Abrahams-inspired error handling — classify errors (bug/recoverable/fatal), assign safety guarantees, design recovery boundaries",
     "type": "prompt",
     "version": "1.0.0",
-    "applies": ["ui"],
+    "applies": [
+      "errors"
+    ],
     "quick": false
   },
   {
@@ -130,129 +141,148 @@
     "description": "Evans/Vernon/Dahan-inspired event design — domain-meaningful naming, fat payloads, schema evolution, and the domain expert test",
     "type": "prompt",
     "version": "1.0.0",
-    "applies": ["integration", "domain"],
+    "applies": [
+      "integration",
+      "domain"
+    ],
     "quick": false
   },
   {
-    "name": "dependency-direction-auditor",
-    "description": "Martin-inspired dependency direction analysis — trace imports across layers, classify violations by severity, recommend inversion",
-    "type": "prompt",
-    "version": "1.0.0",
-    "applies": ["architecture"],
-    "quick": true
-  },
-  {
-    "name": "cohesion-analyzer",
-    "description": "Constantine & Yourdon-inspired cohesion analysis — classify module focus on the 7-level spectrum, find split lines, reduce mixed responsibilities",
+    "name": "evolution-analyzer",
+    "description": "Lehman-inspired software evolution analysis — trajectory assessment, debt visibility, and change impact on system health",
     "type": "prompt",
     "version": "1.0.0",
-    "applies": ["architecture"],
-    "quick": true
+    "applies": [
+      "any"
+    ],
+    "quick": false
   },
   {
-    "name": "demeter-enforcer",
-    "description": "Lieberherr-inspired Law of Demeter analysis — detect chain violations, parameter drilling, and hidden traversal; fix with tell-don't-ask or parameter narrowing",
+    "name": "gestalt-reviewer",
+    "description": "Gestalt-inspired visual perception audit — proximity, similarity, closure, continuity, and figure-ground analysis for UI layouts",
     "type": "prompt",
     "version": "1.0.0",
-    "applies": ["architecture"],
+    "applies": [
+      "ui"
+    ],
     "quick": true
   },
   {
-    "name": "bounded-context-auditor",
-    "description": "Evans-inspired bounded context analysis — detect linguistic fractures, draw context maps, identify leaking language and shared model pollution",
+    "name": "idempotency-guardian",
+    "description": "Helland-inspired idempotency analysis — classify mutation points, check protection mechanisms, evaluate side effect safety for retry-safe systems",
     "type": "prompt",
     "version": "1.0.0",
-    "applies": ["domain"],
+    "applies": [
+      "integration"
+    ],
     "quick": false
   },
   {
-    "name": "port-adapter-auditor",
-    "description": "Cockburn-inspired hexagonal architecture analysis — identify ports and adapters, classify boundary health, ensure core testability and swappability",
+    "name": "improve-my-codebase",
+    "description": "Orchestrator skill that runs every applicable audit skill in parallel and produces a prioritized, convergence-ranked improvement report",
     "type": "prompt",
-    "version": "1.0.0",
-    "applies": ["architecture"],
-    "quick": false
+    "version": "1.0.1"
   },
   {
-    "name": "idempotency-guardian",
-    "description": "Helland-inspired idempotency analysis — classify mutation points, check protection mechanisms, evaluate side effect safety for retry-safe systems",
+    "name": "integration-pattern-auditor",
+    "description": "Hohpe & Woolf-inspired messaging analysis — name the integration pattern, verify delivery guarantees, identify missing infrastructure",
     "type": "prompt",
     "version": "1.0.0",
-    "applies": ["integration"],
+    "applies": [
+      "integration"
+    ],
     "quick": false
   },
   {
-    "name": "type-driven-designer",
-    "description": "Wlaschin & Minsky-inspired type design — make illegal states unrepresentable through branded types, discriminated unions, and domain-encoded constraints",
+    "name": "magpie",
+    "description": "Interactive PR review pipeline. Runs five parallel specialist subagents (security, bugs, performance, code-smells, architecture), dedupes findings, applies a critic rubric, peer-reviews via codex exec, and serves an interactive HTML report for selecting findings to post via gh. Bundles a Bun CLI installed onto PATH via the skill's postinstall step. Use when the user asks to review a GitHub pull request.",
     "type": "prompt",
-    "version": "1.0.0",
-    "applies": ["any"],
-    "quick": false
+    "version": "0.3.0"
   },
   {
-    "name": "cqs-auditor",
-    "description": "Meyer-inspired Command-Query Separation — classify functions as commands or queries, detect mixed violations, separate side effects from return values",
+    "name": "module-secret-auditor",
+    "description": "Parnas-inspired information hiding analysis — module boundaries drawn by change-reason, not by noun or technical layer",
     "type": "prompt",
     "version": "1.0.0",
-    "applies": ["architecture"],
+    "applies": [
+      "architecture"
+    ],
     "quick": true
   },
   {
-    "name": "composability-auditor",
-    "description": "Unix Philosophy-inspired composability analysis — identify reuse blockers, decompose self-sufficient units into composable pieces with standard interfaces",
+    "name": "port-adapter-auditor",
+    "description": "Cockburn-inspired hexagonal architecture analysis — identify ports and adapters, classify boundary health, ensure core testability and swappability",
     "type": "prompt",
     "version": "1.0.0",
-    "applies": ["any"],
+    "applies": [
+      "architecture"
+    ],
     "quick": false
   },
   {
-    "name": "temporal-coupling-detector",
-    "description": "Hidden ordering dependency analysis — detect two-phase init, method order dependencies, invisible preconditions, and resource lifecycle violations; fix with types, parameters, and factory patterns",
+    "name": "rams-design-audit",
+    "description": "Dieter Rams-inspired design audit — every visual element must earn its presence, less but better, clarity through restraint",
     "type": "prompt",
     "version": "1.0.0",
-    "applies": ["any"],
+    "applies": [
+      "ui"
+    ],
     "quick": true
   },
   {
-    "name": "terse",
-    "description": "Professional output compression — proper grammar, no fluff, ~50-60% fewer tokens. Three levels: clean, tight, sharp.",
-    "type": "prompt",
-    "version": "1.1.0"
-  },
-  {
-    "name": "cover-letter",
-    "description": "Cover letter suite router. Routes to write, audit, rewrite, or persona subcommands; shares conventions for file I/O, output formats, and writing principles.",
+    "name": "seam-finder",
+    "description": "Feathers-inspired legacy code modification — find seams, make minimal incisions, preserve existing behavior",
     "type": "prompt",
-    "version": "1.0.0"
+    "version": "1.0.0",
+    "applies": [
+      "legacy"
+    ],
+    "quick": true
   },
   {
-    "name": "cover-letter-write",
-    "description": "Generate a cover letter from resume + job description (PDF, DOCX, markdown, URL). Outputs markdown, DOCX, and PDF. Enforces human prose, evidence alignment, and JD coverage without keyword stuffing.",
+    "name": "simplicity-razor",
+    "description": "Hickey-inspired simplicity analysis — simple vs easy, complecting detection, strand decomposition",
     "type": "prompt",
-    "version": "1.0.0"
+    "version": "1.0.0",
+    "applies": [
+      "any"
+    ],
+    "quick": false
   },
   {
-    "name": "cover-letter-audit",
-    "description": "Score a cover letter on 100 points across content, structure, voice, and correctness. Detects AI-generated-content signals (burstiness, AI phrases, TTR, em-dashes) and produces prioritized fixes.",
+    "name": "temporal-coupling-detector",
+    "description": "Hidden ordering dependency analysis — detect two-phase init, method order dependencies, invisible preconditions, and resource lifecycle violations; fix with types, parameters, and factory patterns",
     "type": "prompt",
-    "version": "1.0.0"
+    "version": "1.0.0",
+    "applies": [
+      "any"
+    ],
+    "quick": true
   },
   {
-    "name": "cover-letter-rewrite",
-    "description": "Revise an existing cover letter with audit-driven targeted fixes. Focus modes: humanize, align, tighten, structure, tone. Preserves voice where it already works.",
+    "name": "terse",
+    "description": "Professional output compression. Cuts ~20-30% of output tokens with proper grammar and semantic accuracy. Three levels: clean, tight, sharp.",
     "type": "prompt",
-    "version": "1.0.0"
+    "version": "1.2.0"
   },
   {
-    "name": "cover-letter-persona",
-    "description": "Manage reusable writing personas for cover letters using the NNGroup 4-dimension tone framework. Locks in tone, sentence style, and vocabulary across applications.",
+    "name": "type-driven-designer",
+    "description": "Wlaschin & Minsky-inspired type design — make illegal states unrepresentable through branded types, discriminated unions, and domain-encoded constraints",
     "type": "prompt",
-    "version": "1.0.0"
+    "version": "1.0.0",
+    "applies": [
+      "any"
+    ],
+    "quick": false
   },
   {
-    "name": "improve-my-codebase",
-    "description": "Orchestrator skill that runs every applicable audit skill in parallel and produces a prioritized, convergence-ranked improvement report",
+    "name": "unidirectional-flow-enforcer",
+    "description": "Elm Architecture-inspired data flow analysis — enforce unidirectional state flow, detect bidirectional mutations, trace state lifecycle in UI applications",
     "type": "prompt",
-    "version": "1.0.0"
+    "version": "1.0.0",
+    "applies": [
+      "ui"
+    ],
+    "quick": false
   }
 ]

package/skills/magpie/README.md

@@ -15,15 +15,13 @@ Given a GitHub PR number, dispatches five specialist subagents in parallel (secu
 
 ## Install
 
-This skill ships in two parts: the prompt (SKILL.md) and a companion Bun CLI (bin + scripts). Both are needed, and `install.sh` handles both in one step.
-
 ```
-./install.sh
+bunx @iceinvein/agent-skills install magpie -g
 ```
 
-That symlinks the full skill source tree (bin/, scripts/, templates/, fixtures/, SKILL.md, skill.json) into `~/.claude/skills/magpie/`, then symlinks `bin/magpie` onto your PATH (preferring `/usr/local/bin`, falling back to `~/.local/bin`). Re-run any time to refresh the links.
+This skill ships in two parts: the prompt (SKILL.md) and a companion Bun CLI (bin + scripts). The agent-skills installer writes both into `~/.claude/skills/magpie/` and then runs the bundled `install.sh` as a postinstall step, which symlinks `bin/magpie` onto your PATH (preferring `/usr/local/bin`, falling back to `~/.local/bin`). Removing the skill with `agent-skills remove magpie -g` runs `uninstall.sh` first to undo the PATH symlink.
 
-Once an agent-skills registry entry exists for `magpie`, the prompt half can also be installed via `bunx @iceinvein/agent-skills install magpie`, but the CLI still requires `./install.sh` (or an equivalent manual symlink) because the registry only ships SKILL.md.
+If you cloned this repo and want to run from source, you can also invoke `./install.sh` directly: it does the PATH-link step against the local source tree.
 
 ## Use
 
@@ -57,11 +55,12 @@ The fixture lives at `fixtures/example-pr/` (pr.json + findings.final.json + pos
 
 - `SKILL.md` is the agent-facing prompt; installed by the agent-skills CLI.
 - `skill.json` is the agent-skills manifest.
-- `bin/magpie` is the CLI invoked by the agent during stages; installed by `install.sh`.
+- `bin/magpie` is the CLI invoked by the agent during stages; symlinked onto PATH by `install.sh`.
 - `scripts/` holds the implementation (server, dedupe, render, setup, cleanup, etc.).
 - `templates/styles.css` is the HTML report stylesheet.
-- `fixtures/` holds canned PR data for tests.
-- `install.sh` symlinks the skill directory into `~/.claude/skills/`.
+- `fixtures/` holds canned PR data for tests (not shipped to users via the registry).
+- `install.sh` is run as a postinstall step by the agent-skills installer; symlinks `bin/magpie` onto PATH and records the location.
+- `uninstall.sh` is run as a postremove step; removes the PATH symlink if it still points back into this bundle.
 
 ## Design docs
 

package/skills/magpie/install.sh

@@ -1,25 +1,20 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# This script is run by agent-skills as a postinstall step after the magpie
+# skill bundle has been written to disk. Its only job is to put the magpie
+# CLI on PATH and record where it linked, so uninstall.sh can clean up.
+
 SOURCE_DIR="$(cd "$(dirname "$0")" && pwd)"
-TARGET="$HOME/.claude/skills/magpie"
+BIN_SOURCE="$SOURCE_DIR/bin/magpie"
+STATE_FILE="$SOURCE_DIR/.installed-cli-path"
 
-if [ -e "$TARGET" ] && [ ! -L "$TARGET" ]; then
-  echo "Refusing to overwrite non-symlink at $TARGET"
-  echo "Remove or move it manually, then re-run."
+if [ ! -f "$BIN_SOURCE" ]; then
+  echo "magpie postinstall: bin/magpie missing at $BIN_SOURCE" >&2
   exit 1
 fi
 
-mkdir -p "$HOME/.claude/skills"
-ln -snf "$SOURCE_DIR" "$TARGET"
-
-echo "Installed magpie skill at $TARGET"
-
-# Install the magpie CLI onto PATH. Try /usr/local/bin first (no sudo
-# needed if the user owns it, common on Homebrew Macs), fall back to
-# ~/.local/bin (which most modern shells already have on PATH; we print a
-# nudge if it isn't).
-BIN_SOURCE="$SOURCE_DIR/bin/magpie"
+chmod +x "$BIN_SOURCE" || true
 
 install_link() {
   local dest_dir="$1"
@@ -28,11 +23,9 @@ install_link() {
   if [ ! -d "$dest_dir" ]; then
     mkdir -p "$dest_dir" 2>/dev/null || return 1
   fi
-
   if [ ! -w "$dest_dir" ]; then
     return 1
   fi
-
   if [ -e "$dest" ] && [ ! -L "$dest" ]; then
     echo "  skipping $dest_dir (a non-symlink magpie already exists there)"
     return 2
@@ -40,23 +33,21 @@ install_link() {
 
   ln -snf "$BIN_SOURCE" "$dest"
   echo "  linked  $dest -> $BIN_SOURCE"
-  CLI_INSTALL_DIR="$dest_dir"
+  printf '%s\n' "$dest" > "$STATE_FILE"
   return 0
 }
 
-echo ""
 echo "Installing magpie CLI on PATH:"
 
 CLI_INSTALL_DIR=""
 if install_link "/usr/local/bin"; then
-  :
+  CLI_INSTALL_DIR="/usr/local/bin"
 elif install_link "$HOME/.local/bin"; then
-  :
+  CLI_INSTALL_DIR="$HOME/.local/bin"
 else
   echo "  Could not write to /usr/local/bin or ~/.local/bin."
-  echo "  Add this to your shell rc instead:"
+  echo "  Add this alias to your shell rc instead:"
   echo "    alias magpie='bun $BIN_SOURCE.ts'"
-  CLI_INSTALL_DIR=""
 fi
 
 if [ -n "$CLI_INSTALL_DIR" ]; then

package/skills/magpie/skill.json

@@ -1,7 +1,7 @@
 {
   "name": "magpie",
-  "version": "0.2.1",
-  "description": "Interactive PR review pipeline. Runs five parallel specialist subagents (security, bugs, performance, code-smells, architecture), dedupes findings, applies a critic rubric, peer-reviews via codex exec, and serves an interactive HTML report for selecting findings to post via gh. Bundles a Bun CLI installed separately via the skill's install.sh. Use when the user asks to review a GitHub pull request.",
+  "version": "0.3.0",
+  "description": "Interactive PR review pipeline. Runs five parallel specialist subagents (security, bugs, performance, code-smells, architecture), dedupes findings, applies a critic rubric, peer-reviews via codex exec, and serves an interactive HTML report for selecting findings to post via gh. Bundles a Bun CLI installed onto PATH via the skill's postinstall step. Use when the user asks to review a GitHub pull request.",
   "author": "iceinvein",
   "type": "prompt",
   "tools": [
@@ -10,9 +10,28 @@
   "files": {
     "prompt": "SKILL.md"
   },
+  "bundle": {
+    "include": [
+      "bin",
+      "scripts",
+      "templates",
+      "install.sh",
+      "uninstall.sh",
+      "package.json",
+      "bun.lock",
+      "README.md",
+      "LICENSE"
+    ],
+    "exclude": [
+      "scripts/__tests__/"
+    ]
+  },
   "install": {
     "claude": {
-      "prompt": ".claude/skills/magpie/SKILL.md"
+      "prompt": ".claude/skills/magpie/SKILL.md",
+      "bundleRoot": ".claude/skills/magpie",
+      "postinstall": "install.sh",
+      "postremove": "uninstall.sh"
     }
   }
 }

package/skills/magpie/uninstall.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Run by agent-skills as a postremove step before the magpie skill bundle is
+# deleted. Reads the path recorded by install.sh and removes the PATH symlink
+# if it still points back into this bundle.
+
+SOURCE_DIR="$(cd "$(dirname "$0")" && pwd)"
+STATE_FILE="$SOURCE_DIR/.installed-cli-path"
+
+if [ ! -f "$STATE_FILE" ]; then
+  exit 0
+fi
+
+CLI_PATH="$(head -n 1 "$STATE_FILE")"
+[ -z "$CLI_PATH" ] && exit 0
+
+if [ -L "$CLI_PATH" ]; then
+  TARGET="$(readlink "$CLI_PATH")"
+  case "$TARGET" in
+    "$SOURCE_DIR"/*)
+      rm -f "$CLI_PATH"
+      echo "Removed magpie CLI symlink at $CLI_PATH"
+      ;;
+    *)
+      echo "magpie uninstall: leaving $CLI_PATH alone (points to $TARGET, not this bundle)"
+      ;;
+  esac
+fi
+
+rm -f "$STATE_FILE"