@iceinvein/agent-skills 0.1.26 → 0.1.28

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:
@@ -157,6 +180,10 @@ The CLI fetches skills from GitHub and installs them into the right locations fo
 
 Skills install to the **current project** by default. Use `-g` to install to your **home directory** so the skill is available everywhere. A `.agent-skills.lock` file tracks installations for update and remove.
 
+## Contributing
+
+- [Releasing](docs/RELEASING.md): how versions are bumped, tagged, and published to npm
+
 ## License
 
 MIT

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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iceinvein/agent-skills",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "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/scripts/post-cmd.ts

@@ -1,9 +1,33 @@
 import { createHash } from 'node:crypto'
 import { appendFile, readFile, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
+import { parseUnifiedDiffToHunks, splitDiffByFile } from './diff-utils.ts'
 import { formatFindingDescriptionMarkdown } from './finding-description.ts'
 import { type FocusId, parseFinding, type ReviewFinding, type Severity } from './types.ts'
 
+/**
+ * Build a per-file set of RIGHT-side line numbers that GitHub's PR Reviews API
+ * will accept as inline-comment anchors (added or context lines within hunks).
+ * Returns an empty map when the diff is empty/unavailable.
+ */
+function buildValidRightLines(diff: string): Map<string, Set<number>> {
+  const result = new Map<string, Set<number>>()
+  if (!diff) return result
+  for (const [file, chunk] of splitDiffByFile(diff)) {
+    const hunks = parseUnifiedDiffToHunks(chunk)
+    const set = new Set<number>()
+    for (const h of hunks) {
+      for (const l of h.lines) {
+        if (l.newLineNo != null && (l.type === 'added' || l.type === 'context')) {
+          set.add(l.newLineNo)
+        }
+      }
+    }
+    result.set(file, set)
+  }
+  return result
+}
+
 export type PostInput = {
   runDir: string
   findingIds: string[]
@@ -289,6 +313,12 @@ export type PostReviewInput = {
   findingIds: string[]
   prNumber: number
   headSha: string
+  /**
+   * Target repo as "owner/name". When omitted, the `{owner}/{repo}` gh
+   * placeholder is used, which resolves from the gh process's cwd. The server
+   * always passes this explicitly so the call does not depend on cwd.
+   */
+  repo?: string
   reviewBody?: string
   ghBin?: string
   dryRun?: boolean
@@ -364,25 +394,59 @@ export async function postFindingsAsReview(input: PostReviewInput): Promise<Post
     // findings.final.json missing or unparseable; strictById stays empty
   }
 
-  // Partition into inline (has file + line) and unplaced.
+  // Build the set of (file, RIGHT-side line) pairs GitHub will accept as inline
+  // anchors. Inline comments on lines outside this set get 422'd and would
+  // poison the whole batch; instead we demote them to the review body.
+  let validRightLines: Map<string, Set<number>> | null = null
+  try {
+    const diff = await readFile(join(input.runDir, 'diff.patch'), 'utf8')
+    validRightLines = buildValidRightLines(diff)
+  } catch {
+    // diff.patch absent (archived/legacy runs); skip validation and trust caller.
+    validRightLines = null
+  }
+
+  // Partition into inline (has file + line in diff) and unplaced (everything else).
   type InlineComment = { path: string; line: number; side: 'RIGHT'; body: string }
   const inlineComments: InlineComment[] = []
   const unplacedBodies: string[] = []
+  const demotedIds: string[] = []
 
   for (const id of input.findingIds) {
-    const f = byId.get(id)
-    if (!f) continue
     const strict = strictById.get(id)
-    if (f.line != null && f.file != null) {
+    const f =
+      byId.get(id) ??
+      (strict
+        ? {
+            id: strict.id,
+            file: strict.file,
+            line: strict.line,
+            title: strict.title,
+            description: strict.description,
+          }
+        : null)
+    if (!f) continue
+    const lineInDiff =
+      f.line != null &&
+      f.file != null &&
+      (validRightLines == null || validRightLines.get(f.file)?.has(f.line) === true)
+    if (lineInDiff) {
       const body = strict
         ? formatInlineBody(strict)
         : formatFindingDescriptionMarkdown(f.description)
       inlineComments.push({
-        path: f.file,
-        line: f.line,
+        path: f.file as string,
+        line: f.line as number,
         side: 'RIGHT',
         body,
       })
+    } else if (f.line != null && f.file != null) {
+      demotedIds.push(id)
+      const anchor = `\`${f.file}:${f.line}\` (anchor not in PR diff, posted in review body)`
+      const inner = strict
+        ? formatConversationBody(strict)
+        : `**${f.title}**\n\n${formatFindingDescriptionMarkdown(f.description)}`
+      unplacedBodies.push(`${anchor}\n\n${inner}`)
     } else {
       const body = strict
         ? formatConversationBody(strict)
@@ -406,20 +470,30 @@ export async function postFindingsAsReview(input: PostReviewInput): Promise<Post
   }
   const payload = JSON.stringify(payloadObj)
 
+  const repoSlug = input.repo ?? '{owner}/{repo}'
   const command = [
     bin,
     'api',
-    `repos/{owner}/{repo}/pulls/${input.prNumber}/reviews`,
+    `repos/${repoSlug}/pulls/${input.prNumber}/reviews`,
     '--method',
     'POST',
     '--input',
     '-',
   ]
 
+  const demoted = new Set(demotedIds)
+  const buildCommentResults = (status: 'posted' | 'failed', message?: string) =>
+    input.findingIds.map((id) => {
+      const base: PostReviewCommentResult = { id, status }
+      const m =
+        message ?? (demoted.has(id) ? 'anchor not in PR diff, posted in review body' : undefined)
+      return m ? { ...base, message: m } : base
+    })
+
   if (input.dryRun) {
     return {
       reviewId: null,
-      comments: input.findingIds.map((id) => ({ id, status: 'posted' as const })),
+      comments: buildCommentResults('posted'),
       command,
       payload,
     }
@@ -444,7 +518,7 @@ export async function postFindingsAsReview(input: PostReviewInput): Promise<Post
     const msg = (err as Error).message ?? `cannot spawn ${bin}`
     return {
       reviewId: null,
-      comments: input.findingIds.map((id) => ({ id, status: 'failed' as const, message: msg })),
+      comments: buildCommentResults('failed', msg),
       command,
       payload,
     }
@@ -453,11 +527,7 @@ export async function postFindingsAsReview(input: PostReviewInput): Promise<Post
   if (exit !== 0) {
     return {
       reviewId: null,
-      comments: input.findingIds.map((id) => ({
-        id,
-        status: 'failed' as const,
-        message: stderrText.trim(),
-      })),
+      comments: buildCommentResults('failed', stderrText.trim()),
       command,
       payload,
     }
@@ -476,7 +546,7 @@ export async function postFindingsAsReview(input: PostReviewInput): Promise<Post
 
   return {
     reviewId,
-    comments: input.findingIds.map((id) => ({ id, status: 'posted' as const })),
+    comments: buildCommentResults('posted'),
     command,
     payload,
   }

package/skills/magpie/scripts/refresh.ts

@@ -1,7 +1,7 @@
-import { readdir, unlink } from 'node:fs/promises'
+import { readdir, readFile, unlink } from 'node:fs/promises'
 import { basename, join } from 'node:path'
 import { type PostStatusMap, renderFindingsToDisk } from './render-findings.ts'
-import { parseFinding } from './types.ts'
+import { type PrFileEntry, parseFinding } from './types.ts'
 
 export type RefreshResult = {
   refreshed: boolean
@@ -60,6 +60,7 @@ export async function refreshFindings(runDir: string): Promise<RefreshResult> {
   }
 
   let pr: { number: number; branch: string; headSha: string } | undefined
+  let files: PrFileEntry[] = []
   try {
     const prJson = (await Bun.file(join(runDir, 'pr.json')).json()) as Record<string, unknown>
     const prNumber = Number(prJson.number ?? 0)
@@ -70,12 +71,23 @@ export async function refreshFindings(runDir: string): Promise<RefreshResult> {
         headSha: String(prJson.headRefOid ?? '?'),
       }
     }
+    const filesArray = Array.isArray(prJson.files) ? (prJson.files as unknown[]) : []
+    files = filesArray.map((f) => {
+      const entry = f as Record<string, unknown>
+      return {
+        path: String(entry.path ?? ''),
+        additions: Number(entry.additions ?? 0),
+        deletions: Number(entry.deletions ?? 0),
+      }
+    })
   } catch {
     // optional file; archived runs may not include pr.json
   }
 
+  const diff = await readFile(join(runDir, 'diff.patch'), 'utf8').catch(() => '')
+
   await renderFindingsToDisk(
-    { findings, postStatus, runId: basename(runDir), pr },
+    { findings, postStatus, runId: basename(runDir), pr, files, diff },
     join(screenDir, 'findings.html'),
   )
 

package/skills/magpie/scripts/server.ts

@@ -1,6 +1,6 @@
 import { appendFile, readdir, readFile, stat, unlink, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { postFindingsAsReview } from './post-cmd.ts'
+import { parseRepoFromUrl, postFindingsAsReview } from './post-cmd.ts'
 
 export type ServerHandle = {
   url: string
@@ -130,12 +130,23 @@ export async function startServer(input: StartServerInput): Promise<ServerHandle
           const prJson = JSON.parse(await readFile(join(runDir, 'pr.json'), 'utf8')) as {
             number: number
             headRefOid: string
+            url?: string
+          }
+          const repo = prJson.url ? parseRepoFromUrl(prJson.url) : null
+          if (!repo) {
+            return new Response(
+              JSON.stringify({
+                error: 'Cannot resolve target repo from pr.json (missing or unparseable url).',
+              }),
+              { status: 500, headers: { 'content-type': 'application/json' } },
+            )
           }
           const result = await postFindingsAsReview({
             runDir,
             findingIds: ids,
             prNumber: prJson.number,
             headSha: prJson.headRefOid,
+            repo,
             dryRun: process.env.MAGPIE_DRY_RUN_POST === '1',
           })
           const status =

package/skills/magpie/skill.json

@@ -1,7 +1,7 @@
 {
   "name": "magpie",
-  "version": "0.2.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 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"