@nylorun/agents 0.2.0-beta → 0.4.0-beta

package/dist/skills/load.js

@@ -0,0 +1,171 @@
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync, } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import matter from "gray-matter";
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export class SkillsError extends Error {
+    code;
+    diagnostics;
+    constructor(code, message, diagnostics = []) {
+        super(message);
+        this.name = "SkillsError";
+        this.code = code;
+        this.diagnostics = diagnostics;
+    }
+}
+/** Resolve a skills catalog directory; throws when missing or not a directory. */
+export function resolveSkillsRoot(directory) {
+    const resolved = resolve(directory);
+    if (!existsSync(resolved))
+        throw new SkillsError("skills.missing", `Skills directory does not exist: ${directory}`);
+    const real = realpathSync(resolved);
+    if (!statSync(real).isDirectory())
+        throw new SkillsError("skills.missing", `Skills path is not a directory: ${directory}`);
+    return real;
+}
+/**
+ * Load Agent Skills (agentskills.io) from a catalog directory.
+ * Each immediate subdirectory with a valid SKILL.md becomes one skill.
+ */
+export function loadSkillsFromDirectory(directory, diagnostics, options = {}) {
+    const root = resolveSkillsRoot(directory);
+    const boundary = options.boundary ?? root;
+    const prefix = options.codePrefix ?? "skills";
+    const skills = {};
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name.startsWith("."))
+            continue;
+        if (entry.name === "node_modules" || entry.name === ".git")
+            continue;
+        const skillDir = join(root, entry.name);
+        const directoryReal = realInside(boundary, skillDir);
+        if (!directoryReal) {
+            diagnostics.push({
+                severity: "warning",
+                code: `${prefix}.skill-skipped`,
+                message: `Skipped skill '${entry.name}' because its directory escapes the package`,
+                path: skillDir,
+            });
+            continue;
+        }
+        const skillFile = join(directoryReal, "SKILL.md");
+        if (!existsSync(skillFile))
+            continue;
+        const skillReal = realInside(boundary, skillFile);
+        if (!skillReal || !statSync(skillReal).isFile()) {
+            diagnostics.push({
+                severity: "warning",
+                code: `${prefix}.skill-skipped`,
+                message: `Skipped skill '${entry.name}' because SKILL.md escapes the package`,
+                path: skillFile,
+            });
+            continue;
+        }
+        const parsed = parseSkill(readFileSync(skillReal, "utf8"), entry.name);
+        if (!parsed) {
+            diagnostics.push({
+                severity: "warning",
+                code: `${prefix}.skill-skipped`,
+                message: `Skipped skill '${entry.name}' because SKILL.md is not a valid Agent Skill`,
+                path: skillFile,
+            });
+            continue;
+        }
+        if (skills[parsed.name]) {
+            diagnostics.push({
+                severity: "warning",
+                code: `${prefix}.skill-skipped`,
+                message: `Skipped duplicate skill '${parsed.name}'`,
+                path: skillFile,
+            });
+            continue;
+        }
+        const resources = readResources(boundary, directoryReal, diagnostics, prefix);
+        skills[parsed.name] = {
+            name: parsed.name,
+            description: parsed.description,
+            instructions: parsed.instructions,
+            ...(Object.keys(resources).length === 0 ? {} : { resources }),
+        };
+    }
+    return skills;
+}
+export function parseSkill(text, directoryName) {
+    let parsed;
+    try {
+        parsed = matter(text);
+    }
+    catch {
+        return undefined;
+    }
+    const name = asTrimmedString(parsed.data.name);
+    const description = asTrimmedString(parsed.data.description);
+    if (!name || !description || description.length > 1024)
+        return undefined;
+    if (name.length > 64 || !SKILL_NAME.test(name) || name !== directoryName)
+        return undefined;
+    return {
+        name,
+        description,
+        instructions: parsed.content.replace(/^\r?\n/, ""),
+    };
+}
+function asTrimmedString(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function readResources(boundary, directory, diagnostics, prefix) {
+    const resources = {};
+    const walk = (current, depth) => {
+        if (depth > 6)
+            return;
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            if (entry.name.startsWith(".") || entry.name === "node_modules")
+                continue;
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) {
+                const real = realInside(boundary, full);
+                if (!real)
+                    continue;
+                walk(real, depth + 1);
+                continue;
+            }
+            if (!entry.isFile() && !entry.isSymbolicLink())
+                continue;
+            if (depth === 0 && entry.name === "SKILL.md")
+                continue;
+            const real = realInside(boundary, full);
+            if (!real || !statSync(real).isFile()) {
+                diagnostics.push({
+                    severity: "warning",
+                    code: `${prefix}.resource-denied`,
+                    message: `Denied resource outside the package: ${entry.name}`,
+                    path: full,
+                });
+                continue;
+            }
+            const bytes = readFileSync(real);
+            if (bytes.includes(0))
+                continue;
+            const rel = relative(directory, real).split(sep).join("/");
+            if (!rel || rel.startsWith(".."))
+                continue;
+            resources[rel] = bytes.toString("utf8");
+        }
+    };
+    walk(directory, 0);
+    return resources;
+}
+function realInside(root, candidate) {
+    if (!existsSync(candidate))
+        return undefined;
+    try {
+        const real = realpathSync(candidate);
+        return isInside(root, real) ? real : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isInside(root, target) {
+    const rel = relative(root, target);
+    return (rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel)));
+}

