skillshelf 0.1.0 → 0.3.0

package/README.md

@@ -7,11 +7,17 @@
 [![CI](https://img.shields.io/github/actions/workflow/status/Wang-Cankun/skillshelf/ci.yml?branch=main)](https://github.com/Wang-Cankun/skillshelf/actions)
 [![npm](https://img.shields.io/npm/v/skillshelf.svg)](https://www.npmjs.com/package/skillshelf)
 
-Your skills are scattered: some in `~/.claude/skills`, some buried in Obsidian or notes
-vaults, more copied into a dozen per-project `.claude` directories. You forget which ones
-exist, rewrite ones you already have, and copies drift out of sync. The naive fix — dump
-everything into `~/.claude/skills` — makes every session pay the token cost of loading
-hundreds of skill descriptions at once.
+Your skills are scattered across **every agent you use** — some in `~/.claude/skills`, some in
+`~/.codex/skills` or `~/.cursor/skills`, some buried in Obsidian or notes vaults, more copied into
+a dozen per-project `.claude` / `.codex` directories. Each tool scatters its own copies and
+symlinks; you forget which ones exist, rewrite ones you already have, and copies drift out of sync.
+The naive fix — dump everything into one agent's dir — makes every session pay the token cost of
+loading hundreds of skill descriptions at once.
+
+skillshelf is **agent-agnostic** (Claude Code, Codex, Cursor, and compatible agents): the library
+is a neutral source, and `skl where` maps where every skill is actually deployed across all of
+them — surfacing untracked copies, drift, and dead links. It's the curation layer *over* your
+agent dirs, complementary to installers like [`vercel-labs/skills`](https://github.com/vercel-labs/skills).
 
 skillshelf is the middle path: a single git-backed **library** that is a *passive shelf*
 (nothing auto-loads), plus a CLI to **search, tag, bundle, and load** exactly the skills a
@@ -22,6 +28,11 @@ actually use.
 
 skillshelf runs on [Bun](https://bun.sh) (>= 1.0). No other runtime dependencies.
 
+> **Bun is required, not optional.** The `skl` bin is a TypeScript entrypoint with a
+> `#!/usr/bin/env bun` shebang — there is no compiled Node build. `npm i -g skillshelf`
+> will *not* give you a working `skl` (a `preinstall` guard aborts with a pointer to Bun);
+> use `bunx` or `bun add -g` instead.
+
 ```bash
 # Run it without installing
 bunx skillshelf <command>
@@ -57,25 +68,72 @@ skl drop bioinfo     # unlink when you're done
 Add `--json` to any command for machine-readable output (skillshelf is built to be driven
 by an agent as well as a human).
 
+## Migrating scattered skills
+
+Already have skills strewn across `~/.claude/skills`, an Obsidian vault, and a dozen project
+`.claude` dirs? Consolidate them with three deterministic primitives — `scan` discovers,
+`import` adopts, `infer` tags. The judgment in between (which copies to keep, which drift wins)
+is yours (or your agent's); the tool never guesses.
+
+```bash
+# 1. Register the places your skills live, then take a read-only inventory.
+#    scan moves nothing — it just reports candidates, duplicates, and drift.
+skl scan --add-root ~/.claude/skills
+skl scan --add-root ~/notes/.agents/skills
+skl scan                       # report every candidate + duplicate/drift group
+
+# 2. Adopt the ones you want, one at a time. Each import moves the skill into the
+#    library and leaves a symlink behind so old paths keep resolving.
+skl import rnaseq-qc --from ~/.claude/skills/rnaseq-qc
+skl import xhs-title --from ~/notes/.agents/skills/xhs-title
+
+#    For a skill living inside a project repo, copy instead of move (no symlink left behind):
+skl import deploy-check --from ~/projects/web/.claude/skills/deploy-check --copy
+
+#    When two copies drifted and you've picked the winner, overwrite the loser:
+skl import rnaseq-qc --from ~/projects/lab/.claude/skills/rnaseq-qc --force
+
+#    For a skill you actively develop in its own git repo, shelve a LINK instead of a copy —
+#    the repo stays canonical and edits show up live, no drift, no re-sync (ADR-0004):
+skl link --from ~/Documents/GitHub/cairn/skill/cairn
+
+# 3. Tag the now-populated library in one pass. Domain is tags, not folders, so this
+#    runs AFTER import with no reorg — no skill ever has to move because a tag changed.
+skl infer --emit               # hand the payload to your agent, then `skl infer --apply`
+```
+
+Domain lives entirely in tags ([ADR-0001](./docs/adr/0001-domain-is-tags-not-folders.md)): the
+library layout is flat (`library/<name>/`) and `import` never decides a domain, so there is no
+chicken-and-egg between adopting a skill and tagging it.
+
 ## How it works
 
 skillshelf separates *owning* a skill from *loading* it.
 
-- **Canonical library** — a dedicated git repo, one file per skill in its primary-domain
-  folder. This is a passive shelf: nothing here auto-loads, which is exactly what kills the
-  all-at-once token cost.
-- **Domain bundles** — bundles are *tag queries*, not folders. A skill tagged
-  `domains: [coding, bioinfo]` shows up in both bundles from a single copy on disk.
-  `skl use bioinfo` resolves every skill carrying that tag.
+- **Canonical library** — a dedicated git repo, one copy per skill in a flat, non-semantic
+  layout (`library/<name>/`). This is a passive shelf: nothing here auto-loads, which is
+  exactly what kills the all-at-once token cost.
+- **Domain bundles** — domain is *tags, not folders* ([ADR-0001](./docs/adr/0001-domain-is-tags-not-folders.md)).
+  A skill tagged `domains: [coding, bioinfo]` shows up in both bundles from a single copy on
+  disk; `skl use bioinfo` resolves every skill carrying that tag. `primaryDomain` is just
+  `domains[0]`, never inferred from a folder.
 - **Thin global core** — a handful of universal skills (commit, search, memory) are
   symlinked permanently into `~/.claude/skills` so they always auto-trigger. Small, bounded
   token cost — "some loaded is fine; all-at-once is the problem."
 - **On-demand `show`** — prints only the SKILL.md instruction body and lists the paths of
   any bundled reference files (without reading them). Progressive disclosure: cheap by
   default, deep when you ask. Works mid-task with no reload.
-- **Sidecar overlay** — installed third-party skills keep a pristine `upstream/` body plus a
-  `<skill>.shelf.json` overlay holding *your* tags, bundle membership, and notes. `skl update`
-  swaps the upstream body cleanly while your taxonomy survives — updates never clobber your tags.
+- **Owned vs linked entries** ([ADR-0004](./docs/adr/0004-owned-vs-linked-entries.md)) — the
+  library is a *bookshelf*: an entry either **owns** its bytes (a real copy; the library is
+  canonical — for downloads and stabilized skills) or is **linked** (a symlink to an external dev
+  repo that stays canonical — for skills you actively develop in their own git, e.g. `cairn`).
+  `skl link --from <dev-repo>` registers a linked entry; `skl where` shows it as a clean
+  `✓ source`; `skl update` / `outdated` skip linked entries so they never pull upstream into your
+  dev repo. The mode is derived from the filesystem (a symlink resolving outside the library),
+  never stored, so it can't go stale.
+- **Updates never clobber your tags** — domain tags live in the central `taxonomy.json`
+  ([ADR-0002](./docs/adr/0002-central-taxonomy-not-sidecars.md)), separate from the skill body, so
+  `skl update` can swap an owned skill's upstream `SKILL.md` cleanly while your taxonomy survives.
 
 ```
                        skl search / ls / show          skl use <bundle>
@@ -95,20 +153,37 @@ See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) for the full design.
 | Command | Summary | Key flags |
 |---|---|---|
 | `skl init` | Set up `~/.skillshelf` config + library and link the global-core skills | `--force` |
+| `skl scan [roots…]` | Read-only discovery of skill candidates across roots (counts, duplicates, drift) | `--add-root <path>`, `--remove-root <path>` |
+| `skl roots` | List the persisted scan roots (read-only; no crawl) | — |
+| `skl import <name> --from <path>` | Adopt your own skill into the library as an OWNED copy (move + symlink-back, or `--copy`) | `--copy`, `--as <slug>`, `--force` |
+| `skl link [<name>] --from <dev-repo>` | Shelve a dev-repo skill as a LINKED entry (library symlinks to it; the repo stays canonical). `--at <path>` instead collapses a stray copy into the library | `--from`, `--at`, `--force` |
 | `skl new <name>` | Scaffold a new skill dir + SKILL.md into the library | `--domain <d>`, `--desc "..."`, `--force` |
-| `skl ls [bundle]` | One-line listing of the library, or one bundle | `--all` |
+| `skl ls [bundle]` | One-line listing of the library, or one bundle (`--json` carries `mode`/`linkTarget`) | `--all` |
 | `skl search <kw...>` | Fuzzy match over name + description + domains across the library | — |
 | `skl show <name>` | Print a skill's SKILL.md body; list reference-file paths (not contents) | — |
-| `skl status` | Show which library skills are linked into `./.claude/skills` | — |
-| `skl use <bundle>` | Symlink a bundle's skills into `./.claude/skills/` (hot-loads) | — |
-| `skl drop <bundle>` | Remove a bundle's symlinks from `./.claude/skills/` | — |
-| `skl add <src>` | Install a third-party skill (`github:`/registry), record provenance, auto-tag | `--domain <d>`, `--name <slug>`, `--no-infer`, `--force` |
-| `skl outdated [name]` | Check upstream ref per tracked skill and mark stale ones | — |
-| `skl update [name]` | Re-pull upstream body, preserve overlay, diff if local body diverged | `--force`, `--dry-run` |
+| `skl tag <name> <domain>…` | Add domain tag(s) to a skill in the central taxonomy (deterministic, no LLM) | — |
+| `skl untag <name> <domain>` | Remove a domain tag from a skill | — |
+| `skl retag <old> <new>` | Rename a domain across the whole library taxonomy (deterministic) | — |
+| `skl rename <old> <new>` | Rename a skill slug atomically (dir + frontmatter + taxonomy + lock). Alias `skl mv` | — |
+| `skl retire <name>` | Soft-delete a skill into `_retired/` (reversible; excluded from deploys) | — |
+| `skl unretire <name>` | Restore a retired skill back to the active library | — |
+| `skl rm <name>` | Delete a skill (dir/symlink + taxonomy + lock), re-index. Refuses a live OWNED skill without `--force`; a LINKED entry `rm`s freely (safe unlink) | `--force`, `--dry-run` |
+| `skl status` | Show which library skills are linked into `./.claude/skills`; flags unmanaged real copies (drift-prone) | — |
+| `skl where [name]` | Map where each skill is deployed across all agents (Claude, Codex, Cursor…); flags copies, drift, 2nd-sources, dead links — a dev repo a library entry links to shows as a clean `✓ source` | `--problems`, `--prune`, `--fix`, `--dry-run` |
+| `skl use <bundle\|skill>` | Symlink a bundle (or a single skill) into `./.claude/skills/` (hot-loads) | — |
+| `skl drop <bundle\|skill>` | Remove a bundle's (or single skill's) symlinks from `./.claude/skills/` | — |
+| `skl refresh` | Re-sync this project's `./.claude/skills` symlinks to current library reality (repoint stale, prune vanished) | `--dry-run` |
+| `skl add <src>` | Install third-party skill(s) into the library (librarian only — no agent-dir writes). One repo = **one clone**: a bare repo with several skills needs `--all`/`--skill`/`--list`; single-skill `add <repo>/<path>` is unchanged. `--list` discovers + prints; `--dry-run` previews drift (new/identical/differs); a `differs` skill is skipped without `--force` | `--all`, `--skill <a,b>`, `--list`, `--dry-run`, `--domain <d>`, `--name <slug>`, `--no-infer`, `--force` |
+| `skl outdated [name]` | Check upstream ref per tracked skill and mark stale ones (LINKED dev-repo entries are reported, never probed); `--check-local` diffs the local body against its baseline offline | `--check-local` |
+| `skl update [name]` | Re-pull upstream body, preserve domain tags, diff if local body diverged (LINKED entries are skipped — their own git owns versioning) | `--force`, `--dry-run` |
 | `skl index` | Regenerate `INDEX.md` (catalog grouped by domain) | — |
 | `skl infer` | Re-run AI domain taxonomy over the library (emit/apply/provider modes) | see below |
 
-Every command also accepts `--json`.
+Every command also accepts `--json`. Destructive/edit verbs (`rm`, `retire`/`unretire`,
+`rename`, `tag`/`untag`/`retag`, `scan --remove-root`, `where --prune`/`--fix`,
+`refresh`) are the inverse + fine-grained-edit family from
+[ADR-0005](./docs/adr/0005-inverse-and-edit-verbs.md): reversible by default, transactional
+across the skill dir + `taxonomy.json` + `shelf.lock.json` + `INDEX.md`.
 
 ## AI taxonomy & inference
 
@@ -126,7 +201,7 @@ skl infer [--emit | --apply <file.json> | --provider <name>] \
 - `--emit` — print a self-contained prompt + the library payload as JSON. Hand it to whatever
   agent or model you already have open; it does the reasoning.
 - `--apply <file.json>` — apply the taxonomy proposal the agent produced back into the library
-  (for review/approval), updating tags via the overlay.
+  (for review/approval), writing tags into the central `taxonomy.json`.
 
 **API mode (skillshelf calls an OpenAI-compatible endpoint itself):**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillshelf",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Agent-first skill registry + manager for Claude Code and compatible agents.",
   "type": "module",
   "license": "MIT",
@@ -25,6 +25,7 @@
     "skl": "./src/cli.ts"
   },
   "scripts": {
+    "preinstall": "bun --version >/dev/null 2>&1 || { echo '\\nskillshelf requires the Bun runtime (https://bun.sh) — its bin is a TypeScript entrypoint, not a compiled Node script.\\nInstall Bun, then:  bun add -g skillshelf   (or run without installing:  bunx skillshelf <command>)\\n' >&2; exit 1; }",
     "skl": "bun run src/cli.ts",
     "test": "bun test"
   },
@@ -38,5 +39,10 @@
     "src",
     "README.md",
     "LICENSE"
-  ]
+  ],
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "@types/node": "22",
+    "typescript": "5.6"
+  }
 }

