skills-reference 1.0.0

package/README.md

@@ -0,0 +1,78 @@
+# skills-reference
+
+TypeScript port of the Agent Skills reference tooling. It mirrors the Python `skills-ref`.
+
+## Installation
+
+### Prerequisites
+
+- Node.js (v14.0.0 or higher)
+- npm (v6.0.0 or higher)
+
+### From npm
+
+```bash
+# Install the package
+npm install skills-reference
+```
+
+## Usage
+
+### CLI
+
+```bash
+# Validate a skill
+skills-reference validate path/to/skill
+
+# Read skill properties (outputs JSON)
+skills-reference read-properties path/to/skill
+
+# Generate <available_skills> XML for agent prompts
+skills-reference to-prompt path/to/skill-a path/to/skill-b
+```
+
+### Node.js API
+
+#### CommonJS Syntax
+
+```javascript
+const { validate, readProperties, toPrompt } = require("skills-reference");
+
+// Validate a skill directory
+const errors = validate("path/to/skill");
+if (errors.length > 0) {
+    console.log("Validation errors:", errors);
+}
+
+// Read skill properties
+const props = readProperties("path/to/skill");
+console.log(`Skill: ${props.name} - ${props.description}`);
+
+// Generate prompt for available skills
+const prompt = toPrompt(["path/to/skill-a", "path/to/skill-b"]);
+console.log(prompt);
+```
+
+#### ESM Syntax
+
+```javascript
+import { validate, readProperties, toPrompt } from "skills-reference";
+
+// Validate a skill directory
+const errors = validate("path/to/skill");
+if (errors.length > 0) {
+    console.log("Validation errors:", errors);
+}
+
+// Read skill properties
+const props = readProperties("path/to/skill");
+console.log(`Skill: ${props.name} - ${props.description}`);
+
+// Generate prompt for available skills
+const prompt = toPrompt(["path/to/skill-a", "path/to/skill-b"]);
+console.log(prompt);
+```
+
+## License
+
+ISC

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import * as path from "path";
+import * as fs from "fs";
+import { Command } from "commander";
+import { readProperties } from "./parser.js";
+import { toPrompt } from "./prompt.js";
+import { validate } from "./validator.js";
+const program = new Command();
+function isSkillMdFile(filePath) {
+    const stats = fs.statSync(filePath);
+    return (stats.isFile() && path.basename(filePath).toLowerCase() === "skill.md");
+}
+program
+    .name("skills-reference")
+    .description("Reference library for Agent Skills")
+    .version("1.0.0");
+program
+    .command("validate")
+    .description("Validate a skill directory")
+    .argument("<skillPath>", "Path to skill directory or SKILL.md file")
+    .action((skillPath) => {
+    try {
+        let resolvedPath = path.resolve(skillPath);
+        if (isSkillMdFile(resolvedPath)) {
+            resolvedPath = path.dirname(resolvedPath);
+        }
+        const errors = validate(resolvedPath);
+        if (errors.length > 0) {
+            console.error(`Validation failed for ${resolvedPath}:`);
+            errors.forEach((error) => {
+                console.error(`  - ${error}`);
+            });
+            process.exit(1);
+        }
+        else {
+            console.log(`Valid skill: ${resolvedPath}`);
+        }
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+});
+program
+    .command("read-properties")
+    .description("Read and print skill properties as JSON")
+    .argument("<skillPath>", "Path to skill directory or SKILL.md file")
+    .action((skillPath) => {
+    try {
+        let resolvedPath = path.resolve(skillPath);
+        if (isSkillMdFile(resolvedPath)) {
+            resolvedPath = path.dirname(resolvedPath);
+        }
+        const props = readProperties(resolvedPath);
+        console.log(JSON.stringify(props.toDict(), null, 2));
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+});
+program
+    .command("to-prompt")
+    .description("Generate <available_skills> XML for agent prompts")
+    .argument("<skillPaths...>", "Paths to skill directories or SKILL.md files")
+    .action((skillPaths) => {
+    try {
+        const resolvedPaths = skillPaths.map((skillPath) => {
+            const resolvedPath = path.resolve(skillPath);
+            if (isSkillMdFile(resolvedPath)) {
+                return path.dirname(resolvedPath);
+            }
+            return resolvedPath;
+        });
+        const output = toPrompt(resolvedPaths);
+        console.log(output);
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+});
+program.parse(process.argv);
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+export declare class SkillError extends Error {
+    constructor(message: string);
+}
+export declare class ParseError extends SkillError {
+    constructor(message: string);
+}
+export declare class ValidationError extends SkillError {
+    errors: string[];
+    constructor(message: string, errors?: string[]);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,UAAW,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,UAAW,SAAQ,UAAU;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,eAAgB,SAAQ,UAAU;IACtC,MAAM,EAAE,MAAM,EAAE,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE;CAK/C"}

package/dist/errors.js

@@ -0,0 +1,20 @@
+export class SkillError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SkillError';
+    }
+}
+export class ParseError extends SkillError {
+    constructor(message) {
+        super(message);
+        this.name = 'ParseError';
+    }
+}
+export class ValidationError extends SkillError {
+    constructor(message, errors) {
+        super(message);
+        this.name = 'ValidationError';
+        this.errors = errors || [message];
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,UAAW,SAAQ,KAAK;IACnC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,OAAO,UAAW,SAAQ,UAAU;IACxC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,UAAU;IAG7C,YAAY,OAAe,EAAE,MAAiB;QAC5C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { SkillError, ParseError, ValidationError } from "./errors.js";
+export { SkillProperties, SkillPropertiesImpl } from "./models.js";
+export { findSkillMd, parseFrontmatter, readProperties } from "./parser.js";
+export { toPrompt } from "./prompt.js";
+export { validate, validateMetadata } from "./validator.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { SkillError, ParseError, ValidationError } from "./errors.js";
+export { SkillPropertiesImpl } from "./models.js";
+export { findSkillMd, parseFrontmatter, readProperties } from "./parser.js";
+export { toPrompt } from "./prompt.js";
+export { validate, validateMetadata } from "./validator.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAmB,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/models.d.ts

@@ -0,0 +1,20 @@
+export interface SkillProperties {
+    name: string;
+    description: string;
+    license?: string;
+    compatibility?: string;
+    allowedTools?: string;
+    metadata: Record<string, string>;
+    toDict(): Record<string, any>;
+}
+export declare class SkillPropertiesImpl implements SkillProperties {
+    name: string;
+    description: string;
+    license?: string | undefined;
+    compatibility?: string | undefined;
+    allowedTools?: string | undefined;
+    metadata: Record<string, string>;
+    constructor(name: string, description: string, license?: string | undefined, compatibility?: string | undefined, allowedTools?: string | undefined, metadata?: Record<string, string>);
+    toDict(): Record<string, any>;
+}
+//# sourceMappingURL=models.d.ts.map

package/dist/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC/B;AAED,qBAAa,mBAAoB,YAAW,eAAe;IAEhD,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,MAAM;IACnB,OAAO,CAAC,EAAE,MAAM;IAChB,aAAa,CAAC,EAAE,MAAM;IACtB,YAAY,CAAC,EAAE,MAAM;IACrB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;gBALhC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,MAAM,YAAA,EAChB,aAAa,CAAC,EAAE,MAAM,YAAA,EACtB,YAAY,CAAC,EAAE,MAAM,YAAA,EACrB,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM;IAG9C,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CAwB9B"}

package/dist/models.js

@@ -0,0 +1,30 @@
+export class SkillPropertiesImpl {
+    constructor(name, description, license, compatibility, allowedTools, metadata = {}) {
+        this.name = name;
+        this.description = description;
+        this.license = license;
+        this.compatibility = compatibility;
+        this.allowedTools = allowedTools;
+        this.metadata = metadata;
+    }
+    toDict() {
+        const result = {
+            name: this.name,
+            description: this.description
+        };
+        if (this.license) {
+            result.license = this.license;
+        }
+        if (this.compatibility) {
+            result.compatibility = this.compatibility;
+        }
+        if (this.allowedTools) {
+            result['allowed-tools'] = this.allowedTools;
+        }
+        if (Object.keys(this.metadata).length > 0) {
+            result.metadata = this.metadata;
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=models.js.map

package/dist/models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,mBAAmB;IAC9B,YACS,IAAY,EACZ,WAAmB,EACnB,OAAgB,EAChB,aAAsB,EACtB,YAAqB,EACrB,WAAmC,EAAE;QALrC,SAAI,GAAJ,IAAI,CAAQ;QACZ,gBAAW,GAAX,WAAW,CAAQ;QACnB,YAAO,GAAP,OAAO,CAAS;QAChB,kBAAa,GAAb,aAAa,CAAS;QACtB,iBAAY,GAAZ,YAAY,CAAS;QACrB,aAAQ,GAAR,QAAQ,CAA6B;IAC3C,CAAC;IAEJ,MAAM;QACJ,MAAM,MAAM,GAAwB;YAClC,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC;QAEF,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAChC,CAAC;QAED,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,MAAM,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;QAC5C,CAAC;QAED,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,MAAM,CAAC,eAAe,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC;QAC9C,CAAC;QAED,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1C,MAAM,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAClC,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;CACF"}

package/dist/parser.d.ts

@@ -0,0 +1,8 @@
+import { SkillProperties } from "./models.js";
+export declare function findSkillMd(skillDir: string): string | null;
+export declare function parseFrontmatter(content: string): {
+    metadata: Record<string, any>;
+    body: string;
+};
+export declare function readProperties(skillDir: string): SkillProperties;
+//# sourceMappingURL=parser.d.ts.map

package/dist/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,eAAe,EAAuB,MAAM,aAAa,CAAC;AAEnE,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAW3D;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG;IAC/C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;CAChB,CA0CA;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CA8ChE"}

package/dist/parser.js

@@ -0,0 +1,71 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as yaml from "js-yaml";
+import { ParseError, ValidationError } from "./errors.js";
+import { SkillPropertiesImpl } from "./models.js";
+export function findSkillMd(skillDir) {
+    const skillPath = path.resolve(skillDir);
+    for (const name of ["SKILL.md", "skill.md"]) {
+        const filePath = path.join(skillPath, name);
+        if (fs.existsSync(filePath)) {
+            return filePath;
+        }
+    }
+    return null;
+}
+export function parseFrontmatter(content) {
+    if (!content.startsWith("---")) {
+        throw new ParseError("SKILL.md must start with YAML frontmatter (---)");
+    }
+    const parts = content.split("---", 3);
+    if (parts.length < 3) {
+        throw new ParseError("SKILL.md frontmatter not properly closed with ---");
+    }
+    const frontmatterStr = parts[1];
+    const body = parts[2].trim();
+    try {
+        const metadata = yaml.load(frontmatterStr);
+        if (typeof metadata !== "object" || metadata === null) {
+            throw new ParseError("SKILL.md frontmatter must be a YAML mapping");
+        }
+        if (metadata.metadata &&
+            typeof metadata.metadata === "object" &&
+            metadata.metadata !== null) {
+            metadata.metadata = Object.entries(metadata.metadata).reduce((acc, [key, value]) => {
+                acc[key] = String(value);
+                return acc;
+            }, {});
+        }
+        return { metadata, body };
+    }
+    catch (error) {
+        throw new ParseError(`Invalid YAML in frontmatter: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export function readProperties(skillDir) {
+    const skillPath = path.resolve(skillDir);
+    const skillMdPath = findSkillMd(skillPath);
+    if (!skillMdPath) {
+        throw new ParseError(`SKILL.md not found in ${skillPath}`);
+    }
+    const content = fs.readFileSync(skillMdPath, "utf8");
+    const { metadata } = parseFrontmatter(content);
+    if (!metadata.name) {
+        throw new ValidationError("Missing required field in frontmatter: name");
+    }
+    if (!metadata.description) {
+        throw new ValidationError("Missing required field in frontmatter: description");
+    }
+    const name = String(metadata.name).trim();
+    const description = String(metadata.description).trim();
+    if (!name) {
+        throw new ValidationError("Field 'name' must be a non-empty string");
+    }
+    if (!description) {
+        throw new ValidationError("Field 'description' must be a non-empty string");
+    }
+    return new SkillPropertiesImpl(name, description, metadata.license ? String(metadata.license) : undefined, metadata.compatibility ? String(metadata.compatibility) : undefined, metadata["allowed-tools"]
+        ? String(metadata["allowed-tools"])
+        : undefined, metadata.metadata || {});
+}
+//# sourceMappingURL=parser.js.map

package/dist/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"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"}

package/dist/prompt.d.ts

@@ -0,0 +1,2 @@
+export declare function toPrompt(skillDirs: string[]): string;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../src/prompt.ts"],"names":[],"mappings":"AAGA,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAgCpD"}

package/dist/prompt.js

@@ -0,0 +1,37 @@
+import * as path from "path";
+import { findSkillMd, readProperties } from "./parser.js";
+export function toPrompt(skillDirs) {
+    if (!skillDirs || skillDirs.length === 0) {
+        return "<available_skills>\n</available_skills>";
+    }
+    const lines = ["<available_skills>"];
+    for (const skillDir of skillDirs) {
+        const resolvedDir = path.resolve(skillDir);
+        const props = readProperties(resolvedDir);
+        lines.push("<skill>");
+        lines.push("<name>");
+        lines.push(escapeHtml(props.name));
+        lines.push("</name>");
+        lines.push("<description>");
+        lines.push(escapeHtml(props.description));
+        lines.push("</description>");
+        const skillMdPath = findSkillMd(resolvedDir);
+        if (skillMdPath) {
+            lines.push("<location>");
+            lines.push(skillMdPath);
+            lines.push("</location>");
+        }
+        lines.push("</skill>");
+    }
+    lines.push("</available_skills>");
+    return lines.join("\n");
+}
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#039;");
+}
+//# sourceMappingURL=prompt.js.map

package/dist/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../src/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE1D,MAAM,UAAU,QAAQ,CAAC,SAAmB;IACxC,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvC,OAAO,yCAAyC,CAAC;IACrD,CAAC;IAED,MAAM,KAAK,GAAa,CAAC,oBAAoB,CAAC,CAAC;IAE/C,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QAC/B,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC3C,MAAM,KAAK,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC;QAE1C,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACrB,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QACnC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC;QAC1C,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QAE7B,MAAM,WAAW,GAAG,WAAW,CAAC,WAAW,CAAC,CAAC;QAC7C,IAAI,WAAW,EAAE,CAAC;YACd,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACzB,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YACxB,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC9B,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;IAElC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED,SAAS,UAAU,CAAC,IAAY;IAC5B,OAAO,IAAI;SACN,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC;SACvB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AACjC,CAAC"}

package/dist/validator.d.ts

@@ -0,0 +1,3 @@
+export declare function validateMetadata(metadata: Record<string, any>, skillDir?: string): string[];
+export declare function validate(skillDir: string): string[];
+//# sourceMappingURL=validator.d.ts.map

package/dist/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../src/validator.ts"],"names":[],"mappings":"AA8HA,wBAAgB,gBAAgB,CAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC7B,QAAQ,CAAC,EAAE,MAAM,GAClB,MAAM,EAAE,CAqBV;AAED,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAuBnD"}

package/dist/validator.js

@@ -0,0 +1,126 @@
+import * as fs from "fs";
+import * as path from "path";
+import { findSkillMd, parseFrontmatter } from "./parser.js";
+const MAX_SKILL_NAME_LENGTH = 64;
+const MAX_DESCRIPTION_LENGTH = 1024;
+const MAX_COMPATIBILITY_LENGTH = 500;
+const ALLOWED_FIELDS = new Set([
+    "name",
+    "description",
+    "license",
+    "allowed-tools",
+    "metadata",
+    "compatibility",
+]);
+function normalizeString(str) {
+    return str.normalize("NFKC");
+}
+function validateName(name, skillDir) {
+    const errors = [];
+    if (!name || typeof name !== "string" || !name.trim()) {
+        errors.push("Field 'name' must be a non-empty string");
+        return errors;
+    }
+    const normalizedName = normalizeString(name.trim());
+    if (normalizedName.length > MAX_SKILL_NAME_LENGTH) {
+        errors.push(`Skill name '${normalizedName}' exceeds ${MAX_SKILL_NAME_LENGTH} character limit ` +
+            `(${normalizedName.length} chars)`);
+    }
+    if (normalizedName !== normalizedName.toLowerCase()) {
+        errors.push(`Skill name '${normalizedName}' must be lowercase`);
+    }
+    if (normalizedName.startsWith("-") || normalizedName.endsWith("-")) {
+        errors.push("Skill name cannot start or end with a hyphen");
+    }
+    if (normalizedName.includes("--")) {
+        errors.push("Skill name cannot contain consecutive hyphens");
+    }
+    if (!/^[a-z0-9-]+$/.test(normalizedName)) {
+        errors.push(`Skill name '${normalizedName}' contains invalid characters. ` +
+            "Only letters, digits, and hyphens are allowed.");
+    }
+    if (skillDir) {
+        const dirName = normalizeString(path.basename(skillDir));
+        if (dirName !== normalizedName) {
+            errors.push(`Directory name '${path.basename(skillDir)}' must match skill name '${normalizedName}'`);
+        }
+    }
+    return errors;
+}
+function validateDescription(description) {
+    const errors = [];
+    if (!description ||
+        typeof description !== "string" ||
+        !description.trim()) {
+        errors.push("Field 'description' must be a non-empty string");
+        return errors;
+    }
+    if (description.length > MAX_DESCRIPTION_LENGTH) {
+        errors.push(`Description exceeds ${MAX_DESCRIPTION_LENGTH} character limit ` +
+            `(${description.length} chars)`);
+    }
+    return errors;
+}
+function validateCompatibility(compatibility) {
+    const errors = [];
+    if (typeof compatibility !== "string") {
+        errors.push("Field 'compatibility' must be a string");
+        return errors;
+    }
+    if (compatibility.length > MAX_COMPATIBILITY_LENGTH) {
+        errors.push(`Compatibility exceeds ${MAX_COMPATIBILITY_LENGTH} character limit ` +
+            `(${compatibility.length} chars)`);
+    }
+    return errors;
+}
+function validateMetadataFields(metadata) {
+    const errors = [];
+    const extraFields = Object.keys(metadata).filter((field) => !ALLOWED_FIELDS.has(field));
+    if (extraFields.length > 0) {
+        errors.push(`Unexpected fields in frontmatter: ${extraFields.sort().join(", ")}. ` +
+            `Only ${Array.from(ALLOWED_FIELDS).sort().join(", ")} are allowed.`);
+    }
+    return errors;
+}
+export function validateMetadata(metadata, skillDir) {
+    const errors = [];
+    errors.push(...validateMetadataFields(metadata));
+    if (!metadata.name) {
+        errors.push("Missing required field in frontmatter: name");
+    }
+    else {
+        errors.push(...validateName(metadata.name, skillDir));
+    }
+    if (!metadata.description) {
+        errors.push("Missing required field in frontmatter: description");
+    }
+    else {
+        errors.push(...validateDescription(metadata.description));
+    }
+    if (metadata.compatibility) {
+        errors.push(...validateCompatibility(metadata.compatibility));
+    }
+    return errors;
+}
+export function validate(skillDir) {
+    const skillPath = path.resolve(skillDir);
+    if (!fs.existsSync(skillPath)) {
+        return [`Path does not exist: ${skillPath}`];
+    }
+    if (!fs.statSync(skillPath).isDirectory()) {
+        return [`Not a directory: ${skillPath}`];
+    }
+    const skillMdPath = findSkillMd(skillPath);
+    if (!skillMdPath) {
+        return ["Missing required file: SKILL.md"];
+    }
+    try {
+        const content = fs.readFileSync(skillMdPath, "utf8");
+        const { metadata } = parseFrontmatter(content);
+        return validateMetadata(metadata, skillPath);
+    }
+    catch (error) {
+        return [error instanceof Error ? error.message : String(error)];
+    }
+}
+//# sourceMappingURL=validator.js.map

package/dist/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../src/validator.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "skills-reference",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "bin": {
+    "skills-reference": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "start": "node dist/cli.js"
+  },
+  "keywords": [
+    "agent",
+    "skills",
+    "cli"
+  ],
+  "author": "carbide",
+  "license": "ISC",
+  "description": "Reference library for Agent Skills",
+  "dependencies": {
+    "commander": "^14.0.0",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.2.3",
+    "@typescript-eslint/eslint-plugin": "^8.55.0",
+    "@typescript-eslint/parser": "^8.55.0",
+    "eslint": "^9.39.2",
+    "jest": "^30.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.6.2"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import * as path from "path";
+import * as fs from "fs";
+import { Command } from "commander";
+import { SkillError } from "./errors.js";
+import { readProperties } from "./parser.js";
+import { toPrompt } from "./prompt.js";
+import { validate } from "./validator.js";
+
+const program = new Command();
+
+function isSkillMdFile(filePath: string): boolean {
+    const stats = fs.statSync(filePath);
+    return (
+        stats.isFile() && path.basename(filePath).toLowerCase() === "skill.md"
+    );
+}
+
+program
+    .name("skills-reference")
+    .description("Reference library for Agent Skills")
+    .version("1.0.0");
+
+program
+    .command("validate")
+    .description("Validate a skill directory")
+    .argument("<skillPath>", "Path to skill directory or SKILL.md file")
+    .action((skillPath: string) => {
+        try {
+            let resolvedPath = path.resolve(skillPath);
+
+            if (isSkillMdFile(resolvedPath)) {
+                resolvedPath = path.dirname(resolvedPath);
+            }
+
+            const errors = validate(resolvedPath);
+
+            if (errors.length > 0) {
+                console.error(`Validation failed for ${resolvedPath}:`);
+                errors.forEach((error) => {
+                    console.error(`  - ${error}`);
+                });
+                process.exit(1);
+            } else {
+                console.log(`Valid skill: ${resolvedPath}`);
+            }
+        } catch (error) {
+            console.error(
+                `Error: ${error instanceof Error ? error.message : String(error)}`,
+            );
+            process.exit(1);
+        }
+    });
+
+program
+    .command("read-properties")
+    .description("Read and print skill properties as JSON")
+    .argument("<skillPath>", "Path to skill directory or SKILL.md file")
+    .action((skillPath: string) => {
+        try {
+            let resolvedPath = path.resolve(skillPath);
+
+            if (isSkillMdFile(resolvedPath)) {
+                resolvedPath = path.dirname(resolvedPath);
+            }
+
+            const props = readProperties(resolvedPath);
+            console.log(JSON.stringify(props.toDict(), null, 2));
+        } catch (error) {
+            console.error(
+                `Error: ${error instanceof Error ? error.message : String(error)}`,
+            );
+            process.exit(1);
+        }
+    });
+
+program
+    .command("to-prompt")
+    .description("Generate <available_skills> XML for agent prompts")
+    .argument("<skillPaths...>", "Paths to skill directories or SKILL.md files")
+    .action((skillPaths: string[]) => {
+        try {
+            const resolvedPaths = skillPaths.map((skillPath) => {
+                const resolvedPath = path.resolve(skillPath);
+                if (isSkillMdFile(resolvedPath)) {
+                    return path.dirname(resolvedPath);
+                }
+                return resolvedPath;
+            });
+
+            const output = toPrompt(resolvedPaths);
+            console.log(output);
+        } catch (error) {
+            console.error(
+                `Error: ${error instanceof Error ? error.message : String(error)}`,
+            );
+            process.exit(1);
+        }
+    });
+
+program.parse(process.argv);

package/src/errors.ts

@@ -0,0 +1,23 @@
+export class SkillError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SkillError';
+  }
+}
+
+export class ParseError extends SkillError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ParseError';
+  }
+}
+
+export class ValidationError extends SkillError {
+  public errors: string[];
+  
+  constructor(message: string, errors?: string[]) {
+    super(message);
+    this.name = 'ValidationError';
+    this.errors = errors || [message];
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export { SkillError, ParseError, ValidationError } from "./errors.js";
+export { SkillProperties, SkillPropertiesImpl } from "./models.js";
+export { findSkillMd, parseFrontmatter, readProperties } from "./parser.js";
+export { toPrompt } from "./prompt.js";
+export { validate, validateMetadata } from "./validator.js";

package/src/models.ts

@@ -0,0 +1,46 @@
+export interface SkillProperties {
+  name: string;
+  description: string;
+  license?: string;
+  compatibility?: string;
+  allowedTools?: string;
+  metadata: Record<string, string>;
+  
+  toDict(): Record<string, any>;
+}
+
+export class SkillPropertiesImpl implements SkillProperties {
+  constructor(
+    public name: string,
+    public description: string,
+    public license?: string,
+    public compatibility?: string,
+    public allowedTools?: string,
+    public metadata: Record<string, string> = {}
+  ) {}
+  
+  toDict(): Record<string, any> {
+    const result: Record<string, any> = {
+      name: this.name,
+      description: this.description
+    };
+    
+    if (this.license) {
+      result.license = this.license;
+    }
+    
+    if (this.compatibility) {
+      result.compatibility = this.compatibility;
+    }
+    
+    if (this.allowedTools) {
+      result['allowed-tools'] = this.allowedTools;
+    }
+    
+    if (Object.keys(this.metadata).length > 0) {
+      result.metadata = this.metadata;
+    }
+    
+    return result;
+  }
+}

package/src/parser.ts

@@ -0,0 +1,113 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as yaml from "js-yaml";
+import { ParseError, ValidationError } from "./errors.js";
+import { SkillProperties, SkillPropertiesImpl } from "./models.js";
+
+export function findSkillMd(skillDir: string): string | null {
+    const skillPath = path.resolve(skillDir);
+
+    for (const name of ["SKILL.md", "skill.md"]) {
+        const filePath = path.join(skillPath, name);
+        if (fs.existsSync(filePath)) {
+            return filePath;
+        }
+    }
+
+    return null;
+}
+
+export function parseFrontmatter(content: string): {
+    metadata: Record<string, any>;
+    body: string;
+} {
+    if (!content.startsWith("---")) {
+        throw new ParseError("SKILL.md must start with YAML frontmatter (---)");
+    }
+
+    const parts = content.split("---", 3);
+    if (parts.length < 3) {
+        throw new ParseError(
+            "SKILL.md frontmatter not properly closed with ---",
+        );
+    }
+
+    const frontmatterStr = parts[1];
+    const body = parts[2].trim();
+
+    try {
+        const metadata = yaml.load(frontmatterStr) as Record<string, any>;
+
+        if (typeof metadata !== "object" || metadata === null) {
+            throw new ParseError("SKILL.md frontmatter must be a YAML mapping");
+        }
+
+        if (
+            metadata.metadata &&
+            typeof metadata.metadata === "object" &&
+            metadata.metadata !== null
+        ) {
+            metadata.metadata = Object.entries(metadata.metadata).reduce(
+                (acc, [key, value]) => {
+                    acc[key] = String(value);
+                    return acc;
+                },
+                {} as Record<string, string>,
+            );
+        }
+
+        return { metadata, body };
+    } catch (error) {
+        throw new ParseError(
+            `Invalid YAML in frontmatter: ${error instanceof Error ? error.message : String(error)}`,
+        );
+    }
+}
+
+export function readProperties(skillDir: string): SkillProperties {
+    const skillPath = path.resolve(skillDir);
+    const skillMdPath = findSkillMd(skillPath);
+
+    if (!skillMdPath) {
+        throw new ParseError(`SKILL.md not found in ${skillPath}`);
+    }
+
+    const content = fs.readFileSync(skillMdPath, "utf8");
+    const { metadata } = parseFrontmatter(content);
+
+    if (!metadata.name) {
+        throw new ValidationError(
+            "Missing required field in frontmatter: name",
+        );
+    }
+
+    if (!metadata.description) {
+        throw new ValidationError(
+            "Missing required field in frontmatter: description",
+        );
+    }
+
+    const name = String(metadata.name).trim();
+    const description = String(metadata.description).trim();
+
+    if (!name) {
+        throw new ValidationError("Field 'name' must be a non-empty string");
+    }
+
+    if (!description) {
+        throw new ValidationError(
+            "Field 'description' must be a non-empty string",
+        );
+    }
+
+    return new SkillPropertiesImpl(
+        name,
+        description,
+        metadata.license ? String(metadata.license) : undefined,
+        metadata.compatibility ? String(metadata.compatibility) : undefined,
+        metadata["allowed-tools"]
+            ? String(metadata["allowed-tools"])
+            : undefined,
+        metadata.metadata || {},
+    );
+}

package/src/prompt.ts

@@ -0,0 +1,45 @@
+import * as path from "path";
+import { findSkillMd, readProperties } from "./parser.js";
+
+export function toPrompt(skillDirs: string[]): string {
+    if (!skillDirs || skillDirs.length === 0) {
+        return "<available_skills>\n</available_skills>";
+    }
+
+    const lines: string[] = ["<available_skills>"];
+
+    for (const skillDir of skillDirs) {
+        const resolvedDir = path.resolve(skillDir);
+        const props = readProperties(resolvedDir);
+
+        lines.push("<skill>");
+        lines.push("<name>");
+        lines.push(escapeHtml(props.name));
+        lines.push("</name>");
+        lines.push("<description>");
+        lines.push(escapeHtml(props.description));
+        lines.push("</description>");
+
+        const skillMdPath = findSkillMd(resolvedDir);
+        if (skillMdPath) {
+            lines.push("<location>");
+            lines.push(skillMdPath);
+            lines.push("</location>");
+        }
+
+        lines.push("</skill>");
+    }
+
+    lines.push("</available_skills>");
+
+    return lines.join("\n");
+}
+
+function escapeHtml(text: string): string {
+    return text
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#039;");
+}

package/src/validator.ts

@@ -0,0 +1,176 @@
+import * as fs from "fs";
+import * as path from "path";
+import { ParseError } from "./errors.js";
+import { findSkillMd, parseFrontmatter } from "./parser.js";
+
+const MAX_SKILL_NAME_LENGTH = 64;
+const MAX_DESCRIPTION_LENGTH = 1024;
+const MAX_COMPATIBILITY_LENGTH = 500;
+
+const ALLOWED_FIELDS = new Set([
+    "name",
+    "description",
+    "license",
+    "allowed-tools",
+    "metadata",
+    "compatibility",
+]);
+
+function normalizeString(str: string): string {
+    return str.normalize("NFKC");
+}
+
+function validateName(name: string, skillDir?: string): string[] {
+    const errors: string[] = [];
+
+    if (!name || typeof name !== "string" || !name.trim()) {
+        errors.push("Field 'name' must be a non-empty string");
+        return errors;
+    }
+
+    const normalizedName = normalizeString(name.trim());
+
+    if (normalizedName.length > MAX_SKILL_NAME_LENGTH) {
+        errors.push(
+            `Skill name '${normalizedName}' exceeds ${MAX_SKILL_NAME_LENGTH} character limit ` +
+                `(${normalizedName.length} chars)`,
+        );
+    }
+
+    if (normalizedName !== normalizedName.toLowerCase()) {
+        errors.push(`Skill name '${normalizedName}' must be lowercase`);
+    }
+
+    if (normalizedName.startsWith("-") || normalizedName.endsWith("-")) {
+        errors.push("Skill name cannot start or end with a hyphen");
+    }
+
+    if (normalizedName.includes("--")) {
+        errors.push("Skill name cannot contain consecutive hyphens");
+    }
+
+    if (!/^[a-z0-9-]+$/.test(normalizedName)) {
+        errors.push(
+            `Skill name '${normalizedName}' contains invalid characters. ` +
+                "Only letters, digits, and hyphens are allowed.",
+        );
+    }
+
+    if (skillDir) {
+        const dirName = normalizeString(path.basename(skillDir));
+        if (dirName !== normalizedName) {
+            errors.push(
+                `Directory name '${path.basename(skillDir)}' must match skill name '${normalizedName}'`,
+            );
+        }
+    }
+
+    return errors;
+}
+
+function validateDescription(description: string): string[] {
+    const errors: string[] = [];
+
+    if (
+        !description ||
+        typeof description !== "string" ||
+        !description.trim()
+    ) {
+        errors.push("Field 'description' must be a non-empty string");
+        return errors;
+    }
+
+    if (description.length > MAX_DESCRIPTION_LENGTH) {
+        errors.push(
+            `Description exceeds ${MAX_DESCRIPTION_LENGTH} character limit ` +
+                `(${description.length} chars)`,
+        );
+    }
+
+    return errors;
+}
+
+function validateCompatibility(compatibility: string): string[] {
+    const errors: string[] = [];
+
+    if (typeof compatibility !== "string") {
+        errors.push("Field 'compatibility' must be a string");
+        return errors;
+    }
+
+    if (compatibility.length > MAX_COMPATIBILITY_LENGTH) {
+        errors.push(
+            `Compatibility exceeds ${MAX_COMPATIBILITY_LENGTH} character limit ` +
+                `(${compatibility.length} chars)`,
+        );
+    }
+
+    return errors;
+}
+
+function validateMetadataFields(metadata: Record<string, any>): string[] {
+    const errors: string[] = [];
+
+    const extraFields = Object.keys(metadata).filter(
+        (field) => !ALLOWED_FIELDS.has(field),
+    );
+    if (extraFields.length > 0) {
+        errors.push(
+            `Unexpected fields in frontmatter: ${extraFields.sort().join(", ")}. ` +
+                `Only ${Array.from(ALLOWED_FIELDS).sort().join(", ")} are allowed.`,
+        );
+    }
+
+    return errors;
+}
+
+export function validateMetadata(
+    metadata: Record<string, any>,
+    skillDir?: string,
+): string[] {
+    const errors: string[] = [];
+    errors.push(...validateMetadataFields(metadata));
+
+    if (!metadata.name) {
+        errors.push("Missing required field in frontmatter: name");
+    } else {
+        errors.push(...validateName(metadata.name, skillDir));
+    }
+
+    if (!metadata.description) {
+        errors.push("Missing required field in frontmatter: description");
+    } else {
+        errors.push(...validateDescription(metadata.description));
+    }
+
+    if (metadata.compatibility) {
+        errors.push(...validateCompatibility(metadata.compatibility));
+    }
+
+    return errors;
+}
+
+export function validate(skillDir: string): string[] {
+    const skillPath = path.resolve(skillDir);
+
+    if (!fs.existsSync(skillPath)) {
+        return [`Path does not exist: ${skillPath}`];
+    }
+
+    if (!fs.statSync(skillPath).isDirectory()) {
+        return [`Not a directory: ${skillPath}`];
+    }
+
+    const skillMdPath = findSkillMd(skillPath);
+    if (!skillMdPath) {
+        return ["Missing required file: SKILL.md"];
+    }
+
+    try {
+        const content = fs.readFileSync(skillMdPath, "utf8");
+        const { metadata } = parseFrontmatter(content);
+        return validateMetadata(metadata, skillPath);
+    } catch (error) {
+        return [error instanceof Error ? error.message : String(error)];
+    }
+}

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "moduleResolution": "node",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/*.test.ts"
+  ]
+}