skilllib 1.11.0 → 1.11.2

package/README.md

@@ -2,7 +2,7 @@
 
 # ◆ skilllib
 
-**Manage your agent skills like dependencies.**<br>
+**Manage your agent skills like dependencies, or let your agents do it.**<br>
 One library for all your skills. Each repo gets only the ones it needs,<br>
 and every agent you use can see them.
 
@@ -12,9 +12,11 @@ and every agent you use can see them.
 ![agents](https://img.shields.io/badge/works%20with-Claude%20Code%20%C2%B7%20Cursor%20%C2%B7%20Codex%20%C2%B7%20Zed%20%C2%B7%20Grok-c792ea)
 
 ```bash
-npx skilllib
+npm install -g skilllib && skilllib agent-skill install
 ```
 
+Then ask your agent: *"Which skills can you use here, and which of my global skills should only load in this repo?"*
+
 <img src="docs/design/repo.svg" alt="skilllib: Places on the left, a repo's skills with their issues and uses, and the selected skill's fixes and actions below" width="100%">
 
 </div>
@@ -43,18 +45,18 @@ Most agents can't turn off a global skill for just one repo. Claude Code can, bu
 
 ## How skilllib fixes it
 
+- **🤖 Your agents run it.** One small skill teaches Claude Code, Cursor, Codex, Zed and Grok to use the skilllib CLI. Ask them what's loaded here, what to add, what's out of date, or to move a global skill into the repos that use it. Every command has `--json` output shaped for agents, and they ask before changing anything.
 - **📚 Your skills: one versioned library.** Every skill has a single master copy in `~/.skilllib/library`, and each change becomes a new version.
 - **📦 Per-repo installs, pinned like dependencies.** Each repo lists its skills and versions in `skilllib.json`. `sync` reproduces them exactly, and `update` moves to the newest.
 - **🤝 One copy, every agent.** skilllib puts one real copy in the repo and links it into whichever folders your other agents read.
-- **🧹 Health: one list of what to fix.** Global skills you haven't decided about, skills loaded twice, duplicate copies, updates, broken links, each with its fix. For a global skill: move it to the repos that need it, keep it global, or delete it. Usage numbers and descriptions help you decide.
+- **🧹 Health: one list of what to fix.** Global skills you haven't decided about, skills loaded twice, duplicate copies, updates, broken links, each with its fix. For a global skill: move it to the repos that need it, keep it global, or delete it. Usage numbers and descriptions help you, or your agent, decide.
 - **✓ Global on purpose.** Some skills belong everywhere. Mark them once and skilllib stops warning about them.
 - **🔎 See everything in a repo:**
   - where each skill comes from (the repo, your library, global, a plugin, claude.ai…)
   - which agents load it
   - whether it's committed to git or gitignored
   - how often it was used
-- **💬 Talk to your agents about your skills.** Ask Claude Code, Cursor, Codex or Grok "which skills can you use here, and where do they come from?" or "which of my skills should this repo use?". They answer with skilllib.
-- **✦ Ask an agent.** Copy a ready-made prompt with all of that data, and let Claude Code, Cursor, Codex or Grok tell you what to keep, move or delete.
+- **🖥 An app when you want to look yourself.** `skilllib` opens a terminal app with the same data and fixes, and can copy a review prompt for any agent.
 - **🛟 Nothing is lost.** Every removal goes to a backup you can restore with one key.
 
 Everything runs locally: no server, no account, no network calls.
@@ -63,17 +65,27 @@ Everything runs locally: no server, no account, no network calls.
 
 ## Quick start
 
+It needs **Node.js 22+** and works on macOS and Linux. Windows support is newer: it uses directory junctions, so no admin rights are needed.
+
+### With your agents
+
 ```bash
-npm install -g skilllib    # or: npx skilllib
-skilllib
+npm install -g skilllib
+skilllib agent-skill install
 ```
 
-It needs **Node.js 22+** and works on macOS and Linux. Windows support is newer: it uses directory junctions, so no admin rights are needed.
+This installs the `skilllib` skill where your agents look, in every repo (see [Use it from your agents](#use-it-from-your-agents)). Start a new agent session in any repo and ask away.
+
+### In the app
+
+```bash
+skilllib    # or: npx skilllib
+```
 
 On first run, skilllib asks two things:
 
 1. **Which agents you use:** Claude Code, Cursor, Codex, Zed, Grok. The ones installed on your machine are pre-selected.
-2. **Where your projects live**, e.g. `~/Projects`. It finds every git repo in there, and rescans each time it opens.
+2. **Where your projects live**, e.g. `~/Projects`. It finds every git repo in there, and rescans each time it opens. Agent worktrees (`<repo>/.claude/worktrees/*`) aren't counted as projects.
 
 Then a good first session looks like this:
 
@@ -83,7 +95,26 @@ Then a good first session looks like this:
 
 ---
 
-## Manual
+## Use it from your agents
+
+`skilllib agent-skill install` puts a small `skilllib` skill in `~/.claude/skills` (Claude Code, Cursor and Grok read it there), with a link in `~/.agents/skills` (Codex and Zed). This is the one skill that should be global, because it's about every repo. Upgrading skilllib keeps it up to date, and `skilllib agent-skill remove` takes it out. Agents use it from their next session.
+
+Then ask in plain words. A few examples, with what the agent runs:
+
+| Ask | The agent runs |
+|---|---|
+| *Which skills can you use here, and where does each come from?* | `status --json`, which Claude Code gets as the skill loads, so it answers in one step |
+| *Which of my skills should this repo use?* | `list --json`, then reads the README and manifests, and gives a reason for each pick |
+| *Which skills do I use most? Which ones never?* | `usage --json` (Claude Code usage only, so "never" is a hint) |
+| *Move my global skills into the repos that actually use them.* | `usage --json` to see where each is used, then `global move <name> --to <repo>`, or `global keep <name>` for the ones you want everywhere |
+| *Is anything broken or out of date? Fix it.* | `status --json` or `doctor --json`, then `doctor --fix` for the safe repairs and `apply <id> <choice>` for each decision you approve |
+| *Add the skill from github.com/acme/skills to my library.* | Clones the repo into a temporary folder, then `import <dir>` and `add <name>`. skilllib itself downloads nothing |
+
+The agent asks before it changes anything, unless you asked for that exact change. Anything skilllib removes can be restored: see [Backups](#backups).
+
+---
+
+## The app
 
 ### The screen
 
@@ -224,25 +255,6 @@ Paste it into Claude Code, Cursor, Codex or Grok. You get back **keep global / m
 
 It's in every skill's actions, in a repo's **⋯** menu (all its skills), and at the top of Global (all your global skills).
 
-### Ask your agents about skills
-
-Run this once:
-
-```bash
-skilllib agent-skill install
-```
-
-This installs a small `skilllib` skill that tells your agents how to use skilllib. It goes where your agents look, in every repo: `~/.claude/skills` for Claude Code and Cursor, with a link in `~/.agents/skills` for Codex and Zed. This is the one skill that should be global, because it's about every repo. Health and Settings offer the same install, and upgrading skilllib keeps the skill up to date.
-
-Then, in any repo, you can ask:
-
-- *Which skills can you use in this repo?*
-- *Where does each one come from?*
-- *Which skills from my library would you add to this project?*
-- *Is anything out of date? Update it.*
-
-The agent runs `skilllib status --json`, `skilllib list --json` and similar commands, reads the repo, and answers. It asks before it adds or removes anything. `skilllib agent-skill remove` uninstalls it.
-
 ### Duplicates
 
 The same skill often reaches your agents more than once: a copy in `.claude/skills` *and* in `.agents/skills`, a global copy *and* a repo copy, a plugin *and* your skill. skilllib keeps **one real copy per skill, plus only the links your agents need**. **Health** lists each case on the skill it's about, with its fix. From the command line, `skilllib doctor` lists them and `skilllib tidy` fixes the folder ones.
@@ -351,7 +363,7 @@ A skill is a folder with a `SKILL.md`. These are all the places your agents load
 
 ## Command line
 
-Everything the app does also works as a command, for scripts and CI:
+Everything the app does also works as a command, for your agents, scripts and CI:
 
 ```
 skilllib                        open the app (prints `status` when piped)
@@ -385,7 +397,7 @@ The repo commands (`status`, `add`, `remove`, `sync`, `outdated`, `update`, `lin
 
 Flags: `--force` (overwrite local edits, backed up to `~/.skilllib/edit-backup`), `--allow-tracked` (link into git-tracked folders; skills git doesn't share are still left out), `--days N`, `--json`. For `tidy`: `--dry-run` (preview), `--allow-git` (also change committed files), `<name> --keep <folder>` (the copy that wins when copies differ).
 
-A command exits 1 when it couldn't do all you asked: a skill skipped (not in the library, or local edits in the way), links git-tracked folders blocked, an unknown `tidy` name or `--keep` folder. What it did do is still done, and listed.
+A command exits 1 when it couldn't do all you asked: a skill skipped (not in the library, or local edits in the way), links git-tracked folders blocked, an unknown `tidy` name or `--keep` folder. What it did do is still done, and listed. An unknown or misspelled flag is an error too, so a typo never runs silently. With `--json`, a failure prints `{"error": "…"}` on stdout as well as the message on stderr.
 
 **`--json`** prints one line of JSON on stdout, for scripts and agents. Messages and warnings go to stderr. It works with `status`, `list`, `show`, `projects`, `outdated`, `usage`, `doctor`, `apply`, `add`, `remove`, `sync`, `update`, `import`, `global move` and `agent-skill`. The output is shaped to keep agents fast and cheap:
 
@@ -442,7 +454,7 @@ Environment variables: `SKILLLIB_HOME` moves `~/.skilllib`, `$VISUAL` / `$EDITOR
 - Turning off Cursor marketplace plugins: skilllib lists them and reports ones that duplicate your skills, but Cursor doesn't record which plugins are on in a file skilllib can read.
 - Installing plugins from a marketplace: use `/plugin` in Claude Code. Plugins a repo's own `.claude/settings.json` turns on without installing them aren't listed in Plugins yet.
 - Unloading a `npx skills` skill doesn't update that tool's lock file.
-- Installing new skills straight from GitHub is coming. For now, `skilllib import <folder>` or copy one from a repo.
+- Downloading skills: skilllib makes no network calls. To get a skill from GitHub, clone the repo and run `skilllib import <folder>`, or ask your agent to.
 
 ---
 

package/dist/{chunk-LO4FMXDE.js → chunk-OFWHWIER.js}

@@ -47,6 +47,7 @@ var jsonMode = false;
 function setJsonMode(on) {
   jsonMode = on;
 }
+var isJsonMode = () => jsonMode;
 function json(output, data) {
   process.stdout.write(JSON.stringify(data) + "\n");
 }
@@ -219,7 +220,8 @@ function isSkillDir(dir) {
 function listFiles(dir) {
   return readdirSync(dir).filter((entry) => !IGNORED.has(entry)).flatMap((entry) => {
     const full = join3(dir, entry);
-    return statSync(full).isDirectory() ? listFiles(full) : [full];
+    const st = statSync(full, { throwIfNoEntry: false });
+    return !st ? [] : st.isDirectory() ? listFiles(full) : [full];
   });
 }
 function treeHash(dir) {
@@ -232,8 +234,9 @@ function treeHash(dir) {
   return hash.digest("hex").slice(0, 16);
 }
 function copySkill(from, to) {
+  const source = realpathSync2(from);
   rmSync(to, { recursive: true, force: true });
-  cpSync(realpathSync2(from), to, { recursive: true, dereference: true, filter: (src) => !IGNORED.has(basename(src)) });
+  cpSync(source, to, { recursive: true, dereference: true, filter: (src) => !IGNORED.has(basename(src)) && existsSync2(src) });
 }
 function skillDirsIn(dir) {
   if (!existsSync2(dir)) return [];
@@ -461,7 +464,7 @@ function setKeepGlobal(names, keep) {
 
 // src/library.ts
 import { execFileSync } from "child_process";
-import { existsSync as existsSync7, lstatSync as lstatSync2, mkdirSync as mkdirSync5, readdirSync as readdirSync4, readFileSync as readFileSync6, realpathSync as realpathSync4, renameSync, rmSync as rmSync2, symlinkSync, unlinkSync, writeFileSync as writeFileSync5 } from "fs";
+import { cpSync as cpSync2, existsSync as existsSync7, lstatSync as lstatSync2, mkdirSync as mkdirSync5, readdirSync as readdirSync4, readFileSync as readFileSync6, realpathSync as realpathSync4, renameSync, rmSync as rmSync2, symlinkSync, unlinkSync, writeFileSync as writeFileSync5 } from "fs";
 import { basename as basename3, dirname as dirname2, join as join8, relative as relative2, sep as sep3 } from "path";
 
 // src/sources.ts
@@ -1032,25 +1035,28 @@ function removeSkill(root, name, { force = false } = {}) {
   return { name, action: "removed", ...backedUp ? { backedUp } : {} };
 }
 function syncProject(root, { force = false } = {}) {
-  const { skills } = readManifest(root);
-  return Object.entries(skills).flatMap(([name, dep]) => {
-    const local = treeHash(join8(root, dep.dir ?? PROJECT_SKILLS_DIR, name));
-    const linksOk = (dep.links ?? []).every((d) => existsSync7(join8(root, d, name, "SKILL.md")));
-    if (local === dep.hash && linksOk) return [];
-    const pinned = dep.version > 0 && getVersion(name, dep.version) ? dep.version : void 0;
-    if (local !== null && local !== dep.hash && !force) return [{ name, action: "skipped", reason: "has local edits (use --force to reset them)" }];
-    const change = addSkill(root, name, { force: true, version: pinned });
-    if (change.action === "skipped") return [{ ...change, reason: `not in your library (${tildify(libraryDir())}); import it, or set SKILLLIB_HOME to the library that has it` }];
-    return [{ ...change, action: local === null ? "installed" : change.action }];
-  });
+  return Object.keys(readManifest(root).skills).flatMap((name) => syncSkill(root, name, { force }));
+}
+function syncSkill(root, name, { force = false } = {}) {
+  const dep = readManifest(root).skills[name];
+  if (!dep) return [];
+  const local = treeHash(join8(root, dep.dir ?? PROJECT_SKILLS_DIR, name));
+  const linksOk = (dep.links ?? []).every((d) => existsSync7(join8(root, d, name, "SKILL.md")));
+  if (local === dep.hash && linksOk) return [];
+  if (local !== null && local !== dep.hash && !force) return [{ name, action: "skipped", reason: "has local edits (use --force to reset them)" }];
+  const change = addSkill(root, name, { force: true, version: pinnedVersion(name, dep) });
+  if (change.action === "skipped") return [{ ...change, reason: `not in your library (${tildify(libraryDir())}); import it, or set SKILLLIB_HOME to the library that has it` }];
+  return [{ ...change, action: local === null ? "installed" : change.action }];
+}
+function pinnedVersion(name, dep) {
+  return versionForHash(name, dep.hash)?.version ?? (dep.version > 0 && getVersion(name, dep.version) ? dep.version : void 0);
 }
 function discardEdits(root, name) {
   const dep = readManifest(root).skills[name];
   if (!dep) return { name, action: "skipped", reason: "not managed by skilllib in this project" };
   const dir = join8(root, dep.dir ?? PROJECT_SKILLS_DIR, name);
-  const pinned = dep.version > 0 && getVersion(name, dep.version) ? dep.version : void 0;
   if (existsSync7(dir) && !isLink(dir)) stash(dir, "edit-backup");
-  return addSkill(root, name, { force: true, version: pinned });
+  return addSkill(root, name, { force: true, version: pinnedVersion(name, dep) });
 }
 function updateProject(root, names, { force = false } = {}) {
   const { skills } = readManifest(root);
@@ -1090,6 +1096,15 @@ function readBackupIndex(bucket) {
     return {};
   }
 }
+function move(from, to) {
+  try {
+    renameSync(from, to);
+  } catch (err) {
+    if (err.code !== "EXDEV") throw err;
+    cpSync2(from, to, { recursive: true, verbatimSymlinks: true });
+    rmSync2(from, { recursive: true, force: true });
+  }
+}
 function stash(dir, bucket) {
   let at = Date.now();
   const entryAt = (ms) => `${basename3(dir)}-${new Date(ms).toISOString().replace(/[:.]/g, "-")}`;
@@ -1097,7 +1112,7 @@ function stash(dir, bucket) {
   const entry = entryAt(at);
   const target = join8(skilllibHome(), bucket, entry);
   mkdirSync5(join8(skilllibHome(), bucket), { recursive: true });
-  renameSync(dir, target);
+  move(dir, target);
   writeFileSync5(backupIndexFile(bucket), JSON.stringify({ ...readBackupIndex(bucket), [entry]: dir }, null, 2) + "\n");
   return target;
 }
@@ -1195,7 +1210,7 @@ function restoreBackup(backup) {
   }
   if (taken) return { ok: false, reason: `${backup.name} already exists there` };
   mkdirSync5(join8(to, ".."), { recursive: true });
-  renameSync(backup.path, to);
+  move(backup.path, to);
   forgetLatest(backup.name);
   return { ok: true, to };
 }
@@ -1265,6 +1280,7 @@ function refreshAgentSkill() {
 
 // src/commands.ts
 import { existsSync as existsSync13, readFileSync as readFileSync9 } from "fs";
+import { parseArgs as parseFlags } from "util";
 import { basename as basename9, join as join14, resolve as resolve7, sep as sep5 } from "path";
 
 // src/git.ts
@@ -2604,23 +2620,35 @@ function moveGlobalSkills(skills, roots, { group, allowTracked = false, label =
 
 // src/commands.ts
 var USAGE_DAYS = 30;
+var FLAGS = {
+  force: { type: "boolean" },
+  all: { type: "boolean" },
+  global: { type: "boolean" },
+  fix: { type: "boolean" },
+  "allow-tracked": { type: "boolean" },
+  json: { type: "boolean" },
+  "dry-run": { type: "boolean" },
+  "allow-git": { type: "boolean" },
+  days: { type: "string" },
+  keep: { type: "string" },
+  to: { type: "string", multiple: true }
+};
 function parseArgs(argv) {
-  const daysIdx = argv.indexOf("--days");
-  const days = daysIdx >= 0 ? Number(argv[daysIdx + 1]) : USAGE_DAYS;
-  const keepIdx = argv.indexOf("--keep");
+  const { values: v, positionals } = parseFlags({ args: argv, options: FLAGS, allowPositionals: true, strict: true });
+  const days = Number(v.days ?? USAGE_DAYS);
   return {
-    positional: argv.filter((a, i) => !a.startsWith("--") && !["--days", "--keep", "--to"].includes(argv[i - 1])),
-    force: argv.includes("--force"),
-    all: argv.includes("--all"),
-    global: argv.includes("--global"),
-    fix: argv.includes("--fix"),
-    allowTracked: argv.includes("--allow-tracked"),
-    json: argv.includes("--json"),
+    positional: positionals,
+    force: !!v.force,
+    all: !!v.all,
+    global: !!v.global,
+    fix: !!v.fix,
+    allowTracked: !!v["allow-tracked"],
+    json: !!v.json,
     days: Number.isFinite(days) && days > 0 ? days : USAGE_DAYS,
-    dryRun: argv.includes("--dry-run"),
-    allowGit: argv.includes("--allow-git"),
-    ...keepIdx >= 0 && argv[keepIdx + 1] ? { keep: argv[keepIdx + 1] } : {},
-    to: argv.flatMap((a, i) => argv[i - 1] === "--to" && !a.startsWith("--") ? a.split(",").filter(Boolean) : [])
+    dryRun: !!v["dry-run"],
+    allowGit: !!v["allow-git"],
+    ...v.keep ? { keep: v.keep } : {},
+    to: (v.to ?? []).flatMap((t) => t.split(",").filter(Boolean))
   };
 }
 function colorState(state) {
@@ -2844,8 +2872,7 @@ function projects(args) {
 }
 function add(args) {
   if (args.positional.length === 0) {
-    error("Usage: skilllib add <skill-name>... [--force]");
-    process.exit(1);
+    throw new Error("Usage: skilllib add <skill-name>... [--force]");
   }
   const root = requireProject();
   if (args.allowTracked) allowTrackedLinks(root);
@@ -2854,13 +2881,13 @@ function add(args) {
 }
 function remove(args) {
   if (args.positional.length === 0) {
-    error("Usage: skilllib remove <skill-name>... [--force]");
-    process.exit(1);
+    throw new Error("Usage: skilllib remove <skill-name>... [--force]");
   }
   const root = requireProject();
   printChanges(root, args.positional.map((name) => removeSkill(root, name, { force: args.force })), args);
 }
 function sync(args) {
+  if (args.positional.length) throw new Error(`sync takes no skill names: it installs exactly what skilllib.json pins. To add a skill: skilllib add ${args.positional.join(" ")}`);
   const roots = args.all ? visibleProjects() : [requireProject()];
   const results = roots.map((root) => {
     if (args.allowTracked) allowTrackedLinks(root);
@@ -2913,20 +2940,21 @@ function outdated(args) {
 function importSkills(args) {
   const dirs = args.global ? machineSkills().filter((m) => m.movable && !m.broken).map((m) => m.path) : args.positional.map((p) => resolve7(p));
   if (dirs.length === 0) {
-    error("Usage: skilllib import <skill-dir>... [--force] | skilllib import --global");
-    process.exit(1);
+    throw new Error("Usage: skilllib import <skill-dir>... [--force] | skilllib import --global");
   }
   const results = [];
   for (const dir of dirs) {
     if (!isSkillDir(dir)) {
       warn(`${tildify(dir)}: no SKILL.md, skipping`);
       results.push({ path: dir, status: "no SKILL.md" });
+      process.exitCode = 1;
       continue;
     }
     const { name, status: result } = importSkill(dir, { force: args.force });
     results.push({ path: dir, name, status: result });
     if (result === "exists") {
       warn(`${name}: the library already has a different version (use --force to replace it)`);
+      process.exitCode = 1;
       continue;
     }
     success(`${name} ${dim(result === "unchanged" ? "already in library" : result === "added" ? "added to library" : "library updated")}`);
@@ -2990,12 +3018,11 @@ function folders(args) {
   info(roots.length ? `Project folders:
 ${roots.map((r) => `  ${tildify(r)}`).join("\n")}` : "No project folders. Add one: skilllib folders add ~/Projects");
   if (hidden.length) info(dim(`Hidden projects: ${hidden.map((h) => tildify(h)).join(", ")}  (skilllib unhide <path>)`));
-  if (failed) process.exit(1);
+  if (failed) process.exitCode = 1;
 }
 function unhide(args) {
   if (args.positional.length === 0) {
-    error("Usage: skilllib unhide <path>...");
-    process.exit(1);
+    throw new Error("Usage: skilllib unhide <path>...");
   }
   let failed = false;
   for (const p of args.positional) {
@@ -3007,18 +3034,16 @@ function unhide(args) {
       failed = true;
     }
   }
-  if (failed) process.exit(1);
+  if (failed) process.exitCode = 1;
 }
 function newSkill(args) {
   const [name, ...rest] = args.positional;
   if (!name) {
-    error("Usage: skilllib new <name> [description]");
-    process.exit(1);
+    throw new Error("Usage: skilllib new <name> [description]");
   }
   const r = createSkill(name, rest.join(" "));
   if (!r.ok) {
-    error(`Can't create ${name}: ${r.reason}`);
-    process.exit(1);
+    throw new Error(`Can't create ${name}: ${r.reason}`);
   }
   success(`Created ${tildify(join14(r.dir, "SKILL.md"))}`);
 }
@@ -3033,8 +3058,7 @@ function restore(args) {
   }
   const backup = backups.find((b) => b.name === name);
   if (!backup) {
-    error(`No backup named ${name}`);
-    process.exit(1);
+    throw new Error(`No backup named ${name}`);
   }
   const r = backup.kind === "plugin" ? restorePlugin(backup) : restoreBackup(backup);
   if (r.ok) success(`Restored ${name} to ${tildify(r.to)}`);
@@ -3160,8 +3184,7 @@ function show(args) {
   const name = args.positional[0];
   const dir = name ? join14(libraryDir(), name) : "";
   if (!name || !isSkillDir(dir)) {
-    error(name ? `${name} is not in the library` : "Usage: skilllib show <skill-name>");
-    process.exit(1);
+    throw new Error(name ? `${name} is not in the library` : "Usage: skilllib show <skill-name>");
   }
   const { description } = readSkillInfo(dir);
   if (args.json) {
@@ -3187,8 +3210,7 @@ function harnessesCommand(args) {
   if (args.positional.length) {
     const unknown = args.positional.filter((p) => !ids.includes(p));
     if (unknown.length) {
-      error(`Unknown harness: ${unknown.join(", ")}. Choose from: ${ids.join(", ")}`);
-      process.exit(1);
+      throw new Error(`Unknown harness: ${unknown.join(", ")}. Choose from: ${ids.join(", ")}`);
     }
     setHarnesses(args.positional);
     success(`Using ${args.positional.join(", ")}`);
@@ -3225,14 +3247,12 @@ function globalCommand(args) {
   if (action === "keep" || action === "unkeep") {
     const unknown = names.filter((n) => !yours.some((m) => m.name === n));
     if (!names.length || unknown.length) {
-      error(names.length ? `Not one of your global skills: ${unknown.join(", ")}` : `Usage: skilllib global ${action} <name>...`);
-      process.exit(1);
+      throw new Error(names.length ? `Not one of your global skills: ${unknown.join(", ")}` : `Usage: skilllib global ${action} <name>...`);
     }
     setKeepGlobal(names, action === "keep");
     success(action === "keep" ? `Keeping ${names.join(", ")} global on purpose` : `${names.join(", ")} will show up in cleanup again`);
   } else if (action) {
-    error("Usage: skilllib global [keep|unkeep <name>...] | skilllib global move <name>... --to <repo>...");
-    process.exit(1);
+    throw new Error("Usage: skilllib global [keep|unkeep <name>...] | skilllib global move <name>... --to <repo>...");
   }
   const kept = keptGlobal();
   if (!yours.length) return info("None of your skills load globally.");
@@ -3285,8 +3305,7 @@ function tidy(args) {
   const names = args.positional;
   const keepFor = (base) => args.keep ? Object.fromEntries(names.map((n) => [n, base ? resolve7(base, args.keep) : expandHome(args.keep)])) : {};
   if (args.keep && !names.length) {
-    error("Usage: skilllib tidy <name>... --keep <folder>");
-    process.exit(1);
+    throw new Error("Usage: skilllib tidy <name>... --keep <folder>");
   }
   const targets = args.global ? [null] : args.all ? visibleProjects() : [requireProject()];
   const problems = [];
@@ -3306,8 +3325,7 @@ function tidy(args) {
     }
   }
   if (problems.length) {
-    for (const p of problems) error(p);
-    process.exit(1);
+    throw new Error(problems.join("\n"));
   }
   const reports = targets.map(
     (root) => root === null ? { label: "global folders", report: planGlobalTidy({ keep: keepFor(null) }) } : { label: basename9(root), report: planProjectTidy(root, { keep: keepFor(root) }) }
@@ -3347,8 +3365,7 @@ function agentSkill(args) {
   if (action === "install") {
     const r = installAgentSkill();
     if (!r.ok) {
-      error(`Can't install the skilllib skill: ${r.reason}`);
-      process.exit(1);
+      throw new Error(`Can't install the skilllib skill: ${r.reason}`);
     }
     if (args.json) return json("agent-skill", { state: agentSkillState(), dirs: r.dirs });
     success(`Installed in ${r.dirs.map((d) => tildify(d)).join(" and ")}`);
@@ -3380,6 +3397,8 @@ export {
   projectHere,
   readManifest,
   setJsonMode,
+  isJsonMode,
+  json,
   error,
   tildify,
   readConfig,
@@ -3406,7 +3425,7 @@ export {
   relinkDependency,
   addSkill,
   removeSkill,
-  syncProject,
+  syncSkill,
   updateProject,
   importSkill,
   removeUntracked,

package/dist/index.js

@@ -9,6 +9,8 @@ import {
   globalCommand,
   harnessesCommand,
   importSkills,
+  isJsonMode,
+  json,
   link,
   list,
   newSkill,
@@ -28,7 +30,7 @@ import {
   unhide,
   update,
   usage
-} from "./chunk-LO4FMXDE.js";
+} from "./chunk-OFWHWIER.js";
 
 // src/index.ts
 import { readFileSync } from "fs";
@@ -91,15 +93,15 @@ function packageVersion() {
 }
 async function main() {
   const [command, ...rest] = process.argv.slice(2);
+  setJsonMode(rest.includes("--json"));
   const args = parseArgs(rest);
-  setJsonMode(args.json);
   if (!["--version", "-v", "version", "help", "--help", "-h"].includes(command ?? "")) refreshAgentSkill();
   switch (command) {
     case void 0:
-      return process.stdin.isTTY && process.stdout.isTTY ? (await import("./tui-3LDZ5GOZ.js")).tui() : overview(args);
+      return process.stdin.isTTY && process.stdout.isTTY ? (await import("./tui-NGTOOVAQ.js")).tui() : overview(args);
     case "ui":
       if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error("`skilllib ui` needs an interactive terminal. Agents and scripts: use `skilllib status --json`.");
-      return (await import("./tui-3LDZ5GOZ.js")).tui();
+      return (await import("./tui-NGTOOVAQ.js")).tui();
     case "status":
       return status(args);
     case "add":
@@ -108,7 +110,6 @@ async function main() {
     case "rm":
       return remove(args);
     case "sync":
-    case "install":
       return sync(args);
     case "update":
     case "upgrade":
@@ -165,6 +166,7 @@ async function main() {
       console.log(HELP);
       return;
     default:
+      if (isJsonMode()) throw new Error(`Unknown command: ${command} (skilllib help lists them)`);
       console.error(`Unknown command: ${command}
 `);
       console.log(HELP);
@@ -172,7 +174,9 @@ async function main() {
   }
 }
 main().catch((err) => {
-  error(err instanceof Error ? err.message : String(err));
+  const message = err instanceof Error ? err.message : String(err);
+  if (isJsonMode()) json("error", { error: message });
+  error(message);
   if (process.env.DEBUG && err instanceof Error) console.error(err.stack);
   process.exit(1);
 });

package/dist/json.d.cts

@@ -178,6 +178,10 @@ type DoctorJson = {
         message: string;
     };
 }[];
+/** Any command with --json that fails: it exits 1, and this is the one line on stdout. */
+type ErrorJson = {
+    error: string;
+};
 /** `skilllib apply <issue-id> [choice] --json` */
 type ApplyJson = {
     id: string;
@@ -219,4 +223,4 @@ type AgentSkillJson = {
     removed?: string[];
 };
 
-export type { AgentSkillJson, AgentSkillState, AllChangesJson, ApplyJson, ChangeJson, ChangesJson, DoctorJson, GitState, GlobalMoveJson, HarnessId, ImportJson, ListJson, OutdatedJson, ProjectSource, ProjectsJson, ShowJson, SkillState, SourceKind, StatusGlobalGroup, StatusIssue, StatusJson, StatusSkillGroup, UsageJson };
+export type { AgentSkillJson, AgentSkillState, AllChangesJson, ApplyJson, ChangeJson, ChangesJson, DoctorJson, ErrorJson, GitState, GlobalMoveJson, HarnessId, ImportJson, ListJson, OutdatedJson, ProjectSource, ProjectsJson, ShowJson, SkillState, SourceKind, StatusGlobalGroup, StatusIssue, StatusJson, StatusSkillGroup, UsageJson };

package/dist/json.d.ts

@@ -178,6 +178,10 @@ type DoctorJson = {
         message: string;
     };
 }[];
+/** Any command with --json that fails: it exits 1, and this is the one line on stdout. */
+type ErrorJson = {
+    error: string;
+};
 /** `skilllib apply <issue-id> [choice] --json` */
 type ApplyJson = {
     id: string;
@@ -219,4 +223,4 @@ type AgentSkillJson = {
     removed?: string[];
 };
 
-export type { AgentSkillJson, AgentSkillState, AllChangesJson, ApplyJson, ChangeJson, ChangesJson, DoctorJson, GitState, GlobalMoveJson, HarnessId, ImportJson, ListJson, OutdatedJson, ProjectSource, ProjectsJson, ShowJson, SkillState, SourceKind, StatusGlobalGroup, StatusIssue, StatusJson, StatusSkillGroup, UsageJson };
+export type { AgentSkillJson, AgentSkillState, AllChangesJson, ApplyJson, ChangeJson, ChangesJson, DoctorJson, ErrorJson, GitState, GlobalMoveJson, HarnessId, ImportJson, ListJson, OutdatedJson, ProjectSource, ProjectsJson, ShowJson, SkillState, SourceKind, StatusGlobalGroup, StatusIssue, StatusJson, StatusSkillGroup, UsageJson };

package/dist/{tui-3LDZ5GOZ.js → tui-NGTOOVAQ.js}

@@ -63,7 +63,7 @@ import {
   setPluginOn,
   skilllibHome,
   skillsLoadedIn,
-  syncProject,
+  syncSkill,
   tildify,
   turnOffIn,
   uninstallPlugin,
@@ -73,7 +73,7 @@ import {
   versionHistory,
   visibilityOf,
   visibleProjects
-} from "./chunk-LO4FMXDE.js";
+} from "./chunk-OFWHWIER.js";
 
 // src/tui/index.tsx
 import { render } from "ink";
@@ -1671,7 +1671,7 @@ function App({ initial, reload, loadUsage: loadUsage2 }) {
           pickRepos: (w, repos) => w.ops.moveGlobal(mine, repos, label)
         }),
         ...mine.some((m) => !m.kept) ? [fixOption({ label: `Keep all ${mine.length} global on purpose`, preview: `skilllib stops warning about these ${n(mine.length)}.`, run: (w) => (mine.forEach((m) => w.ops.keepGlobal(m.name, true)), `${n(mine.length)} marked as global on purpose`) })] : [],
-        fixOption({ label: `Delete all ${mine.length}`, preview: `Move these ${n(mine.length)} to Settings \u203A Backups.`, run: (w) => (mine.forEach((m) => w.ops.deleteGlobal(m)), `Deleted ${n(mine.length)} (in Settings \u203A Backups)`) })
+        fixOption({ label: `Delete all ${mine.length}`, preview: `Move these ${n(mine.length)} to Settings \u203A Backups.`, run: (w) => joined(mine.map((m) => w.ops.deleteGlobal(m))) })
       ] : [],
       ...libs.length ? [
         fixOption({
@@ -1683,7 +1683,7 @@ function App({ initial, reload, loadUsage: loadUsage2 }) {
         })
       ] : [],
       ...libs.length ? [fixOption(deleteLibraryFix(world, libs.map((l) => l.name)))] : [],
-      ...locals.length ? [fixOption({ label: `Remove all ${locals.length} from this repo`, preview: `Remove these ${n(locals.length)} from ${open}; your library keeps the tracked ones.`, run: (w) => (locals.forEach((s) => w.ops.remove(open, s.name)), `Removed ${n(locals.length)} from ${open}`) })] : [],
+      ...locals.length ? [fixOption({ label: `Remove all ${locals.length} from this repo`, preview: `Remove these ${n(locals.length)} from ${open}; your library keeps the tracked ones.`, run: (w) => joined(locals.map((s) => w.ops.remove(open, s.name))) })] : [],
       ...[...new Set(machines.filter((m) => m.source === "plugin").map((m) => m.where))].map((id) => ({ label: `Open ${id.split("@")[0]} in Plugins`, action: () => openInPlugins(id) })),
       { label: "Review prompt", action: () => ui.copy(reviewPrompt(world, names, `Review these related skills (${label}).`), `a review prompt for ${label}`) }
     ];
@@ -2013,7 +2013,8 @@ function App({ initial, reload, loadUsage: loadUsage2 }) {
         if (row.create && !/^[a-z0-9]/.test(m.query)) return setToast("Type the new skill's name first");
         setModal(null);
         if (!row.create) return apply(row.run);
-        row.run(world);
+        const created = row.run(world);
+        if (isFailure(created)) return setToast(`\u2717 ${said2(created)}`);
         return edit(world.ops.libraryFile(m.query), row.afterEdit);
       }
       if (isNameChar(input, key)) return setModal({ ...m, query: m.query + input.toLowerCase(), cursor: 0 });
@@ -2636,7 +2637,7 @@ function realOps(roots, backups) {
       return orForce(removeSkill(rootOf(repo), name), repo, "Remove it anyway", () => removeSkill(rootOf(repo), name, { force: true }));
     },
     restore: (repo, name) => {
-      const c = syncProject(rootOf(repo)).find((x) => x.name === name);
+      const [c] = syncSkill(rootOf(repo), name);
       return c ? result(c, repo) : `${name} is already in place`;
     },
     update: (repo, name) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilllib",
-  "version": "1.11.0",
+  "version": "1.11.2",
   "description": "Manage your agent skills like dependencies. One library for all your skills; each repo gets only the ones it needs, and every agent can see them. Works with Claude Code, Cursor, Codex, Zed and Grok.",
   "keywords": [
     "agent-skills",

package/skills/skilllib/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Bash(skilllib:*)
 
 The user manages agent skills with the `skilllib` CLI. Their **library** (`~/.skilllib/library`, "my skills", "the registry") holds versioned skills that load nowhere until added to a repo. A repo pins its skills in `skilllib.json`.
 
-Always pass `--json` (one line of JSON on stdout; messages go to stderr). Never run bare `skilllib` or `skilllib ui`: that's an interactive app.
+Always pass `--json` (one line of JSON on stdout; messages go to stderr). A failure exits 1 with `{"error": "..."}` as that line; `link`, `tidy` and `global keep` print messages only. Unknown flags are errors. Never run bare `skilllib` or `skilllib ui`: that's an interactive app.
 
 ## Reading
 
@@ -25,12 +25,12 @@ Also: `usage --json` (Claude Code usage only, so "unused" is a hint; each skill
 
 ## Changing (ask first unless the user asked for this exact change)
 
-`add <name>...` · `remove <name>...` · `update [name...]` · `sync` (pinned versions) · `import <dir>` (into the library) · `doctor --fix`. Pass several names in one call. Their result is `[{name, action, from, to, dirs, reason, blocked, uncommitted, backedUp}]`, which is the whole result: there's no need to check files afterwards.
+`add <name>...` · `remove <name>...` · `update [name...]` · `sync` (installs what `skilllib.json` pins; takes no names). Pass several names in one call. Their result is `[{name, action, from, to, dirs, reason, blocked, uncommitted, backedUp}]`, which is the whole result: there's no need to check files afterwards. `import <dir>...` (into the library) prints `[{path, name, status}]` and exits 1 if a folder was skipped (`exists`, `no SKILL.md`). `doctor --fix` prints doctor's issues, each fix with `fixed: {ok, message}`.
 
 - `skipped` + `reason`: nothing changed for that skill, and the command exits 1; tell the user. `--force` overwrites local edits (`backedUp` says where they went; `skilllib restore <name>` brings them back), but only use it with their OK.
 - `blocked`: git tracks that folder. Re-run with `--allow-tracked` only with their OK.
 - `uncommitted`: git tracks that folder but not the skill's real copy, so a link there would break for teammates; `--allow-tracked` doesn't change that. Once the copy is committed, `link --allow-tracked` adds it.
-- Changes apply from the agent's next session. Remind the user to commit `skilllib.json` and `.claude/skills`.
+- Changes apply from the agent's next session. Remind the user to commit `skilllib.json` and the folders in `dirs`.
 
 **Prefer per-repo skills to global ones.** A global skill loads in every repo, for every agent. When `usage --json` shows one used in only a few repos, propose moving it there: