@supersuit/superskill 0.1.0

package/src/collection.mjs

@@ -0,0 +1,139 @@
+// Checks that only make sense for a SET of skills: how much of a harness's skill-listing
+// budget they use, which entries get cut off, and which pairs overlap enough that an
+// agent could load the wrong one. Plus the plugin line for a packaged set.
+import { readFileSync, existsSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join, relative, sep } from "node:path";
+import { findSkills } from "./doctor.mjs";
+import { loadSkill, listFiles } from "./context.mjs";
+
+/**
+ * Characters of description + when_to_use a harness shows per skill before cutting it off.
+ * Claude Code documents this (code.claude.com/docs/en/skills, read 2026-09-28).
+ */
+export const ENTRY_CAP = 1536;
+/**
+ * Default whole-listing budgets, in characters. Neither vendor publishes this number (checked
+ * 2026-09-28), so it is a conservative default, and --budget overrides it.
+ */
+export const BUDGETS = { "claude-code": 8000, codex: 8000 };
+export const OVERLAP = 0.5;
+
+const STOP = new Set(("a an and are as at be by can do does for from has have how i if in into is it its of on or " +
+  "so that the their them then there these this to use used uses using via was what when where which who will " +
+  "with you your someone asks ask user users wants want skill skills not any all also one more other").split(" "));
+
+/** The text a skill costs in the listing: its description plus when_to_use. */
+export function listingText(data) {
+  const s = (v) => (typeof v === "string" ? v.trim() : "");
+  return [s(data.description), s(data.when_to_use)].filter(Boolean).join(" ");
+}
+
+export function listingEntry(data) {
+  const name = typeof data.name === "string" ? data.name.trim() : "";
+  return `${name}: ${listingText(data)}`;
+}
+
+export function tokens(text) {
+  return new Set(String(text).toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 2 && !STOP.has(t)));
+}
+
+export function jaccard(a, b) {
+  const A = tokens(a), B = tokens(b);
+  if (!A.size || !B.size) return 0;
+  let inter = 0;
+  for (const t of A) if (B.has(t)) inter++;
+  return inter / (A.size + B.size - inter);
+}
+
+/**
+ * collection(paths, {budget, overlap}) -> {skills, total_chars, budgets, truncated, overlaps, plugin}
+ * `listed_chars` is what the harness actually shows (capped per entry); totals use it.
+ */
+export function collection(paths, opts = {}) {
+  const dirs = [];
+  for (const p of paths) dirs.push(...findSkills(p));
+  const seen = new Set();
+  const skills = [];
+  for (const d of dirs) {
+    if (seen.has(d)) continue;
+    seen.add(d);
+    const ctx = loadSkill(d);
+    const name = typeof ctx.data.name === "string" && ctx.data.name ? ctx.data.name : ctx.folderName;
+    const text = listingText(ctx.data);
+    const head = name.length + 2; // "name: "
+    skills.push({ name, path: d, chars: head + text.length, listed_chars: head + Math.min(text.length, ENTRY_CAP), description_chars: text.length, description: typeof ctx.data.description === "string" ? ctx.data.description : "" });
+  }
+  const total = skills.reduce((n, s) => n + s.listed_chars, 0);
+  const limits = opts.budget ? Object.fromEntries(Object.keys(BUDGETS).map((k) => [k, Number(opts.budget)])) : BUDGETS;
+  const budgets = Object.entries(limits).map(([harness, limit]) => ({ harness, limit, used: total, over: Math.max(0, total - limit) }));
+  const truncated = skills.filter((s) => s.description_chars > ENTRY_CAP).map((s) => ({ name: s.name, chars: s.description_chars, cut: s.description_chars - ENTRY_CAP }));
+
+  const threshold = opts.overlap ?? OVERLAP;
+  const overlaps = [];
+  for (let i = 0; i < skills.length; i++) {
+    for (let j = i + 1; j < skills.length; j++) {
+      const a = skills[i], b = skills[j];
+      const score = jaccard(a.description, b.description);
+      if (score >= threshold) {
+        overlaps.push({
+          a: a.name, b: b.name, score: Math.round(score * 100) / 100,
+          suggest: [
+            { skill: a.name, trigger: { query: nearMiss(b), should_trigger: false } },
+            { skill: b.name, trigger: { query: nearMiss(a), should_trigger: false } },
+          ],
+        });
+      }
+    }
+  }
+  overlaps.sort((x, y) => y.score - x.score);
+  const out = { skills: skills.map(({ description, ...s }) => s), total_chars: total, budgets, truncated, overlaps };
+  if (paths.length === 1) {
+    const plugin = pluginReport(paths[0]);
+    if (plugin) out.plugin = plugin;
+  }
+  out.ok = budgets.every((b) => b.over === 0) && truncated.length === 0;
+  return out;
+}
+
+/** A near-miss request built from the other skill's own description. */
+function nearMiss(other) {
+  const first = other.description.split(/(?<=[.!?])\s/)[0].replace(/\.$/, "");
+  return `${first.slice(0, 200)} (this is ${other.name}'s job)`;
+}
+
+/** The plugin line: version, changelog entry for it, helpers copied between skills. */
+export function pluginReport(root) {
+  const manifest = join(root, ".claude-plugin", "plugin.json");
+  if (!existsSync(manifest)) return null;
+  const findings = [];
+  let meta = {};
+  try { meta = JSON.parse(readFileSync(manifest, "utf8")); }
+  catch (e) { findings.push({ rule: "plugin-manifest", severity: "fail", message: `.claude-plugin/plugin.json is not valid JSON: ${e.message}`, fix: "Fix the manifest." }); }
+  const version = typeof meta.version === "string" ? meta.version : null;
+  if (!version) findings.push({ rule: "plugin-version", severity: "fail", message: "plugin.json has no version", fix: "Add a semver version and bump it on every release." });
+  let changelogHas = false;
+  const cl = join(root, "CHANGELOG.md");
+  if (!existsSync(cl)) findings.push({ rule: "plugin-changelog", severity: "fail", message: "no CHANGELOG.md", fix: "Add a CHANGELOG.md with an entry per release." });
+  else if (version) {
+    const esc = version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    changelogHas = new RegExp(`^#+\\s*\\[?v?${esc}\\b`, "m").test(readFileSync(cl, "utf8"));
+    if (!changelogHas) findings.push({ rule: "plugin-changelog", severity: "fail", message: `CHANGELOG.md has no entry for ${version}`, fix: `Add a "## ${version}" entry saying what changed.` });
+  }
+  const byHash = new Map();
+  for (const rel of listFiles(join(root, "skills"))) {
+    if (/(^|\/)SKILL\.md$/.test(rel) || /\.(md|json)$/i.test(rel) || /(^|\/)(evals|goldens)\//.test(rel) || rel.endsWith(".gitkeep")) continue;
+    const abs = join(root, "skills", rel);
+    let buf;
+    try { buf = readFileSync(abs); } catch { continue; }
+    if (!buf.length) continue;
+    const h = createHash("sha256").update(buf).digest("hex");
+    const skillName = rel.split("/")[0];
+    const list = byHash.get(h) || [];
+    list.push({ skill: skillName, file: relative(root, abs).split(sep).join("/") });
+    byHash.set(h, list);
+  }
+  const duplicates = [...byHash.values()].filter((l) => new Set(l.map((x) => x.skill)).size > 1).map((l) => ({ files: l.map((x) => x.file) }));
+  for (const d of duplicates) findings.push({ rule: "plugin-shared-helpers", severity: "warn", message: `same file copied into ${d.files.length} skills: ${d.files.join(", ")}`, fix: "share this helper: keep one copy in a shared scripts/ folder and call it from each skill." });
+  return { name: meta.name || null, version, changelog_has_version: changelogHas, duplicates, findings };
+}

package/src/commands/approve.mjs

@@ -0,0 +1,41 @@
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { parseArgs, clock, UsageError } from "../args.mjs";
+import { skillDir, refuse } from "./common.mjs";
+import { readGoldens } from "../goldens.mjs";
+
+export const help = `superskill approve <skill> <golden-id> [--note "<why it is right>"]
+
+Record that a person checked goldens/<id>/ and signs off on its output. Works only at an
+interactive terminal and asks for your name, so an agent cannot approve its own output.
+Writes goldens/<id>/APPROVAL.json with the SKILL.md hash it was approved against.
+`;
+
+export async function run(argv) {
+  const a = parseArgs(argv);
+  if (a.flags.help) { process.stdout.write(help); return 0; }
+  const dir = skillDir(a._[0], "approve");
+  const id = a._[1];
+  if (!id) throw new UsageError("approve needs a golden id");
+  if (!(process.stdin.isTTY && process.stdout.isTTY)) return refuse("approval needs a person at a terminal. Run this yourself, not through an agent.");
+  const g = readGoldens(dir).find((x) => x.id === id);
+  if (!g) return refuse(`no goldens/${id}/`);
+  if (g.input === null || g.output === null || !g.output.trim()) return refuse(`goldens/${id}/ needs an input file and a non-empty output file before it can be approved`);
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    process.stdout.write(`\n--- goldens/${id}/${g.outputFile} ---\n${g.output.slice(0, 2000)}${g.output.length > 2000 ? "\n[...]" : ""}\n---\n`);
+    const name = (await rl.question("Your name (blank to cancel): ")).trim();
+    if (!name) return refuse("not approved");
+    const note = a.flags.note || (await rl.question("Why is this right? (optional): ")).trim();
+    const sha = createHash("sha256").update(readFileSync(join(dir, "SKILL.md"))).digest("hex");
+    const p = join(dir, "goldens", id, "APPROVAL.json");
+    const existed = existsSync(p);
+    writeFileSync(p, JSON.stringify({ approved_by: name, approved_at: clock(a.flags).toISOString(), skill_sha: sha, note }, null, 2) + "\n");
+    process.stdout.write(`${existed ? "re-approved" : "approved"} goldens/${id}/ by ${name}\n`);
+    return 0;
+  } finally {
+    rl.close();
+  }
+}

