skillshelf 0.1.0

package/src/commands/new.ts

@@ -0,0 +1,163 @@
+// `skl new` — scaffold a new skill directory + SKILL.md into the library.
+//
+//   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.
+
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import type { Ctx } from "../types.ts";
+import { serializeFrontmatter } from "../lib/frontmatter.ts";
+import { ensureDir } from "../lib/fs.ts";
+
+export const meta = {
+  name: "new",
+  summary: "Scaffold a new skill dir + SKILL.md into the library",
+  usage: 'skl new <name> [--domain <d>] [--desc "..."] [--force] [--json]',
+} as const;
+
+interface Args {
+  name: string | null;
+  domain: string | null;
+  desc: string | null;
+  force: boolean;
+  json: boolean;
+}
+
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+function parseArgs(argv: string[]): { args: Args } | { error: string } {
+  const args: Args = { name: null, domain: null, desc: null, force: false, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--domain") {
+      const v = argv[++i];
+      if (!v) return { error: "--domain requires a value" };
+      args.domain = v;
+    } else if (a.startsWith("--domain=")) {
+      args.domain = a.slice("--domain=".length);
+    } else if (a === "--desc" || a === "--description") {
+      const v = argv[++i];
+      if (v === undefined) return { error: "--desc requires a value" };
+      args.desc = v;
+    } else if (a.startsWith("--desc=")) {
+      args.desc = a.slice("--desc=".length);
+    } else if (a.startsWith("--description=")) {
+      args.desc = a.slice("--description=".length);
+    } else if (a === "--force") {
+      args.force = true;
+    } else if (a === "--json") {
+      args.json = true;
+    } else if (a.startsWith("--")) {
+      return { error: `unknown argument: ${a}` };
+    } else if (args.name === null) {
+      args.name = a;
+    } else {
+      return { error: `unexpected argument: ${a}` };
+    }
+  }
+  return { args };
+}
+
+function defaultBody(name: string, desc: string): string {
+  const title = name
+    .split("-")
+    .map((w) => (w ? w[0]!.toUpperCase() + w.slice(1) : w))
+    .join(" ");
+  return [
+    `# ${title}`,
+    "",
+    desc ? desc : "One-line statement of what this skill does and when to use it.",
+    "",
+    "## When to use",
+    "",
+    "- Describe the trigger conditions.",
+    "",
+    "## Steps",
+    "",
+    "1. First step.",
+    "2. Second step.",
+    "",
+  ].join("\n");
+}
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  const parsed = parseArgs(argv);
+  if ("error" in parsed) {
+    ctx.error(`skl new: ${parsed.error}`);
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  const args = parsed.args;
+
+  if (!args.name || args.name.trim() === "") {
+    ctx.error("skl new: a <name> is required");
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  const name = args.name.trim();
+  if (!SLUG_RE.test(name)) {
+    ctx.error(
+      `skl new: invalid skill name "${name}" — use lowercase letters, digits, and hyphens (e.g. my-skill)`,
+    );
+    return 1;
+  }
+  const domain = args.domain?.trim() || null;
+  if (domain && !SLUG_RE.test(domain)) {
+    ctx.error(
+      `skl new: invalid domain "${domain}" — use lowercase letters, digits, and hyphens`,
+    );
+    return 1;
+  }
+  const desc = (args.desc ?? "").trim();
+
+  try {
+    const libraryPath = ctx.config.libraryPath;
+    const skillDir = domain
+      ? join(libraryPath, domain, name)
+      : join(libraryPath, name);
+    const bodyPath = join(skillDir, "SKILL.md");
+
+    if (existsSync(bodyPath) && !args.force) {
+      ctx.error(
+        `skl new: SKILL.md already exists at ${bodyPath} — pass --force to overwrite`,
+      );
+      return 1;
+    }
+
+    await ensureDir(skillDir);
+
+    const frontmatterData: Record<string, unknown> = {
+      name,
+      description: desc || `TODO: describe ${name}.`,
+    };
+    if (domain) {
+      frontmatterData.primaryDomain = domain;
+      frontmatterData.domains = [domain];
+    }
+
+    const content = serializeFrontmatter(frontmatterData, defaultBody(name, desc));
+    await Bun.write(bodyPath, content);
+
+    if (args.json) {
+      ctx.json({
+        ok: true,
+        name,
+        domain,
+        path: skillDir,
+        bodyPath,
+        created: true,
+      });
+    } else {
+      ctx.log(`Created skill "${name}"`);
+      ctx.log(`  dir:  ${skillDir}`);
+      ctx.log(`  file: ${bodyPath}`);
+      ctx.log("Edit SKILL.md, then run `skl infer` to tag it and `skl index` to list it.");
+    }
+    return 0;
+  } catch (e) {
+    ctx.error(`skl new: ${e instanceof Error ? e.message : String(e)}`);
+    return 1;
+  }
+}

package/src/commands/outdated.ts

@@ -0,0 +1,113 @@
+// skl outdated — per locked skill, check the upstream latest commit/ref and
+// mark which installed skills are stale (upstream moved past the installed ref).
+//
+// github channel: `gh api` / `git ls-remote` (via core/fetch).
+// vercel-registry channel: `skills info` (degrades gracefully if absent).
+//
+// Read command: supports --json.
+
+import type { Ctx, LockEntry } from "../types.ts";
+import { readLockfile } from "../core/provenance.ts";
+import { parseStoredSource, latestRef } from "../core/fetch.ts";
+
+export const meta = {
+  name: "outdated",
+  summary: "Check upstream ref per tracked skill and mark stale ones",
+  usage: "skl outdated [name] [--json]",
+} as const;
+
+type Status = "stale" | "current" | "unknown";
+
+interface Row {
+  name: string;
+  channel: string;
+  source: string;
+  installedRef: string;
+  latestRef: string | null;
+  status: Status;
+  note: string;
+}
+
+function shortRef(ref: string): string {
+  return /^[0-9a-f]{7,40}$/i.test(ref) ? ref.slice(0, 10) : ref;
+}
+
+async function checkEntry(entry: LockEntry): Promise<Row> {
+  const parsed = parseStoredSource(entry.source);
+  const res = await latestRef(parsed);
+  if (!res.ok) {
+    return {
+      name: entry.name,
+      channel: entry.channel,
+      source: entry.source,
+      installedRef: entry.ref,
+      latestRef: null,
+      status: "unknown",
+      note: res.error,
+    };
+  }
+  const latest = res.ref;
+  const same = latest === entry.ref;
+  return {
+    name: entry.name,
+    channel: entry.channel,
+    source: entry.source,
+    installedRef: entry.ref,
+    latestRef: latest,
+    status: same ? "current" : "stale",
+    note: entry.localEdits ? "has local edits" : "",
+  };
+}
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  const json = argv.includes("--json");
+  const nameArg = argv.find((a) => !a.startsWith("-")) ?? null;
+
+  try {
+    const lock = await readLockfile(ctx.config.libraryPath);
+    let entries = Object.values(lock.entries);
+    if (nameArg) entries = entries.filter((e) => e.name === nameArg);
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+    if (entries.length === 0) {
+      if (json) ctx.json({ ok: true, checked: 0, stale: 0, rows: [] });
+      else if (nameArg) ctx.log(`no tracked skill named "${nameArg}"`);
+      else ctx.log("no tracked third-party skills (lockfile is empty)");
+      return 0;
+    }
+
+    const rows = await Promise.all(entries.map((e) => checkEntry(e)));
+    const stale = rows.filter((r) => r.status === "stale");
+
+    if (json) {
+      ctx.json({
+        ok: true,
+        checked: rows.length,
+        stale: stale.length,
+        rows,
+      });
+    } else {
+      for (const r of rows) {
+        const mark = r.status === "stale" ? "STALE  " : r.status === "current" ? "current" : "unknown";
+        const refInfo =
+          r.status === "stale"
+            ? `${shortRef(r.installedRef)} -> ${shortRef(r.latestRef ?? "")}`
+            : r.status === "current"
+              ? shortRef(r.installedRef)
+              : `${shortRef(r.installedRef)} (${r.note})`;
+        const extra = r.note && r.status !== "unknown" ? `  [${r.note}]` : "";
+        ctx.log(`${mark}  ${r.name.padEnd(28)} ${r.channel.padEnd(15)} ${refInfo}${extra}`);
+      }
+      ctx.log("");
+      ctx.log(`${rows.length} tracked, ${stale.length} stale.`);
+      if (stale.length > 0) {
+        ctx.log(`run \`skl update [name]\` to re-pull (overlays are preserved).`);
+      }
+    }
+    // Non-zero exit when stale skills exist, so agents/CI can branch on it.
+    return stale.length > 0 ? 2 : 0;
+  } catch (err) {
+    ctx.error("outdated: failed:", err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+}

package/src/commands/search.ts

@@ -0,0 +1,61 @@
+// `skl search <kw>` — fuzzy match over skill name + description (+ domains)
+// across the whole library. Kills "forgot it exists".
+
+import type { Ctx, Skill } from "../types.ts";
+import { searchSkills } from "../core/library.ts";
+
+export const meta = {
+  name: "search",
+  summary: "Fuzzy over name+desc+domains across the library",
+  usage: "skl search <kw...> [--json]",
+} as const;
+
+function oneLine(desc: string, max = 100): string {
+  const flat = desc.replace(/\s+/g, " ").trim();
+  return flat.length <= max ? flat : flat.slice(0, max - 1).trimEnd() + "…";
+}
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  try {
+    const json = argv.includes("--json");
+    const terms = argv.filter((a) => a !== "--json");
+    const query = terms.join(" ").trim();
+
+    if (query === "") {
+      ctx.error("usage: " + meta.usage);
+      return 1;
+    }
+
+    const skills = await ctx.loadLibrary();
+    const matches = searchSkills(skills, query);
+
+    if (json) {
+      ctx.json(
+        matches.map((s: Skill) => ({
+          name: s.name,
+          description: s.description,
+          primaryDomain: s.primaryDomain,
+          domains: s.domains,
+          path: s.path,
+          retired: s.retired,
+        })),
+      );
+      return 0;
+    }
+
+    if (matches.length === 0) {
+      ctx.log(`No skills match "${query}".`);
+      return 0;
+    }
+
+    for (const s of matches) {
+      const tag = s.retired ? " (retired)" : "";
+      const dom = s.domains.length ? ` [${s.domains.join(", ")}]` : "";
+      ctx.log(`${s.name}${dom}${tag} — ${oneLine(s.description)}`);
+    }
+    return 0;
+  } catch (err) {
+    ctx.error(`search failed: ${(err as Error).message}`);
+    return 1;
+  }
+}

package/src/commands/show.ts

@@ -0,0 +1,70 @@
+// `skl show <name>` — print ONLY the SKILL.md instruction layer (the body
+// after frontmatter) and list bundled reference-file paths. Reference file
+// CONTENTS are never printed; the agent Reads them on demand. Manual
+// progressive disclosure: cheap by default, deep on demand.
+
+import type { Ctx, Skill } from "../types.ts";
+import { findByName } from "../core/library.ts";
+import { parseFrontmatter } from "../lib/frontmatter.ts";
+
+export const meta = {
+  name: "show",
+  summary: "Print SKILL.md body; list reference-file paths (not contents)",
+  usage: "skl show <name> [--json]",
+} as const;
+
+async function bodyOf(skill: Skill): Promise<string> {
+  const raw = await Bun.file(skill.bodyPath).text();
+  const { body, hasFrontmatter } = parseFrontmatter(raw);
+  return hasFrontmatter ? body : raw;
+}
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  try {
+    const json = argv.includes("--json");
+    const positional = argv.filter((a) => !a.startsWith("--"));
+    const name = positional[0];
+
+    if (!name) {
+      ctx.error("usage: " + meta.usage);
+      return 1;
+    }
+
+    const skills = await ctx.loadLibrary();
+    const skill = findByName(skills, name);
+    if (!skill) {
+      ctx.error(`No skill named "${name}". Try: skl search ${name}`);
+      return 1;
+    }
+
+    const body = await bodyOf(skill);
+
+    if (json) {
+      ctx.json({
+        name: skill.name,
+        description: skill.description,
+        primaryDomain: skill.primaryDomain,
+        domains: skill.domains,
+        path: skill.path,
+        bodyPath: skill.bodyPath,
+        body,
+        refFiles: skill.refFiles,
+        retired: skill.retired,
+        source: skill.source,
+      });
+      return 0;
+    }
+
+    ctx.log(body.replace(/\n+$/, ""));
+
+    if (skill.refFiles.length) {
+      ctx.log("");
+      ctx.log(`# Reference files (${skill.refFiles.length}) — Read on demand:`);
+      for (const f of skill.refFiles) ctx.log(f);
+    }
+    return 0;
+  } catch (err) {
+    ctx.error(`show failed: ${(err as Error).message}`);
+    return 1;
+  }
+}

