@rckflr/llms-skills 0.1.0

package/README.md

@@ -0,0 +1,90 @@
+# @rckflr/llms-skills
+
+One-command publisher CLI for the [llms.txt Skills](https://github.com/MauricioPerera/llms-txt-skills)
+standard. Scaffold a skill, then let the CLI compute the `sha256`, render the
+`## Skills` section into your `llms.txt`, sync `.well-known/agent-skills/index.json`,
+and (optionally) sign — so you never touch the seven artifacts by hand.
+
+It produces artifacts **byte-identical** to the reference Python generator
+(`scripts/generate.py`), enforced by `cli/test.mjs`. What you publish is exactly
+what a runtime — [mcpwasm](https://github.com/MauricioPerera/mcpwasm), the MCP
+server, agents.txt — verifies. **Zero dependencies** (ed25519 and hashing via
+Node's built-in `crypto`).
+
+```bash
+npx @rckflr/llms-skills <command>
+```
+
+## The 2-minute path (L0)
+
+```bash
+npx @rckflr/llms-skills init my-skill     # scaffolds skills/my-skill/SKILL.md + a manifest
+#   …edit the SKILL.md (frontmatter + instructions) and set the manifest summary…
+npx @rckflr/llms-skills publish            # writes ## Skills into llms.txt + index.json
+```
+
+That's it — an agent reading your `llms.txt` now discovers the skill. Everything
+below is optional hardening you climb into when your risk model asks for it (see
+the [adoption ladder](../docs/adoption.md)).
+
+## Commands
+
+| Command | What it does |
+| :--- | :--- |
+| `init <name> [--tool]` | Scaffold `skills/<name>/SKILL.md` (and `tool.js` with `--tool` for an executable skill), and add the entry to `llms-skills.json`. |
+| `publish [--check]` | Read the manifest, hash every `SKILL.md`/`tool.js`, render `## Skills` into `llms.txt`, write `index.json`, and sign if the manifest has a `signing` block. `--check` writes nothing and exits non-zero on drift — the CI guard. |
+| `validate <src> [--strict]` | Validate an `llms.txt` (local path or `https://` URL) and its skills: section shape, `sha256`/`tool_sha256` match, frontmatter, memory line. |
+| `keygen [--out <file>]` | Generate an ed25519 signing keypair. Keep the private key **offline** (never commit it); the public key is embedded in `index.json` on publish. |
+
+## Executable skills (L2)
+
+```bash
+npx @rckflr/llms-skills init fetch-quote --tool   # also scaffolds tool.js
+```
+
+`tool.js` runs verbatim inside a sandbox (QuickJS-wasm in mcpwasm); its only
+bridge out is the host capabilities the runtime injects (`host.fetchOrigin`,
+scoped to your origin). `publish` computes `tool_sha256` and carries `tool` +
+`tool_sha256` in both the inline metadata and `index.json`.
+
+## Signing / attestation (L3)
+
+```bash
+npx @rckflr/llms-skills keygen --out signing.key   # once; keep signing.key offline
+# add to the manifest:  "signing": { "private_key_path": "signing.key" }
+npx @rckflr/llms-skills publish                    # now every skill is ed25519-signed
+```
+
+The signature covers the CRLF-normalized `SKILL.md` bytes; consumers pin the
+public key per origin (TOFU). A server compromise *without* the offline key
+cannot forge valid signatures. For identity-bound, keyless provenance, the
+standard also defines Sigstore attestations (see the
+[Skill Attestations](../docs/ext-skill-attestations.md) extension).
+
+## Manifest (`llms-skills.json`)
+
+`init` creates and maintains it; you rarely edit it by hand beyond the summaries.
+
+```json
+{
+  "section_intro": "Remote Agent Skills published by this domain.",
+  "signing": { "private_key_path": "signing.key" },
+  "published": [
+    { "path": "skills/my-skill/SKILL.md", "url": "/skills/my-skill/SKILL.md", "summary": "what it does" }
+  ]
+}
+```
+
+`section_intro` and `signing` are optional. Your `llms.txt` is the source of
+truth; `index.json` is a **derived** artifact the CLI keeps in sync.
+
+## CI
+
+Run `publish --check` on every push to fail the build if the published artifacts
+drift from the sources:
+
+```yaml
+- run: npx @rckflr/llms-skills publish --check
+```
+
+MIT. Part of the [llms-txt-skills](https://github.com/MauricioPerera/llms-txt-skills) project.

package/bin/llms-skills.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+// llms-skills — one-command publisher CLI for the llms.txt Skills standard.
+//
+//   llms-skills init <name>        scaffold a SKILL.md (+ optional tool.js) and manifest entry
+//   llms-skills publish            regenerate ## Skills in llms.txt + .well-known/index.json (+ sign)
+//   llms-skills validate <src>     validate an llms.txt (local path or URL) and its skills
+//   llms-skills keygen             generate an ed25519 signing keypair (keep the key offline)
+//
+// Produces byte-identical artifacts to scripts/generate.py (enforced by cli/test.mjs),
+// so what you publish is exactly what a runtime (mcpwasm, the MCP server, agents.txt) verifies.
+// Zero external dependencies.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname, relative } from "node:path";
+import {
+  loadSkills, loadMemory, renderSkillsSection, renderSkillsMemoryLine, renderLlmsTxt,
+  renderIndex, loadSigningKey, signSkills, publicKeyRawB64, generateKeyPair, validateLlmsTxt,
+} from "../lib/core.mjs";
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+function flag(name) { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; }
+function has(name) { return args.includes(name); }
+function die(msg) { console.error(msg); process.exit(1); }
+
+const USAGE = `llms-skills — publisher CLI for the llms.txt Skills standard
+
+Usage:
+  llms-skills init <name> [--tool] [--root <dir>]   scaffold SKILL.md (+ tool.js) + manifest entry
+  llms-skills publish [--check] [--manifest <p>] [--root <dir>]   generate llms.txt ## Skills + index.json
+  llms-skills validate <src> [--strict]             validate an llms.txt (path or URL)
+  llms-skills keygen [--out <keyfile>]              generate an ed25519 signing keypair
+
+The minimal case (L0) needs no signing key and no tool.js — just init + publish.
+Add --tool for an executable skill; add a "signing" block to the manifest for L3 attestation.`;
+
+function findManifest(root) {
+  const cands = [flag("--manifest"), "llms-skills.json", "scripts/skills-manifest.json"].filter(Boolean);
+  for (const c of cands) { const p = join(root, c); if (existsSync(p)) return p; }
+  return null;
+}
+
+// ---- init ----
+function cmdInit() {
+  const name = args[1];
+  if (!name || name.startsWith("--")) die("init: needs a skill name, e.g. `llms-skills init my-skill`");
+  const root = flag("--root") || process.cwd();
+  const withTool = has("--tool");
+
+  const skillDir = join(root, "skills", name);
+  const skillPath = join(skillDir, "SKILL.md");
+  if (existsSync(skillPath)) die(`init: ${skillPath} already exists (refusing to overwrite)`);
+  mkdirSync(skillDir, { recursive: true });
+
+  writeFileSync(skillPath,
+`---
+name: ${name}
+description: <one line — when an agent should reach for this skill>
+version: 0.1.0
+license: MIT
+---
+
+# ${name}
+
+<Concrete instructions the agent follows to use your site/API. Name the exact
+endpoints, parameters, and the shape of a correct call.>
+`, "utf8");
+  console.log(`[WRITE] skills/${name}/SKILL.md`);
+
+  const entry = { path: `skills/${name}/SKILL.md`, url: `/skills/${name}/SKILL.md`, summary: `<what this skill does>` };
+  if (withTool) {
+    const toolPath = join(skillDir, "tool.js");
+    writeFileSync(toolPath,
+`// tool.js — executed verbatim inside a QuickJS-wasm sandbox. Call registerTool once.
+// The only bridge out of the sandbox is the host capabilities the runtime injects
+// (e.g. host.fetchOrigin(path, init) — scoped to your origin).
+registerTool({
+  name: "${name}",
+  description: "<what this tool does>",
+  inputSchema: { type: "object", properties: {}, required: [] },
+  async handler(args, host) {
+    // const res = await host.fetchOrigin("/api/...", { method: "GET" });
+    return { ok: true };
+  },
+});
+`, "utf8");
+    console.log(`[WRITE] skills/${name}/tool.js`);
+    entry.tool = `skills/${name}/tool.js`;
+    entry.tool_url = `/skills/${name}/tool.js`;
+  }
+
+  const manifestPath = join(root, "llms-skills.json");
+  let manifest = existsSync(manifestPath)
+    ? JSON.parse(readFileSync(manifestPath, "utf8"))
+    : { section_intro: "Remote Agent Skills published by this domain.", published: [] };
+  if (!manifest.published) manifest.published = [];
+  if (manifest.published.some((e) => e.path === entry.path)) {
+    console.log(`[skip] manifest already lists ${entry.path}`);
+  } else {
+    manifest.published.push(entry);
+    writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+    console.log(`[WRITE] llms-skills.json (added ${name})`);
+  }
+  console.log(`\nNext: fill in the SKILL.md${withTool ? " and tool.js" : ""}, then run  llms-skills publish`);
+}
+
+// ---- publish ----
+function cmdPublish() {
+  const root = flag("--root") || process.cwd();
+  const manifestPath = findManifest(root);
+  if (!manifestPath) die("publish: no manifest found (looked for llms-skills.json / scripts/skills-manifest.json). Run `llms-skills init` first.");
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+
+  const skills = loadSkills(manifest, root);
+  const memory = loadMemory(manifest, root);
+  const section = renderSkillsSection(manifest, skills);
+  const memoryLine = renderSkillsMemoryLine(memory);
+
+  const llmsTxtPath = join(root, "llms.txt");
+  const currentLlms = existsSync(llmsTxtPath) ? readFileSync(llmsTxtPath, "utf8") : "# " + (manifest.title || "My site") + "\n";
+  const newLlms = renderLlmsTxt(currentLlms, section, memoryLine);
+
+  const privateKey = loadSigningKey(manifest, root);
+  let signingKeyB64 = null;
+  if (privateKey) { signSkills(skills, privateKey); signingKeyB64 = publicKeyRawB64(privateKey); }
+  const newIndex = renderIndex(skills, signingKeyB64);
+
+  const indexPath = join(root, ".well-known", "agent-skills", "index.json");
+  const pubKeyPath = join(root, ".well-known", "agent-skills", "signing-key.pub");
+  const targets = [[llmsTxtPath, newLlms], [indexPath, newIndex]];
+  if (signingKeyB64) targets.push([pubKeyPath, signingKeyB64 + "\n"]);
+
+  const check = has("--check");
+  const rel = (p) => (relative(root, p) || p).replaceAll("\\", "/");
+  // Newline-insensitive comparison (matches generate.py, which reads via Python's
+  // universal-newline mode): the generated content is LF; a file checked out with
+  // CRLF (git autocrlf on Windows) is not real drift.
+  const norm = (s) => s.replaceAll("\r\n", "\n");
+  const drift = targets.filter(([p, c]) => (existsSync(p) ? norm(readFileSync(p, "utf8")) : null) !== norm(c));
+  if (check) {
+    if (drift.length) {
+      console.error("[DRIFT] Out-of-date files. Run: llms-skills publish");
+      for (const [p] of drift) console.error(`  - ${rel(p)}`);
+      process.exit(1);
+    }
+    console.log("[OK] Everything in sync.");
+    return;
+  }
+  for (const [p, c] of targets) {
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, c, "utf8");
+    console.log(`[WRITE] ${rel(p)}`);
+  }
+  console.log(`\n${skills.length} skill(s) published${signingKeyB64 ? " (signed)" : ""}.`);
+}
+
+// ---- validate ----
+async function cmdValidate() {
+  const src = args[1];
+  if (!src || src.startsWith("--")) die("validate: needs a path or URL to an llms.txt");
+  let text;
+  if (/^https?:\/\//.test(src)) {
+    const res = await fetch(src);
+    if (!res.ok) die(`validate: fetch failed: ${res.status} ${res.statusText}`);
+    text = await res.text();
+  } else {
+    if (!existsSync(src)) die(`validate: file not found: ${src}`);
+    text = readFileSync(src, "utf8");
+  }
+  const { errors, warnings } = validateLlmsTxt(src, text);
+  for (const e of errors) { console.log(`[ERROR] ${e.message}`); if (e.line) console.log(`  line: ${e.line}`); }
+  for (const w of warnings) { console.log(`[WARNING] ${w.message}`); if (w.line) console.log(`  line: ${w.line}`); }
+  if (!errors.length && !warnings.length) console.log("[OK] Valid. No errors or warnings.");
+  else if (!errors.length) console.log(`[OK] Valid with ${warnings.length} warning(s).`);
+  else console.log(`[FAIL] ${errors.length} error(s), ${warnings.length} warning(s).`);
+  if (errors.length || (has("--strict") && warnings.length)) process.exit(1);
+}
+
+// ---- keygen ----
+function cmdKeygen() {
+  const out = flag("--out") || "llms-skills-signing.key";
+  if (existsSync(out)) die(`keygen: ${out} already exists (refusing to overwrite)`);
+  const { privatePem, publicB64 } = generateKeyPair();
+  writeFileSync(out, privatePem, { encoding: "utf8", mode: 0o600 });
+  console.log(`[WRITE] ${out}  (ed25519 private key — keep it OFFLINE, never commit it)`);
+  console.log(`public key (base64): ${publicB64}`);
+  console.log(`\nTo sign on publish, add to your manifest:\n  "signing": { "private_key_path": "${out}" }\nand keep ${out} out of git (.gitignore).`);
+}
+
+// ---- dispatch ----
+(async () => {
+  try {
+    switch (cmd) {
+      case "init": cmdInit(); break;
+      case "publish": cmdPublish(); break;
+      case "validate": await cmdValidate(); break;
+      case "keygen": cmdKeygen(); break;
+      case "-h": case "--help": case "help": case undefined: console.log(USAGE); break;
+      default: die(`Unknown command: ${cmd}\n\n${USAGE}`);
+    }
+  } catch (e) {
+    die(`Error: ${e.message}`);
+  }
+})();

package/lib/core.mjs

@@ -0,0 +1,282 @@
+// core.mjs — pure functions behind the llms-skills CLI.
+//
+// These reproduce, byte-for-byte, what scripts/generate.py and scripts/validate.py
+// produce, so a publisher can generate/verify the exact artifacts a runtime (mcpwasm,
+// the MCP server, agents.txt) already consumes — without cloning this repo or having
+// Python. The byte-identity is enforced by cli/test.mjs against the Python output.
+//
+// No external dependencies: ed25519 via node:crypto, hashing via node:crypto.
+
+import { createHash, createPrivateKey, createPublicKey, sign as cryptoSign, generateKeyPairSync } from "node:crypto";
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname, resolve as pathResolve } from "node:path";
+
+// ---- hashing (CRLF normalized to LF, identical to generate.py/validate.py) ----
+export function sha256NormalizedBuf(buf) {
+  // latin1 is a 1:1 byte<->char map, so this CRLF->LF replace is byte-exact.
+  const normalized = Buffer.from(buf.toString("latin1").replaceAll("\r\n", "\n"), "latin1");
+  return createHash("sha256").update(normalized).digest("hex");
+}
+export function sha256NormalizedFile(path) {
+  return sha256NormalizedBuf(readFileSync(path));
+}
+
+// ---- YAML frontmatter (flat key: value, same subset generate.py handles) ----
+export function parseFrontmatter(text) {
+  if (!text.startsWith("---")) return {};
+  const parts = text.split("---");
+  if (parts.length < 3) return {};
+  const body = parts[1].trim();
+  const result = {};
+  for (const line of body.split(/\r?\n/)) {
+    const m = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*)\s*:\s*(.*)$/);
+    if (m) result[m[1]] = m[2].trim().replace(/^"|"$/g, "");
+  }
+  return result;
+}
+
+const REQUIRED_FRONTMATTER = ["name", "description", "version", "license"];
+
+// ---- load skills from a manifest (mirrors generate.py load_skills) ----
+export function loadSkills(manifest, repoRoot) {
+  const skills = [];
+  for (const entry of manifest.published) {
+    const path = join(repoRoot, entry.path);
+    if (!existsSync(path)) throw new Error(`SKILL.md not found: ${entry.path}`);
+    const fm = parseFrontmatter(readFileSync(path, "utf8"));
+    for (const key of REQUIRED_FRONTMATTER) {
+      if (!(key in fm)) throw new Error(`${entry.path}: frontmatter missing '${key}'`);
+    }
+    let toolUrl = null, toolSha256 = null;
+    if (entry.tool) {
+      if (!entry.tool_url) throw new Error(`${entry.path}: declares 'tool' without 'tool_url' (both required together)`);
+      const toolPath = join(repoRoot, entry.tool);
+      if (!existsSync(toolPath)) throw new Error(`tool.js not found: ${entry.tool}`);
+      toolUrl = entry.tool_url;
+      toolSha256 = sha256NormalizedFile(toolPath);
+    }
+    skills.push({
+      name: fm.name, description: fm.description, version: fm.version, license: fm.license,
+      homepage: fm.homepage || null, url: entry.url, summary: entry.summary,
+      sha256: sha256NormalizedFile(path), path, toolUrl, toolSha256,
+    });
+  }
+  return skills;
+}
+
+export function loadMemory(manifest, repoRoot) {
+  const memory = manifest.memory;
+  if (!memory) return null;
+  for (const key of ["snapshot_path", "snapshot_url", "format"]) {
+    if (!memory[key]) throw new Error(`manifest.memory needs '${key}'`);
+  }
+  const snapshotPath = join(repoRoot, memory.snapshot_path);
+  if (!existsSync(snapshotPath)) throw new Error(`snapshot not found: ${memory.snapshot_path}`);
+  return { snapshot_url: memory.snapshot_url, format: memory.format, snapshot_sha256: sha256NormalizedFile(snapshotPath) };
+}
+
+// ---- render: ## Skills section (compact JSON, exact key order of generate.py) ----
+export function renderSkillsSection(manifest, skills) {
+  const lines = ["## Skills", "", manifest.section_intro, ""];
+  for (const s of skills) {
+    const meta = { version: s.version, license: s.license, sha256: s.sha256 };
+    if (s.toolUrl && s.toolSha256) { meta.tool = s.toolUrl; meta.tool_sha256 = s.toolSha256; }
+    lines.push(`- [${s.name}](${s.url}): ${s.summary} <!-- skill: ${JSON.stringify(meta)} -->`);
+  }
+  return lines.join("\n") + "\n";
+}
+
+export function renderSkillsMemoryLine(memory) {
+  if (!memory) return "";
+  const meta = { snapshot: memory.snapshot_url, snapshot_sha256: memory.snapshot_sha256, format: memory.format };
+  return `<!-- skills-memory: ${JSON.stringify(meta)} -->\n\n`;
+}
+
+const MEMORY_LINE_RE = /^<!--\s*skills-memory:\s*\{.*?\}\s*-->\s*$/;
+
+export function renderLlmsTxt(current, section, memoryLine = "") {
+  const out = [];
+  for (const line of current.split(/\r?\n/)) {
+    if (/^##\s+skills\s*$/i.test(line.trim())) break;
+    if (MEMORY_LINE_RE.test(line.trim())) continue;
+    out.push(line);
+  }
+  while (out.length && out[out.length - 1].trim() === "") out.pop();
+  return out.join("\n") + "\n\n" + memoryLine + section;
+}
+
+// ---- ed25519 (matches generate.py's raw-32-byte + PKCS8 handling) ----
+const PKCS8_ED25519_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+
+export function privateKeyFromSeed(seed32) {
+  const der = Buffer.concat([PKCS8_ED25519_PREFIX, seed32]);
+  return createPrivateKey({ key: der, format: "der", type: "pkcs8" });
+}
+export function deriveDemoKey(seedStr) {
+  return privateKeyFromSeed(createHash("sha256").update(seedStr, "utf8").digest());
+}
+export function privateKeyFromPem(pem) {
+  return createPrivateKey({ key: pem, format: "pem" });
+}
+export function publicKeyRawB64(privateKey) {
+  const spki = createPublicKey(privateKey).export({ type: "spki", format: "der" });
+  return spki.subarray(spki.length - 32).toString("base64"); // last 32 bytes = raw ed25519 pubkey
+}
+export function signB64(privateKey, msgBuf) {
+  return cryptoSign(null, msgBuf, privateKey).toString("base64");
+}
+export function generateKeyPair() {
+  const { privateKey } = generateKeyPairSync("ed25519");
+  return {
+    privatePem: privateKey.export({ type: "pkcs8", format: "pem" }),
+    publicB64: publicKeyRawB64(privateKey),
+  };
+}
+
+// signing config: {private_key_path} (real, offline) or {demo_seed} (reproducible demo)
+export function loadSigningKey(manifest, repoRoot) {
+  const signing = manifest.signing;
+  if (!signing) return null;
+  if (signing.private_key_path) return privateKeyFromPem(readFileSync(join(repoRoot, signing.private_key_path)));
+  if (signing.demo_seed) return deriveDemoKey(signing.demo_seed);
+  throw new Error("manifest.signing needs 'private_key_path' or 'demo_seed'");
+}
+
+export function signSkills(skills, privateKey) {
+  for (const s of skills) {
+    const normalized = Buffer.from(readFileSync(s.path).toString("latin1").replaceAll("\r\n", "\n"), "latin1");
+    s.signature = signB64(privateKey, normalized);
+  }
+}
+
+// ---- render: .well-known/agent-skills/index.json (superset of agentskills.io 0.2.0) ----
+const AGENTSKILLS_DISCOVERY_SCHEMA = "https://schemas.agentskills.io/discovery/0.2.0/schema.json";
+
+export function renderIndex(skills, signingKeyB64) {
+  const items = skills.map((s) => {
+    const item = { name: s.name, type: "skill-md", description: s.description, url: s.url, digest: `sha256:${s.sha256}` };
+    item.version = s.version;
+    item.license = s.license;
+    if (s.homepage) item.homepage = s.homepage;
+    item.sha256 = s.sha256;
+    if (s.toolUrl && s.toolSha256) { item.tool = s.toolUrl; item.tool_sha256 = s.toolSha256; }
+    if (s.signature) item.signature = s.signature;
+    return item;
+  });
+  const doc = { $schema: AGENTSKILLS_DISCOVERY_SCHEMA };
+  if (signingKeyB64) { doc.signing_alg = "ed25519"; doc.signing_key = signingKeyB64; }
+  doc.skills = items;
+  return JSON.stringify(doc, null, 2) + "\n";
+}
+
+// ---- validate (port of validate.py validate_llms_txt) ----
+function resolveSkillPath(skillUrl, source) {
+  if (/^https?:\/\//.test(skillUrl)) return skillUrl;
+  if (/^https?:\/\//.test(source)) return new URL(skillUrl, source).href;
+  const baseDir = dirname(source);
+  return pathResolve(baseDir, skillUrl.replace(/^\/+/, ""));
+}
+
+export function validateLlmsTxt(source, text) {
+  const errors = [], warnings = [];
+  const err = (message, line = "") => errors.push({ message, line });
+  const warn = (message, line = "") => warnings.push({ message, line });
+
+  // origin memory line (optional)
+  const memMatch = text.split(/\r?\n/).map((l) => l.trim().match(MEMORY_CAPTURE_RE)).find(Boolean);
+  if (memMatch) validateMemory(memMatch[1], source, err, warn);
+
+  // find ## Skills section
+  const lines = text.split(/\r?\n/);
+  let inSkills = false;
+  const skillLines = [];
+  for (const line of lines) {
+    const t = line.trim();
+    if (/^##\s+skills\s*$/i.test(t)) { inSkills = true; continue; }
+    if (inSkills && /^##\s+/i.test(t)) break;
+    if (inSkills) skillLines.push(line);
+  }
+  if (!inSkills) { err("No ## Skills section found"); return { errors, warnings }; }
+  if (skillLines.every((l) => !l.trim())) warn("## Skills section exists but is empty");
+
+  // group items (lines starting with "- ")
+  const items = [];
+  let cur = null;
+  for (const line of skillLines) {
+    const t = line.trim();
+    if (!t) continue;
+    if (t.startsWith("- ")) { if (cur) items.push(cur); cur = [t]; }
+    else if (cur) cur.push(t);
+  }
+  if (cur) items.push(cur);
+  if (!items.length) warn("No items found in ## Skills");
+
+  for (const itemLines of items) {
+    const raw = itemLines.join(" ");
+    const m = raw.match(/^-\s*\[([^\]]+)\]\s*\(([^)]+)\)\s*:\s*([\s\S]+?)(?:\s*<!--\s*skill:\s*(\{[\s\S]*?\})\s*-->)?$/i);
+    if (!m) { err("Invalid skill entry format", raw.slice(0, 80)); continue; }
+    const url = m[2].trim(), desc = m[3].trim(), metaRaw = m[4];
+    let metaParsed = null;
+    if (metaRaw) {
+      try {
+        metaParsed = JSON.parse(metaRaw);
+        if ("version" in metaParsed && !/^\d+\.\d+\.\d+$/.test(String(metaParsed.version)))
+          warn(`Non-semantic version: ${metaParsed.version}`, raw.slice(0, 80));
+        if ("sha256" in metaParsed && !/^[a-fA-F0-9]{64}$/.test(String(metaParsed.sha256)))
+          err("Invalid SHA-256 (must be 64 hex chars)", raw.slice(0, 80));
+        const hasTool = "tool" in metaParsed, hasToolSha = "tool_sha256" in metaParsed;
+        if (hasTool && !hasToolSha) err("'tool' declared without 'tool_sha256' (both required together)", raw.slice(0, 80));
+        if (hasToolSha && !hasTool) err("'tool_sha256' declared without 'tool' (both required together)", raw.slice(0, 80));
+        if (hasToolSha && !/^[a-fA-F0-9]{64}$/.test(String(metaParsed.tool_sha256)))
+          err("Invalid tool_sha256 (must be 64 hex chars)", raw.slice(0, 80));
+      } catch (e) { err(`Invalid metadata JSON: ${e.message}`, raw.slice(0, 80)); }
+    }
+    const resolved = resolveSkillPath(url, source);
+    if (!/^https?:\/\//.test(resolved)) {
+      if (!existsSync(resolved)) { err(`Skill file not found: ${resolved}`, raw.slice(0, 80)); }
+      else {
+        if (metaParsed && metaParsed.sha256) {
+          const actual = sha256NormalizedFile(resolved);
+          if (actual !== metaParsed.sha256) err(`SHA-256 mismatch: declared ${metaParsed.sha256}, actual ${actual}`, raw.slice(0, 80));
+        }
+        if (metaParsed && metaParsed.tool && metaParsed.tool_sha256) {
+          const toolResolved = resolveSkillPath(metaParsed.tool, source);
+          if (!/^https?:\/\//.test(toolResolved)) {
+            if (!existsSync(toolResolved)) err(`tool.js not found: ${toolResolved}`, raw.slice(0, 80));
+            else {
+              const actual = sha256NormalizedFile(toolResolved);
+              if (actual !== metaParsed.tool_sha256) err(`tool_sha256 mismatch: declared ${metaParsed.tool_sha256}, actual ${actual}`, raw.slice(0, 80));
+            }
+          }
+        }
+        const fm = parseFrontmatter(readFileSync(resolved, "utf8"));
+        if (!Object.keys(fm).length) err("Skill without valid YAML frontmatter");
+        else for (const key of REQUIRED_FRONTMATTER) if (!(key in fm)) err(`Frontmatter missing '${key}'`);
+      }
+    }
+    if (!desc || desc.length < 10) warn("Description too short", raw.slice(0, 80));
+  }
+  return { errors, warnings };
+}
+
+const MEMORY_CAPTURE_RE = /^<!--\s*skills-memory:\s*(.*?)\s*-->\s*$/;
+function validateMemory(memJson, source, err, warn) {
+  let meta;
+  try { meta = JSON.parse(memJson); }
+  catch (e) { err(`skills-memory: invalid JSON: ${e.message}`); return; }
+  let ok = true;
+  for (const key of ["snapshot", "snapshot_sha256", "format"]) {
+    if (typeof meta[key] !== "string") { err(`skills-memory: missing or invalid '${key}' (must be string)`); ok = false; }
+  }
+  if (!ok) return;
+  if (!/^[a-fA-F0-9]{64}$/.test(meta.snapshot_sha256)) err("skills-memory: invalid snapshot_sha256 (must be 64 hex chars)");
+  if (meta.format !== "minimemory-okf-v1") warn(`skills-memory: format '${meta.format}' is not the only one recognized today (minimemory-okf-v1)`);
+  const resolved = resolveSkillPath(meta.snapshot, source);
+  if (!/^https?:\/\//.test(resolved)) {
+    if (!existsSync(resolved)) err(`skills-memory: snapshot not found: ${resolved}`);
+    else if (/^[a-fA-F0-9]{64}$/.test(meta.snapshot_sha256)) {
+      const actual = sha256NormalizedFile(resolved);
+      if (actual !== meta.snapshot_sha256) err(`skills-memory: snapshot_sha256 mismatch: declared ${meta.snapshot_sha256}, actual ${actual}`);
+    }
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@rckflr/llms-skills",
+  "version": "0.1.0",
+  "description": "One-command publisher CLI for the llms.txt Skills standard: scaffold, hash, sign, and sync the ## Skills section + .well-known/agent-skills/index.json. Byte-identical to the reference Python generator; zero dependencies.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Mauricio Perera <mauricio.perera@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MauricioPerera/llms-txt-skills.git",
+    "directory": "cli"
+  },
+  "homepage": "https://mauricioperera.github.io/llms-txt-skills/",
+  "bugs": {
+    "url": "https://github.com/MauricioPerera/llms-txt-skills/issues"
+  },
+  "keywords": ["llms.txt", "agent-skills", "skills", "mcp", "publisher", "cli", "ed25519", "sha256"],
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "llms-skills": "bin/llms-skills.mjs"
+  },
+  "exports": {
+    ".": "./lib/core.mjs"
+  },
+  "files": [
+    "bin/llms-skills.mjs",
+    "lib/core.mjs",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node test.mjs"
+  }
+}