package/src/commands/collection.mjs

@@ -0,0 +1,56 @@
+import { parseArgs, UsageError } from "../args.mjs";
+import { collection, ENTRY_CAP } from "../collection.mjs";
+
+export const help = `superskill collection <folder...> [--budget <chars>] [--overlap <0-1>] [--json]
+
+Check a set of skills together:
+  - listing budget: characters of "name: description" the harness loads every turn,
+    against claude-code and codex budgets (8000 each by default, a conservative figure:
+    neither harness publishes one; --budget overrides)
+  - cut-off entries: skills whose description + when_to_use exceeds ${ENTRY_CAP} characters
+    (Claude Code's documented per-skill cap)
+  - overlap: pairs whose descriptions share enough words (--overlap, default 0.5) that an
+    agent could load the wrong one, each with a near-miss trigger to add to the other
+  - plugin line (when the folder has .claude-plugin/plugin.json): version, changelog
+    entry, helpers copied between skills
+
+Exit codes: 0 within budget and nothing cut off, 1 otherwise, 2 usage or IO error.
+`;
+
+export async function run(argv) {
+  const a = parseArgs(argv);
+  if (a.flags.help) { process.stdout.write(help); return 0; }
+  if (!a._.length) throw new UsageError("collection needs a folder");
+  const opts = {};
+  if (a.flags.budget !== undefined) { opts.budget = Number(a.flags.budget); if (!(opts.budget > 0)) throw new UsageError("--budget must be a positive number"); }
+  if (a.flags.overlap !== undefined) { opts.overlap = Number(a.flags.overlap); if (!(opts.overlap > 0 && opts.overlap <= 1)) throw new UsageError("--overlap must be between 0 and 1"); }
+  const r = collection(a._, opts);
+  if (a.flags.json) { process.stdout.write(JSON.stringify(r, null, 2) + "\n"); return r.ok ? 0 : 1; }
+  const L = [];
+  L.push(`${r.skills.length} skills, ${r.total_chars} listing characters`);
+  for (const b of r.budgets) L.push(`  ${b.harness.padEnd(12)} ${b.used} / ${b.limit}${b.over ? `  OVER by ${b.over}` : "  ok"}`);
+  if (r.truncated.length) {
+    L.push(`cut off (description over ${ENTRY_CAP} characters):`);
+    for (const t of r.truncated) L.push(`  ${t.name}: ${t.chars} characters, ${t.cut} not shown`);
+  }
+  const top = [...r.skills].sort((x, y) => y.chars - x.chars).slice(0, 5);
+  L.push("largest entries:");
+  for (const s of top) L.push(`  ${String(s.chars).padStart(5)}  ${s.name}`);
+  if (r.overlaps.length) {
+    L.push(`overlapping descriptions (${r.overlaps.length}):`);
+    for (const o of r.overlaps.slice(0, 25)) {
+      L.push(`  ${o.score.toFixed(2)}  ${o.a} <> ${o.b}`);
+      for (const s of o.suggest) L.push(`        add to ${s.skill}/evals/triggers.json: ${JSON.stringify(s.trigger)}`);
+    }
+    if (r.overlaps.length > 25) L.push(`  ... ${r.overlaps.length - 25} more (--json for all)`);
+  } else L.push("no overlapping descriptions");
+  if (r.plugin) L.push(...pluginLines(r.plugin));
+  process.stdout.write(L.join("\n") + "\n");
+  return r.ok ? 0 : 1;
+}
+
+export function pluginLines(p, superplugin) {
+  const L = [`plugin ${p.name || "(unnamed)"} ${p.version || "(no version)"}${superplugin === undefined ? "" : superplugin ? "  superplugin" : ""}`];
+  for (const f of p.findings) L.push(`  ${f.severity.padEnd(4)}  ${f.rule}: ${f.message}${f.severity === "info" ? "" : `\n        fix: ${f.fix}`}`);
+  return L;
+}