package/src/commands/status.ts

@@ -0,0 +1,117 @@
+// `skl status` — which library skills are currently symlinked into the
+// project you're in (./.claude/skills/). Groups the linked skills by the
+// bundles (domain tags) they belong to, so you can see what `skl use` pinned.
+
+import { join } from "node:path";
+import type { Ctx, Skill } from "../types.ts";
+import {
+  pathExists,
+  isSymlink,
+  realpathOrSelf,
+  listDirNames,
+} from "../lib/fs.ts";
+
+export const meta = {
+  name: "status",
+  summary: "Which library skills are linked into ./.claude/skills",
+  usage: "skl status [--json]",
+} as const;
+
+interface LinkedEntry {
+  link: string; // entry name under .claude/skills
+  linkPath: string; // abs path of the symlink
+  target: string; // realpath the symlink resolves to
+  skill: Skill | null; // matching library skill, if the target is one of ours
+}
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  try {
+    const json = argv.includes("--json");
+    const cwd = process.cwd();
+    const skillsDir = join(cwd, ".claude", "skills");
+
+    const skills = await ctx.loadLibrary();
+    // index library skills by their realpath for matching
+    const byReal = new Map<string, Skill>();
+    for (const s of skills) byReal.set(realpathOrSelf(s.path), s);
+
+    const linked: LinkedEntry[] = [];
+    if (pathExists(skillsDir)) {
+      const names = await listDirNames(skillsDir);
+      for (const name of names) {
+        const linkPath = join(skillsDir, name);
+        if (!isSymlink(linkPath)) continue; // only count managed symlinks
+        const target = realpathOrSelf(linkPath);
+        linked.push({
+          link: name,
+          linkPath,
+          target,
+          skill: byReal.get(target) ?? null,
+        });
+      }
+    }
+    linked.sort((a, b) => (a.link < b.link ? -1 : a.link > b.link ? 1 : 0));
+
+    // group resolved skills by bundle (domain tag) for the human summary
+    const bundles = new Map<string, string[]>();
+    for (const e of linked) {
+      if (!e.skill) continue;
+      for (const d of e.skill.domains) {
+        const arr = bundles.get(d);
+        if (arr) arr.push(e.skill.name);
+        else bundles.set(d, [e.skill.name]);
+      }
+    }
+
+    if (json) {
+      ctx.json({
+        projectRoot: cwd,
+        skillsDir,
+        skillsDirExists: pathExists(skillsDir),
+        linkedCount: linked.length,
+        bundles: [...bundles.keys()].sort().map((name) => ({
+          name,
+          skills: bundles.get(name)!.slice().sort(),
+        })),
+        linked: linked.map((e) => ({
+          link: e.link,
+          target: e.target,
+          skill: e.skill ? e.skill.name : null,
+          inLibrary: e.skill != null,
+          domains: e.skill ? e.skill.domains : [],
+        })),
+      });
+      return 0;
+    }
+
+    if (linked.length === 0) {
+      ctx.log(`No skills linked into ${skillsDir}`);
+      return 0;
+    }
+
+    ctx.log(`Linked into ${skillsDir} (${linked.length}):`);
+    for (const e of linked) {
+      if (e.skill) {
+        const dom = e.skill.domains.length
+          ? ` [${e.skill.domains.join(", ")}]`
+          : "";
+        ctx.log(`  ${e.link}${dom} -> ${e.skill.name}`);
+      } else {
+        ctx.log(`  ${e.link} -> ${e.target} (not a library skill)`);
+      }
+    }
+
+    if (bundles.size) {
+      ctx.log("");
+      ctx.log("Bundles present:");
+      for (const name of [...bundles.keys()].sort()) {
+        const members = bundles.get(name)!.slice().sort();
+        ctx.log(`  ${name} (${members.length}): ${members.join(", ")}`);
+      }
+    }
+    return 0;
+  } catch (err) {
+    ctx.error(`status failed: ${(err as Error).message}`);
+    return 1;
+  }
+}