package/dist/skills/skills.d.ts

@@ -0,0 +1,28 @@
+import type { CapabilityDeclaration } from "@nylorun/core/define";
+import { type SkillDiagnostic } from "./load.js";
+export interface SkillsOptions {
+    /** Capability id. Defaults to the catalog directory basename. */
+    readonly id?: string;
+}
+export interface SkillsCapability extends CapabilityDeclaration {
+    readonly diagnostics: readonly SkillDiagnostic[];
+    /** Absolute catalog directory that was loaded. */
+    readonly root: string;
+}
+/**
+ * Load an agentskills.io catalog folder and return one capability for `Agent.use`.
+ *
+ * Expected layout:
+ * ```
+ * assistant-skills/
+ *   lookup-order/SKILL.md
+ *   refund/
+ *     SKILL.md
+ *     references/policy.md
+ * ```
+ *
+ * Sets both `skills` (manifest names/descriptions) and `skillRecords` (bodies +
+ * resources) so callers do not duplicate content. The harness injects
+ * `load_skill` / `read_skill_resource` from the records.
+ */
+export declare function skills(directory: string, options?: SkillsOptions): SkillsCapability;

package/dist/skills/skills.js

@@ -0,0 +1,47 @@
+import { basename } from "node:path";
+import { formatSkillCatalog, SKILLS_USAGE } from "./catalog.js";
+import { loadSkillsFromDirectory, resolveSkillsRoot, } from "./load.js";
+/**
+ * Load an agentskills.io catalog folder and return one capability for `Agent.use`.
+ *
+ * Expected layout:
+ * ```
+ * assistant-skills/
+ *   lookup-order/SKILL.md
+ *   refund/
+ *     SKILL.md
+ *     references/policy.md
+ * ```
+ *
+ * Sets both `skills` (manifest names/descriptions) and `skillRecords` (bodies +
+ * resources) so callers do not duplicate content. The harness injects
+ * `load_skill` / `read_skill_resource` from the records.
+ */
+export function skills(directory, options = {}) {
+    const root = resolveSkillsRoot(directory);
+    const diagnostics = [];
+    const records = loadSkillsFromDirectory(root, diagnostics);
+    const listed = Object.values(records);
+    const id = options.id ?? basename(root);
+    if (listed.length === 0) {
+        return { id, root, diagnostics };
+    }
+    const skillManifest = Object.fromEntries(listed.map((skill) => [
+        skill.name,
+        { name: skill.name, description: skill.description },
+    ]));
+    return {
+        id,
+        root,
+        instructions: [
+            SKILLS_USAGE,
+            formatSkillCatalog(listed.map((skill) => ({
+                name: skill.name,
+                description: skill.description,
+            }))),
+        ],
+        skills: skillManifest,
+        skillRecords: records,
+        diagnostics,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/agents",
-  "version": "0.2.0-beta",
+  "version": "0.4.0-beta",
   "description": "Nylorun agent definitions, session client and connected executor",
   "type": "module",
   "license": "Apache-2.0",
@@ -35,15 +35,16 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "@nylorun/core": "0.1.1-beta"
+    "@nylorun/core": "0.3.0-beta",
+    "gray-matter": "^4.0.3"
   },
   "peerDependencies": {
-    "zod": "^4.5.4"
+    "zod": "^4.6.5"
   },
   "devDependencies": {
-    "typescript": "npm:@typescript/typescript6@^6.0.2",
     "@types/node": "^24.0.0",
-    "vitest": "^5.0.0"
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "^5.0.1"
   },
   "engines": {
     "node": ">=24"