@codemcp/agentskills-core 0.0.4

package/dist/registry.js

@@ -0,0 +1,180 @@
+/**
+ * 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 { promises as fs } from "fs";
+import { join, basename } from "path";
+import { parseSkill } from "./parser.js";
+import { validateSkill } from "./validator.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 class SkillRegistry {
+    skills = new Map();
+    skillsDir = "";
+    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
+     */
+    async loadSkills(skillsDir) {
+        // Clear existing skills
+        this.skills.clear();
+        this.skillsDir = "";
+        // 1. Check if skillsDir exists
+        let stat;
+        try {
+            stat = await fs.stat(skillsDir);
+        }
+        catch {
+            throw new Error(`Skills directory does not exist: ${skillsDir}`);
+        }
+        // 2. Check if it's a directory
+        if (!stat.isDirectory()) {
+            throw new Error(`Skills directory is not a directory: ${skillsDir}`);
+        }
+        // 3. Read immediate subdirectories (depth 1 only)
+        const entries = await fs.readdir(skillsDir, { withFileTypes: true });
+        let loadedCount = 0;
+        // 4. Process each subdirectory
+        for (const entry of entries) {
+            // Skip non-directories
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            // Skip hidden directories
+            if (entry.name.startsWith(".")) {
+                continue;
+            }
+            const skillDir = join(skillsDir, entry.name);
+            const skillPath = join(skillDir, "SKILL.md");
+            // Check for SKILL.md
+            let skillStat;
+            try {
+                skillStat = await fs.stat(skillPath);
+            }
+            catch {
+                throw new Error(`Missing SKILL.md in: ${skillDir}`);
+            }
+            // Verify SKILL.md is a file
+            if (!skillStat.isFile()) {
+                throw new Error(`Missing SKILL.md in: ${skillDir}`);
+            }
+            // Parse SKILL.md
+            const parseResult = await parseSkill(skillPath);
+            if (!parseResult.success) {
+                throw new Error(`Failed to parse SKILL.md in ${skillDir}: ${parseResult.error.message}`);
+            }
+            const { skill } = parseResult;
+            // Validate the skill
+            const validationResult = validateSkill(skill);
+            if (!validationResult.valid) {
+                const errorMessages = validationResult.errors
+                    .map((e) => e.message)
+                    .join(", ");
+                throw new Error(`Validation failed for ${skillDir}: ${errorMessages}`);
+            }
+            // Verify directory name matches skill name
+            const dirName = basename(skillDir);
+            if (skill.metadata.name !== dirName) {
+                throw new Error(`Directory name '${dirName}' does not match skill name '${skill.metadata.name}' in ${skillPath}`);
+            }
+            // Store the skill
+            this.skills.set(skill.metadata.name, { skill, sourcePath: skillPath });
+            loadedCount++;
+        }
+        // Update state
+        this.skillsDir = skillsDir;
+        this.lastLoaded = new Date();
+        return {
+            loaded: loadedCount,
+            skillsDir: skillsDir,
+            timestamp: this.lastLoaded
+        };
+    }
+    /**
+     * Get a skill by name
+     *
+     * @param name - The skill name
+     * @returns The skill or undefined if not found
+     */
+    getSkill(name) {
+        const entry = this.skills.get(name);
+        if (!entry) {
+            return undefined;
+        }
+        // Return a deep copy to maintain immutability
+        return {
+            metadata: { ...entry.skill.metadata },
+            body: entry.skill.body
+        };
+    }
+    /**
+     * Get all loaded skills
+     *
+     * @returns Array of all skills
+     */
+    getAllSkills() {
+        return Array.from(this.skills.values()).map((entry) => ({
+            metadata: { ...entry.skill.metadata },
+            body: entry.skill.body
+        }));
+    }
+    /**
+     * Get skill metadata without body content
+     *
+     * @param name - The skill name
+     * @returns The skill metadata or undefined if not found
+     */
+    getSkillMetadata(name) {
+        const entry = this.skills.get(name);
+        if (!entry) {
+            return undefined;
+        }
+        return { ...entry.skill.metadata };
+    }
+    /**
+     * Get all skill metadata without body content
+     *
+     * @returns Array of all skill metadata
+     */
+    getAllMetadata() {
+        return Array.from(this.skills.values()).map((entry) => ({
+            ...entry.skill.metadata
+        }));
+    }
+    /**
+     * Get current registry state
+     *
+     * @returns Current state with counts and source info
+     */
+    getState() {
+        return {
+            skillCount: this.skills.size,
+            skillsDir: this.skillsDir,
+            lastLoaded: this.lastLoaded
+        };
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Type definitions for Agent Skills Parser
+ *
+ * These types define the structure of parsed Agent Skills following
+ * the Agent Skills standard and Claude Code extensions.
+ */
+/**
+ * Metadata extracted from skill YAML frontmatter
+ */
+export interface SkillMetadata {
+    name: string;
+    description: string;
+    license?: string;
+    compatibility?: string;
+    metadata?: Record<string, unknown>;
+    allowedTools?: string[];
+    disableModelInvocation?: boolean;
+    userInvocable?: boolean;
+    argumentHint?: string;
+    context?: string;
+    agent?: string;
+    model?: string;
+    hooks?: Record<string, string>;
+}
+/**
+ * Parsed skill with metadata and body content
+ */
+export interface Skill {
+    metadata: SkillMetadata;
+    body: string;
+}
+/**
+ * Error codes for parsing failures
+ */
+export type ParseErrorCode = "EMPTY_FILE" | "MISSING_FRONTMATTER" | "INVALID_YAML" | "MISSING_REQUIRED_FIELD" | "FILE_NOT_FOUND" | "FILE_READ_ERROR";
+/**
+ * Error information for parsing failures
+ */
+export interface ParseError {
+    code: ParseErrorCode;
+    message: string;
+    field?: string;
+}
+/**
+ * Successful parse result
+ */
+export interface ParseSuccess {
+    success: true;
+    skill: Skill;
+}
+/**
+ * Failed parse result
+ */
+export interface ParseFailure {
+    success: false;
+    error: ParseError;
+}
+/**
+ * Result of parsing a skill (discriminated union)
+ */
+export type ParseResult = ParseSuccess | ParseFailure;
+/**
+ * Error codes for validation failures
+ */
+export type ValidationErrorCode = "MISSING_FIELD" | "INVALID_NAME_LENGTH" | "INVALID_NAME_FORMAT" | "INVALID_DESCRIPTION_LENGTH" | "INVALID_COMPATIBILITY_LENGTH" | "INVALID_FIELD_TYPE";
+/**
+ * Warning codes for non-blocking validation issues
+ */
+export type ValidationWarningCode = "MISSING_RECOMMENDED_FIELD" | "SHORT_DESCRIPTION" | "LONG_CONTENT";
+/**
+ * Validation error information
+ */
+export interface ValidationError {
+    code: ValidationErrorCode;
+    message: string;
+    field?: string;
+}
+/**
+ * Validation warning information
+ */
+export interface ValidationWarning {
+    code: ValidationWarningCode;
+    message: string;
+    field?: string;
+}
+/**
+ * Result of validating a skill
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+}
+/**
+ * Result of loading skills into registry
+ *
+ * Note: Loading is strict - any error throws exception.
+ * No partial failures allowed (fail fast on misconfiguration).
+ */
+export interface LoadResult {
+    loaded: number;
+    skillsDir: string;
+    timestamp: Date;
+}
+/**
+ * Current state of the registry
+ */
+export interface RegistryState {
+    skillCount: number;
+    skillsDir: string;
+    lastLoaded?: Date;
+}
+/**
+ * Error codes for installation failures
+ */
+export type InstallErrorCode = "INVALID_SPEC" | "INSTALL_FAILED" | "NETWORK_ERROR" | "MISSING_SKILL_MD" | "INVALID_SKILL_FORMAT" | "PERMISSION_ERROR";
+/**
+ * Error information for installation failures
+ */
+export interface InstallError {
+    code: InstallErrorCode;
+    message: string;
+}
+/**
+ * Skill manifest extracted from installed package
+ */
+export interface SkillManifest {
+    name: string;
+    description: string;
+    license?: string;
+    compatibility?: string;
+    packageName?: string;
+    version?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Successful installation result
+ */
+export interface InstallSuccess {
+    success: true;
+    name: string;
+    spec: string;
+    resolvedVersion: string;
+    integrity: string;
+    installPath: string;
+    manifest?: SkillManifest;
+}
+/**
+ * Failed installation result
+ */
+export interface InstallFailure {
+    success: false;
+    name?: string;
+    spec?: string;
+    error?: InstallError;
+}
+/**
+ * Result of installing a single skill (discriminated union)
+ */
+export type InstallResult = InstallSuccess | InstallFailure;
+/**
+ * Result of installing multiple skills
+ */
+export interface InstallAllResult {
+    success: boolean;
+    installed: Set<string>;
+    failed: Set<string>;
+    results: Record<string, InstallResult>;
+}
+/**
+ * Lock file entry for a single skill
+ */
+export interface SkillLockEntry {
+    spec: string;
+    resolvedVersion: string;
+    integrity: string;
+}
+/**
+ * Lock file structure for reproducible installations
+ */
+export interface SkillLockFile {
+    version: string;
+    generated: string;
+    skills: Record<string, SkillLockEntry>;
+}
+/**
+ * Package configuration for agent skills
+ */
+export interface PackageConfig {
+    skills: Record<string, string>;
+    config: {
+        skillsDirectory: string;
+        autoDiscover: string[];
+        maxSkillSize: number;
+        logLevel: "error" | "warn" | "info" | "debug";
+    };
+    source: {
+        type: "file" | "defaults";
+        path?: string;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Type definitions for Agent Skills Parser
+ *
+ * These types define the structure of parsed Agent Skills following
+ * the Agent Skills standard and Claude Code extensions.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/validator.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Skill Validator
+ *
+ * Validates Agent Skills format against specification.
+ * This is a stub implementation - tests define the expected behavior.
+ *
+ * Implementation to be completed following TDD approach.
+ */
+import type { Skill, ValidationResult } from "./types.js";
+/**
+ * Validate a skill against Agent Skills specification
+ *
+ * Validates:
+ * - Required fields: name (1-64 chars, lowercase-hyphens), description (1-1024 chars)
+ * - Optional fields: license, compatibility (1-500 chars), metadata, allowedTools
+ * - Name format: lowercase letters, numbers, hyphens only, no leading/trailing/consecutive hyphens
+ *
+ * Returns ValidationResult with:
+ * - valid: boolean indicating if skill passes validation
+ * - errors: array of blocking validation errors
+ * - warnings: array of non-blocking issues
+ *
+ * @param skill - The skill to validate
+ * @returns ValidationResult with validation status, errors, and warnings
+ */
+export declare function validateSkill(skill: Skill): ValidationResult;
+//# 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":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,gBAAgB,CA8J5D"}

package/dist/validator.js

@@ -0,0 +1,165 @@
+/**
+ * Skill Validator
+ *
+ * Validates Agent Skills format against specification.
+ * This is a stub implementation - tests define the expected behavior.
+ *
+ * Implementation to be completed following TDD approach.
+ */
+/**
+ * Validate a skill against Agent Skills specification
+ *
+ * Validates:
+ * - Required fields: name (1-64 chars, lowercase-hyphens), description (1-1024 chars)
+ * - Optional fields: license, compatibility (1-500 chars), metadata, allowedTools
+ * - Name format: lowercase letters, numbers, hyphens only, no leading/trailing/consecutive hyphens
+ *
+ * Returns ValidationResult with:
+ * - valid: boolean indicating if skill passes validation
+ * - errors: array of blocking validation errors
+ * - warnings: array of non-blocking issues
+ *
+ * @param skill - The skill to validate
+ * @returns ValidationResult with validation status, errors, and warnings
+ */
+export function validateSkill(skill) {
+    const errors = [];
+    const warnings = [];
+    // Extract metadata for validation
+    const { name, description, compatibility, metadata, allowedTools, license } = skill.metadata;
+    // Validate name - required field
+    if (name === undefined || name === null) {
+        errors.push({
+            code: "MISSING_FIELD",
+            field: "name",
+            message: "Field 'name' is required"
+        });
+    }
+    else {
+        const trimmedName = name.trim();
+        // Check name length (after trimming)
+        if (trimmedName.length < 1 || trimmedName.length > 64) {
+            errors.push({
+                code: "INVALID_NAME_LENGTH",
+                field: "name",
+                message: "Name must be between 1 and 64 characters"
+            });
+        }
+        // Check name format if not empty
+        if (trimmedName.length > 0) {
+            // Check for leading hyphen
+            if (trimmedName.startsWith("-")) {
+                errors.push({
+                    code: "INVALID_NAME_FORMAT",
+                    field: "name",
+                    message: "Name must not start with a leading hyphen"
+                });
+            }
+            // Check for trailing hyphen
+            if (trimmedName.endsWith("-")) {
+                errors.push({
+                    code: "INVALID_NAME_FORMAT",
+                    field: "name",
+                    message: "Name must not end with a trailing hyphen"
+                });
+            }
+            // Check for consecutive hyphens
+            if (trimmedName.includes("--")) {
+                errors.push({
+                    code: "INVALID_NAME_FORMAT",
+                    field: "name",
+                    message: "Name must not contain consecutive hyphens"
+                });
+            }
+            // Check for valid characters (lowercase letters, numbers, hyphens only)
+            const validNamePattern = /^[a-z0-9-]+$/;
+            if (!validNamePattern.test(trimmedName)) {
+                errors.push({
+                    code: "INVALID_NAME_FORMAT",
+                    field: "name",
+                    message: "Name must contain only lowercase letters, numbers, and hyphens"
+                });
+            }
+        }
+    }
+    // Validate description - required field
+    if (description === undefined || description === null) {
+        errors.push({
+            code: "MISSING_FIELD",
+            field: "description",
+            message: "Field 'description' is required"
+        });
+    }
+    else {
+        const trimmedDescription = description.trim();
+        // Check description length (after trimming)
+        if (trimmedDescription.length < 1 || trimmedDescription.length > 1024) {
+            errors.push({
+                code: "INVALID_DESCRIPTION_LENGTH",
+                field: "description",
+                message: "Description must be between 1 and 1024 characters"
+            });
+        }
+        // Warning: short description
+        if (trimmedDescription.length > 0 && trimmedDescription.length < 50) {
+            warnings.push({
+                code: "SHORT_DESCRIPTION",
+                field: "description",
+                message: "Description should be at least 50 characters for clarity"
+            });
+        }
+    }
+    // Validate compatibility - optional field
+    if (compatibility !== undefined) {
+        if (compatibility.length > 500) {
+            errors.push({
+                code: "INVALID_COMPATIBILITY_LENGTH",
+                field: "compatibility",
+                message: "Compatibility must not exceed 500 characters"
+            });
+        }
+    }
+    // Validate metadata - optional field, must be object if present
+    if (metadata !== undefined) {
+        if (metadata === null ||
+            Array.isArray(metadata) ||
+            typeof metadata !== "object") {
+            errors.push({
+                code: "INVALID_FIELD_TYPE",
+                field: "metadata",
+                message: "Metadata must be an object"
+            });
+        }
+    }
+    // Validate allowedTools - optional field, must be array if present
+    if (allowedTools !== undefined) {
+        if (allowedTools === null || !Array.isArray(allowedTools)) {
+            errors.push({
+                code: "INVALID_FIELD_TYPE",
+                field: "allowedTools",
+                message: "AllowedTools must be an array"
+            });
+        }
+    }
+    // Warning: missing license (recommended field)
+    if (license === undefined) {
+        warnings.push({
+            code: "MISSING_RECOMMENDED_FIELD",
+            field: "license",
+            message: "License field is recommended for skills"
+        });
+    }
+    // Warning: long body content (> 20000 chars ≈ 5000 tokens)
+    if (skill.body && skill.body.length > 20000) {
+        warnings.push({
+            code: "LONG_CONTENT",
+            message: "Body content exceeds 5000 tokens estimate, which may impact performance"
+        });
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings
+    };
+}
+//# 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,56 @@
+{
+  "name": "@codemcp/agentskills-core",
+  "version": "0.0.4",
+  "description": "Core functionality for Agent Skills parsing, validation, and discovery",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "gray-matter": "4.0.3",
+    "js-yaml": "^4.1.0",
+    "pacote": "21.3.1"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.10.7",
+    "@types/pacote": "11.1.8",
+    "@typescript-eslint/eslint-plugin": "^8.21.0",
+    "@typescript-eslint/parser": "^8.21.0",
+    "eslint": "^9.18.0",
+    "eslint-config-prettier": "^10.0.1",
+    "prettier": "^3.4.2",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "8.21.0",
+    "vitest": "^3.0.3"
+  },
+  "keywords": [
+    "agentskills",
+    "skills",
+    "parser",
+    "validator"
+  ],
+  "author": "Oliver Jägle <github@beimir.net>",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "clean:build": "rimraf dist",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --check .",
+    "format:fix": "prettier --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}