skyl.dev 0.1.2 → 0.2.0

package/dist/{bin.js → skyl.js}

@@ -112,7 +112,7 @@ function list(fm, key) {
   if (Array.isArray(v)) return v;
   throw new SkillFormatError(`\`${key}\` must be a list`);
 }
-function parseSkill(text) {
+function parseSkill(text, references = []) {
   const fm = parseFrontmatter(text);
   const md = body(text);
   const name = requireString(fm, "name");
@@ -152,6 +152,7 @@ ${found}`;
     family: name.slice(0, slash),
     skill: name.slice(slash + 1),
     axis,
+    description: typeof fm["description"] === "string" ? fm["description"] : "",
     version,
     requires: list(fm, "requires"),
     agentSections,
@@ -161,7 +162,8 @@ ${found}`;
     rules: rules(md),
     installable,
     installableWords: installable.split(/\s+/).filter(Boolean).length,
-    raw: text
+    raw: text,
+    references
   };
 }
 
@@ -303,13 +305,24 @@ function directorySource(root, label = "directory") {
       } catch (cause) {
         throw new SourceError(`cannot read ${root}`, String(cause));
       }
+      const referencesIn = async (skillDir) => {
+        const dir = join9(skillDir, "references");
+        const names = await readdir4(dir).catch(() => []);
+        const out3 = [];
+        for (const file of names.filter((f) => f.endsWith(".md")).sort()) {
+          out3.push({ file, body: await readFile9(join9(dir, file), "utf8") });
+        }
+        return out3;
+      };
       for (const family of families) {
         const dir = join9(root, family);
         const entries = (await readdir4(dir, { withFileTypes: true })).filter((e) => e.isDirectory());
         for (const entry of entries) {
-          const file = join9(dir, entry.name, "SKILL.md");
+          const skillDir = join9(dir, entry.name);
+          const file = join9(skillDir, "SKILL.md");
           try {
-            out2.push(parseSkill(await readFile9(file, "utf8")));
+            const text = await readFile9(file, "utf8");
+            out2.push(parseSkill(text, await referencesIn(skillDir)));
           } catch (cause) {
             if (cause.code === "ENOENT") continue;
             throw new SourceError(`cannot parse ${file}`, cause.message);
@@ -326,8 +339,9 @@ function bundleSource(load, label) {
     async load() {
       const bundle = await load();
       return Object.entries(bundle.skills).map(([name, raw]) => {
+        const refs = Object.entries(bundle.references?.[name] ?? {}).sort(([a], [b]) => a.localeCompare(b)).map(([file, body2]) => ({ file, body: body2 }));
         try {
-          return parseSkill(raw);
+          return parseSkill(raw, refs);
         } catch (cause) {
           throw new SourceError(`cannot parse \`${name}\` from ${label}`, cause.message);
         }
@@ -358,28 +372,83 @@ async function firstAvailable(sources2) {
 
 // ../core/src/targets.ts
 var flat = (name) => name.replace("/", "-");
+var quoted = (text) => JSON.stringify(text);
+var takesReferences = (target) => target.fileFor("x/y").includes("/");
 var TARGETS = [
   {
+    // Claude Code finds a skill by reading `name` and `description` out of the
+    // frontmatter. Without them the directory is passed over silently at startup.
     id: "claude",
     dir: ".claude/skills",
-    fileFor: (name) => `${flat(name)}/SKILL.md`
+    fileFor: (name) => `${flat(name)}/SKILL.md`,
+    header: (s) => `---
+name: ${flat(s.name)}
+description: ${quoted(s.description)}
+---
+
+`
   },
   {
+    // Cursor decides when to apply a rule from its own frontmatter, so a skill that
+    // arrives without one is either always on or never on, depending on the version.
+    // The description is what it matches against, which is why this is the description
+    // and not the name: the name says `android/core` and answers no question.
     id: "cursor",
     dir: ".cursor/rules",
     fileFor: (name) => `${flat(name)}.mdc`,
-    // Cursor decides when to apply a rule from its own frontmatter, so a skill that
-    // arrives without one is either always on or never on, depending on the version.
-    header: (name) => `---
-description: ${name}
+    header: (s) => `---
+description: ${quoted(s.description)}
 alwaysApply: false
 ---
 
 `
   },
-  { id: "windsurf", dir: ".windsurf/rules", fileFor: (name) => `${flat(name)}.md` },
-  { id: "continue", dir: ".continue/rules", fileFor: (name) => `${flat(name)}.md` },
-  { id: "agents", dir: ".agents/skills", fileFor: (name) => `${flat(name)}.md` }
+  {
+    // Windsurf reads one `trigger` field, and `model_decision` is the mode that means
+    // "read the description and decide", which is what a skill is for. It also caps a
+    // rule at 6,000 characters and the whole active set at 12,000, and enforces both by
+    // truncating rather than by saying anything.
+    id: "windsurf",
+    dir: ".windsurf/rules",
+    fileFor: (name) => `${flat(name)}.md`,
+    header: (s) => `---
+trigger: model_decision
+description: ${quoted(s.description)}
+---
+
+`,
+    limit: {
+      perFile: 6e3,
+      total: 12e3,
+      says: "Windsurf reads 6,000 characters of a rule and 12,000 across all of them,\nand truncates the rest without saying so."
+    }
+  },
+  {
+    id: "continue",
+    dir: ".continue/rules",
+    fileFor: (name) => `${flat(name)}.md`,
+    header: (s) => `---
+name: ${s.name}
+description: ${quoted(s.description)}
+alwaysApply: false
+---
+
+`
+  },
+  {
+    // The vendor-neutral Agent Skills layout: a directory per skill holding SKILL.md,
+    // with the same two fields Claude Code reads. This was a flat file until the
+    // frontmatter went in, and a flat file has nowhere to put a skill's references.
+    id: "agents",
+    dir: ".agents/skills",
+    fileFor: (name) => `${flat(name)}/SKILL.md`,
+    header: (s) => `---
+name: ${flat(s.name)}
+description: ${quoted(s.description)}
+---
+
+`
+  }
 ];
 var DEFAULT_TARGET = "claude";
 function targetById(id) {
@@ -577,6 +646,19 @@ function lintSkill(text, path) {
       });
     }
   }
+  if (skill.description === "") {
+    found.push({
+      level: "warn",
+      message: "no `description`",
+      detail: "nothing that lists this skill can say what it is for"
+    });
+  } else if (skill.description.length > 300) {
+    found.push({
+      level: "warn",
+      message: `description is ${String(skill.description.length)} characters`,
+      detail: "one line, read in a list next to a dozen others"
+    });
+  }
   const md = body(text);
   const all = sections(md);
   const offset = text.slice(0, text.length - md.length).split("\n").length - 1;
@@ -870,10 +952,24 @@ async function writeLockfile(root, lock) {
   await writeFile(join2(root, LOCKFILE_NAME), formatLockfile(lock), "utf8");
 }
 function renderFor(target, skill) {
-  const header = target.header?.(skill.name, skill.version) ?? "";
-  return `${header}${skill.installable}
+  return `${target.header(skill)}${skill.installable}
 `;
 }
+function referencePathFor(root, target, skill, file) {
+  return join2(dirname2(pathFor(root, target, skill)), "references", file);
+}
+function referencesDropped(target, ordered) {
+  if (takesReferences(target)) return [];
+  return ordered.filter((s) => s.references.length > 0);
+}
+function overLimit(target, ordered) {
+  if (!target.limit) return { over: [], total: 0 };
+  const size = (s) => renderFor(target, s).length;
+  return {
+    over: ordered.filter((s) => size(s) > target.limit.perFile),
+    total: ordered.reduce((n, s) => n + size(s), 0)
+  };
+}
 function pathFor(root, target, skill) {
   return join2(root, target.dir, target.fileFor(skill.name));
 }
@@ -890,11 +986,19 @@ async function install(root, target, ordered, requested, existing) {
     target: target.id,
     skills: { ...existing?.target === target.id ? existing.skills : {} }
   };
+  const carriesReferences = takesReferences(target);
   for (const skill of ordered) {
     const file = pathFor(root, target, skill);
     const text = renderFor(target, skill);
     await mkdir(dirname2(file), { recursive: true });
     await writeFile(file, text, "utf8");
+    if (carriesReferences) {
+      for (const reference of skill.references) {
+        const at = referencePathFor(root, target, skill, reference.file);
+        await mkdir(dirname2(at), { recursive: true });
+        await writeFile(at, reference.body, "utf8");
+      }
+    }
     lock.skills[skill.name] = entryFor(
       skill,
       text,
@@ -930,7 +1034,8 @@ function err(line) {
 `);
 }
 function tokens(words2) {
-  return `~${(Math.round(words2 * 4 / 300) * 100).toLocaleString()} tokens`;
+  const n = Math.round(words2 * 4 / 300) * 100;
+  return `~${(words2 > 0 ? Math.max(n, 100) : 0).toLocaleString()} tokens`;
 }
 async function confirm(question, assumeYes) {
   if (assumeYes) return true;
@@ -965,9 +1070,36 @@ async function add(opts) {
     out(`    ${bold(skill.name.padEnd(22))} ${skill.version.padEnd(8)} ${state.padEnd(18)} ${why}`);
   }
   const words2 = ordered.reduce((n, s) => n + s.installableWords, 0);
+  const files = ordered.reduce((n, s) => n + s.references.length, 0);
+  const alsoRefs = files > 0 && referencesDropped(target, ordered).length === 0 ? dim(`, plus ${files} reference ${files === 1 ? "file" : "files"}`) : "";
   out();
-  out(`  ${ordered.length} skills, ${tokens(words2)} ${dim(`into ${target.dir}`)}`);
+  const count = `${ordered.length} ${ordered.length === 1 ? "skill" : "skills"}`;
+  out(`  ${count}${alsoRefs}, ${tokens(words2)} ${dim(`into ${target.dir}`)}`);
   out();
+  const dropped = referencesDropped(target, ordered);
+  if (dropped.length > 0) {
+    out(`  ${yellow("References stay behind.")} ${dim(`${target.id} keeps one file per skill, so the`)}`);
+    out(`  ${dim("files these rules point at cannot sit beside them:")}`);
+    for (const skill of dropped) {
+      out(`    ${dim(`${skill.name}  ${skill.references.map((r) => r.file).join(", ")}`)}`);
+    }
+    out(`  ${dim("Read them on https://skyl.dev/skills, under References.")}`);
+    out();
+  }
+  const { over, total } = overLimit(target, ordered);
+  if (target.limit && (over.length > 0 || total > target.limit.total)) {
+    out(`  ${yellow("Past what this tool reads.")}`);
+    for (const line of target.limit.says.split("\n")) out(`  ${dim(line)}`);
+    for (const skill of over) {
+      const size = skill.installable.length;
+      out(`    ${dim(`${skill.name.padEnd(22)} ${size.toLocaleString()} characters`)}`);
+    }
+    if (total > target.limit.total) {
+      out(`    ${dim(`all of them together    ${total.toLocaleString()} characters`)}`);
+    }
+    out(`  ${dim("Install fewer of them, or use a tool with no ceiling.")}`);
+    out();
+  }
   if (!await confirm("  Write them?", opts.yes === true)) {
     out(`  ${dim("Nothing written.")}`);
     return 1;
@@ -1778,6 +1910,13 @@ async function lint(opts) {
     err(`${yellow("No SKILL.md found in")} ${targets.join(", ")}`);
     return 1;
   }
+  const written = await Promise.all(files.map((f) => readFile8(f, "utf8")));
+  if (written.length > 0 && written.every((text) => /^---\nname: [^/\n]+\n/.test(text))) {
+    err(`${yellow("That is an install directory, not a registry.")}`);
+    err(dim("  Installed skills carry a flattened name and only the sections an agent is given."));
+    err(dim("  Lint the registry they came from: skyl lint <checkout>/skills"));
+    return 1;
+  }
   let errors = 0;
   let warnings = 0;
   const parsed = [];
@@ -2118,7 +2257,7 @@ async function recordVersions(root, lock, pairs) {
 }
 
 // src/cli.ts
-var VERSION = "0.1.2";
+var VERSION = "0.2.0";
 var HELP = `
   ${bold("skyl")} ${dim("curated agent skills for what your project actually uses")}
 

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "skyl.dev",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Install curated AI agent skills for what your project actually uses",
   "type": "module",
   "license": "MIT",
   "bin": {
-    "skyl": "dist/bin.js"
+    "skyl": "dist/skyl.js"
   },
   "files": [
-    "dist/bin.js",
+    "dist/skyl.js",
     "bundle.json",
     "README.md"
   ],