@rynx-ai/skills 0.1.0

package/dist/artifact.d.ts

@@ -0,0 +1,41 @@
+import type { SkillRef } from "@rynx-ai/protocol";
+export interface SkillMeta {
+    /** Lowercase kebab-case skill id (the directory / `name:` frontmatter). */
+    name: string;
+    description: string;
+    /** Absolute path to the skill's directory. */
+    dir: string;
+    /** The skill's install identity from its `.rynx-skill.json` v3 receipt —
+     *  the exact `SkillRef` that reproduces this install (agent-editor selection
+     *  copies it verbatim into the spec). Absent when the receipt is missing,
+     *  not schema 3, or fails the dir-name sanity check. */
+    ref?: SkillRef;
+}
+/**
+ * `.rynx-skill.json` v3 — the record of ONE install event. Its payload IS a
+ * {@link SkillRef} (declaration ≡ receipt, literally): the replayable install
+ * recipe plus the content fingerprint observed at commit time. `installedAt`
+ * is observation metadata, not identity. An update is simply a new install
+ * event (the whole file is rewritten).
+ */
+export interface SkillReceipt {
+    schema: 3;
+    ref: SkillRef;
+    installedAt: string;
+}
+/** Receipt file written next to a skill at install time. */
+export declare const SKILL_RECEIPT_FILE = ".rynx-skill.json";
+/** The raw YAML frontmatter block of a `SKILL.md` (between the leading `---`s), or null. */
+export declare function extractSkillFrontmatter(content: string): string | null;
+/** Parse a `SKILL.md` body's leading YAML frontmatter for name + description. */
+export declare function parseSkillFrontmatter(content: string): {
+    name: string;
+    description: string;
+} | null;
+/** Read one skill directory's metadata, or null if it has no valid `SKILL.md`.
+ *  Merges the install identity (`ref`) from a valid v3 receipt if present. */
+export declare function readSkillMeta(skillDir: string): Promise<SkillMeta | null>;
+/** Structural validation of an untrusted `SkillRef` value (receipt payload). */
+export declare function parseSkillRefValue(value: unknown): SkillRef | null;
+/** Scan a skills root for immediate subdirectories that are valid skills. */
+export declare function scanSkillsDir(root: string): Promise<SkillMeta[]>;

package/dist/artifact.js