package/src/commands/common.mjs

@@ -0,0 +1,19 @@
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { UsageError } from "../args.mjs";
+
+/** Resolve a skill folder argument or throw a usage error naming what is wrong. */
+export function skillDir(arg, cmd) {
+  if (!arg) throw new UsageError(`${cmd} needs a skill folder`);
+  const dir = resolve(arg);
+  if (!existsSync(join(dir, "SKILL.md"))) throw new UsageError(`no SKILL.md in ${arg}`);
+  return dir;
+}
+
+export const today = (now) => now.toISOString().slice(0, 10);
+
+/** A refusal: the command understood the request and declines it (exit 1). */
+export function refuse(message) {
+  process.stderr.write(`superskill: ${message}\n`);
+  return 1;
+}

package/src/commands/doctor.mjs

@@ -0,0 +1,63 @@
+import { readFileSync } from "node:fs";
+import { parseArgs, clock, UsageError } from "../args.mjs";
+import { doctor, findSkills } from "../doctor.mjs";
+import { formatDoctor } from "../report.mjs";
+import { LEVELS } from "../levels.mjs";
+import { changedFiles, touchedSkills, levelDrops } from "../changed.mjs";
+
+export const help = `superskill doctor <path...> [options]
+
+Score one skill, a folder of skills, or a plugin (skills/*/SKILL.md).
+Levels: skill (spec-valid, hygienic) < tested (evals + triggers) < superskill
+(approved golden, misses fixed with evals, a fresh --run that beats no-skill).
+
+Options:
+  --level <skill|tested|superskill>  target level for the exit code (default skill)
+  --json                             print one JSON document and nothing else
+  --changed                          score only skills a change touched (git): changes
+                                     since --base <ref> plus the working tree
+  --base <ref>                       with --changed, e.g. origin/main in CI
+  --baseline-json <file>             a previous --json; exit 1 if any skill's level dropped
+  --run                              run the evals with and without the skill (costs
+                                     model calls; see "superskill doctor --run --help")
+  --now <iso date>                   evaluate dates as of this moment
+  --help                             this text
+
+Exit codes: 0 every skill meets the target, 1 below target or a level dropped,
+2 usage or IO error.
+`;
+
+export async function run(argv) {
+  const a = parseArgs(argv, ["changed", "run", "yes"]);
+  if (a.flags.run) return (await import("../run/index.mjs")).runCommand(a);
+  if (a.flags.help) { process.stdout.write(help); return 0; }
+  const level = a.flags.level || "skill";
+  if (!LEVELS.includes(level)) throw new UsageError(`--level must be one of ${LEVELS.join(", ")}`);
+  if (!a._.length) throw new UsageError("doctor needs a path");
+  const opts = { level, now: clock(a.flags) };
+  if (a.flags.changed) {
+    const all = a._.flatMap((p) => findSkills(p));
+    const files = a._.flatMap((p) => changedFiles(p, a.flags.base));
+    opts.only = touchedSkills(all, files);
+    if (!opts.only.length) {
+      if (a.flags.json) process.stdout.write(JSON.stringify({ target: level, ok: true, skills: [], drops: [] }, null, 2) + "\n");
+      else process.stdout.write("no changed skills\n");
+      return 0;
+    }
+  }
+  const result = doctor(a._, opts);
+  if (a.flags["baseline-json"]) {
+    let baseline;
+    try { baseline = JSON.parse(readFileSync(a.flags["baseline-json"], "utf8")); }
+    catch (e) { throw new UsageError(`cannot read --baseline-json: ${e.message}`); }
+    result.drops = levelDrops(result, baseline);
+    if (result.drops.length) result.ok = false;
+  }
+  if (a.flags.json) process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  else {
+    let out = formatDoctor(result);
+    for (const d of result.drops || []) out += `REFUSED: ${d.name} dropped from ${d.from} to ${d.to}\n`;
+    process.stdout.write(out);
+  }
+  return result.ok ? 0 : 1;
+}