package/src/adapters/inference/agent.ts

@@ -4,15 +4,15 @@
 //   - emit : assemble an InferenceCorpus + JSON schema + instruction and print it
 //            to stdout so the HOST agent (Claude Code) can reason over it and
 //            produce a proposal file.
-//   - apply: read the agent's proposal JSON and write proposed domains/tags into
-//            each skill's `<name>.shelf.json` overlay (never upstream SKILL.md).
+//   - apply: read the agent's proposal JSON and write proposed domains into the
+//            central taxonomy.json (never upstream SKILL.md).
 //
 // The api.ts adapter reuses buildCorpus() + applyProposal() to close the loop
 // automatically against any OpenAI-compatible LLM endpoint.
 
-import type { InferenceCorpus, Overlay, Skill } from "../../types.ts";
+import type { InferenceCorpus, Skill } from "../../types.ts";
 import { listDomains } from "../../core/library.ts";
-import { readOverlay, writeOverlay } from "../../core/overlay.ts";
+import { readTaxonomy, writeTaxonomy, domainsForName } from "../../core/taxonomy.ts";
 import { parseFrontmatter } from "../../lib/frontmatter.ts";
 
 /** Max characters of SKILL.md body included per skill in the corpus preview. */
@@ -20,8 +20,9 @@ const BODY_PREVIEW_CHARS = 1200;
 
 /**
  * The proposal shape the host agent (or the gateway) must return: a map of
- * skill name -> proposed domains, plus optional primary + notes. Authors apply
- * `domains` into each overlay (unioned with existing, never destructive).
+ * skill name -> proposed domains, plus optional primary + notes. Applying unions
+ * `domains` into the central taxonomy (per skill, never destructive). `notes` is
+ * accepted for backward compatibility but is no longer persisted (ADR-0002).
  */
 export interface InferenceProposalEntry {
   name: string;
@@ -82,7 +83,7 @@ export const INFER_INSTRUCTION = [
   "domain plus any honest secondary tags (a dual-use skill belongs to multiple).",
   "Keep domain tokens lowercase and hyphenated.",
   "Return ONE JSON object that validates against `schema` (no prose, no markdown",
-  "fences). Then run `skl infer --apply <file.json>` to write it into the overlays.",
+  "fences). Then run `skl infer --apply <file.json>` to write it into taxonomy.json.",
 ].join(" ");
 
 /** Build the deterministic InferenceCorpus snapshot from loaded skills. */
@@ -185,7 +186,7 @@ export function normalizeProposal(raw: unknown): InferenceProposal {
 }
 
 export interface ApplyResult {
-  /** skill name -> domains written into its overlay */
+  /** skill name -> domains written into the taxonomy for that skill */
   applied: Array<{ name: string; domains: string[]; added: string[] }>;
   /** assignment names with no matching skill in the library */
   unmatched: string[];
@@ -194,11 +195,13 @@ export interface ApplyResult {
 }
 
 /**
- * Apply a proposal into each skill's overlay. Domains are UNIONED with the
- * skill's existing effective domains (never destructive), written to
- * `<name>.shelf.json` only — upstream SKILL.md is never touched.
+ * Apply a proposal into the central taxonomy (`<library>/taxonomy.json`). For each
+ * assignment, domains are UNIONED with the skill's EXISTING taxonomy entry (never
+ * destructive); upstream SKILL.md is never touched. `notes` is dropped (ADR-0002).
+ * The taxonomy is read once and written once at the end.
  */
 export async function applyProposal(
+  libraryPath: string,
   skills: Skill[],
   proposal: InferenceProposal,
 ): Promise<ApplyResult> {
@@ -209,6 +212,8 @@ export async function applyProposal(
     if (!existing || (existing.mirrorOf && !s.mirrorOf)) byName.set(s.name, s);
   }
 
+  const tax = await readTaxonomy(libraryPath);
+
   const applied: ApplyResult["applied"] = [];
   const unmatched: string[] = [];
   const skipped: string[] = [];
@@ -232,8 +237,9 @@ export async function applyProposal(
       continue;
     }
 
-    const prev = await readOverlay(skill);
-    const existingDomains = Array.isArray(prev?.domains) ? prev!.domains : [];
+    // Union with the skill's EXISTING taxonomy domains (non-destructive). Resolve
+    // by the canonical skill name so mirror copies map to the same entry.
+    const existingDomains = domainsForName(tax, skill.name);
     const merged: string[] = [...existingDomains];
     const added: string[] = [];
     for (const d of ordered) {
@@ -243,11 +249,12 @@ export async function applyProposal(
       }
     }
 
-    const next: Overlay = { ...(prev ?? {}), domains: merged };
-    if (a.notes) next.notes = a.notes;
-    await writeOverlay(skill, next);
+    tax.skills[skill.name] = merged;
     applied.push({ name: a.name, domains: merged, added });
   }
 
+  // Persist the whole taxonomy once.
+  await writeTaxonomy(libraryPath, tax);
+
   return { applied, unmatched, skipped };
 }

package/src/cli.ts

@@ -27,16 +27,44 @@ import * as outdated from "./commands/outdated.ts";
 import * as update from "./commands/update.ts";
 import * as infer from "./commands/infer.ts";
 import * as newCmd from "./commands/new.ts";
+import * as scan from "./commands/scan.ts";
+import * as roots from "./commands/roots.ts";
+import * as importCmd from "./commands/import.ts";
+import * as link from "./commands/link.ts";
+import * as where from "./commands/where.ts";
+import * as agents from "./commands/agents.ts";
+import * as tag from "./commands/tag.ts";
+import * as untag from "./commands/untag.ts";
+import * as retag from "./commands/retag.ts";
+import * as rm from "./commands/rm.ts";
+import * as retire from "./commands/retire.ts";
+import * as unretire from "./commands/unretire.ts";
+import * as rename from "./commands/rename.ts";
+import * as refresh from "./commands/refresh.ts";
 
 // Registration order = display order in help.
 const MODULES: CommandModule[] = [
   search,
   ls,
   status,
+  where,
+  agents,
   show,
   use,
   drop,
+  refresh,
   add,
+  scan,
+  roots,
+  importCmd,
+  link,
+  tag,
+  untag,
+  retag,
+  retire,
+  unretire,
+  rename,
+  rm,
   outdated,
   update,
   init,
@@ -50,6 +78,13 @@ for (const mod of MODULES) {
   COMMANDS.set(mod.meta.name, mod);
 }
 
+// Command aliases (not shown in the help listing; resolve to the canonical module).
+const ALIASES: Record<string, string> = { mv: "rename" };
+for (const [alias, target] of Object.entries(ALIASES)) {
+  const mod = COMMANDS.get(target);
+  if (mod) COMMANDS.set(alias, mod);
+}
+
 function helpText(): string {
   const lines: string[] = [];
   lines.push("skl — skillshelf: agent-first skill registry + manager");