@codemcp/agentskills-core 0.0.4

package/dist/package-config.js

@@ -0,0 +1,267 @@
+import { promises as fs } from "fs";
+import { join } from "path";
+/**
+ * PackageConfigManager - Manages package.json configuration for agent skills
+ *
+ * Responsibilities:
+ * - Read package.json from a directory
+ * - Parse `agentskills` field (skill dependencies)
+ * - Parse `agentskillsConfig` field (configuration settings)
+ * - Provide defaults when package.json doesn't exist
+ * - Provide defaults when fields are missing
+ * - Validate configuration structure
+ * - Save/update skills in package.json
+ */
+export class PackageConfigManager {
+    projectRoot;
+    packageJsonPath;
+    constructor(projectRoot) {
+        if (!projectRoot) {
+            throw new Error("Project root directory is required");
+        }
+        this.projectRoot = projectRoot;
+        this.packageJsonPath = join(projectRoot, "package.json");
+    }
+    /**
+     * Get default configuration with empty skills and standard defaults
+     */
+    getDefaultConfig() {
+        return {
+            skills: {},
+            config: {
+                skillsDirectory: ".agentskills/skills",
+                autoDiscover: [".claude/skills"],
+                maxSkillSize: 5000,
+                logLevel: "info"
+            },
+            source: {
+                type: "defaults"
+            }
+        };
+    }
+    /**
+     * Load configuration from package.json
+     * Returns defaults if package.json doesn't exist
+     */
+    async loadConfig() {
+        try {
+            const content = await fs.readFile(this.packageJsonPath, "utf-8");
+            let packageJson;
+            try {
+                packageJson = JSON.parse(content);
+            }
+            catch (error) {
+                throw new Error(`Failed to parse package.json: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            // Validate and extract agentskills
+            const skills = this.validateAndExtractSkills(packageJson);
+            // Validate and extract agentskillsConfig
+            const config = this.validateAndExtractConfig(packageJson);
+            return {
+                skills,
+                config,
+                source: {
+                    type: "file",
+                    path: this.packageJsonPath
+                }
+            };
+        }
+        catch (error) {
+            // Return defaults if file doesn't exist
+            if (error.code === "ENOENT") {
+                return this.getDefaultConfig();
+            }
+            // Handle permission errors
+            if (error.code === "EACCES") {
+                throw new Error(`Permission denied reading package.json at ${this.packageJsonPath}`);
+            }
+            // Re-throw other errors (like parse errors)
+            throw error;
+        }
+    }
+    /**
+     * Validate and extract skills from package.json
+     */
+    validateAndExtractSkills(packageJson) {
+        if (!packageJson.agentskills) {
+            return {};
+        }
+        const agentskills = packageJson.agentskills;
+        // Validate agentskills is an object
+        if (typeof agentskills !== "object" ||
+            agentskills === null ||
+            Array.isArray(agentskills)) {
+            throw new Error("agentskills must be an object");
+        }
+        // Validate all values are strings
+        for (const value of Object.values(agentskills)) {
+            if (typeof value !== "string") {
+                throw new Error("agentskills values must be strings");
+            }
+        }
+        return agentskills;
+    }
+    /**
+     * Validate and extract config from package.json
+     */
+    validateAndExtractConfig(packageJson) {
+        const defaultConfig = this.getDefaultConfig().config;
+        if (!packageJson.agentskillsConfig) {
+            return defaultConfig;
+        }
+        const agentskillsConfig = packageJson.agentskillsConfig;
+        // Validate agentskillsConfig is an object
+        if (typeof agentskillsConfig !== "object" ||
+            agentskillsConfig === null ||
+            Array.isArray(agentskillsConfig)) {
+            throw new Error("agentskillsConfig must be an object");
+        }
+        // Type assertion after validation
+        const configObj = agentskillsConfig;
+        // Start with defaults and merge
+        const config = { ...defaultConfig };
+        // Validate and merge skillsDirectory
+        if (configObj.skillsDirectory !== undefined) {
+            if (typeof configObj.skillsDirectory !== "string") {
+                throw new Error("skillsDirectory must be a string");
+            }
+            if (configObj.skillsDirectory === "") {
+                throw new Error("skillsDirectory cannot be empty");
+            }
+            config.skillsDirectory = configObj.skillsDirectory;
+        }
+        // Validate and merge autoDiscover
+        if (configObj.autoDiscover !== undefined) {
+            if (!Array.isArray(configObj.autoDiscover)) {
+                throw new Error("autoDiscover must be an array");
+            }
+            for (const item of configObj.autoDiscover) {
+                if (typeof item !== "string") {
+                    throw new Error("autoDiscover must contain only strings");
+                }
+            }
+            config.autoDiscover = configObj.autoDiscover;
+        }
+        // Validate and merge maxSkillSize
+        if (configObj.maxSkillSize !== undefined) {
+            if (typeof configObj.maxSkillSize !== "number") {
+                throw new Error("maxSkillSize must be a number");
+            }
+            if (configObj.maxSkillSize <= 0) {
+                throw new Error("maxSkillSize must be a positive number");
+            }
+            config.maxSkillSize = configObj.maxSkillSize;
+        }
+        // Validate and merge logLevel
+        if (configObj.logLevel !== undefined) {
+            if (typeof configObj.logLevel !== "string") {
+                throw new Error("logLevel must be a string");
+            }
+            const validLogLevels = ["error", "warn", "info", "debug"];
+            if (!validLogLevels.includes(configObj.logLevel)) {
+                throw new Error(`Invalid logLevel '${configObj.logLevel}'. Must be one of: error, warn, info, debug`);
+            }
+            config.logLevel = configObj.logLevel;
+        }
+        return config;
+    }
+    /**
+     * Save skills to package.json
+     * Creates package.json if it doesn't exist
+     * Preserves other fields
+     */
+    async saveSkills(skills) {
+        let packageJson;
+        try {
+            const content = await fs.readFile(this.packageJsonPath, "utf-8");
+            packageJson = JSON.parse(content);
+        }
+        catch (error) {
+            if (error &&
+                typeof error === "object" &&
+                "code" in error &&
+                error.code === "ENOENT") {
+                // Create minimal package.json
+                packageJson = {
+                    name: "agentskills-project"
+                };
+            }
+            else {
+                throw error;
+            }
+        }
+        // Update agentskills field
+        packageJson.agentskills = skills;
+        // Write back to file with proper formatting
+        await fs.writeFile(this.packageJsonPath, JSON.stringify(packageJson, null, 2), "utf-8");
+    }
+    /**
+     * Add a single skill to package.json
+     * Updates existing skill if name already exists
+     */
+    async addSkill(name, spec) {
+        if (!name) {
+            throw new Error("Skill name cannot be empty");
+        }
+        if (!spec) {
+            throw new Error("Skill spec cannot be empty");
+        }
+        let packageJson;
+        try {
+            const content = await fs.readFile(this.packageJsonPath, "utf-8");
+            packageJson = JSON.parse(content);
+        }
+        catch (error) {
+            if (error &&
+                typeof error === "object" &&
+                "code" in error &&
+                error.code === "ENOENT") {
+                // Create minimal package.json
+                packageJson = {
+                    name: "agentskills-project"
+                };
+            }
+            else {
+                throw error;
+            }
+        }
+        // Initialize agentskills if it doesn't exist
+        if (!packageJson.agentskills) {
+            packageJson.agentskills = {};
+        }
+        // Add or update skill - use type assertion after validation
+        const agentskills = packageJson.agentskills;
+        agentskills[name] = spec;
+        // Write back to file with proper formatting
+        await fs.writeFile(this.packageJsonPath, JSON.stringify(packageJson, null, 2), "utf-8");
+    }
+    /**
+     * Remove a skill from package.json
+     * Does not error if skill doesn't exist or file doesn't exist
+     */
+    async removeSkill(name) {
+        if (!name) {
+            throw new Error("Skill name cannot be empty");
+        }
+        try {
+            const content = await fs.readFile(this.packageJsonPath, "utf-8");
+            const packageJson = JSON.parse(content);
+            // If agentskills doesn't exist, nothing to remove
+            if (!packageJson.agentskills) {
+                return;
+            }
+            // Remove skill
+            delete packageJson.agentskills[name];
+            // Write back to file with proper formatting
+            await fs.writeFile(this.packageJsonPath, JSON.stringify(packageJson, null, 2), "utf-8");
+        }
+        catch (error) {
+            // If file doesn't exist, nothing to remove
+            if (error.code === "ENOENT") {
+                return;
+            }
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=package-config.js.map

package/dist/package-config.js.map

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

package/dist/parser.d.ts

@@ -0,0 +1,59 @@
+/**
+ * SkillParser Component
+ *
+ * Responsibility: Parse SKILL.md files into structured Skill objects
+ * following the Agent Skills standard and Claude Code extensions.
+ *
+ * This module provides two main functions:
+ * - parseSkillContent: Parse skill content string directly
+ * - parseSkill: Read and parse a skill file from the filesystem
+ */
+import type { ParseResult } from "./types.js";
+/**
+ * Parse skill content from a string
+ *
+ * Extracts YAML frontmatter and Markdown body, validates required fields,
+ * and returns a structured Skill object.
+ *
+ * @param content - Raw skill file content (YAML frontmatter + Markdown body)
+ * @returns ParseResult with either success (Skill) or failure (ParseError)
+ *
+ * @example
+ * ```typescript
+ * const content = `---
+ * name: example-skill
+ * description: An example skill
+ * ---
+ * # Example Skill
+ *
+ * This is the skill body.
+ * `;
+ *
+ * const result = parseSkillContent(content);
+ * if (result.success) {
+ *   console.log(result.skill.metadata.name); // "example-skill"
+ * }
+ * ```
+ */
+export declare function parseSkillContent(content: string): ParseResult;
+/**
+ * Read and parse a skill file from the filesystem
+ *
+ * Reads the file at the given path, then delegates to parseSkillContent
+ * for parsing. Handles file system errors gracefully.
+ *
+ * @param filePath - Absolute path to SKILL.md file
+ * @returns ParseResult with either success (Skill) or failure (ParseError)
+ *
+ * @example
+ * ```typescript
+ * const result = await parseSkill('/path/to/SKILL.md');
+ * if (result.success) {
+ *   console.log(result.skill.metadata.name);
+ * } else {
+ *   console.error(result.error.message);
+ * }
+ * ```
+ */
+export declare function parseSkill(filePath: string): Promise<ParseResult>;
+//# 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":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EACV,WAAW,EAKZ,MAAM,YAAY,CAAC;AAsDpB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CAiD9D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA0BvE"}

package/dist/parser.js

@@ -0,0 +1,154 @@
+/**
+ * SkillParser Component
+ *
+ * Responsibility: Parse SKILL.md files into structured Skill objects
+ * following the Agent Skills standard and Claude Code extensions.
+ *
+ * This module provides two main functions:
+ * - parseSkillContent: Parse skill content string directly
+ * - parseSkill: Read and parse a skill file from the filesystem
+ */
+import matter from "gray-matter";
+import { promises as fs } from "fs";
+/**
+ * Field name mapping from kebab-case (YAML) to camelCase (TypeScript)
+ */
+const FIELD_MAP = {
+    name: "name",
+    description: "description",
+    license: "license",
+    compatibility: "compatibility",
+    metadata: "metadata",
+    "allowed-tools": "allowedTools",
+    "disable-model-invocation": "disableModelInvocation",
+    "user-invocable": "userInvocable",
+    "argument-hint": "argumentHint",
+    context: "context",
+    agent: "agent",
+    model: "model",
+    hooks: "hooks"
+};
+/**
+ * Required fields that must be present in skill metadata
+ */
+const REQUIRED_FIELDS = ["name", "description"];
+/**
+ * Helper function to create error result
+ */
+function createError(code, message, field) {
+    return {
+        success: false,
+        error: { code, message, ...(field && { field }) }
+    };
+}
+/**
+ * Map YAML field names (kebab-case) to TypeScript field names (camelCase)
+ */
+function mapFieldNames(data) {
+    const metadata = {};
+    for (const [key, value] of Object.entries(data)) {
+        const mappedKey = FIELD_MAP[key] || key;
+        metadata[mappedKey] = value;
+    }
+    return metadata;
+}
+/**
+ * Parse skill content from a string
+ *
+ * Extracts YAML frontmatter and Markdown body, validates required fields,
+ * and returns a structured Skill object.
+ *
+ * @param content - Raw skill file content (YAML frontmatter + Markdown body)
+ * @returns ParseResult with either success (Skill) or failure (ParseError)
+ *
+ * @example
+ * ```typescript
+ * const content = `---
+ * name: example-skill
+ * description: An example skill
+ * ---
+ * # Example Skill
+ *
+ * This is the skill body.
+ * `;
+ *
+ * const result = parseSkillContent(content);
+ * if (result.success) {
+ *   console.log(result.skill.metadata.name); // "example-skill"
+ * }
+ * ```
+ */
+export function parseSkillContent(content) {
+    // Check for empty file
+    if (!content || content.trim().length === 0) {
+        return createError("EMPTY_FILE", "Skill file is empty");
+    }
+    // Parse frontmatter using gray-matter
+    let parsed;
+    try {
+        parsed = matter(content);
+    }
+    catch (error) {
+        return createError("INVALID_YAML", `Failed to parse YAML frontmatter: ${error.message}`);
+    }
+    // Check if frontmatter exists
+    if (!parsed.data || Object.keys(parsed.data).length === 0) {
+        return createError("MISSING_FRONTMATTER", "Skill file must contain YAML frontmatter");
+    }
+    // Validate required fields
+    for (const field of REQUIRED_FIELDS) {
+        if (!(field in parsed.data)) {
+            return createError("MISSING_REQUIRED_FIELD", `required field '${field}' is missing from skill metadata`, field);
+        }
+    }
+    // Map field names from kebab-case to camelCase
+    const metadata = mapFieldNames(parsed.data);
+    // Create Skill object
+    const skill = Object.freeze({
+        metadata: Object.freeze(metadata),
+        body: parsed.content
+    });
+    return {
+        success: true,
+        skill
+    };
+}
+/**
+ * Read and parse a skill file from the filesystem
+ *
+ * Reads the file at the given path, then delegates to parseSkillContent
+ * for parsing. Handles file system errors gracefully.
+ *
+ * @param filePath - Absolute path to SKILL.md file
+ * @returns ParseResult with either success (Skill) or failure (ParseError)
+ *
+ * @example
+ * ```typescript
+ * const result = await parseSkill('/path/to/SKILL.md');
+ * if (result.success) {
+ *   console.log(result.skill.metadata.name);
+ * } else {
+ *   console.error(result.error.message);
+ * }
+ * ```
+ */
+export async function parseSkill(filePath) {
+    try {
+        const content = await fs.readFile(filePath, "utf-8");
+        return parseSkillContent(content);
+    }
+    catch (error) {
+        const nodeError = error;
+        // File not found error
+        if (nodeError.code === "ENOENT") {
+            return createError("FILE_NOT_FOUND", `File not found: ${filePath}`);
+        }
+        // Permission or other read errors
+        if (nodeError.code === "EACCES" || nodeError.code === "EISDIR") {
+            return createError("FILE_READ_ERROR", `Failed to read file: ${nodeError.message}`);
+        }
+        // Other errors
+        return createError("FILE_READ_ERROR", `Failed to read file: ${nodeError.message}`);
+    }
+}
+//# sourceMappingURL=parser.js.map

package/dist/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,IAAI,CAAC;AASpC;;GAEG;AACH,MAAM,SAAS,GAA2B;IACxC,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,aAAa;IAC1B,OAAO,EAAE,SAAS;IAClB,aAAa,EAAE,eAAe;IAC9B,QAAQ,EAAE,UAAU;IACpB,eAAe,EAAE,cAAc;IAC/B,0BAA0B,EAAE,wBAAwB;IACpD,gBAAgB,EAAE,eAAe;IACjC,eAAe,EAAE,cAAc;IAC/B,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;CACf,CAAC;AAEF;;GAEG;AACH,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,aAAa,CAAU,CAAC;AAEzD;;GAEG;AACH,SAAS,WAAW,CAClB,IAAoB,EACpB,OAAe,EACf,KAAc;IAEd,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,KAAK,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE;KAClD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,aAAa,CAAC,IAA6B;IAClD,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAE7C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC;QACxC,QAAQ,CAAC,SAAS,CAAC,GAAG,KAAK,CAAC;IAC9B,CAAC;IAED,OAAO,QAAoC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,uBAAuB;IACvB,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5C,OAAO,WAAW,CAAC,YAAY,EAAE,qBAAqB,CAAC,CAAC;IAC1D,CAAC;IAED,sCAAsC;IACtC,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,WAAW,CAChB,cAAc,EACd,qCAAsC,KAAe,CAAC,OAAO,EAAE,CAChE,CAAC;IACJ,CAAC;IAED,8BAA8B;IAC9B,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1D,OAAO,WAAW,CAChB,qBAAqB,EACrB,0CAA0C,CAC3C,CAAC;IACJ,CAAC;IAED,2BAA2B;IAC3B,KAAK,MAAM,KAAK,IAAI,eAAe,EAAE,CAAC;QACpC,IAAI,CAAC,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5B,OAAO,WAAW,CAChB,wBAAwB,EACxB,mBAAmB,KAAK,kCAAkC,EAC1D,KAAK,CACN,CAAC;QACJ,CAAC;IACH,CAAC;IAED,+CAA+C;IAC/C,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAE5C,sBAAsB;IACtB,MAAM,KAAK,GAAU,MAAM,CAAC,MAAM,CAAC;QACjC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC;QACjC,IAAI,EAAE,MAAM,CAAC,OAAO;KACrB,CAAC,CAAC;IAEH,OAAO;QACL,OAAO,EAAE,IAAI;QACb,KAAK;KACN,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAAgB;IAC/C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACrD,OAAO,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,SAAS,GAAG,KAA8B,CAAC;QAEjD,uBAAuB;QACvB,IAAI,SAAS,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAChC,OAAO,WAAW,CAAC,gBAAgB,EAAE,mBAAmB,QAAQ,EAAE,CAAC,CAAC;QACtE,CAAC;QAED,kCAAkC;QAClC,IAAI,SAAS,CAAC,IAAI,KAAK,QAAQ,IAAI,SAAS,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC/D,OAAO,WAAW,CAChB,iBAAiB,EACjB,wBAAwB,SAAS,CAAC,OAAO,EAAE,CAC5C,CAAC;QACJ,CAAC;QAED,eAAe;QACf,OAAO,WAAW,CAChB,iBAAiB,EACjB,wBAAwB,SAAS,CAAC,OAAO,EAAE,CAC5C,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,72 @@
+/**
+ * SkillRegistry Component
+ *
+ * Responsibility: In-memory skill storage with Map-based O(1) lookups.
+ * Load skills from a single directory with strict fail-fast behavior.
+ *
+ * Expected structure: <skillsDir>/<skill-name>/SKILL.md (exactly 2 levels deep)
+ * Throws errors on any misconfiguration (no partial failures).
+ */
+import type { Skill, SkillMetadata, LoadResult, RegistryState } from "./types.js";
+/**
+ * In-memory registry for managing agent skills
+ *
+ * Features:
+ * - O(1) skill lookups using Map
+ * - Load skills from single directory (strict fail-fast)
+ * - Expected structure: <skillsDir>/<skill-name>/SKILL.md
+ * - Validates directory name matches skill name
+ * - Immutable skill objects
+ */
+export declare class SkillRegistry {
+    private skills;
+    private skillsDir;
+    private lastLoaded?;
+    /**
+     * Load skills from a single directory with strict error handling
+     *
+     * Expected structure: <skillsDir>/<skill-name>/SKILL.md (exactly 2 levels deep)
+     * - Throws on any error (fail fast)
+     * - Ignores hidden directories (.git/, etc.)
+     * - Ignores non-directory files
+     * - Validates directory name matches skill name in SKILL.md
+     *
+     * @param skillsDir - Directory containing skill subdirectories
+     * @returns Load result with count, directory, and timestamp
+     * @throws Error if directory doesn't exist, isn't a directory, or any skill is invalid
+     */
+    loadSkills(skillsDir: string): Promise<LoadResult>;
+    /**
+     * Get a skill by name
+     *
+     * @param name - The skill name
+     * @returns The skill or undefined if not found
+     */
+    getSkill(name: string): Skill | undefined;
+    /**
+     * Get all loaded skills
+     *
+     * @returns Array of all skills
+     */
+    getAllSkills(): Skill[];
+    /**
+     * Get skill metadata without body content
+     *
+     * @param name - The skill name
+     * @returns The skill metadata or undefined if not found
+     */
+    getSkillMetadata(name: string): SkillMetadata | undefined;
+    /**
+     * Get all skill metadata without body content
+     *
+     * @returns Array of all skill metadata
+     */
+    getAllMetadata(): SkillMetadata[];
+    /**
+     * Get current registry state
+     *
+     * @returns Current state with counts and source info
+     */
+    getState(): RegistryState;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EACV,KAAK,EACL,aAAa,EACb,UAAU,EACV,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;GASG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAgE;IAC9E,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,UAAU,CAAC,CAAO;IAE1B;;;;;;;;;;;;OAYG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAgGxD;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAazC;;;;OAIG;IACH,YAAY,IAAI,KAAK,EAAE;IAOvB;;;;;OAKG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IASzD;;;;OAIG;IACH,cAAc,IAAI,aAAa,EAAE;IAMjC;;;;OAIG;IACH,QAAQ,IAAI,aAAa;CAO1B"}