package/src/commands/fix.mjs

@@ -0,0 +1,29 @@
+import { parseArgs, UsageError } from "../args.mjs";
+import { skillDir, refuse } from "./common.mjs";
+import { readMisses, updateMiss } from "../misses.mjs";
+import { readEvals } from "../evals.mjs";
+import { readGoldens } from "../goldens.mjs";
+
+export const help = `superskill fix <skill> <miss-id> --eval <eval-id> [--commit <sha>]
+
+Close a miss. Refuses unless the named eval exists in evals/evals.json or goldens/, so
+every fix leaves behind a check that would catch the same miss again.
+`;
+
+export async function run(argv) {
+  const a = parseArgs(argv);
+  if (a.flags.help) { process.stdout.write(help); return 0; }
+  const dir = skillDir(a._[0], "fix");
+  const id = (a._[1] || "").toLowerCase();
+  if (!id) throw new UsageError("fix needs a miss id");
+  const evalId = a.flags.eval;
+  if (!evalId || evalId === true) throw new UsageError("fix needs --eval <id>: the regression eval that would catch this miss again");
+  const miss = (readMisses(dir) || []).find((m) => m.id === id);
+  if (!miss) return refuse(`no miss ${id} in MISSES.md`);
+  const ids = new Set(readEvals(dir).cases.map((c) => String(c.id)));
+  for (const g of readGoldens(dir)) ids.add(g.id);
+  if (!ids.has(String(evalId))) return refuse(`eval "${evalId}" is not in evals/evals.json or goldens/. Add the case first, then fix.`);
+  updateMiss(dir, id, { status: "fixed", eval: String(evalId), fix: a.flags.commit || miss.fix || "" });
+  process.stdout.write(`${id} fixed, guarded by eval ${evalId}\n`);
+  return 0;
+}

