@oneezy/skills-sync 0.2.0

package/README.md

@@ -0,0 +1,84 @@
+# @oneezy/skills-sync
+
+One skills library. Every agent harness. Every project on the machine.
+
+```
+npx @oneezy/skills-sync
+```
+
+Run it anywhere and it works out the rest:
+
+- **No library on this machine?** It clones one into `~/.skills-sync` (default `oneezy/skills`; `--library owner/repo` for another) and asks nothing.
+- **Library present?** It pulls it, restores whatever the lock file has that is missing, rebuilds the library's harness layers, and links every skill into each harness's user folder. Every step is skipped when its result is already right, so a no-op run is silent and fast.
+- **On another machine or in a cloud session?** Run the same command there (or ask the agent to run the `oneezy-skills` skill, which does exactly that). Nothing is installed into any harness's settings.
+
+First run on a machine with a terminal asks which harnesses, whether to link the user folders, which projects (if any) should carry copies, and (on Windows) which WSL distros. Answers are remembered in `skills-sync.json` beside the lock; `--ask` prompts again. Node 20+, git. Windows uses junctions (no admin), everything else symlinks.
+
+Edit a skill in the library and every harness sees the change immediately: the user-folder entries are links. `git push` from the library is how it reaches other machines; their next session start pulls it.
+
+## The library
+
+A skills library is a folder with two committed things:
+
+| path | holds | written by |
+|---|---|---|
+| `skills/<name>/` | your own skills, bare Agent Skills form (`SKILL.md`, optional `scripts/`, `references/`, `agents/openai.yaml`) | you |
+| `skills-lock.json` | pins for third-party skills: source repo, path, hash | `npx skills add <owner>/<repo>` and `npx skills update` |
+
+Everything else in it is generated and should be gitignored:
+
+| path | holds |
+|---|---|
+| `.agents/skills/<name>` | the working set: third-party skills restored from the lock, plus one link per own skill. Codex reads this folder directly. |
+| `.claude/skills/<name>`, `.goose/skills/<name>`, `.hermes/skills/<name>` | one link per working-set entry, for each harness that does not read `.agents/skills` |
+
+`oneezy/skills` is one such library; `npx skills add oneezy/skills` installs its own skills anywhere, and cloning it plus one `npx @oneezy/skills-sync` gives a new machine the whole set.
+
+## What a run does
+
+1. **Find the library.** `--repo`, else `$SKILLS_REPO`, else `~/.skills-sync` (the clone, or a link to wherever the library really lives), else a library folder above the current one (both `skills/` and `skills-lock.json`; never a dot-folder). Found somewhere else than `~/.skills-sync`? A link is left there so the next run finds it from anywhere. Nothing found? Clone one.
+1. **Pull.** Fast-forward the library from its remote, at most every 30 minutes, only when its tree is clean (`--pull` forces, `--no-pull` skips).
+2. **Restore.** Lock entries with no folder in `.agents/skills` are fetched: one shallow clone per source, each skill copied from its recorded path, or found by folder name when upstream moved it. Skills upstream deleted are reported, remembered, and skipped until `--retry`. (`npx skills experimental_install` clones once per skill and stops at the first stale path, so this is done natively.)
+3. **Layers.** `.agents/skills/<name>` links to `skills/<name>` for own skills, listed in a generated `.agents/skills/.gitignore`. Each selected harness that has its own project folder gets one link per working-set entry. With `--sidecars`, own skills that lack `agents/openai.yaml` get one generated from their frontmatter, so Codex sees the same policy; it writes into `skills/`, so it is opt-in.
+4. **User folders.** One link per skill in each selected harness's user skills folder (`~/.claude/skills`, `~/.agents/skills`, `~/.config/goose/skills`, `~/.hermes/skills`), pointing at the real folder. Every project on the machine now sees the set, and an edit in the library is live everywhere.
+5. **Projects.** Optional. Git repos under the dev folder that you check get their skills too: **link** mode makes the same links inside the repo and hides them from git through `.git/info/exclude`; **copy** mode writes real folders meant to be committed, for repos that must carry their own (cloud sessions, other people).
+6. **WSL.** Windows only, optional. Each checked distro runs the same sync for its own user folders through `/mnt/<drive>/…`. The distro needs Node.
+
+
+Then it prints one line per change and a summary. `--plan` prints the same without touching anything.
+
+## Rules it never breaks
+
+- A link is created, retargeted or removed only when its target is inside the library. A real folder in the way, or a link pointing elsewhere, is reported as a conflict and left alone.
+- `synced/` (Claude's account skills) and `.system/` are never touched.
+- Third-party copies in `.agents/skills` are never modified; `npx skills update` owns them.
+- Inside WSL the library's own layers are left to Windows.
+
+## Prompts and flags
+
+Interactive (a terminal, no `-y`): library path, harnesses to sync (detected ones pre-checked), where (user folders, projects), which projects and link or copy, machines (Windows plus WSL distros). Answers are saved in `skills-sync.json` beside the lock; `--ask` prompts again.
+
+Every answer is also a flag, so scripts and agents never see a prompt:
+
+```
+--repo <path>        --agents claude-code,codex,goose,hermes
+--global | --no-global
+--projects a,b | --projects '*' | --no-projects     --dev <dir>     --copy
+--wsl Ubuntu | --wsl '*' | --no-wsl
+--library owner/repo   --pull | --no-pull
+--no-restore  --retry  --sidecars  --no-layers
+--watch  --plan  --quiet  --json  -y  --ask
+```
+
+Commands: `sync` (default), `status`, `unlink` (remove every link this tool made in the user folders), `projects` (only step 5).
+
+`--watch` keeps running and redoes layers and user folders when `skills/` or the lock changes, so a skill you add is linked the moment its folder appears.
+
+## Development
+
+```
+cd clis/skills-sync
+pnpm install && pnpm build
+pnpm test          # node:test on temp folders; junctions on Windows, symlinks elsewhere
+node dist/src/cli.js --repo <library> --plan
+```

package/dist/src/cli.js

@@ -0,0 +1,369 @@
+#!/usr/bin/env node
+// skills-sync: one skills library, every harness, every project on the machine. One command that works out where it is.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import * as p from "@clack/prompts";
+import { readConfig, writeConfig } from "./config.js";
+import { gitExclude, isDir, isLink, lexists, linkTarget, real, samePath } from "./fs.js";
+import { detected, harnessTable } from "./harnesses.js";
+import { cloneLibrary, DEFAULT_LIBRARY, findLibrary, homeLibrary, Library, looksLikeLibrary, pullLibrary } from "./library.js";
+import { apply, line, Report } from "./plan.js";
+import { findProjects, home, isRepo, layers, projects, status, unlink } from "./steps.js";
+import { runInWsl, wslDistros } from "./wsl.js";
+const VERSION = "0.2.0";
+const HELP = `skills-sync ${VERSION}
+One skills library, every harness, every project on this machine. Run it anywhere; it works out the rest.
+
+  no library on this machine   clone one into ~/.skills-sync (default: ${DEFAULT_LIBRARY}, or --library owner/repo)
+  library present              pull it, restore what the lock has, rebuild its layers, link the user folders
+
+Usage: skills-sync [command] [options]
+
+Commands
+  sync (default)   everything above
+  status           what is linked and what is missing
+  unlink           remove every link this tool made in the user folders
+  projects         only the project step
+
+Options
+  --repo <path>          the skills library (default: $SKILLS_REPO, ~/.skills-sync, a library folder above here)
+  --library <src>        what to clone when there is no library yet (owner/repo or URL; default ${DEFAULT_LIBRARY})
+  --agents <ids>         harnesses: claude-code,codex,goose,hermes (default: detected)
+  --global / --no-global link into the harnesses' user skills folders (default: yes)
+  --projects <names|*>   repos under --dev to sync; "*" for all; --no-projects for none
+  --dev <dir>            folder whose git repos are offered (default: here, or the parent when here is a repo)
+  --copy                 projects get real copies instead of links
+  --wsl <distros|*>      Windows: also sync the user folders inside these WSL distros; --no-wsl for none
+  --no-pull / --pull     skip, or force, the library pull (default: at most every 30 minutes)
+  --no-restore           do not restore missing lock entries from their sources
+  --retry                retry lock entries an earlier run reported as gone upstream
+  --sidecars             generate agents/openai.yaml for own skills that lack one (writes into skills/, so opt-in)
+  --no-layers            leave the library's own layers alone (used inside WSL, where Windows owns them)
+  --watch                stay running; redo layers and user folders when skills/ or the lock changes
+  --plan                 show what would change, touch nothing
+  --quiet                for scripts: no prompts, no WSL fan-out, print only changes and problems
+  --json                 machine output
+  -y, --yes              no prompts: flags, then remembered answers, then defaults
+  --ask                  prompt even when answers are remembered
+  -h, --help
+`;
+function parseArgs(argv) {
+    const a = { command: "sync", pull: true, restore: true, retry: false, sidecars: false, layers: true, watch: false, plan: false, quiet: false, json: false, yes: false, ask: false };
+    const list = (v) => v.split(",").map((s) => s.trim()).filter(Boolean);
+    for (let i = 0; i < argv.length; i++) {
+        const x = argv[i];
+        const next = () => argv[++i];
+        if (x === "-h" || x === "--help") {
+            process.stdout.write(HELP);
+            process.exit(0);
+        }
+        else if (x === "--repo")
+            a.repo = next();
+        else if (x === "--library")
+            a.library = next();
+        else if (x === "--agents")
+            a.agents = list(next());
+        else if (x === "--global")
+            a.global = true;
+        else if (x === "--no-global")
+            a.global = false;
+        else if (x === "--projects") {
+            const v = next();
+            a.projects = v === "*" ? "*" : list(v);
+        }
+        else if (x === "--no-projects")
+            a.projects = false;
+        else if (x === "--dev")
+            a.dev = next();
+        else if (x === "--copy")
+            a.copy = true;
+        else if (x === "--wsl") {
+            const v = next();
+            a.wsl = v === "*" ? "*" : list(v);
+        }
+        else if (x === "--no-wsl")
+            a.wsl = false;
+        else if (x === "--no-pull")
+            a.pull = false;
+        else if (x === "--pull")
+            a.pull = "force";
+        else if (x === "--no-restore")
+            a.restore = false;
+        else if (x === "--retry")
+            a.retry = true;
+        else if (x === "--sidecars")
+            a.sidecars = true;
+        else if (x === "--no-layers")
+            a.layers = false;
+        else if (x === "--watch")
+            a.watch = true;
+        else if (x === "--plan")
+            a.plan = true;
+        else if (x === "--quiet")
+            a.quiet = true;
+        else if (x === "--json")
+            a.json = true;
+        else if (x === "-y" || x === "--yes")
+            a.yes = true;
+        else if (x === "--ask")
+            a.ask = true;
+        else if (x.startsWith("-")) {
+            process.stderr.write(`unknown option ${x}\n${HELP}`);
+            process.exit(2);
+        }
+        else
+            a.command = x;
+    }
+    if (a.quiet)
+        a.yes = true;
+    return a;
+}
+function bail(msg) {
+    process.stderr.write(msg + "\n");
+    process.exit(1);
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const cwd = process.cwd();
+    const userHome = os.homedir();
+    const interactive = !args.yes && !args.json && process.stdin.isTTY && process.stdout.isTTY;
+    const log = (m) => (args.json ? undefined : process.stderr.write(m + "\n"));
+    const setup = new Report();
+    // 1. the library: find it, or get one
+    let root = args.repo ? real(path.resolve(args.repo)) : findLibrary(cwd);
+    if (!root && !args.plan) {
+        let source = args.library ?? DEFAULT_LIBRARY;
+        if (interactive) {
+            p.intro("skills-sync");
+            const v = await p.text({ message: "No skills library on this machine. Clone which one into ~/.skills-sync?", initialValue: source, placeholder: "owner/repo, a git URL, or a local path" });
+            if (p.isCancel(v))
+                return p.cancel("nothing changed");
+            source = String(v);
+        }
+        if (looksLikeLibrary(source))
+            root = real(path.resolve(source));
+        else {
+            const c = cloneLibrary(source, userHome, log);
+            if (!c.ok)
+                bail(`could not clone ${source}: ${c.error}`);
+            root = c.root;
+        }
+    }
+    if (!root || !looksLikeLibrary(root))
+        bail("no skills library found: run this inside one, or pass --repo <path> or --library owner/repo");
+    const lib = new Library(root);
+    // ~/.skills-sync points at the library from now on, so every later run finds it from anywhere
+    const hl = homeLibrary(userHome);
+    if (!samePath(real(hl), lib.root)) {
+        if (!lexists(hl))
+            setup.add({ kind: "link", path: hl, target: lib.root, note: "remembers where the library is" });
+        else if (isLink(hl))
+            setup.add({ kind: "relink", path: hl, target: lib.root, note: `was ${linkTarget(hl)}` });
+        else
+            setup.add({ kind: "conflict", path: hl, note: "a folder is in the way; ~/.skills-sync is not a link to the library" });
+    }
+    apply(setup, args.plan);
+    // 2. keep the library current
+    if (args.pull && args.command !== "status" && !args.plan) {
+        if (args.pull === "force") {
+            try {
+                fs.unlinkSync(path.join(lib.root, ".git", "skills-sync-pulled"));
+            }
+            catch {
+                /* nothing to reset */
+            }
+        }
+        const r = pullLibrary(lib.root, 30, log);
+        if (r === "pulled" && !args.quiet)
+            log("library pulled");
+        if (r === "dirty" && !args.quiet)
+            log("library has local changes; pull skipped");
+    }
+    const cfg = readConfig(lib.root);
+    const table = harnessTable();
+    if (args.command === "status") {
+        const ids = args.agents ?? cfg.agents;
+        return printStatus(lib, ids ? table.filter((h) => ids.includes(h.id)) : detected(table), args.json);
+    }
+    if (args.command === "unlink") {
+        const r = new Report();
+        unlink(lib, table, r);
+        apply(r, args.plan);
+        return printReport(r, args);
+    }
+    // 3. the choices: flags, then remembered answers, then defaults; prompts fill the gaps when interactive
+    const choices = await decide(args, cfg, lib, table, cwd, interactive);
+    if (!choices)
+        return p.cancel("nothing changed");
+    if (!args.plan)
+        saveConfig(lib.root, choices);
+    // 4. run
+    const run = () => runOnce(lib, choices, args, cwd, setup);
+    await run();
+    if (args.watch) {
+        log(`watching ${lib.own} and ${path.basename(lib.lockFile)}; ctrl-c to stop`);
+        let timer = null;
+        const trigger = (why) => {
+            if (timer)
+                clearTimeout(timer);
+            timer = setTimeout(() => {
+                log(`change in ${why}`);
+                runOnce(lib, choices, { ...args, restore: false }, cwd, new Report()).catch((e) => log(String(e)));
+            }, 400);
+        };
+        fs.watch(lib.own, { recursive: true }, (_e, f) => trigger(String(f ?? "skills/")));
+        if (fs.existsSync(lib.lockFile))
+            fs.watch(lib.lockFile, () => trigger("skills-lock.json"));
+        await new Promise(() => undefined);
+    }
+}
+function saveConfig(root, c) {
+    const saved = { agents: c.agents.map((h) => h.id), global: c.global, dev: c.dev, projects: c.projects, mode: c.mode, wsl: c.wsl };
+    if (c.unavailable.length)
+        saved.unavailable = c.unavailable;
+    writeConfig(root, saved);
+}
+async function decide(args, cfg, lib, table, cwd, interactive) {
+    const found = detected(table);
+    const byId = new Map(table.map((h) => [h.id, h]));
+    // first run with nothing remembered: only the two harnesses this tool is built around, unless asked
+    let agentIds = args.agents ?? cfg.agents ?? found.filter((h) => h.id === "claude-code" || h.id === "codex").map((h) => h.id);
+    let global = args.global ?? cfg.global ?? true;
+    const here = path.resolve(cwd);
+    let dev = args.dev ? path.resolve(args.dev) : cfg.dev ?? (isRepo(here) && !looksLikeLibrary(here) ? path.dirname(here) : here);
+    const offered = findProjects(dev, lib).map((pp) => path.basename(pp));
+    let projectNames = args.projects === false ? [] : args.projects === "*" ? offered : args.projects ?? cfg.projects ?? [];
+    let mode = args.copy ? "copy" : cfg.mode ?? "link";
+    const distros = args.quiet ? [] : wslDistros();
+    let wsl = args.wsl === false ? [] : args.wsl === "*" ? distros : args.wsl ?? cfg.wsl ?? [];
+    const remembered = Object.keys(cfg).length > 0;
+    if (interactive && (args.ask || !remembered || args.command === "projects")) {
+        if (!remembered)
+            p.intro("skills-sync: first run on this machine");
+        const agentsPick = await p.multiselect({
+            message: "Harnesses to sync (checked = detected on this machine)",
+            options: table.map((h) => ({ value: h.id, label: h.name, hint: found.includes(h) ? "detected" : "not found" })),
+            initialValues: agentIds,
+            required: true,
+        });
+        if (p.isCancel(agentsPick))
+            return null;
+        agentIds = agentsPick;
+        const whereOptions = [{ value: "global", label: "User folders", hint: "every project on this machine; edits are live" }];
+        if (offered.length)
+            whereOptions.push({ value: "projects", label: `Projects in ${dev}`, hint: `${offered.length} git repos; only for repos that must carry copies` });
+        const where = await p.multiselect({ message: "Where", options: whereOptions, initialValues: [global ? "global" : "", projectNames.length ? "projects" : ""].filter(Boolean), required: false });
+        if (p.isCancel(where))
+            return null;
+        global = where.includes("global");
+        if (where.includes("projects")) {
+            const pick = await p.multiselect({ message: "Which projects (space to check)", options: offered.map((n) => ({ value: n, label: n })), initialValues: projectNames.length ? projectNames : offered, required: false });
+            if (p.isCancel(pick))
+                return null;
+            projectNames = pick;
+            const m = await p.select({
+                message: "Project mode",
+                options: [
+                    { value: "link", label: "link", hint: "machine-local, hidden from git through .git/info/exclude" },
+                    { value: "copy", label: "copy", hint: "committed, travels with the repo" },
+                ],
+                initialValue: mode,
+            });
+            if (p.isCancel(m))
+                return null;
+            mode = m;
+        }
+        else
+            projectNames = [];
+        if (distros.length) {
+            const m = await p.multiselect({ message: "Machines", options: [{ value: "__win__", label: "Windows", hint: "this one" }, ...distros.map((d) => ({ value: d, label: `WSL: ${d}` }))], initialValues: ["__win__", ...wsl], required: true });
+            if (p.isCancel(m))
+                return null;
+            wsl = m.filter((x) => x !== "__win__");
+        }
+    }
+    const agents = agentIds.map((id) => byId.get(id)).filter((h) => !!h);
+    if (!agents.length)
+        bail("no harness selected; pass --agents claude-code,codex");
+    return { agents, global, dev, projects: projectNames, mode, wsl, unavailable: args.retry ? [] : cfg.unavailable ?? [] };
+}
+async function runOnce(lib, c, args, cwd, report) {
+    const log = (m) => (args.json ? undefined : process.stderr.write(m + "\n"));
+    const userHome = os.homedir();
+    const missing = lib.missingFromLock().filter((n) => !c.unavailable.includes(n));
+    if (args.restore && args.command !== "projects" && missing.length && !args.plan) {
+        const r = lib.restore(log, missing);
+        log(`restored ${r.restored.length} skill(s) from skills-lock.json`);
+        for (const m of r.moved)
+            log(`  moved upstream: ${m}`);
+        for (const m of r.missing)
+            log(`  gone upstream: ${m}`);
+        if (r.missing.length)
+            log(`  (npx skills remove <name> drops it from the lock; a copy in skills/ keeps it as your own; --retry checks again)`);
+        for (const m of r.failed)
+            log(`  failed: ${m}`);
+        c.unavailable = [...new Set([...c.unavailable, ...r.missing.map((m) => m.split(":")[0])])];
+        saveConfig(lib.root, c);
+    }
+    else if (missing.length)
+        log(`${missing.length} lock entries are not installed yet (run without --plan or --no-restore to restore them)`);
+    if (c.unavailable.length && !args.quiet)
+        log(`${c.unavailable.length} lock entr${c.unavailable.length === 1 ? "y is" : "ies are"} gone upstream (${c.unavailable.join(", ")}); --retry to check again`);
+    if (args.command !== "projects") {
+        if (args.layers) {
+            const s = new Report();
+            layers(lib, c.agents, s, args.sidecars);
+            apply(s, args.plan);
+            report.merge(s);
+        }
+        if (c.global) {
+            const u = new Report();
+            home(lib, c.agents, u);
+            apply(u, args.plan);
+            report.merge(u);
+        }
+    }
+    if (c.projects.length) {
+        const targets = c.projects.map((n) => path.join(c.dev, n)).filter((pp) => isDir(pp));
+        const pr = new Report();
+        projects(lib, c.agents, targets, null, c.mode, pr);
+        apply(pr, args.plan, gitExclude);
+        report.merge(pr);
+    }
+    printReport(report, args);
+    if (c.wsl.length && args.command !== "projects" && !args.quiet) {
+        for (const d of c.wsl) {
+            const r = runInWsl(d, lib.root, [], args.plan);
+            log(`WSL ${d}: ${r.ok ? "ok" : "failed"}${r.output ? "\n  " + r.output.split("\n").slice(-3).join("\n  ") : ""}`);
+        }
+    }
+}
+function printReport(r, args) {
+    if (args.json) {
+        process.stdout.write(JSON.stringify({ plan: args.plan, actions: r.actions }, null, 2) + "\n");
+        return;
+    }
+    const changes = r.changes();
+    const conflicts = r.conflicts();
+    if (args.quiet && !changes.length && !conflicts.length)
+        return;
+    for (const a of r.actions)
+        if (a.kind !== "skip")
+            process.stdout.write(line(a) + "\n");
+    const verb = args.plan ? "would change" : "changed";
+    process.stdout.write(`${args.plan ? "plan: " : ""}${changes.length} ${verb}, ${r.skips()} already right, ${conflicts.length} left alone\n`);
+}
+function printStatus(lib, table, json) {
+    const s = status(lib, table);
+    if (json) {
+        process.stdout.write(JSON.stringify(s, null, 2) + "\n");
+        return;
+    }
+    process.stdout.write(`library ${s.library}: ${s.own.length} own, ${s.thirdParty.length} third-party, ${s.missingFromLock.length} in the lock but not installed\n`);
+    for (const [layer, v] of Object.entries(s.layers))
+        process.stdout.write(`${layer}: ${v.linked} linked, ${v.missing.length} missing\n`);
+    for (const [dir, v] of Object.entries(s.user))
+        process.stdout.write(`${dir}: ${v.linked} linked, ${v.missing.length} missing\n`);
+}
+main().catch((e) => bail(String(e?.stack ?? e)));

package/dist/src/config.js

@@ -0,0 +1,15 @@
+// Remembered answers, kept beside the lock file so the second run needs no prompts.
+import fs from "node:fs";
+import path from "node:path";
+export const CONFIG_NAME = "skills-sync.json";
+export function readConfig(libraryRoot) {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(libraryRoot, CONFIG_NAME), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeConfig(libraryRoot, cfg) {
+    fs.writeFileSync(path.join(libraryRoot, CONFIG_NAME), JSON.stringify(cfg, null, 2) + "\n");
+}

package/dist/src/fs.js

@@ -0,0 +1,146 @@
+// Link primitives that behave the same on Windows (junctions, no admin) and POSIX (symlinks).
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+export function lexists(p) {
+    try {
+        fs.lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** A directory symlink, or a junction on Windows. */
+export function isLink(p) {
+    try {
+        const st = fs.lstatSync(p);
+        if (st.isSymbolicLink())
+            return true;
+        // junctions report as directories with a reparse point; readlink resolves them
+        if (process.platform === "win32" && st.isDirectory()) {
+            try {
+                fs.readlinkSync(p);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+export function linkTarget(p) {
+    try {
+        let raw = fs.readlinkSync(p);
+        if (raw.startsWith("\\\\?\\"))
+            raw = raw.slice(4);
+        return path.isAbsolute(raw) ? raw : path.resolve(path.dirname(p), raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function norm(p) {
+    const n = path.normalize(p).replace(/[\\/]+$/, "");
+    return process.platform === "win32" ? n.toLowerCase() : n;
+}
+export function samePath(a, b) {
+    return norm(a) === norm(b);
+}
+export function under(p, root) {
+    const a = norm(p);
+    const r = norm(root);
+    return a === r || a.startsWith(r + path.sep);
+}
+export function real(p) {
+    try {
+        return fs.realpathSync.native(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+export function makeLink(target, link) {
+    fs.mkdirSync(path.dirname(link), { recursive: true });
+    fs.symlinkSync(target, link, process.platform === "win32" ? "junction" : "dir");
+}
+export function removeLink(link) {
+    try {
+        fs.rmdirSync(link); // junctions and directory symlinks on Windows
+    }
+    catch {
+        fs.unlinkSync(link);
+    }
+}
+export function isSkillDir(p) {
+    try {
+        return fs.statSync(path.join(p, "SKILL.md")).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export function isDir(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Content hash of a folder: relative paths plus bytes, so two copies compare equal. */
+export function folderHash(folder) {
+    const h = createHash("sha256");
+    const walk = (dir) => {
+        for (const e of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory())
+                walk(full);
+            else if (e.isFile()) {
+                h.update(path.relative(folder, full).replace(/\\/g, "/"));
+                h.update(fs.readFileSync(full));
+            }
+        }
+    };
+    walk(folder);
+    return h.digest("hex");
+}
+export function copyDir(src, dst) {
+    if (fs.existsSync(dst))
+        fs.rmSync(dst, { recursive: true, force: true });
+    fs.mkdirSync(path.dirname(dst), { recursive: true });
+    fs.cpSync(src, dst, { recursive: true, dereference: true });
+}
+/** Add lines to a repo's .git/info/exclude (honored by git, never committed). */
+export function gitExclude(repo, entries) {
+    const gitDir = path.join(repo, ".git");
+    let infoDir;
+    try {
+        const st = fs.statSync(gitDir);
+        if (st.isDirectory())
+            infoDir = path.join(gitDir, "info");
+        else {
+            // worktree: ".git" is a file pointing at the real git dir
+            const m = /gitdir:\s*(.+)/.exec(fs.readFileSync(gitDir, "utf8"));
+            if (!m)
+                return false;
+            infoDir = path.join(path.resolve(repo, m[1].trim()), "info");
+        }
+    }
+    catch {
+        return false;
+    }
+    fs.mkdirSync(infoDir, { recursive: true });
+    const file = path.join(infoDir, "exclude");
+    const existing = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+    const lines = new Set(existing.split(/\r?\n/));
+    const missing = entries.filter((e) => !lines.has(e));
+    if (!missing.length)
+        return false;
+    fs.writeFileSync(file, existing.replace(/\n?$/, "\n") + "# skills-sync links\n" + missing.join("\n") + "\n");
+    return true;
+}

package/dist/src/harnesses.js

@@ -0,0 +1,58 @@
+// The table of harnesses: where each one keeps user-level and project-level skills.
+// Adding a harness is one row. Paths follow each harness's own docs, not another tool's guess.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export function harnessTable(home = os.homedir(), env = process.env) {
+    const codexHome = env.CODEX_HOME?.trim() || path.join(home, ".codex");
+    const claudeHome = env.CLAUDE_CONFIG_DIR?.trim() || path.join(home, ".claude");
+    const configHome = env.XDG_CONFIG_HOME?.trim() || path.join(home, ".config");
+    const hermesHome = env.HERMES_HOME?.trim() || path.join(home, ".hermes");
+    return [
+        {
+            id: "claude-code",
+            name: "Claude Code",
+            configDir: claudeHome,
+            userSkills: path.join(claudeHome, "skills"),
+            projectSkills: path.join(".claude", "skills"),
+            universal: false,
+        },
+        {
+            id: "codex",
+            name: "Codex",
+            configDir: codexHome,
+            // Codex reads ~/.agents/skills; ~/.codex/skills is its deprecated location
+            userSkills: path.join(home, ".agents", "skills"),
+            projectSkills: path.join(".agents", "skills"),
+            universal: true,
+        },
+        {
+            id: "goose",
+            name: "Goose",
+            configDir: path.join(configHome, "goose"),
+            userSkills: path.join(configHome, "goose", "skills"),
+            projectSkills: path.join(".goose", "skills"),
+            universal: false,
+        },
+        {
+            id: "hermes",
+            name: "Hermes",
+            configDir: hermesHome,
+            userSkills: path.join(hermesHome, "skills"),
+            projectSkills: path.join(".hermes", "skills"),
+            universal: false,
+        },
+    ];
+}
+export function detected(table) {
+    return table.filter((h) => {
+        try {
+            return fs.statSync(h.configDir).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** Names a harness must never see as a skill folder. */
+export const RESERVED = new Set(["synced", ".system"]);

package/dist/src/library.js

@@ -0,0 +1,244 @@
+// The skills library: a folder with skills/<name>/ (own skills) and skills-lock.json (third-party pins).
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import YAML from "yaml";
+import { isDir, isSkillDir, real } from "./fs.js";
+import { RESERVED } from "./harnesses.js";
+export class Library {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    get own() {
+        return path.join(this.root, "skills");
+    }
+    get agents() {
+        return path.join(this.root, ".agents", "skills");
+    }
+    get lockFile() {
+        return path.join(this.root, "skills-lock.json");
+    }
+    ownSkills() {
+        if (!isDir(this.own))
+            return [];
+        return fs
+            .readdirSync(this.own)
+            .filter((n) => !n.startsWith(".") && isSkillDir(path.join(this.own, n)))
+            .sort();
+    }
+    /** name -> real folder, for every entry of .agents/skills that holds a SKILL.md */
+    workingSet() {
+        const out = new Map();
+        if (!isDir(this.agents))
+            return out;
+        for (const n of fs.readdirSync(this.agents).sort()) {
+            if (n.startsWith(".") || RESERVED.has(n))
+                continue;
+            const p = path.join(this.agents, n);
+            if (isSkillDir(p))
+                out.set(n, real(p));
+        }
+        return out;
+    }
+    lockedSkills() {
+        try {
+            const lock = JSON.parse(fs.readFileSync(this.lockFile, "utf8"));
+            return Object.keys(lock.skills ?? {}).sort();
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Lock entries with no folder in .agents/skills yet. */
+    missingFromLock() {
+        return this.lockedSkills().filter((n) => !isSkillDir(path.join(this.agents, n)));
+    }
+    lockEntries() {
+        try {
+            return JSON.parse(fs.readFileSync(this.lockFile, "utf8")).skills ?? {};
+        }
+        catch {
+            return {};
+        }
+    }
+    /**
+     * Restore missing lock entries into .agents/skills: one shallow clone per source, then each skill
+     * copied from its recorded path, or found by folder name when upstream moved it. Entries whose
+     * source no longer has the skill are reported, never invented. (`npx skills experimental_install`
+     * clones once per skill and stops at the first stale path, which is why this exists.)
+     */
+    restore(log, only) {
+        const result = { restored: [], moved: [], missing: [], failed: [] };
+        const wanted = new Set(only ?? this.missingFromLock());
+        const bySource = new Map();
+        for (const [name, e] of Object.entries(this.lockEntries())) {
+            if (!wanted.has(name))
+                continue;
+            const url = cloneUrl(e);
+            if (!url) {
+                result.failed.push(`${name}: source type ${e.sourceType} is not restorable`);
+                continue;
+            }
+            const key = `${url}#${e.ref ?? ""}`;
+            bySource.set(key, [...(bySource.get(key) ?? []), [name, e]]);
+        }
+        for (const [key, entries] of bySource) {
+            const [url, ref] = key.split("#");
+            const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "skills-sync-src-"));
+            log(`cloning ${url}${ref ? "@" + ref : ""} for ${entries.length} skill(s)`);
+            const args = ["clone", "--quiet", "--depth", "1", ...(ref ? ["--branch", ref] : []), url, tmp];
+            const r = spawnSync("git", args, { encoding: "utf8" });
+            if (r.status !== 0) {
+                result.failed.push(`${url}: ${(r.stderr ?? "").trim().split("\n").pop()}`);
+                fs.rmSync(tmp, { recursive: true, force: true });
+                continue;
+            }
+            for (const [name, e] of entries) {
+                const recorded = e.skillPath ? path.join(tmp, path.dirname(e.skillPath)) : null;
+                let src = recorded && isSkillDir(recorded) ? recorded : null;
+                if (!src) {
+                    src = findSkillByName(tmp, name);
+                    if (src)
+                        result.moved.push(`${name}: now at ${path.relative(tmp, src).replace(/\\/g, "/")}`);
+                }
+                if (!src) {
+                    result.missing.push(`${name}: not in ${url} any more (was ${e.skillPath ?? "?"})`);
+                    continue;
+                }
+                fs.mkdirSync(this.agents, { recursive: true });
+                fs.cpSync(src, path.join(this.agents, name), { recursive: true });
+                result.restored.push(name);
+            }
+            fs.rmSync(tmp, { recursive: true, force: true });
+        }
+        return result;
+    }
+}
+function cloneUrl(e) {
+    if (e.sourceType === "github")
+        return `https://github.com/${e.source.replace(/^https?:\/\/github\.com\//, "").replace(/\.git$/, "")}.git`;
+    if (e.sourceType === "git" || e.sourceType === "gitlab")
+        return e.sourceUrl ?? null;
+    return null;
+}
+function findSkillByName(root, name) {
+    const stack = [root];
+    while (stack.length) {
+        const dir = stack.pop();
+        for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (!ent.isDirectory() || ent.name === ".git" || ent.name === "node_modules")
+                continue;
+            const full = path.join(dir, ent.name);
+            if (ent.name === name && isSkillDir(full))
+                return full;
+            stack.push(full);
+        }
+    }
+    return null;
+}
+export const DEFAULT_LIBRARY = "oneezy/skills";
+/** ~/.skills-sync: the library itself, or a link to wherever the library really lives. */
+export function homeLibrary(home = os.homedir()) {
+    return path.join(home, ".skills-sync");
+}
+/**
+ * Where the library is, in this order: --repo, $SKILLS_REPO, ~/.skills-sync (a clone or a link),
+ * a library folder above the current directory. null when none exists yet.
+ */
+export function findLibrary(from, env = process.env, home = os.homedir()) {
+    if (env.SKILLS_REPO && looksLikeLibrary(env.SKILLS_REPO))
+        return path.resolve(env.SKILLS_REPO);
+    const hl = homeLibrary(home);
+    if (looksLikeLibrary(hl))
+        return real(hl);
+    let dir = path.resolve(from);
+    for (;;) {
+        // the walk-up never accepts a dot-folder: ~/.claude has a skills/ subfolder too
+        if (!path.basename(dir).startsWith(".") && looksLikeLibrary(dir))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** Clone `owner/repo` (or a URL) into ~/.skills-sync. */
+export function cloneLibrary(source, home = os.homedir(), log = () => undefined) {
+    const root = homeLibrary(home);
+    const url = /^(https?:|git@|ssh:)/.test(source) ? source : `https://github.com/${source.replace(/\.git$/, "")}.git`;
+    log(`no skills library here yet; cloning ${url} into ${root}`);
+    const r = spawnSync("git", ["clone", "--quiet", url, root], { encoding: "utf8" });
+    if (r.status !== 0)
+        return { ok: false, root, error: (r.stderr ?? "").trim().split("\n").pop() };
+    return { ok: true, root };
+}
+/** Fast-forward the library from its remote, at most once per `minutes`, only when the tree is clean. */
+export function pullLibrary(root, minutes, log) {
+    const stamp = path.join(root, ".git", "skills-sync-pulled");
+    try {
+        const last = fs.statSync(stamp).mtimeMs;
+        if (Date.now() - last < minutes * 60_000)
+            return "throttled";
+    }
+    catch {
+        /* never pulled */
+    }
+    if (!fs.existsSync(path.join(root, ".git")))
+        return "skipped";
+    const status = spawnSync("git", ["-C", root, "status", "--porcelain", "--untracked-files=no"], { encoding: "utf8" });
+    if (status.status !== 0)
+        return "skipped";
+    if (status.stdout.trim())
+        return "dirty";
+    const r = spawnSync("git", ["-C", root, "pull", "--ff-only", "--quiet"], { encoding: "utf8", timeout: 20_000 });
+    try {
+        fs.writeFileSync(stamp, new Date().toISOString());
+    }
+    catch {
+        /* stamp is best-effort */
+    }
+    if (r.status !== 0) {
+        log(`library pull skipped: ${(r.stderr ?? "").trim().split("\n").pop()}`);
+        return "failed";
+    }
+    return "pulled";
+}
+/**
+ * A library has both skills/ and skills-lock.json, and is never a dot-folder: a harness config dir
+ * such as ~/.claude also has a skills/ subfolder, and must never be mistaken for one.
+ */
+export function looksLikeLibrary(dir) {
+    const abs = path.resolve(dir);
+    return isDir(path.join(abs, "skills")) && fs.existsSync(path.join(abs, "skills-lock.json"));
+}
+/** An empty lock, for a library that has no third-party skills yet. */
+export const EMPTY_LOCK = JSON.stringify({ version: 1, skills: {} }, null, 2) + "\n";
+/**
+ * Codex reads policy from agents/openai.yaml next to SKILL.md. Derive it from the Claude frontmatter
+ * of an own skill so one file is the source of truth. Returns the yaml text, or null when nothing to say.
+ */
+export function sidecarFor(skillDir) {
+    const md = fs.readFileSync(path.join(skillDir, "SKILL.md"), "utf8");
+    const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(md);
+    if (!m)
+        return null;
+    let fm;
+    try {
+        fm = YAML.parse(m[1]) ?? {};
+    }
+    catch {
+        return null;
+    }
+    const manual = fm["disable-model-invocation"] === true;
+    const desc = typeof fm.description === "string" ? fm.description : "";
+    const short = desc.length > 80 ? desc.slice(0, 77).trimEnd() + "..." : desc;
+    const doc = {
+        interface: { display_name: String(fm.name ?? path.basename(skillDir)), short_description: short },
+    };
+    if (manual)
+        doc.policy = { allow_implicit_invocation: false };
+    return "# generated by skills-sync from SKILL.md frontmatter; edit SKILL.md, not this file\n" + YAML.stringify(doc);
+}

package/dist/src/plan.js

@@ -0,0 +1,79 @@
+// Every step builds a list of actions first; apply() executes them unless planning.
+import fs from "node:fs";
+import path from "node:path";
+import { copyDir, isLink, lexists, linkTarget, makeLink, removeLink, samePath, under } from "./fs.js";
+export class Report {
+    actions = [];
+    add(a) {
+        this.actions.push(a);
+        return a;
+    }
+    changes() {
+        return this.actions.filter((a) => a.kind !== "skip" && a.kind !== "conflict");
+    }
+    conflicts() {
+        return this.actions.filter((a) => a.kind === "conflict");
+    }
+    skips() {
+        return this.actions.filter((a) => a.kind === "skip").length;
+    }
+    merge(other) {
+        this.actions.push(...other.actions);
+    }
+}
+const MARK = { link: "+", relink: "~", remove: "-", "replace-copy": "~", copy: "+", write: "+", exclude: "+", skip: "=", conflict: "!" };
+export function line(a) {
+    const tail = a.target ? ` -> ${a.target}` : "";
+    const note = a.note ? `  (${a.note})` : "";
+    return `${MARK[a.kind]} ${a.kind.padEnd(12)} ${a.path}${tail}${note}`;
+}
+export function apply(report, plan, exclude) {
+    if (plan)
+        return;
+    for (const a of report.actions) {
+        switch (a.kind) {
+            case "link":
+                makeLink(a.target, a.path);
+                break;
+            case "relink":
+                removeLink(a.path);
+                makeLink(a.target, a.path);
+                break;
+            case "remove":
+                removeLink(a.path);
+                break;
+            case "replace-copy":
+                fs.rmSync(a.path, { recursive: true, force: true });
+                makeLink(a.target, a.path);
+                break;
+            case "copy":
+                copyDir(a.target, a.path);
+                break;
+            case "write":
+                fs.mkdirSync(path.dirname(a.path), { recursive: true });
+                fs.writeFileSync(a.path, a.payload);
+                break;
+            case "exclude":
+                exclude?.(a.path, a.payload);
+                break;
+        }
+    }
+}
+/** Make `link` point at `target`. Never destroys a real folder; only manages links into `managedRoot`. */
+export function ensureLink(report, link, target, managedRoot, what) {
+    if (!lexists(link)) {
+        report.add({ kind: "link", path: link, target });
+        return;
+    }
+    if (isLink(link)) {
+        const current = linkTarget(link);
+        if (current && samePath(current, target))
+            report.add({ kind: "skip", path: link, note: "ok" });
+        else if (current && under(current, managedRoot))
+            report.add({ kind: "relink", path: link, target, note: `was ${current}` });
+        else
+            report.add({ kind: "conflict", path: link, note: `${what}: link points outside the skills library (${current}); left alone` });
+        return;
+    }
+    report.add({ kind: "conflict", path: link, note: `${what}: a real folder is in the way; left alone` });
+}

package/dist/src/steps.js

@@ -0,0 +1,184 @@
+// The steps: layers (inside the library), home (user folders), projects (other repos), unlink, status.
+import fs from "node:fs";
+import path from "node:path";
+import { folderHash, isDir, isLink, isSkillDir, lexists, linkTarget, real, samePath, under } from "./fs.js";
+import { RESERVED } from "./harnesses.js";
+import { sidecarFor } from "./library.js";
+import { ensureLink } from "./plan.js";
+const GITIGNORE_HEADER = "# Generated by skills-sync: links to this library's own skills in skills/<name>. Do not edit.\n";
+/** Inside the library: .agents/skills links for own skills, one project layer per non-universal harness, sidecars. */
+export function layers(lib, harnesses, report, sidecars = true) {
+    const own = lib.ownSkills();
+    for (const n of own)
+        ensureLink(report, path.join(lib.agents, n), path.join(lib.own, n), lib.root, "own skill");
+    if (isDir(lib.agents)) {
+        for (const n of fs.readdirSync(lib.agents)) {
+            const p = path.join(lib.agents, n);
+            if (!isLink(p))
+                continue;
+            const t = linkTarget(p);
+            if (t && under(t, lib.own) && (!own.includes(n) || !isDir(t)))
+                report.add({ kind: "remove", path: p, note: "stale link to a removed own skill" });
+        }
+    }
+    const gi = path.join(lib.agents, ".gitignore");
+    const body = GITIGNORE_HEADER + own.map((n) => `/${n}/\n`).join("");
+    if (!fs.existsSync(gi) || fs.readFileSync(gi, "utf8") !== body)
+        report.add({ kind: "write", path: gi, payload: body, note: `${own.length} entries` });
+    else
+        report.add({ kind: "skip", path: gi, note: "ok" });
+    if (sidecars) {
+        for (const n of own) {
+            const dir = path.join(lib.own, n);
+            const file = path.join(dir, "agents", "openai.yaml");
+            if (fs.existsSync(file)) {
+                report.add({ kind: "skip", path: file, note: "exists" });
+                continue;
+            }
+            const yaml = sidecarFor(dir);
+            if (yaml)
+                report.add({ kind: "write", path: file, payload: yaml, note: "Codex sidecar from SKILL.md frontmatter" });
+        }
+    }
+    const working = lib.workingSet();
+    for (const n of own)
+        if (!working.has(n))
+            working.set(n, path.join(lib.own, n)); // links not applied yet
+    for (const h of harnesses) {
+        if (h.universal)
+            continue;
+        const layer = path.join(lib.root, h.projectSkills);
+        for (const [n, target] of [...working].sort()) {
+            const link = path.join(layer, n);
+            if (lexists(link) && !isLink(link) && isSkillDir(link))
+                report.add({ kind: "replace-copy", path: link, target, note: "stale copy in a generated layer" });
+            else
+                ensureLink(report, link, target, lib.root, `${h.name} layer`);
+        }
+        if (isDir(layer)) {
+            for (const n of fs.readdirSync(layer)) {
+                const p = path.join(layer, n);
+                if (!working.has(n) && isLink(p)) {
+                    const t = linkTarget(p);
+                    if (t && under(t, lib.root))
+                        report.add({ kind: "remove", path: p, note: "no longer in .agents/skills" });
+                }
+            }
+        }
+    }
+}
+/** One link per skill in each harness's user skills folder. */
+export function home(lib, harnesses, report) {
+    const working = lib.workingSet();
+    for (const n of lib.ownSkills())
+        if (!working.has(n))
+            working.set(n, path.join(lib.own, n));
+    for (const h of harnesses) {
+        for (const [n, target] of [...working].sort()) {
+            if (RESERVED.has(n))
+                continue;
+            ensureLink(report, path.join(h.userSkills, n), target, lib.root, `${h.name} user folder`);
+        }
+        if (isDir(h.userSkills)) {
+            for (const n of fs.readdirSync(h.userSkills)) {
+                const p = path.join(h.userSkills, n);
+                if (working.has(n) || !isLink(p))
+                    continue;
+                const t = linkTarget(p);
+                if (t && under(t, lib.root))
+                    report.add({ kind: "remove", path: p, note: "skill no longer in the library" });
+            }
+        }
+    }
+}
+export function unlink(lib, harnesses, report) {
+    for (const h of harnesses) {
+        if (!isDir(h.userSkills))
+            continue;
+        for (const n of fs.readdirSync(h.userSkills)) {
+            const p = path.join(h.userSkills, n);
+            if (!isLink(p))
+                continue;
+            const t = linkTarget(p);
+            if (t && under(t, lib.root))
+                report.add({ kind: "remove", path: p, note: "made by skills-sync" });
+        }
+    }
+}
+/** Git repos directly under `dir`, the library excluded. */
+export function findProjects(dir, lib) {
+    if (!isDir(dir))
+        return [];
+    return fs
+        .readdirSync(dir)
+        .map((n) => path.join(dir, n))
+        .filter((p) => isDir(p) && fs.existsSync(path.join(p, ".git")) && !samePath(real(p), real(lib.root)))
+        .sort();
+}
+export function isRepo(dir) {
+    return fs.existsSync(path.join(dir, ".git"));
+}
+/**
+ * Give a project its skills. Link mode: one link per skill per harness layer, hidden from git through
+ * .git/info/exclude. Copy mode: real folders, meant to be committed.
+ */
+export function projects(lib, harnesses, targets, names, mode, report) {
+    const working = lib.workingSet();
+    for (const n of lib.ownSkills())
+        if (!working.has(n))
+            working.set(n, path.join(lib.own, n));
+    const chosen = [...working].filter(([n]) => !names || names.includes(n)).sort();
+    const layersFor = (h) => h.projectSkills;
+    const seenLayers = new Set();
+    const layerDirs = harnesses.map(layersFor).filter((l) => (seenLayers.has(l) ? false : (seenLayers.add(l), true)));
+    for (const proj of targets) {
+        const excludes = [];
+        for (const layer of layerDirs) {
+            for (const [n, src] of chosen) {
+                const dst = path.join(proj, layer, n);
+                if (mode === "link") {
+                    if (lexists(dst) && !isLink(dst))
+                        report.add({ kind: "conflict", path: dst, note: "a real folder is in the way (a committed copy?); left alone" });
+                    else
+                        ensureLink(report, dst, src, lib.root, "project");
+                    excludes.push("/" + path.join(layer, n).replace(/\\/g, "/") + "/");
+                }
+                else if (isLink(dst))
+                    report.add({ kind: "conflict", path: dst, note: "is a link; a committed copy must be a real folder" });
+                else if (isDir(dst) && folderHash(dst) === folderHash(src))
+                    report.add({ kind: "skip", path: dst, note: "ok" });
+                else
+                    report.add({ kind: "copy", path: dst, target: src });
+            }
+        }
+        if (mode === "link" && excludes.length)
+            report.add({ kind: "exclude", path: proj, payload: excludes, note: `${excludes.length} entries in .git/info/exclude` });
+    }
+}
+export function status(lib, harnesses) {
+    const own = lib.ownSkills();
+    const working = lib.workingSet();
+    const names = [...new Set([...own, ...working.keys()])].sort();
+    const linkedInto = (dir) => {
+        const linked = names.filter((n) => {
+            const p = path.join(dir, n);
+            const t = isLink(p) ? linkTarget(p) : null;
+            return !!t && under(t, lib.root);
+        });
+        return { linked: linked.length, missing: names.filter((n) => !linked.includes(n)) };
+    };
+    const out = {
+        library: lib.root,
+        own,
+        thirdParty: [...working.keys()].filter((n) => !own.includes(n)),
+        missingFromLock: lib.missingFromLock(),
+        layers: {},
+        user: {},
+    };
+    for (const h of harnesses) {
+        if (!h.universal)
+            out.layers[h.projectSkills] = linkedInto(path.join(lib.root, h.projectSkills));
+        out.user[h.userSkills] = linkedInto(h.userSkills);
+    }
+    return out;
+}

package/dist/src/wsl.js

@@ -0,0 +1,32 @@
+// Windows only: list WSL distros and run the same sync inside each one.
+import { spawnSync } from "node:child_process";
+export function wslDistros() {
+    if (process.platform !== "win32")
+        return [];
+    const r = spawnSync("wsl.exe", ["-l", "-q"], { encoding: "utf16le" });
+    if (r.status !== 0 || !r.stdout)
+        return [];
+    return r.stdout
+        .split(/\r?\n/)
+        .map((s) => s.replace(/\0/g, "").trim())
+        .filter((s) => s && !s.startsWith("docker-desktop"));
+}
+/** V:\dev\skills -> /mnt/v/dev/skills */
+export function toWslPath(win) {
+    const m = /^([A-Za-z]):[\\/](.*)$/.exec(win);
+    if (!m)
+        return win.replace(/\\/g, "/");
+    return `/mnt/${m[1].toLowerCase()}/${m[2].replace(/\\/g, "/")}`;
+}
+/**
+ * Run skills-sync inside a distro against the same library through /mnt. Only the user folders
+ * are synced there (projects live on the Windows side). Needs Node in the distro.
+ */
+export function runInWsl(distro, libraryRoot, extraArgs, plan) {
+    const lib = toWslPath(libraryRoot);
+    const bin = process.env.SKILLS_SYNC_WSL_BIN?.trim() || "npx --yes @oneezy/skills-sync";
+    const args = [bin, "--repo", `'${lib}'`, "--global", "--no-projects", "--no-wsl", "--no-layers", "--no-restore", "-y", ...(plan ? ["--plan"] : []), ...extraArgs].join(" ");
+    // -i: node is often only on PATH through the interactive profile (nvm, vite-plus); -l for login vars
+    const r = spawnSync("wsl.exe", ["-d", distro, "--", "bash", "-lic", args], { encoding: "utf8" });
+    return { distro, ok: r.status === 0, output: ((r.stdout ?? "") + (r.stderr ?? "")).trim() };
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@oneezy/skills-sync",
+  "publishConfig": { "access": "public" },
+  "version": "0.2.0",
+  "description": "One skills library, every agent harness, every project on the machine. Restores third-party skills from skills-lock.json, links every skill into Claude Code, Codex, Goose and Hermes, and into the projects you pick.",
+  "license": "MIT",
+  "type": "module",
+  "bin": { "skills-sync": "dist/src/cli.js" },
+  "files": ["dist/src", "README.md"],
+  "repository": { "type": "git", "url": "https://github.com/oneezy/tools.git", "directory": "clis/skills-sync" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.json && node --test \"dist/test/*.test.js\"",
+    "start": "node dist/src/cli.js",
+    "prepublishOnly": "npm run build && node --test \"dist/test/*.test.js\""
+  },
+  "engines": { "node": ">=20" },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  }
+}