skilllib 1.3.1 → 1.6.0

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import {
   add,
+  agentSkill,
   doctor,
   error,
   folders,
@@ -13,9 +14,11 @@ import {
   outdated,
   parseArgs,
   projects,
+  refreshAgentSkill,
   remove,
   restore,
   scan,
+  setJsonMode,
   show,
   status,
   sync,
@@ -23,7 +26,7 @@ import {
   unhide,
   update,
   usage
-} from "./chunk-TWQQHXVG.js";
+} from "./chunk-PHRUPZGX.js";
 
 // src/index.ts
 import { readFileSync } from "fs";
@@ -64,6 +67,13 @@ Health:
   skilllib restore [name]        Restore something skilllib moved out of the way
   skilllib unhide <path>         Show a hidden project again
 
+Agents:
+  skilllib agent-skill [install|remove]
+                                 Teach your agents to use skilllib, so you can ask them
+                                 "which skills can you use here?" in any repo
+  --json                         Machine-readable output (status list show projects outdated
+                                 usage doctor add remove sync update import agent-skill)
+
 Options: --force (overwrite local edits)  --allow-tracked (link into git-tracked skill folders)  --days N
 `.trim();
 function packageVersion() {
@@ -77,11 +87,14 @@ function packageVersion() {
 async function main() {
   const [command, ...rest] = process.argv.slice(2);
   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-H5IQAGAL.js")).tui() : status(args);
+      return process.stdin.isTTY && process.stdout.isTTY ? (await import("./tui-WYVSDGHD.js")).tui() : status(args);
     case "ui":
-      return (await import("./tui-H5IQAGAL.js")).tui();
+      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-WYVSDGHD.js")).tui();
     case "status":
       return status(args);
     case "add":
@@ -107,7 +120,7 @@ async function main() {
     case "scan":
       return scan(args);
     case "projects":
-      return projects();
+      return projects(args);
     case "link":
       return link(args);
     case "tidy":
@@ -132,6 +145,8 @@ async function main() {
       return doctor(args);
     case "usage":
       return usage(args);
+    case "agent-skill":
+      return agentSkill(args);
     case "--version":
     case "-v":
     case "version":

package/dist/{tui-H5IQAGAL.js → tui-WYVSDGHD.js}

@@ -3,15 +3,21 @@ import {
   addRoot,
   addSkill,
   allowTrackedLinks,
+  applyTidy,
   claudeBinary,
+  claudePlugins,
+  copyLabel,
   createSkill,
+  cursorPluginSkills,
   deleteGlobal,
   deleteLibrarySkill,
+  describeStep,
   discoverProjects,
   enabledHarnesses,
   findProjectRoot,
   forgetLatest,
   gitInfo,
+  gitVisibleSteps,
   harness,
   harnessesChosen,
   importSkill,
@@ -22,8 +28,11 @@ import {
   librarySkillDir,
   librarySkills,
   linkEverywhere,
+  linkGlobal,
   listBackups,
   machineSkills,
+  planGlobalTidy,
+  planProjectTidy,
   pluginBackups,
   projectOfFactory,
   projectStatus,
@@ -45,13 +54,15 @@ import {
   setKeepGlobal,
   setPluginEnabled,
   skilllibHome,
+  skillsLoadedIn,
   syncProject,
+  turnOffIn,
   unloadGlobal,
   updateProject,
   userHome,
   versionHistory,
   visibleProjects
-} from "./chunk-TWQQHXVG.js";
+} from "./chunk-PHRUPZGX.js";
 
 // src/tui/index.tsx
 import { render } from "ink";
@@ -299,17 +310,71 @@ function dailyUses(w, name, onlyRepo) {
   }
   return days;
 }
+function machineIn(w, p) {
+  return p.machine ?? w.machine;
+}
 function usable(w, projectName) {
   const p = project(w, projectName);
   const uses = (n) => w.usage[projectName]?.[n] ?? 0;
   return [
     ...p.skills.map((s) => ({ name: s.name, source: s.source, where: s.dir, agents: s.agents, uses: uses(s.name), local: s })),
-    ...w.machine.map((m) => ({ name: m.name, source: m.source, where: m.where, agents: m.agents, uses: uses(m.name), machine: m }))
+    ...machineIn(w, p).map((m) => ({ name: m.name, source: m.source, where: m.where, agents: m.agents, uses: uses(m.name), machine: m }))
   ];
 }
 function lib(w, name) {
   return w.library.find((l) => l.name === name);
 }
+var agentNames = (ids) => ids.map((a) => harness(a).name).join(", ");
+function dupeIssues(repo, name, d) {
+  const g = repo === null ? "-g" : "";
+  if (d.differ)
+    return [
+      {
+        id: `conflict${g}:${name}`,
+        severity: "problem",
+        title: `Copies differ: ${d.differ.map((c) => c.label + (c.runs.length ? ` (${agentNames(c.runs)})` : "")).join(" vs ")}`,
+        short: "Copies differ",
+        decision: true,
+        fixes: d.differ.filter((c) => c.canWin).map((c) => ({
+          label: `Keep the ${c.label} copy`,
+          preview: `The other ${d.differ.length === 2 ? "copy becomes a link" : "copies become links"} to it, so every agent runs this one. Replaced copies go to Settings \u203A Backups.${repo ? " If git tracks a copy that changes, skilllib asks first." : ""}`,
+          run: (w) => w.ops.tidy(repo, name, { keep: c.dir })
+        }))
+      }
+    ];
+  return [
+    {
+      id: `copies${g}:${name}`,
+      severity: "warning",
+      title: repo ? "More copies or links in this repo than your agents need" : "Identical copies in several global folders",
+      short: "Extra copies",
+      decision: false,
+      fixes: [
+        {
+          label: "Keep one copy, plus the links your agents need",
+          preview: `${d.steps.join("; ")}. Replaced copies go to Settings \u203A Backups.${d.git.length ? ` Git would see ${d.git.join(", ")}: skilllib asks before ${d.git.length === 1 ? "that one" : "those"}.` : ""}`,
+          run: (w) => w.ops.tidy(repo, name)
+        }
+      ]
+    }
+  ];
+}
+function cursorPluginIssue(name, plugin) {
+  return {
+    id: `cursor-plugin:${name}`,
+    severity: "warning",
+    title: `Also in the Cursor plugin ${plugin}: Cursor lists both while it's on`,
+    short: "Also in a Cursor plugin",
+    decision: true,
+    fixes: [
+      {
+        label: "Turn the plugin off in Cursor (Settings \u203A Plugins)",
+        preview: "skilllib can't read or change Cursor's plugins. Your skill wins once the plugin is off.",
+        run: () => `Turn ${plugin} off in Cursor; skilllib can't tell whether it's on`
+      }
+    ]
+  };
+}
 function globalFixes(m) {
   return [
     {
@@ -355,26 +420,38 @@ function machineIssues(w, m) {
         }
       ]
     });