package/src/commands/import.mjs

@@ -0,0 +1,42 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { parseArgs, clock, UsageError } from "../args.mjs";
+import { skillDir, today } from "./common.mjs";
+import { readMisses, appendMisses, nextMissId } from "../misses.mjs";
+import { ledgerPaths, ledgerMisses } from "../ledger.mjs";
+import { parseSkillFile } from "../frontmatter.mjs";
+
+export const help = `superskill miss import <skill> --freedom-ledger [--ledger <file.jsonl>]
+
+Turn Freedom's automatic run record into misses: every run that needed a correction, a
+rescue or a redirect, or that failed, becomes an open miss. Taste corrections and runs
+already imported are skipped. Reads <skill>/invocations.jsonl and
+~/.freedom/ledger/skills/*/<skill>.jsonl, or the file given with --ledger. Freedom does not
+need to be installed; the ledger is read as plain files.
+`;
+
+export async function run(argv) {
+  const a = parseArgs(argv, ["freedom-ledger"]);
+  if (a.flags.help) { process.stdout.write(help); return 0; }
+  const dir = skillDir(a._[0], "miss import");
+  if (!a.flags["freedom-ledger"]) throw new UsageError("miss import needs a source: --freedom-ledger");
+  const name = parseSkillFile(readFileSync(join(dir, "SKILL.md"), "utf8")).data.name || "";
+  let paths;
+  if (a.flags.ledger) {
+    if (!existsSync(a.flags.ledger)) throw new UsageError(`ledger not found: ${a.flags.ledger}`);
+    paths = [a.flags.ledger];
+  } else paths = ledgerPaths(dir, name);
+  if (!paths.length) { process.stdout.write(`no Freedom ledger found for ${name || dir}; nothing imported\n`); return 0; }
+  const existing = readMisses(dir) || [];
+  const known = new Set(existing.map((m) => (m.source || "").replace(/^freedom-ledger\s+/, "")).filter(Boolean));
+  const fresh = paths.flatMap((p) => ledgerMisses(p, known, name));
+  const all = [...existing];
+  const entries = fresh.map((m) => {
+    const e = { ...m, id: nextMissId(all), date: m.date || today(clock(a.flags)) };
+    all.push(e);
+    return e;
+  });
+  if (entries.length) appendMisses(dir, entries);
+  process.stdout.write(`${entries.length} new miss${entries.length === 1 ? "" : "es"} from ${paths.length} ledger file${paths.length === 1 ? "" : "s"}${entries.length ? `: ${entries.map((e) => e.id).join(", ")}` : ""}\n`);
+  return 0;
+}

