skillshelf 0.1.0 → 0.2.0

package/README.md

@@ -57,16 +57,51 @@ 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
+
+# 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."
@@ -95,6 +130,8 @@ 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>` |
+| `skl import <name> --from <path>` | Adopt your own skill into the library (move + symlink-back, or `--copy`) | `--copy`, `--as <slug>`, `--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 search <kw...>` | Fuzzy match over name + description + domains across the library | — |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillshelf",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Agent-first skill registry + manager for Claude Code and compatible agents.",
   "type": "module",
   "license": "MIT",

package/src/cli.ts

@@ -27,6 +27,8 @@ 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 importCmd from "./commands/import.ts";
 
 // Registration order = display order in help.
 const MODULES: CommandModule[] = [
@@ -37,6 +39,8 @@ const MODULES: CommandModule[] = [
   use,
   drop,
   add,
+  scan,
+  importCmd,
   outdated,
   update,
   init,

package/src/commands/import.ts

@@ -0,0 +1,284 @@
+// `skl import <name> --from <path>` — turn ONE candidate (a skill discovered in
+// an external root) into a managed library skill.
+//
+//   skl import <name> --from <path> [--copy] [--as <slug>] [--force] [--json]
+//
+// Flat layout (ADR-0001): the skill always lands at <library>/<name>/. No domain
+// is decided here — import is a thin, deterministic primitive (move + symlink-back).
+// Tagging happens AFTER, via `skl infer`.
+//
+// Default behavior = MOVE the candidate dir into the library, then leave a SYMLINK
+// at the original <path> pointing at the library copy, so old paths still resolve
+// (e.g. ~/.claude/skills/<name> keeps working).
+//
+//   --copy          copy instead of move; leave the original untouched (project repos)
+//   --no-link-back  move WITHOUT leaving a symlink — the original location is emptied.
+//                   Use to THIN a root (e.g. drop a skill out of ~/.claude/skills so it
+//                   stops auto-loading; reach it on demand via `skl use`). Implies move.
+//   --as <slug>     import under a different library name than <name>
+//   --force         overwrite an existing same-named library skill
+//
+// Provenance: these are the user's OWN skills, not third-party — source is null and
+// NO lockfile entry is written (that is `add`'s job). We still create an EMPTY
+// overlay (<name>.shelf.json) so taxonomy can be applied later without clobbering
+// the upstream SKILL.md.
+
+import { join, basename, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { rename, cp, rm } from "node:fs/promises";
+import type { Ctx, Skill } from "../types.ts";
+import { writeOverlay } from "../core/overlay.ts";
+import {
+  ensureDir,
+  safeSymlink,
+  isDirectory,
+  realpathOrSelfAsync,
+} from "../lib/fs.ts";
+
+export const meta = {
+  name: "import",
+  summary: "Adopt your own skill into the library (move + symlink-back, or --copy)",
+  usage: "skl import <name> --from <path> [--copy | --no-link-back] [--as <slug>] [--force] [--json]",
+} as const;
+
+interface Flags {
+  name: string | null;
+  from: string | null;
+  as: string | null;
+  copy: boolean;
+  noLinkBack: boolean;
+  force: boolean;
+  json: boolean;
+}
+
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+function parseFlags(argv: string[]): { flags: Flags } | { error: string } {
+  const flags: Flags = {
+    name: null,
+    from: null,
+    as: null,
+    copy: false,
+    noLinkBack: false,
+    force: false,
+    json: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--from") {
+      const v = argv[++i];
+      if (v === undefined) return { error: "--from requires a value" };
+      flags.from = v;
+    } else if (a.startsWith("--from=")) {
+      flags.from = a.slice("--from=".length);
+    } else if (a === "--as") {
+      const v = argv[++i];
+      if (v === undefined) return { error: "--as requires a value" };
+      flags.as = v;
+    } else if (a.startsWith("--as=")) {
+      flags.as = a.slice("--as=".length);
+    } else if (a === "--copy") {
+      flags.copy = true;
+    } else if (a === "--no-link-back" || a === "--no-link") {
+      flags.noLinkBack = true;
+    } else if (a === "--force") {
+      flags.force = true;
+    } else if (a === "--json") {
+      flags.json = true;
+    } else if (a.startsWith("--")) {
+      return { error: `unknown argument: ${a}` };
+    } else if (flags.name === null) {
+      flags.name = a;
+    } else {
+      return { error: `unexpected argument: ${a}` };
+    }
+  }
+  return { flags };
+}
+
+/**
+ * Move srcDir -> destDir. Prefers an atomic rename; falls back to copy+remove on
+ * EXDEV (cross-device, e.g. when the library lives on a different mount than the
+ * candidate). destDir's parent must already exist.
+ */
+async function moveDir(srcDir: string, destDir: string): Promise<void> {
+  try {
+    await rename(srcDir, destDir);
+  } catch (err) {
+    const code = (err as { code?: string }).code;
+    if (code !== "EXDEV") throw err;
+    await cp(srcDir, destDir, {
+      recursive: true,
+      force: true,
+      filter: (s: string) => basename(s) !== ".git",
+    });
+    await rm(srcDir, { recursive: true, force: true });
+  }
+}
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  const parsed = parseFlags(argv);
+  if ("error" in parsed) {
+    ctx.error(`skl import: ${parsed.error}`);
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  const flags = parsed.flags;
+
+  if (!flags.name || flags.name.trim() === "") {
+    ctx.error("skl import: a <name> is required");
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  if (!flags.from || flags.from.trim() === "") {
+    ctx.error("skl import: --from <path> is required");
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  if (flags.copy && flags.noLinkBack) {
+    ctx.error(
+      "skl import: --copy and --no-link-back are mutually exclusive (--copy keeps the original; --no-link-back removes it)",
+    );
+    return 1;
+  }
+
+  // The library name is --as if given, else <name>.
+  const targetName = (flags.as ?? flags.name).trim();
+  if (!SLUG_RE.test(targetName)) {
+    ctx.error(
+      `skl import: invalid skill name "${targetName}" — use lowercase letters, digits, and hyphens (e.g. my-skill)`,
+    );
+    return 1;
+  }
+
+  // Resolve the candidate path (absolute). Do NOT realpath it: if it is already a
+  // symlink we want to operate on the link location the user pointed at.
+  const fromPath = resolve(flags.from.trim());
+
+  try {
+    if (!existsSync(fromPath)) {
+      ctx.error(`skl import: --from path does not exist: ${fromPath}`);
+      return 1;
+    }
+    if (!(await isDirectory(fromPath))) {
+      ctx.error(`skl import: --from must be a skill directory: ${fromPath}`);
+      return 1;
+    }
+    if (!existsSync(join(fromPath, "SKILL.md"))) {
+      ctx.error(
+        `skl import: no SKILL.md found in ${fromPath} — not a skill directory`,
+      );
+      return 1;
+    }
+
+    const libraryPath = ctx.config.libraryPath;
+    // Flat, non-semantic layout (ADR-0001): always <library>/<name>/.
+    const destDir = join(libraryPath, targetName);
+
+    // Idempotency guard: refuse to clobber an existing library skill unless --force
+    // (or the user re-aimed with --as). This protects a managed copy from a stray
+    // re-import.
+    if (existsSync(destDir) && !flags.force) {
+      ctx.error(
+        `skl import: ${targetName} already exists at ${destDir} — pass --force to overwrite, or --as <slug> to import under another name`,
+      );
+      return 1;
+    }
+
+    // If --from already IS the library copy (a re-run pointing at the symlink, or
+    // the dir itself), there is nothing to move. Detect by realpath equality.
+    const fromReal = await realpathOrSelfAsync(fromPath);
+    const destReal = existsSync(destDir) ? await realpathOrSelfAsync(destDir) : destDir;
+    if (fromReal === destReal) {
+      ctx.error(
+        `skl import: ${fromPath} already resolves to the library copy at ${destDir} — nothing to import`,
+      );
+      return 1;
+    }
+
+    await ensureDir(libraryPath);
+    if (existsSync(destDir)) {
+      // --force: replace the existing managed copy.
+      await rm(destDir, { recursive: true, force: true });
+    }
+
+    const mode: "move" | "copy" = flags.copy ? "copy" : "move";
+    let linkedBack = false;
+
+    if (mode === "copy") {
+      // Copy into the library; leave the original untouched (no symlink-back).
+      await cp(fromPath, destDir, {
+        recursive: true,
+        force: true,
+        filter: (s: string) => basename(s) !== ".git",
+      });
+    } else {
+      // Move the dir into the library. By default symlink the old location back so
+      // existing paths keep resolving; with --no-link-back leave the original empty
+      // (thinning a root, e.g. removing a skill from ~/.claude/skills' auto-load).
+      await moveDir(fromPath, destDir);
+      if (!flags.noLinkBack) {
+        await safeSymlink(destDir, fromPath, { force: true });
+        linkedBack = true;
+
+        // Verify the symlink actually resolves to the library copy after the move.
+        const linkReal = await realpathOrSelfAsync(fromPath);
+        const movedReal = await realpathOrSelfAsync(destDir);
+        if (linkReal !== movedReal) {
+          ctx.error(
+            `skl import: symlink-back verification failed — ${fromPath} resolves to ${linkReal}, expected ${movedReal}`,
+          );
+          return 1;
+        }
+      }
+    }
+
+    // Empty overlay so taxonomy (domains/bundles) can be applied later via
+    // `skl infer` without touching the upstream SKILL.md. These are the user's own
+    // skills: source/provenance is null and NO lockfile entry is written.
+    const imported: Skill = {
+      name: targetName,
+      description: "",
+      primaryDomain: null,
+      domains: [],
+      path: destDir,
+      bodyPath: join(destDir, "SKILL.md"),
+      refFiles: [],
+      source: null,
+      retired: false,
+      mirrorOf: null,
+      contentHash: "",
+    };
+    const overlayPathStr = join(destDir, `${targetName}.shelf.json`);
+    if (!existsSync(overlayPathStr)) {
+      await writeOverlay(imported, {});
+    }
+
+    const summary = {
+      ok: true,
+      name: targetName,
+      from: fromPath,
+      to: destDir,
+      mode,
+      linkedBack,
+    };
+
+    if (flags.json) {
+      ctx.json(summary);
+    } else {
+      ctx.log(`imported ${targetName}`);
+      ctx.log(`  from:  ${fromPath}`);
+      ctx.log(`  to:    ${destDir}`);
+      ctx.log(`  mode:  ${mode}`);
+      if (linkedBack) ctx.log(`  link:  ${fromPath} -> ${destDir} (old path still resolves)`);
+      else if (mode === "move") ctx.log(`  note:  original location emptied (no symlink-back) — reach it via \`skl use\``);
+      ctx.log("Run `skl infer` to tag it and `skl index` to list it.");
+    }
+    return 0;
+  } catch (err) {
+    ctx.error(
+      `skl import: failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return 1;
+  }
+}

package/src/commands/new.ts

@@ -2,8 +2,9 @@
 //
 //   skl new <name> [--domain <d>] [--desc "..."] [--force] [--json]
 //
-// Writes <library>/[<domain>/]<name>/SKILL.md with frontmatter (name,
-// description, domains). Refuses to clobber an existing SKILL.md unless --force.
+// Writes <library>/<name>/SKILL.md with frontmatter (name, description, domains).
+// Layout is FLAT (ADR-0001): `--domain` becomes a frontmatter tag, never a folder.
+// Refuses to clobber an existing SKILL.md unless --force.
 
 import { join } from "node:path";
 import { existsSync } from "node:fs";
@@ -114,9 +115,8 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
 
   try {
     const libraryPath = ctx.config.libraryPath;
-    const skillDir = domain
-      ? join(libraryPath, domain, name)
-      : join(libraryPath, name);
+    // Flat, non-semantic layout (ADR-0001): always <library>/<name>/.
+    const skillDir = join(libraryPath, name);
     const bodyPath = join(skillDir, "SKILL.md");
 
     if (existsSync(bodyPath) && !args.force) {
@@ -133,7 +133,7 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
       description: desc || `TODO: describe ${name}.`,
     };
     if (domain) {
-      frontmatterData.primaryDomain = domain;
+      // Domain is a tag, not a folder; primaryDomain is derived as domains[0].
       frontmatterData.domains = [domain];
     }
 

package/src/commands/scan.ts

@@ -0,0 +1,257 @@
+// `skl scan [roots…]` — read-only discovery pass over scan roots.
+//
+// Crawls each root (see core/crawl.ts) and reports:
+//   - per-root candidate counts and a total
+//   - every candidate (a discovered skill — see CONTEXT.md) with its location
+//   - duplicate / drift groups (via core/dedupe.ts) with their locations and a
+//     recommendation for the human/agent to act on
+//
+// Roots come from positional args if given, else ctx.roots (config-persisted).
+// Scan NEVER moves anything and emits NO inference payload — taxonomy is the job
+// of `skl infer`. Use `skl import` to actually consolidate candidates.
+//
+// Flags:
+//   --add-root <path>   persist a scan root into config.json, then report roots
+//   --json              emit a structured object instead of the human report
+
+import { sep } from "node:path";
+import type { Ctx, Skill, DuplicateGroup } from "../types.ts";
+import { crawl } from "../core/crawl.ts";
+import {
+  findDuplicates,
+  driftedGroups,
+  exactDuplicateGroups,
+} from "../core/dedupe.ts";
+import { realpathOrSelf } from "../lib/fs.ts";
+
+export const meta = {
+  name: "scan",
+  summary: "Read-only discovery of skill candidates across roots (counts, duplicates, drift)",
+  usage:
+    "skl scan [roots…] [--add-root <path>] [--json]",
+} as const;
+
+interface Args {
+  roots: string[];
+  addRoot: string | null;
+  json: boolean;
+}
+
+function parseArgs(argv: string[]): { args: Args } | { error: string } {
+  const args: Args = { roots: [], addRoot: null, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--json") {
+      args.json = true;
+    } else if (a === "--add-root") {
+      const p = argv[++i];
+      if (!p) return { error: "--add-root requires a <path>" };
+      args.addRoot = p;
+    } else if (a.startsWith("--add-root=")) {
+      args.addRoot = a.slice("--add-root=".length);
+      if (args.addRoot === "") return { error: "--add-root requires a <path>" };
+    } else if (a.startsWith("--")) {
+      return { error: `unknown argument: ${a}` };
+    } else {
+      args.roots.push(a);
+    }
+  }
+  return { args };
+}
+
+/** True if a discovered skill dir lives under `root` (by realpath prefix). */
+function underRoot(skillPath: string, root: string): boolean {
+  const r = realpathOrSelf(root);
+  const p = realpathOrSelf(skillPath);
+  if (p === r) return true;
+  return p.startsWith(r.endsWith(sep) ? r : r + sep);
+}
+
+/** Attribute a discovered skill to the first matching scan root (else null). */
+function rootOf(skill: Skill, roots: string[]): string | null {
+  for (const root of roots) {
+    if (underRoot(skill.path, root)) return root;
+  }
+  return null;
+}
+
+interface CandidateView {
+  name: string;
+  description: string;
+  path: string;
+  root: string | null;
+  retired: boolean;
+  mirror: boolean;
+}
+
+function toCandidate(s: Skill, roots: string[]): CandidateView {
+  return {
+    name: s.name,
+    description: s.description,
+    path: s.path,
+    root: rootOf(s, roots),
+    retired: s.retired,
+    mirror: s.mirrorOf != null,
+  };
+}
+
+/** Human-readable recommendation for one duplicate/drift group. */
+function recommendationFor(g: DuplicateGroup): string {
+  if (g.divergent.length > 0) {
+    return `drift — ${g.divergent.length + 1} copies of "${g.name}" differ; review and pick a canonical copy (skillshelf won't choose for you)`;
+  }
+  return `exact duplicate — ${g.duplicates.length + 1} identical copies of "${g.name}"; import the canonical one and let the others become symlinks`;
+}
+
+function groupLocations(g: DuplicateGroup): string[] {
+  return [g.canonical, ...g.duplicates, ...g.divergent].map((s) => s.path);
+}
+
+interface GroupView {
+  name: string;
+  kind: "drift" | "duplicate";
+  identical: boolean;
+  canonical: string;
+  duplicates: string[];
+  divergent: string[];
+  locations: string[];
+  recommendation: string;
+}
+
+function toGroupView(g: DuplicateGroup): GroupView {
+  return {
+    name: g.name,
+    kind: g.divergent.length > 0 ? "drift" : "duplicate",
+    identical: g.identical,
+    canonical: g.canonical.path,
+    duplicates: g.duplicates.map((s) => s.path),
+    divergent: g.divergent.map((s) => s.path),
+    locations: groupLocations(g),
+    recommendation: recommendationFor(g),
+  };
+}
+
+/** Report the configured roots when there is nothing to scan. */
+function reportNoRoots(args: Args, roots: string[], ctx: Ctx): number {
+  if (args.json) {
+    ctx.json({ roots, totals: { roots: roots.length, candidates: 0 }, candidates: [], duplicateGroups: [] });
+    return 0;
+  }
+  if (roots.length === 0) {
+    ctx.log("No scan roots configured.");
+    ctx.log("Add one with:  skl scan --add-root <path>");
+    ctx.log("Or scan ad-hoc:  skl scan <path> [<path>…]");
+  } else {
+    ctx.log(`Configured scan roots (${roots.length}):`);
+    for (const r of roots) ctx.log(`  ${r}`);
+  }
+  return 0;
+}
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  const parsed = parseArgs(argv);
+  if ("error" in parsed) {
+    ctx.error(`skl scan: ${parsed.error}`);
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  const args = parsed.args;
+
+  try {
+    // --add-root: persist, then report the updated roots (no scan side effect).
+    if (args.addRoot != null) {
+      const roots = await ctx.addRoot(args.addRoot);
+      if (args.json) {
+        ctx.json({ added: realpathLike(args.addRoot, roots), roots });
+        return 0;
+      }
+      ctx.log(`Roots (${roots.length}):`);
+      for (const r of roots) ctx.log(`  ${r}`);
+      return 0;
+    }
+
+    // Roots: explicit args win; else fall back to configured roots.
+    const roots = args.roots.length > 0 ? args.roots : ctx.roots;
+    if (roots.length === 0) {
+      return reportNoRoots(args, ctx.roots, ctx);
+    }
+
+    // Single combined crawl: realpath-dedupe and cross-root drift detection both
+    // need every copy in one set.
+    const { skills, dedupedRoots } = await crawl(roots);
+
+    // Per-root counts (a candidate is a discovered skill; mirrors counted too so
+    // the count matches what's physically on disk under each root).
+    const perRoot = new Map<string, number>();
+    for (const r of roots) perRoot.set(r, 0);
+    for (const s of skills) {
+      const r = rootOf(s, roots);
+      if (r != null) perRoot.set(r, (perRoot.get(r) ?? 0) + 1);
+    }
+
+    const candidates = skills.map((s) => toCandidate(s, roots));
+    const allGroups = findDuplicates(skills);
+    const drifted = driftedGroups(allGroups);
+    const exact = exactDuplicateGroups(allGroups);
+    const reported = [...drifted, ...exact].sort((a, b) =>
+      a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
+    );
+    const groupViews = reported.map(toGroupView);
+
+    if (args.json) {
+      ctx.json({
+        roots,
+        totals: {
+          roots: roots.length,
+          candidates: candidates.length,
+          duplicateGroups: groupViews.length,
+          driftGroups: drifted.length,
+          exactDuplicateGroups: exact.length,
+        },
+        perRoot: roots.map((r) => ({ root: r, candidates: perRoot.get(r) ?? 0 })),
+        dedupedRoots,
+        candidates,
+        duplicateGroups: groupViews,
+      });
+      return 0;
+    }
+
+    // --- Human report ----------------------------------------------------
+    ctx.log(`Scanned ${roots.length} root${roots.length === 1 ? "" : "s"}:`);
+    for (const r of roots) {
+      ctx.log(`  ${r} — ${perRoot.get(r) ?? 0} candidate${(perRoot.get(r) ?? 0) === 1 ? "" : "s"}`);
+    }
+    if (dedupedRoots.length) {
+      ctx.log(`  (skipped ${dedupedRoots.length} aliased root${dedupedRoots.length === 1 ? "" : "s"}: ${dedupedRoots.join(", ")})`);
+    }
+    ctx.log("");
+    ctx.log(`Total candidates: ${candidates.length}`);
+
+    if (groupViews.length === 0) {
+      ctx.log("No duplicates or drift detected.");
+      return 0;
+    }
+
+    ctx.log("");
+    ctx.log(`Duplicate / drift groups (${groupViews.length}):`);
+    for (const g of groupViews) {
+      ctx.log(`  ${g.name} [${g.kind}]`);
+      for (const loc of g.locations) ctx.log(`    - ${loc}`);
+      ctx.log(`    → ${g.recommendation}`);
+    }
+    return 0;
+  } catch (err) {
+    ctx.error(`scan failed: ${(err as Error).message}`);
+    return 1;
+  }
+}
+
+/** Best-effort: report which root in the list corresponds to the added path. */
+function realpathLike(added: string, roots: string[]): string {
+  // ctx.addRoot expands/absolutizes; find the matching persisted entry to report.
+  const real = realpathOrSelf(added);
+  for (const r of roots) {
+    if (realpathOrSelf(r) === real) return r;
+  }
+  return roots[roots.length - 1] ?? added;
+}

package/src/config.ts

@@ -72,7 +72,51 @@ export async function resolveConfig(opts: {
         ? abs(fileCfg.globalCore.trim())
         : DEFAULT_GLOBAL_CORE;
 
-  return { libraryPath, globalCoreTarget, configFile: usedConfigFile, source };
+  const roots = normalizeRoots(fileCfg?.roots);
+
+  return {
+    libraryPath,
+    globalCoreTarget,
+    roots,
+    configFile: usedConfigFile,
+    configFilePath,
+    source,
+  };
+}
+
+/** Expand ~, absolutize, and de-duplicate a list of root paths (order-preserving). */
+function normalizeRoots(input: unknown): string[] {
+  if (!Array.isArray(input)) return [];
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const r of input) {
+    if (typeof r !== "string" || r.trim() === "") continue;
+    const a = abs(r.trim());
+    if (seen.has(a)) continue;
+    seen.add(a);
+    out.push(a);
+  }
+  return out;
+}
+
+/**
+ * Persist a new scan root into the config file (`configFilePath`), expanding ~,
+ * absolutizing, and de-duplicating against existing roots. Preserves the rest of
+ * the config file (library / globalCore). Returns the full updated roots list.
+ */
+export async function addRoot(
+  configFilePath: string,
+  existingRoots: string[],
+  path: string,
+): Promise<string[]> {
+  const a = abs(path.trim());
+  const roots = [...existingRoots];
+  if (!roots.includes(a)) roots.push(a);
+
+  const current = (await readConfigFile(configFilePath)) ?? {};
+  const next: ConfigFile = { ...current, roots };
+  await Bun.write(configFilePath, JSON.stringify(next, null, 2) + "\n");
+  return roots;
 }
 
 /**
@@ -85,6 +129,8 @@ export async function loadContext(opts: {
 } = {}): Promise<Ctx> {
   const config = await resolveConfig(opts);
 
+  let roots = config.roots;
+
   const ctx: Ctx = {
     config,
     libraryPath: config.libraryPath,
@@ -92,6 +138,14 @@ export async function loadContext(opts: {
       const { loadLibrary } = await import("./core/library.ts");
       return loadLibrary(config.libraryPath);
     },
+    roots,
+    addRoot: async (path: string): Promise<string[]> => {
+      roots = await addRoot(config.configFilePath, roots, path);
+      // keep the live ctx/config views in sync after a persist
+      ctx.roots = roots;
+      config.roots = roots;
+      return roots;
+    },
     log: (...args: unknown[]) => {
       console.log(...args);
     },

package/src/core/library.ts

@@ -2,51 +2,38 @@
 // effective skills, attach provenance from the lockfile, content-hash, list.
 
 import { existsSync } from "node:fs";
-import { basename, dirname, sep } from "node:path";
+import { basename, dirname } from "node:path";
 import type { Skill } from "../types.ts";
 import { crawl } from "./crawl.ts";
 import { withOverlay } from "./overlay.ts";
 import { readLockfile, provenanceForName } from "./provenance.ts";
 
-/**
- * Derive a primary-domain hint from a skill dir inside the library: the first
- * path segment under the library root is the primary-domain folder.
- *   <lib>/bioinfo/foo/SKILL.md -> "bioinfo"
- */
-function libraryPrimaryDomain(libraryRoot: string): (dir: string) => string | null {
-  const rootParts = libraryRoot.replace(/\/+$/, "").split(sep);
-  // Structural folders that are not real domains (bridge/layout dirs).
-  const STRUCTURAL = new Set([".agents", ".claude", "skills", "skill", "_retired"]);
-  return (dir: string) => {
-    const parts = dir.split(sep);
-    // dir is <lib>/<domain>/<name>; domain is the segment right after root.
-    if (parts.length > rootParts.length + 1) {
-      const seg = parts[rootParts.length] ?? null;
-      if (seg && !STRUCTURAL.has(seg)) return seg;
-    }
-    // Not a clean domain folder (e.g. a .agents mirror) — let frontmatter win.
-    return null;
-  };
-}
-
 /**
  * Load the canonical library at `libraryPath` into effective Skill[]:
  * crawl + overlay-merge + provenance attach. Returns [] if the path is missing.
+ *
+ * Library layout is FLAT and non-semantic (`library/<name>/`). Domain membership
+ * lives entirely in tags (frontmatter + overlay); `primaryDomain` is the derived
+ * view `domains[0]` of the *effective* (overlay-merged) tags, or null if a skill
+ * has no domains. See docs/adr/0001-domain-is-tags-not-folders.md.
  */
 export async function loadLibrary(libraryPath: string): Promise<Skill[]> {
   if (!existsSync(libraryPath)) return [];
 
-  const { skills } = await crawl([libraryPath], {
-    primaryDomainOf: libraryPrimaryDomain(libraryPath),
-  });
+  const { skills } = await crawl([libraryPath]);
 
   const lock = await readLockfile(libraryPath);
 
   const effective: Skill[] = [];
   for (const s of skills) {
     const merged = await withOverlay(s);
-    const prov = provenanceForName(lock, merged.name);
-    effective.push(prov ? { ...merged, source: prov } : merged);
+    // primaryDomain is derived from the EFFECTIVE (post-overlay) tags: domains[0].
+    const withPrimary: Skill = {
+      ...merged,
+      primaryDomain: merged.domains.length > 0 ? merged.domains[0]! : null,
+    };
+    const prov = provenanceForName(lock, withPrimary.name);
+    effective.push(prov ? { ...withPrimary, source: prov } : withPrimary);
   }
   // stable ordering: primaryDomain then name
   effective.sort((a, b) => {

package/src/types.ts

@@ -27,7 +27,7 @@ export interface Skill {
   name: string;
   /** frontmatter `description` (may be multi-line) */
   description: string;
-  /** primary domain folder this skill physically lives under (library), or inferred. null if unknown */
+  /** derived view = effective `domains[0]` (post-overlay); null if the skill has no domains. NOT folder-derived (see ADR-0001). */
   primaryDomain: string | null;
   /** effective domain tags (primary first), de-duplicated */
   domains: string[];
@@ -136,8 +136,12 @@ export interface Config {
   libraryPath: string;
   /** absolute path to the global-core symlink target (~/.claude/skills) */
   globalCoreTarget: string;
+  /** persisted, absolute, de-duplicated scan roots (`skl scan` searches these) */
+  roots: string[];
   /** absolute path to the config file that was read, if any */
   configFile: string | null;
+  /** absolute path of the config file roots would be persisted to (read or default) */
+  configFilePath: string;
   /** how libraryPath was resolved */
   source: "env" | "config" | "default";
 }
@@ -148,6 +152,8 @@ export interface ConfigFile {
   library?: string;
   /** override global-core target */
   globalCore?: string;
+  /** persisted scan roots (`skl scan`) */
+  roots?: string[];
 }
 
 /**
@@ -161,6 +167,10 @@ export interface Ctx {
   libraryPath: string;
   /** load the canonical library (effective skills, overlays merged) */
   loadLibrary: () => Promise<Skill[]>;
+  /** configured scan roots (absolute, de-duplicated); convenience alias for config.roots */
+  roots: string[];
+  /** add a scan root: expands ~, makes absolute, de-dupes, persists to config.json. Returns the updated roots. */
+  addRoot: (path: string) => Promise<string[]>;
   /** human-readable logging to stdout */
   log: (...args: unknown[]) => void;
   /** machine-parseable single-line JSON to stdout */