skills-reference 1.0.5 → 1.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skills-reference",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "type": "module",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -52,4 +52,4 @@
     "ts-node": "^10.9.2",
     "typescript": "^5.6.2"
   }
-}
+}

package/src/cli.ts

@@ -1,101 +0,0 @@
-#!/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

@@ -1,23 +0,0 @@
-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

@@ -1,5 +0,0 @@
-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

@@ -1,46 +0,0 @@
-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

@@ -1,113 +0,0 @@
-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

@@ -1,45 +0,0 @@
-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

@@ -1,176 +0,0 @@
-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)];
-    }
-}