package/src/commands/init.mjs

@@ -0,0 +1,74 @@
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseArgs, UsageError } from "../args.mjs";
+import { skillDir } from "./common.mjs";
+import { MISSES_HEADER } from "../misses.mjs";
+import { readSession } from "../session.mjs";
+import { parseSkillFile } from "../frontmatter.mjs";
+
+export const help = `superskill init <skill> [--from-session <transcript>]
+
+Add whatever a skill is missing to climb the levels: evals/evals.json (an example case),
+evals/triggers.json (example should / should-not requests), goldens/, and MISSES.md.
+Never overwrites a file that exists.
+
+--from-session <file>  build the first eval and golden candidate from the session where
+                       the job was done by hand. A Claude Code .jsonl gives the first
+                       request and the final answer; any other file is the request.
+                       The golden waits for a person: run \`superskill approve\`.
+`;
+
+const TRIGGER_EXAMPLE = [
+  { query: "REPLACE: a realistic request that should load this skill", should_trigger: true },
+  { query: "REPLACE: a near-miss that shares words with this skill but needs something else", should_trigger: false },
+];
+
+export async function run(argv) {
+  const a = parseArgs(argv);
+  if (a.flags.help) { process.stdout.write(help); return 0; }
+  const dir = skillDir(a._[0], "init");
+  const name = parseSkillFile(readFileSync(join(dir, "SKILL.md"), "utf8")).data.name || "";
+  const session = a.flags["from-session"];
+  if (session !== undefined && (session === true || !existsSync(session))) throw new UsageError(`--from-session file not found: ${session}`);
+  const made = [], kept = [];
+  const put = (rel, content) => {
+    const p = join(dir, rel);
+    if (existsSync(p)) { kept.push(rel); return false; }
+    mkdirSync(join(p, ".."), { recursive: true });
+    writeFileSync(p, content);
+    made.push(rel);
+    return true;
+  };
+
+  let sessionCase = null;
+  if (session) {
+    const { prompt, output } = readSession(session);
+    if (!prompt) throw new UsageError(`no request found in ${session}`);
+    sessionCase = { prompt, output };
+  }
+
+  const evalsPath = join(dir, "evals", "evals.json");
+  const example = { id: 1, prompt: "REPLACE: a real request this skill handles", expected_output: "REPLACE: what a good answer looks like", files: [], expectations: ["REPLACE: a statement a grader can check, or contains:<text> / regex:<pattern>"] };
+  put("evals/evals.json", JSON.stringify({ skill_name: name, evals: sessionCase ? [] : [example] }, null, 2) + "\n");
+  put("evals/triggers.json", JSON.stringify(TRIGGER_EXAMPLE, null, 2) + "\n");
+  put("goldens/.gitkeep", "");
+  put("MISSES.md", MISSES_HEADER);
+
+  if (sessionCase) {
+    const doc = JSON.parse(readFileSync(evalsPath, "utf8"));
+    const list = Array.isArray(doc) ? doc : (doc.evals ||= []);
+    const taken = new Set(list.map((c) => String(c.id)));
+    let n = 1;
+    while (taken.has(`s${n}`) || existsSync(join(dir, "goldens", `s${n}`))) n++;
+    const id = `s${n}`;
+    list.push({ id, prompt: sessionCase.prompt, expected_output: "Matches the approved output in goldens/" + id + "/", files: [], expectations: ["Output addresses the request in the prompt"] });
+    writeFileSync(evalsPath, JSON.stringify(doc, null, 2) + "\n");
+    put(`goldens/${id}/input.md`, sessionCase.prompt + "\n");
+    put(`goldens/${id}/output.md`, sessionCase.output ? sessionCase.output + "\n" : "");
+    process.stdout.write(`eval ${id} and golden candidate goldens/${id}/ written from ${session}\n`);
+    process.stdout.write(`a person approves it with: superskill approve ${a._[0]} ${id}\n`);
+  }
+  for (const m of made) process.stdout.write(`created ${m}\n`);
+  for (const k of kept) process.stdout.write(`kept    ${k} (exists)\n`);
+  return 0;
+}