@@ -0,0 +1,158 @@
+/**
+ * Scan + parse on-disk skills. A skill is a directory with a `SKILL.md` whose
+ * YAML frontmatter declares `name` + `description` (the universal skill format
+ * shared by claude/codex/etc.). Used by the daemon's skill catalog, the
+ * per-session env build, and any runtime skill discovery.
+ *
+ * (The codex runtime keeps its own richer scanner in `runtime/codex-skills.ts`;
+ * this is the minimal, catalog-facing variant.)
+ */
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+/** Receipt file written next to a skill at install time. */
+export const SKILL_RECEIPT_FILE = ".rynx-skill.json";
+/** The raw YAML frontmatter block of a `SKILL.md` (between the leading `---`s), or null. */
+export function extractSkillFrontmatter(content) {
+    const match = content.match(/^---\s*\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/);
+    return match ? match[1].trim() : null;
+}
+/** Parse a `SKILL.md` body's leading YAML frontmatter for name + description. */
+export function parseSkillFrontmatter(content) {
+    const match = content.match(/^---\s*\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/);
+    if (!match)
+        return null;
+    const name = frontmatterScalar(match[1], "name");
+    const description = frontmatterScalar(match[1], "description");
+    if (!name || !description)
+        return null;
+    return { name, description };
+}
+function frontmatterScalar(frontmatter, key) {
+    const match = frontmatter.match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
+    if (!match)
+        return null;
+    const value = match[1].trim();
+    if (!value)
+        return null;
+    if (["|", "|-", ">", ">-"].includes(value)) {
+        return frontmatterBlockScalar(frontmatter, key);
+    }
+    return value.replace(/^["'](.*)["']$/, "$1").trim() || null;
+}
+function frontmatterBlockScalar(frontmatter, key) {
+    const lines = frontmatter.split(/\r?\n/);
+    const start = lines.findIndex((line) => line.match(new RegExp(`^${key}:\\s*[>|]`)));
+    if (start < 0)
+        return null;
+    const body = [];
+    for (const line of lines.slice(start + 1)) {
+        if (/^\S/.test(line))
+            break;
+        if (!line.trim()) {
+            body.push("");
+            continue;
+        }
+        body.push(line.replace(/^\s{2}/, ""));
+    }
+    return body.join(" ").replace(/\s+/g, " ").trim() || null;
+}
+/** Read one skill directory's metadata, or null if it has no valid `SKILL.md`.
+ *  Merges the install identity (`ref`) from a valid v3 receipt if present. */
+export async function readSkillMeta(skillDir) {
+    let content;
+    try {
+        content = await readFile(path.join(skillDir, "SKILL.md"), "utf8");
+    }
+    catch {
+        return null;
+    }
+    const fm = parseSkillFrontmatter(content);
+    if (!fm)
+        return null;
+    const ref = await readReceiptRef(skillDir);
+    return { ...fm, dir: skillDir, ...(ref ? { ref } : {}) };
+}
+/**
+ * Read a skill dir's v3 receipt and return its `ref`, or null. Anything that
+ * isn't a structurally valid v3 receipt — old schema versions included — is
+ * treated as receipt-less (clean break; the owner reinstalls to restore). A
+ * dir-name ≠ `ref.name` mismatch (a hand-renamed dir) is also receipt-less,
+ * loudly: the receipt no longer describes the directory it sits in.
+ */
+async function readReceiptRef(skillDir) {
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(path.join(skillDir, SKILL_RECEIPT_FILE), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    const receipt = raw;
+    if (receipt.schema !== 3)
+        return null;
+    const ref = parseSkillRefValue(receipt.ref);
+    if (!ref)
+        return null;
+    if (ref.name !== path.basename(skillDir)) {
+        console.warn(`[skills] receipt/name mismatch at ${skillDir}: receipt says "${ref.name}" — treating as receipt-less`);
+        return null;
+    }
+    return ref;
+}
+/** Structural validation of an untrusted `SkillRef` value (receipt payload). */
+export function parseSkillRefValue(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const v = value;
+    if (typeof v.name !== "string" || !v.name.trim())
+        return null;
+    const install = v.install;
+    if (typeof install !== "object" || install === null)
+        return null;
+    let recipe;
+    if (install.tool === "skills-cli") {
+        if (typeof install.source !== "string" || !install.source.trim())
+            return null;
+        if (install.skill !== undefined && typeof install.skill !== "string")
+            return null;
+        recipe = {
+            tool: "skills-cli",
+            source: install.source,
+            ...(typeof install.skill === "string" && install.skill ? { skill: install.skill } : {}),
+        };
+    }
+    else if (install.tool === "npx") {
+        if (typeof install.package !== "string" || !install.package.trim())
+            return null;
+        if (typeof install.version !== "string" || !install.version.trim())
+            return null;
+        if (!Array.isArray(install.args) || install.args.some((a) => typeof a !== "string"))
+            return null;
+        recipe = { tool: "npx", package: install.package, version: install.version, args: install.args };
+    }
+    else {
+        return null;
+    }
+    return {
+        name: v.name,
+        install: recipe,
+        ...(typeof v.contentHash === "string" && v.contentHash ? { contentHash: v.contentHash } : {}),
+    };
+}
+/** Scan a skills root for immediate subdirectories that are valid skills. */
+export async function scanSkillsDir(root) {
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return []; // missing root ⇒ empty catalog
+    }
+    const dirs = entries
+        .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+        .map((e) => path.join(root, e.name));
+    const metas = await Promise.all(dirs.map(readSkillMeta));
+    return metas
+        .filter((m) => m !== null)
+        .sort((a, b) => a.name.localeCompare(b.name));
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @rynx-ai/skills — the skill artifact domain.
+ *
+ * Everything about on-disk skills (the universal `SKILL.md` format shared by
+ * claude/codex/etc.) and nothing else: discovering and parsing them, installing
+ * them from replayable recipes, and reading/writing the catalog's
+ * `.rynx-skill.json` install-info files. Depends on `@rynx-ai/protocol` (the type
+ * home for `SkillRef`/`SkillInstallRecipe`) and node built-ins only.
+ *
+ * Consumed by `@rynx-ai/core` (daemon catalog + per-session env build) and
+ * `@rynx-ai/emulator` (its `skill install-rynx` catalog install) — one
+ * implementation on both sides of the package boundary.
+ */
+export * from "./artifact.js";
+export * from "./install.js";

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * @rynx-ai/skills — the skill artifact domain.
+ *
+ * Everything about on-disk skills (the universal `SKILL.md` format shared by
+ * claude/codex/etc.) and nothing else: discovering and parsing them, installing
+ * them from replayable recipes, and reading/writing the catalog's
+ * `.rynx-skill.json` install-info files. Depends on `@rynx-ai/protocol` (the type
+ * home for `SkillRef`/`SkillInstallRecipe`) and node built-ins only.
+ *
+ * Consumed by `@rynx-ai/core` (daemon catalog + per-session env build) and
+ * `@rynx-ai/emulator` (its `skill install-rynx` catalog install) — one
+ * implementation on both sides of the package boundary.
+ */
+export * from "./artifact.js";
+export * from "./install.js";

package/dist/install.d.ts

@@ -0,0 +1,37 @@
+import type { SkillInstallRecipe, SkillRef } from "@rynx-ai/protocol";
+import { type SkillMeta } from "./artifact.js";
+/** One skill an install produced: where it landed + the content hash observed
+ *  during the install (the skills CLI's `computedHash`), when available. */
+export interface InstalledSkill {
+    name: string;
+    dir: string;
+    contentHash?: string;
+}
+/** Runs `npx <args>` with cwd = the temp install dir. Injectable (tests). */
+export type NpxRunner = (args: string[], opts: {
+    cwd: string;
+}) => Promise<void>;
+/** Turn install params into the command line that performs them. Both tools
+ *  produce an `npx` invocation, run with cwd = the temp install dir. */
+export declare function buildInstallCommand(recipe: SkillInstallRecipe): {
+    npxArgs: string[];
+};
+/**
+ * INSTALL ONLY: run `recipe`'s install command in a throwaway temp dir and
+ * move every skill it produced into `targetDir`. Writes no metadata — the
+ * observations come back as the return value. Throws on bad input / failure.
+ */
+export declare function installFromRecipe(recipe: SkillInstallRecipe, targetDir: string, opts?: {
+    runNpx?: NpxRunner;
+}): Promise<InstalledSkill[]>;
+/** Write one skill dir's `.rynx-skill.json` v3 install-info file (catalog
+ *  artifact: the payload IS the SkillRef — declaration ≡ record, literally). */
+export declare function writeSkillInstallInfo(skillDir: string, ref: SkillRef): Promise<void>;
+/**
+ * The CATALOG layer: install per `recipe` AND write each produced skill its
+ * install-info file — `ref` = these exact install params + the observed
+ * content hash. Returns the installed skills' catalog metadata.
+ */
+export declare function installIntoCatalog(recipe: SkillInstallRecipe, catalogRoot: string, opts?: {
+    runNpx?: NpxRunner;
+}): Promise<SkillMeta[]>;

package/dist/install.js

@@ -0,0 +1,204 @@
+/**
+ * Skill installation from replayable recipes.
+ *
+ * Layering (rynx RFC: docs/rfc-skillref-recipe-install.md §4):
+ *
+ *   installFromRecipe(recipe, targetDir)      — INSTALL ONLY: run the recipe's
+ *     command in a throwaway temp dir, move the produced skill folders into
+ *     `targetDir`, and RETURN what was observed (names + content hashes).
+ *     Writes no metadata anywhere.
+ *
+ *   writeSkillInstallInfo(dir, ref)           — write one skill's
+ *     `.rynx-skill.json` v3 install-info file. A CATALOG artifact only: the
+ *     Skills page shows it and the agent editor copies its `ref` into specs —
+ *     session dirs and cache slots never carry it.
+ *
+ *   installIntoCatalog(recipe, catalogRoot)   — the composition: install, then
+ *     write each produced skill an info file recording these exact params +
+ *     the observed hash.
+ *
+ * Every install bottoms out at `npx skills add` (the npx recipe variant is a
+ * self-installing proxy that runs it in its cwd), so both tools share one
+ * pickup path and one hash algorithm; they differ only in the command line.
+ */
+import { execFile } from "node:child_process";
+import { cp, mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { readSkillMeta, SKILL_RECEIPT_FILE } from "./artifact.js";
+const runNpxDefault = async (args, opts) => {
+    await promisify(execFile)("npx", args, { cwd: opts.cwd, timeout: 180_000 }).catch((err) => {
+        throw new Error(`skills install failed: ${cliErrorDetail(err)}`);
+    });
+};
+/** Reject shell metacharacters / control chars early (clearer than a CLI parse
+ *  error; args go through execFile — no shell — so this is belt-and-braces).
+ *  Plain spaces are allowed: a local-directory source is a legal path. */
+function assertSafeArg(label, value) {
+    // eslint-disable-next-line no-control-regex
+    if (/[;&|`$()<>\x00-\x1f]/.test(value))
+        throw new Error(`invalid ${label}: ${value}`);
+}
+/** Turn install params into the command line that performs them. Both tools
+ *  produce an `npx` invocation, run with cwd = the temp install dir. */
+export function buildInstallCommand(recipe) {
+    if (recipe.tool === "skills-cli") {
+        const src = recipe.source.trim();
+        if (!src)
+            throw new Error("missing skill source");
+        assertSafeArg("source", src);
+        if (recipe.skill?.trim())
+            assertSafeArg("skill", recipe.skill.trim());
+        const args = ["-y", "skills", "add", src];
+        if (recipe.skill?.trim())
+            args.push("--skill", recipe.skill.trim());
+        // --full-depth: repo sources only scan conventional roots by default;
+        // always search the whole tree so skills at non-standard depths (a
+        // monorepo's packages/<x>/skills/) install too. Part of the fixed
+        // invocation (like --copy), so recipe replays inherit it.
+        // --agent universal is a MATERIALIZE TRICK, not a target choice: the CLI
+        // must be told some agent layout before it writes files; "universal" is
+        // its agent-neutral one (`<cwd>/.agents/skills/`), which we use as the
+        // predictable pickup location inside the throwaway temp dir. Which agent
+        // actually sees a skill is decided downstream, at materialize time.
+        args.push("--full-depth", "--agent", "universal", "--copy", "--yes");
+        return { npxArgs: args };
+    }
+    const pkg = recipe.package.trim();
+    const version = recipe.version.trim();
+    if (!pkg || !version)
+        throw new Error("missing npx package/version");
+    assertSafeArg("package", pkg);
+    assertSafeArg("version", version);
+    return { npxArgs: ["-y", `${pkg}@${version}`, ...recipe.args] };
+}
+/**
+ * INSTALL ONLY: run `recipe`'s install command in a throwaway temp dir and
+ * move every skill it produced into `targetDir`. Writes no metadata — the
+ * observations come back as the return value. Throws on bad input / failure.
+ */
+export async function installFromRecipe(recipe, targetDir, opts = {}) {
+    const staged = await execStagedInstall(buildInstallCommand(recipe).npxArgs, opts.runNpx);
+    try {
+        if (staged.names.length === 0)
+            throw new Error("no skill was installed — check the source identifier");
+        await mkdir(targetDir, { recursive: true });
+        const installed = [];
+        for (const name of staged.names) {
+            const target = path.join(targetDir, name);
+            await rm(target, { recursive: true, force: true });
+            await cp(path.join(staged.root, name), target, { recursive: true });
+            installed.push({
+                name,
+                dir: target,
+                ...(staged.contentHash[name] ? { contentHash: staged.contentHash[name] } : {}),
+            });
+        }
+        return installed;
+    }
+    finally {
+        await rm(staged.staging, { recursive: true, force: true });
+    }
+}
+/** Write one skill dir's `.rynx-skill.json` v3 install-info file (catalog
+ *  artifact: the payload IS the SkillRef — declaration ≡ record, literally). */
+export async function writeSkillInstallInfo(skillDir, ref) {
+    const info = { schema: 3, ref, installedAt: new Date().toISOString() };
+    await writeFile(path.join(skillDir, SKILL_RECEIPT_FILE), `${JSON.stringify(info, null, 2)}\n`);
+}
+/**
+ * The CATALOG layer: install per `recipe` AND write each produced skill its
+ * install-info file — `ref` = these exact install params + the observed
+ * content hash. Returns the installed skills' catalog metadata.
+ */
+export async function installIntoCatalog(recipe, catalogRoot, opts = {}) {
+    const installed = await installFromRecipe(recipe, catalogRoot, opts);
+    const metas = [];
+    for (const skill of installed) {
+        await writeSkillInstallInfo(skill.dir, {
+            name: skill.name,
+            install: recipe,
+            ...(skill.contentHash ? { contentHash: skill.contentHash } : {}),
+        });
+        const meta = await readSkillMeta(skill.dir);
+        if (meta)
+            metas.push(meta);
+    }
+    return metas;
+}
+/**
+ * Run one `npx` command in a throwaway temp dir, list the skill folders it
+ * produced under `.agents/skills/`, and pick up the `skills` CLI's per-skill
+ * content hashes from its `skills-lock.json`. The caller moves the folders
+ * and owns the temp dir's cleanup.
+ */
+async function execStagedInstall(npxArgs, runNpx = runNpxDefault) {
+    const staging = await mkdtemp(path.join(tmpdir(), "rynx-skill-"));
+    try {
+        await runNpx(npxArgs, { cwd: staging });
+    }
+    catch (err) {
+        await rm(staging, { recursive: true, force: true });
+        throw err;
+    }
+    const root = path.join(staging, ".agents", "skills");
+    let names;
+    try {
+        names = (await readdir(root, { withFileTypes: true }))
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    catch {
+        names = [];
+    }
+    const contentHash = {};
+    try {
+        const lock = JSON.parse(await readFile(path.join(staging, "skills-lock.json"), "utf8"));
+        for (const [name, entry] of Object.entries(lock.skills ?? {})) {
+            if (typeof entry?.computedHash === "string")
+                contentHash[name] = entry.computedHash;
+        }
+    }
+    catch {
+        /* no lock → no hashes; the skill is simply uncacheable */
+    }
+    return { staging, root, names, contentHash };
+}
+/**
+ * Extract a readable failure reason from an execFile rejection, stripping the
+ * `skills` CLI's clack/ANSI UI noise. Surfaces a headline + the source's
+ * available-skills list (the actionable part of an unmatched-`--skill` error).
+ */
+function cliErrorDetail(err) {
+    const e = err;
+    const raw = [e.stderr, e.stdout].filter(Boolean).join("\n") || e.message || String(err);
+    const lines = raw
+        .split(/\r?\n/)
+        .map((line) => line
+        // eslint-disable-next-line no-control-regex
+        .replace(new RegExp("\\x1b\\[[0-9;?]*[A-Za-z]", "g"), "") // ANSI/CSI escape sequences
+        // eslint-disable-next-line no-control-regex
+        .replace(new RegExp("[\x00-\x1f\x7f]", "g"), " ") // stray control chars
+        .replace(/[│╮╯╰─■◇◒◐◓◑●◆]/g, "") // clack box-drawing / spinner glyphs
+        .replace(/\s+/g, " ")
+        .trim())
+        .filter(Boolean);
+    // The common failure is an unmatched `--skill`: the CLI prints a headline plus
+    // a bulleted list of the source's available skills. Surface both so the user
+    // can pick a valid skill, instead of a cryptic tail of the list.
+    const bullets = [];
+    const rest = [];
+    for (const line of lines) {
+        const match = line.match(/^[-•]\s*(.+)$/);
+        if (match)
+            bullets.push(match[1].trim());
+        else
+            rest.push(line);
+    }
+    const errorLine = rest.find((l) => /not\s*found|fail|does not exist|error|invalid|unknown/i.test(l));
+    const detail = bullets.length > 0
+        ? `${errorLine ? `${errorLine} — ` : ""}available skills: ${bullets.join(", ")}`
+        : errorLine || rest.at(-1) || "unknown error";
+    return detail.length > 600 ? `${detail.slice(0, 597)}…` : detail;
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@rynx-ai/skills",
+  "version": "0.1.0",
+  "description": "The rynx skill artifact domain: discover/parse on-disk skills (SKILL.md), install them from replayable recipes (everything bottoms out at `npx skills add`), and read/write the catalog's `.rynx-skill.json` install-info files. Node built-ins + @rynx-ai/protocol only.",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@rynx-ai/protocol": "0.1.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json"
+  }
+}