-  const twins = w.machine.filter((x) => x.source === "global" && x.name === m.name && !x.broken && x.agents.some((a) => m.agents.includes(a)));
-  if (m.source === "global" && twins.length > 1)
+  if (m.source === "global" && m.dupes) issues.push(...dupeIssues(null, m.name, m.dupes));
+  if (m.source === "global" && m.cursorPlugin && m.agents.includes("cursor")) issues.push(cursorPluginIssue(m.name, m.cursorPlugin));
+  const seen = new Set(w.machine.filter((x) => x.name === m.name && !x.broken).flatMap((x) => x.agents));
+  const blind = m.source === "global" && m.agents.length && !m.dupes ? w.agents.filter((a) => !seen.has(a)) : [];
+  const names = blind.map((a) => harness(a).name).join(", ");
+  const link = {
+    label: `Link it for ${names}`,
+    preview: `Add a link in the global skills folder ${names} read${blind.length === 1 ? "s" : ""} (nothing is copied or moved), so ${names} load${blind.length === 1 ? "s" : ""} it in every repo too.`,
+    run: (w2) => w2.ops.linkGlobal(m, blind)
+  };
+  if (m.kept && blind.length)
+    issues.push({ id: `blind-global:${m.name}`, severity: "warning", title: `${names} can't see it: only ${m.agents.map((a) => harness(a).name).join(", ")} load${m.agents.length === 1 ? "s" : ""} it`, short: `${names} can't see it`, decision: false, fixes: [link] });
+  if (m.source === "global" && !m.kept) {
+    const [move, ...rest] = globalFixes(m);
     issues.push({
-      id: `dup-global:${m.name}`,
-      severity: "problem",
-      title: `Loaded twice: in ${twins.map((t) => t.where).join(" and ")}`,
-      short: "Loaded twice",
+      id: `global:${m.name}`,
+      severity: "warning",
+      title: blind.length ? `Global, not reviewed: loads in every repo, but ${names} can't see it` : "Global, not reviewed: loads in every repo",
+      short: blind.length ? `Not reviewed \xB7 ${names} can't see it` : "Not reviewed",
       decision: true,
-      fixes: twins.map((t) => ({ label: `Delete the copy in ${t.where}`, preview: `Move ${t.path} to Settings \u203A Backups; the other copy stays.`, run: (w2) => w2.ops.deleteGlobal(t) }))
+      fixes: blind.length ? [move, link, ...rest] : [move, ...rest]
     });
-  if (m.source === "global" && !m.kept)
-    issues.push({ id: `global:${m.name}`, severity: "warning", title: "Global, not reviewed: loads in every repo", short: "Not reviewed", decision: true, fixes: globalFixes(m) });
+  }
   return issues;
 }
 function issuesOf(w, projectName, u) {
   const s = u.local;
   const issues = [];
   const shares = (m) => m.name === s.name && !m.broken && m.agents.some((a) => s.agents.includes(a));
-  const g = w.machine.find((m) => m.source === "global" && shares(m));
-  const vendor = w.machine.find((m) => m.source !== "global" && shares(m));
+  const loaded = machineIn(w, project(w, projectName));
+  const g = loaded.find((m) => m.source === "global" && shares(m));
+  const vendor = loaded.find((m) => m.source !== "global" && shares(m));
   const l = lib(w, s.name);
   const remove = {
     label: "Remove this repo's copy",
@@ -399,7 +476,23 @@ function issuesOf(w, projectName, u) {
       decision: false,
       fixes: [{ label: "Copy it back into your library", preview: `Copy this repo's ${s.name} into your library, so it can be restored and shared again.`, run: (w2) => w2.ops.copyToLibrary(projectName, s.name) }]
     });
-  if (g)
+  if (g?.kept)
+    issues.push({
+      id: `kept-g:${s.name}`,
+      severity: "warning",
+      title: `Also global in ${g.where}, and you keep it global: this repo's copy is extra`,
+      short: "Extra: you keep it global",
+      decision: true,
+      fixes: [
+        ...s.source !== "repo" ? [{ ...remove, label: "Remove this repo's copy, keep it global" }] : [],
+        {
+          label: "Stop loading it globally after all",
+          preview: `Copy ${s.name} into your library if needed, then move ${g.path} to the backups. Other repos stop seeing it.`,
+          run: (w2) => w2.ops.unloadGlobal(g)
+        }
+      ]
+    });
+  else if (g)
     issues.push({
       id: `twice-g:${s.name}`,
       severity: "problem",
@@ -424,13 +517,19 @@ function issuesOf(w, projectName, u) {
       decision: true,
       fixes: [
         ...s.source !== "repo" ? [{ ...remove, label: `Remove this repo's copy, use the ${vendor.source}'s` }] : [],
-        {
-          label: vendor.source === "plugin" ? "Turn the plugin off with /plugin in Claude Code" : `Turn it off in ${vendor.where}`,
-          preview: "skilllib can't turn it off for you yet.",
+        vendor.source === "plugin" ? {
+          label: `Turn the plugin off in ${projectName} only`,
+          preview: `Sets "${vendor.where}": false in ${projectName}'s .claude/settings.local.json (claude plugin disable --scope local). Other repos keep it.`,
+          run: (w2) => w2.ops.pluginOffHere(projectName, vendor.where)
+        } : {
+          label: `Turn it off in ${vendor.where}`,
+          preview: "skilllib can't turn it off for you.",
           run: () => `Turn ${vendor.where} off at its source; skilllib picks it up next time`
         }
       ]
     });
+  if (s.dupes) issues.push(...dupeIssues(projectName, s.name, s.dupes));
+  if (s.cursorPlugin && s.agents.includes("cursor")) issues.push(cursorPluginIssue(s.name, s.cursorPlugin));
   if (s.source === "lib" && s.edited)
     issues.push({
       id: `edited:${s.name}`,
@@ -468,7 +567,8 @@ function issuesOf(w, projectName, u) {
         }
       ]
     });
-  if (s.source !== "lib" && s.library === "differs")
+  const differ = !!s.dupes?.differ;
+  if (s.source !== "lib" && s.library === "differs" && !differ)
     issues.push({
       id: `differs:${s.name}`,
       severity: "hint",
@@ -480,7 +580,7 @@ function issuesOf(w, projectName, u) {
         ...s.source === "untracked" ? [{ label: "Replace it with the library version", preview: `Replace ${s.dir}/${s.name} with your library's newest version and track it (this copy backed up).`, run: (w2) => w2.ops.discardEdits(projectName, s.name) }] : []
       ]
     });
-  if (s.source === "untracked" && s.library === "same")
+  if (s.source === "untracked" && s.library === "same" && !differ)
     issues.push({
       id: `adopt:${s.name}`,
       severity: "hint",
@@ -489,7 +589,7 @@ function issuesOf(w, projectName, u) {
       decision: false,
       fixes: [{ label: "Track it", preview: `Record ${s.name} in skilllib.json so library updates reach it.`, run: (w2) => w2.ops.track(projectName, s.name) }]
     });
-  if (s.source === "untracked" && !l && !vendor)
+  if (s.source === "untracked" && !l && !vendor && !differ)
     issues.push({
       id: `local:${s.name}`,
       severity: "hint",
@@ -589,6 +689,7 @@ function groupCandidates(w, u) {
   if (m?.source === "plugin") return [{ key: `plugin:${m.where}`, label: `\u29C9 ${m.where.split("@")[0]} plugin` }];
   if (m?.source === "claude.ai") return [{ key: "claude.ai", label: "claude.ai skills" }];
   if (m?.source === "cursor") return [{ key: "cursor", label: "Cursor built-ins" }];
+  if (m?.source === "system") return [{ key: `system:${m.where}`, label: m.where }];
   if (m) {
     const origin = originGroup(m.origin);
     return [...origin ? [origin] : [], ...byTime("global", m.installed), ...byWord("global", m.name)];
@@ -775,7 +876,7 @@ function TitleRow({ cells, width }) {
 }
 var fixOption = (fix) => ({ label: fix.label, fix });
 var GIT_LABEL = { committed: "\u2713 committed", changed: "\xB1 uncommitted changes", new: "+ not committed", ignored: "\u2205 gitignored" };
-var COPY_RANK = { lib: 0, repo: 0, untracked: 0, global: 1, plugin: 2, "claude.ai": 3, cursor: 3 };
+var COPY_RANK = { lib: 0, repo: 0, untracked: 0, global: 1, plugin: 2, "claude.ai": 3, cursor: 3, system: 3 };
 function byName(copies) {
   const groups = /* @__PURE__ */ new Map();
   for (const c of copies) groups.set(c.name, [...groups.get(c.name) ?? [], c]);
@@ -955,7 +1056,7 @@ function globalItems(w, nameW, ui) {
 }
 function globalActions(w, u, ui) {
   const m = u.machine;
-  const atSource = m.source === "plugin" ? "Turn it off with /plugin in Claude Code" : m.source === "claude.ai" ? "Turn it off in claude.ai \u203A Settings" : "Cursor manages it";
+  const atSource = m.source === "plugin" ? "Turn it off with /plugin in Claude Code" : m.source === "claude.ai" ? "Turn it off in claude.ai \u203A Settings" : m.source === "system" ? `An admin manages ${m.where}` : "Cursor manages it";
   return [
     ...machineActions(m).map(fixOption),
     ...m.source === "plugin" ? [fixOption(replacePluginFix(w, m.where))] : [],
@@ -1903,7 +2004,7 @@ function machineSkill(s, kept) {
   const global = s.kind === "global" || s.kind === "skills.sh";
   return {
     name: s.name,
-    source: global ? "global" : s.kind === "plugin" ? "plugin" : s.kind === "claude.ai" ? "claude.ai" : "cursor",
+    source: global ? "global" : s.kind === "plugin" ? "plugin" : s.kind === "claude.ai" ? "claude.ai" : s.kind === "system" ? "system" : "cursor",
     where: global ? tildify3(dirname(s.path)) : s.kind === "claude.ai" ? "claude.ai account" : s.kind === "built-in" ? `${s.origin} built-in` : s.origin,
     ...s.kind === "skills.sh" ? { origin: `npx skills: ${s.origin}` } : {},
     path: s.path,
@@ -1915,6 +2016,13 @@ function machineSkill(s, kept) {
     ...s.kind === "plugin" ? { pluginParts: pluginParts(dirname(dirname(s.path))) } : {}
   };
 }
+function dupesOf(r, root, git2 = null) {
+  const out = /* @__PURE__ */ new Map();
+  for (const p of r.plans) out.set(p.name, { steps: p.steps.map((s) => describeStep(s, root)), git: gitVisibleSteps(p, git2).map((s) => describeStep(s, root)) });
+  for (const c of r.conflicts)
+    out.set(c.name, { steps: [], git: [], differ: c.copies.map((x) => ({ dir: x.dir, label: root ? copyLabel(c, x.dir) : tildify3(x.dir), runs: x.runs, canWin: !c.managed || x.dir === c.managed })) });
+  return out;
+}
 function loadWorld() {
   forgetLatest();
   const agents = enabledHarnesses();
@@ -1938,20 +2046,39 @@ function loadWorld() {
     return { name: s.name, latest: latestVersion(s.name)?.version ?? 1, origin: origins[s.name] };
   });
   const kept = keptGlobal();
-  const machine = machineSkills(agents).map((s) => {
+  const cursorPlugin = new Map(agents.includes("cursor") ? cursorPluginSkills().map((s) => [s.name, s.plugin]) : []);
+  const globalDupes = dupesOf(planGlobalTidy({ enabled: agents }), null);
+  const sourced = machineSkills(agents);
+  const machine = sourced.map((s) => {
     descriptions[s.name] ??= s.description;
-    return machineSkill(s, kept);
+    const m = machineSkill(s, kept);
+    if (m.source !== "global" || m.broken) return m;
+    const dupes = globalDupes.get(m.name);
+    const plugin = cursorPlugin.get(m.name);
+    return { ...m, ...dupes ? { dupes } : {}, ...plugin ? { cursorPlugin: plugin } : {} };
   });
+  const plugins = (root) => {
+    const loaded = skillsLoadedIn(root, sourced, agents);
+    if (loaded === sourced) return {};
+    for (const s of loaded) descriptions[s.name] ??= s.description;
+    return { machine: loaded.map((s) => machine[sourced.indexOf(s)] ?? machineSkill(s, kept)) };
+  };
   const projects = roots.map((root) => {
     const status = projectStatus(root);
     const hasManifest = existsSync3(join2(root, "skilllib.json"));
     const git2 = status.length || hasManifest ? gitInfo(root) : null;
     for (const s of status) if (!descriptions[s.name] && !s.state.includes("missing")) descriptions[s.name] = readSkillInfo(s.path).description;
+    const dupes = status.length ? dupesOf(planProjectTidy(root, { enabled: agents }), root, git2) : /* @__PURE__ */ new Map();
     return {
       name: names.get(root),
       path: root,
       manifest: hasManifest ? git2 ? git2.of("skilllib.json") : "no git" : "none",
-      skills: status.map((s) => localSkill(root, s, git2))
+      skills: status.map((s) => {
+        const d = dupes.get(s.name);
+        const plugin = cursorPlugin.get(s.name);
+        return { ...localSkill(root, s, git2), ...d ? { dupes: d } : {}, ...plugin ? { cursorPlugin: plugin } : {} };
+      }),
+      ...plugins(root)
     };
   });
   const backups = [...listBackups(), ...pluginBackups()].sort((a, b) => b.movedAt.localeCompare(a.movedAt));
@@ -2065,6 +2192,24 @@ function realOps(roots, backups) {
       return withLinks(addSkill(rootOf(repo), name), repo, name);
     },
     copyToLibrary: (repo, name) => toLibrary(find(repo, name).path),
+    tidy: (repo, name, { keep, allowGit = false } = {}) => {
+      const root = repo === null ? null : rootOf(repo);
+      const opts = keep ? { keep: { [name]: keep } } : {};
+      const plan = (root ? planProjectTidy(root, opts) : planGlobalTidy(opts)).plans.find((p) => p.name === name);
+      if (!plan) return `${name}: nothing to tidy`;
+      const r = applyTidy(plan, { git: allowGit ? "go" : "keep" });
+      const steps = (list) => list.map((s) => describeStep(s, root)).join(", ");
+      const message = r.applied.length ? `${name}: ${steps(r.applied)}` : `${name}: nothing changed yet`;
+      if (!r.held.length) return message;
+      return {
+        message,
+        then: {
+          label: "Also change what git tracks",
+          preview: `${steps(r.held)}: these changes will show in git status in ${repo}. Replaced copies go to Settings \u203A Backups.`,
+          run: (w) => w.ops.tidy(repo, name, { keep, allowGit: true })
+        }
+      };
+    },
     unloadGlobal: (m) => {
       if (!m.broken && !latestVersion(m.name)) importSkill(m.path);
       const r = unloadGlobal(m.path, m.links);
@@ -2075,6 +2220,12 @@ function realOps(roots, backups) {
       return r.ok ? m.broken ? `Removed the broken link ${m.name}` : `Deleted ${m.name} (in Settings \u203A Backups)` : `${m.name}: ${r.reason}`;
     },
     keepGlobal: (name, keep) => (setKeepGlobal([name], keep), keep ? `${name} marked as global on purpose` : `${name} is no longer marked as global on purpose`),
+    linkGlobal: (m, agents) => {
+      const r = linkGlobal(m.path, agents);
+      const linked = r.linked.map(tildify3).join(", ");
+      const skipped = r.skipped.length ? `; ${r.skipped.map(tildify3).join(", ")} already holds a different skill` : "";
+      return `${m.name}: ${linked ? `linked ${linked}` : "nothing linked"}${skipped}`;
+    },
     moveGlobal: (m, repos, group) => {
       if (importSkill(m.path).status === "exists") return `${m.name}: your library has a different ${m.name}; nothing moved (update your library from this copy first)`;
       if (group) recordOrigin(m.name, `group: ${group}`);
@@ -2091,6 +2242,14 @@ function realOps(roots, backups) {
       const r = createSkill(name, "");
       return r.ok ? `Created ${name} in your library: edit its SKILL.md from Your skills` : `${name}: ${r.reason}`;
     },
+    pluginOffHere: (repo, id) => {
+      const root = rootOf(repo);
+      const plugin = claudePlugins(skillsLoadedIn(root, machineSkills()), root).find((p) => p.id === id);
+      if (!plugin) return `${id} isn't on in ${repo}`;
+      const r = turnOffIn(plugin, root);
+      if (!r.ok) throw new Error(r.message);
+      return r.message;
+    },
     replacePlugin: (id, repos) => {
       const skills = machineSkills().filter((s) => s.kind === "plugin" && s.origin === id && !s.broken);
       const clashes = skills.filter((s) => importSkill(s.path).status === "exists").map((s) => s.name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilllib",
-  "version": "1.3.1",
+  "version": "1.6.0",
   "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 and Zed.",
   "keywords": [
     "agent-skills",
@@ -32,6 +32,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],

package/skills/skilllib/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: skilllib
+description: Agent skills (SKILL.md) loaded in this repo and the user's skill library, via the skilllib CLI. Use for which skills you can use here and where each comes from, which library skills to add, what's out of date, broken or duplicated, and adding, removing or updating skills.
+allowed-tools: Bash(skilllib:*)
+---
+
+# 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.
+
+## Reading
+
+The **Now** section at the end has this repo's `status` and `list` output. Answer from it and don't run them again. If it shows the commands instead of their output, run both in parallel.
+
+`status --json`: `skills` are this repo's own; `global` groups load in every repo; `issues` are everything skilllib finds wrong (out-of-date or missing skills, broken links, skills loaded twice), with either a `fix` (a safe repair; `skilllib doctor --fix` applies every fix, across all the user's projects) or `choices` (decisions the user makes in `skilllib` → Health). When asked what's out of date or broken, `issues` and each skill's `state` are the answer. Don't audit skill contents unless asked.
+
+- `source`: `library` (added with skilllib) · `repo` (committed to `.agents/skills` by the team) · `local` (unmanaged folder) · `global` (`~/.claude/skills`, `~/.agents/skills` or `~/.codex/skills`) · `skills.sh` (`npx skills add`; `from` is the source repo) · `plugin` (Claude Code plugin; turn off with `/plugin`) · `claude.ai` (synced from the account) · `built-in` (bundled with an agent).
+- Missing fields mean the usual: loaded by all of `agents`, state ok, in `.claude/skills`. `usesHere` counts Claude Code uses in this repo.
+
+`list --json`: `inThisProject` (names) and `skills`, the library skills the repo doesn't have, each with a short `description` and the `projects` using it. To recommend, read the repo's README and manifests (see `files` in `status`) in one parallel step, then give a reason for each pick. Don't add a skill that already loads globally (it would load twice): name it, and say `skilllib` → Global → Clean up moves it into just the repos that need it. `show <name> --json` has the full SKILL.md.
+
+Also: `usage --json` (Claude Code usage only, so "unused" is a hint), `projects --json` (every repo), `outdated --all --json`.
+
+## 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. Each prints `[{name, action, from, to, dirs, reason, blocked}]`, which is the whole result: there's no need to check files afterwards.
+
+- `skipped` + `reason`: nothing changed; tell the user. `--force` overwrites local edits, but only use it with their OK.
+- `blocked`: git tracks that folder. Re-run with `--allow-tracked` only with their OK.
+- Changes apply from the agent's next session. Remind the user to commit `skilllib.json` and `.claude/skills`.
+
+To move global skills into repos, tell the user to run `skilllib` and open Global → Clean up.
+
+## Now
+
+This repo (`skilllib status --json`):
+!`skilllib status --json`
+
+Library skills it could add (`skilllib list --json`):
+!`skilllib list --json`