package/src/commands/miss.mjs

@@ -0,0 +1,24 @@
+import { parseArgs, clock, UsageError } from "../args.mjs";
+import { skillDir, today } from "./common.mjs";
+import { readMisses, appendMisses, nextMissId } from "../misses.mjs";
+
+export const help = `superskill miss <skill> "<what happened>" [--expected "<what should have>"]
+superskill miss import <skill> --freedom-ledger [--ledger <file>]
+
+Log a time the skill got something wrong. The entry opens today; an open miss older than
+14 days blocks the superskill level. Close it with \`superskill fix\`.
+`;
+
+export async function run(argv) {
+  if (argv[0] === "import") return (await import("./import.mjs")).run(argv.slice(1));
+  const a = parseArgs(argv);
+  if (a.flags.help) { process.stdout.write(help); return 0; }
+  const dir = skillDir(a._[0], "miss");
+  const what = (a._[1] || "").trim();
+  if (!what) throw new UsageError('miss needs a description: superskill miss <skill> "<what happened>"');
+  const misses = readMisses(dir) || [];
+  const id = nextMissId(misses);
+  appendMisses(dir, [{ id, date: today(clock(a.flags)), status: "open", what, expected: a.flags.expected || "" }]);
+  process.stdout.write(`${id} logged (open). Close it with: superskill fix ${a._[0]} ${id} --eval <id>\n`);
+  return 0;
+}

package/src/commands/snippet.mjs

@@ -0,0 +1,14 @@
+import { readFileSync } from "node:fs";
+
+export const help = `superskill snippet
+
+Print a block to paste into AGENTS.md or CLAUDE.md so any agent proposes a skill after doing
+a job once, logs a miss whenever a skill needed correcting, and runs the doctor before
+calling a skill done.
+`;
+
+export async function run(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) { process.stdout.write(help); return 0; }
+  process.stdout.write(readFileSync(new URL("../snippet.md", import.meta.url), "utf8"));
+  return 0;
+}

package/src/context.mjs

@@ -0,0 +1,60 @@
+import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { join, basename, resolve, relative, sep } from "node:path";
+import { parseSkillFile } from "./frontmatter.mjs";
+
+const SKIP_DIRS = new Set([".git", "node_modules", "__pycache__", ".venv", "venv", "dist", "build"]);
+const MAX_FILES = 2000;
+
+/** Every file under dir, relative, forward slashes. Follows symlinked dirs once, never loops. */
+export function listFiles(dir) {
+  const out = [];
+  const seen = new Set();
+  const walk = (abs) => {
+    let real;
+    try { real = resolve(abs); } catch { return; }
+    if (seen.has(real)) return;
+    seen.add(real);
+    let entries;
+    try { entries = readdirSync(abs, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (out.length >= MAX_FILES) return;
+      const p = join(abs, e.name);
+      let isDir = e.isDirectory();
+      let isFile = e.isFile();
+      if (e.isSymbolicLink()) {
+        try { const s = statSync(p); isDir = s.isDirectory(); isFile = s.isFile(); } catch { continue; }
+      }
+      if (isDir) { if (!SKIP_DIRS.has(e.name)) walk(p); }
+      else if (isFile) out.push(relative(dir, p).split(sep).join("/"));
+    }
+  };
+  walk(dir);
+  return out.sort();
+}
+
+export function readText(dir, rel) {
+  try { return readFileSync(join(dir, rel), "utf8"); } catch { return null; }
+}
+
+/**
+ * Load one skill folder into the context every rule reads.
+ * Never throws: an unreadable skill comes back with `error` set.
+ */
+export function loadSkill(dir) {
+  const abs = resolve(dir);
+  const ctx = { dir: abs, folderName: basename(abs), data: {}, body: "", bodyStartLine: 1, raw: "", files: [] };
+  const skillPath = join(abs, "SKILL.md");
+  if (!existsSync(skillPath)) return { ...ctx, error: "no SKILL.md in this folder" };
+  try {
+    ctx.raw = readFileSync(skillPath, "utf8");
+  } catch (e) {
+    return { ...ctx, error: `cannot read SKILL.md: ${e.code || e.message}` };
+  }
+  const parsed = parseSkillFile(ctx.raw);
+  ctx.data = parsed.data;
+  ctx.body = parsed.body;
+  ctx.bodyStartLine = parsed.bodyStartLine;
+  if (parsed.error) ctx.parseError = parsed.error;
+  ctx.files = listFiles(abs);
+  return ctx;
+}

package/src/doctor.mjs

@@ -0,0 +1,65 @@
+import { existsSync, statSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { loadSkill } from "./context.mjs";
+import { allRules } from "./rules/index.mjs";
+import { runRules, computeLevel, nextLevel, meets } from "./levels.mjs";
+import { pluginReport } from "./collection.mjs";
+
+export class DoctorError extends Error {}
+
+const isDir = (p) => { try { return statSync(p).isDirectory(); } catch { return false; } };
+const hasSkill = (p) => existsSync(join(p, "SKILL.md"));
+
+/**
+ * Resolve a path to skill folders: the path itself if it holds SKILL.md, otherwise every
+ * direct child that does, plus skills/<name>/ for a plugin root.
+ */
+export function findSkills(path) {
+  const abs = resolve(path);
+  if (!existsSync(abs)) throw new DoctorError(`path not found: ${path}`);
+  if (!isDir(abs)) throw new DoctorError(`not a folder: ${path}`);
+  if (hasSkill(abs)) return [abs];
+  const out = [];
+  const scan = (dir) => {
+    let names = [];
+    try { names = readdirSync(dir).sort(); } catch { return; }
+    for (const n of names) {
+      if (n.startsWith(".")) continue;
+      const p = join(dir, n);
+      if (isDir(p) && hasSkill(p)) out.push(p);
+    }
+  };
+  scan(abs);
+  if (isDir(join(abs, "skills"))) scan(join(abs, "skills"));
+  return out;
+}
+
+/** Score one loaded skill. */
+export function scoreSkill(dir, opts = {}) {
+  const ctx = loadSkill(dir);
+  const findings = runRules(ctx, opts.rules || allRules, opts);
+  const level = computeLevel(findings);
+  const up = nextLevel(level);
+  const next = up ? findings.filter((f) => f.level === up && f.severity === "fail") : [];
+  return { path: ctx.dir, name: typeof ctx.data.name === "string" && ctx.data.name ? ctx.data.name : ctx.folderName, level, next, findings };
+}
+
+/**
+ * doctor(paths, {level, now}) -> {skills, ok, target}
+ * `ok` is true when every skill reaches the target level (default "skill").
+ */
+export function doctor(paths, opts = {}) {
+  const target = opts.level || "skill";
+  let dirs = [];
+  for (const p of paths) dirs.push(...findSkills(p));
+  if (opts.only) dirs = dirs.filter((d) => opts.only.includes(d));
+  else if (!dirs.length) throw new DoctorError(`no skills found under ${paths.join(", ")} (looked for SKILL.md in the folder, its children, and skills/*/)`);
+  const skills = [...new Set(dirs)].map((d) => scoreSkill(d, opts));
+  const result = { target, ok: skills.every((s) => meets(s.level, target)), skills };
+  if (paths.length === 1) {
+    const plugin = pluginReport(paths[0]);
+    // A plugin is a superplugin only when every skill in it is a superskill.
+    if (plugin) result.plugin = { ...plugin, superplugin: skills.every((s) => s.level === "superskill") && !plugin.findings.some((f) => f.severity === "fail") };
+  }
+  return result;
+}