@evalops/maestro 0.10.51 → 0.10.53

package/dist/skills/loader.js

@@ -1,957 +0,0 @@
-/**
- * Skills Loader - Dynamic skill discovery and loading system.
- *
- * Implements the Agent Skills specification (https://agentskills.io/specification).
- *
- * Skills are domain-specific instruction sets that provide:
- * - Detailed workflows and procedures
- * - Access to bundled resources (scripts, templates, references)
- * - Domain expertise for specialized tasks
- *
- * Skills are discovered from:
- * - ~/.maestro/skills/ (user skills)
- * - .maestro/skills/ (project skills)
- *
- * Each skill is a directory containing:
- * - SKILL.md or skill.md - Main skill file with YAML frontmatter
- * - Optional: scripts/, references/, assets/ directories
- */
-import { createHash } from "node:crypto";
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { load as loadYaml } from "js-yaml";
-import { PATHS } from "../config/constants.js";
-import { loadConfiguredPackageResources } from "../packages/runtime.js";
-import { createLogger } from "../utils/logger.js";
-import { promptSafeText } from "../utils/prompt-safe-text.js";
-const logger = createLogger("skills:loader");
-const LEGACY_FLAT_RESOURCE_EXCLUDES = new Set([
-    "scripts",
-    "reference",
-    "references",
-    "assets",
-    "toolbox",
-    "mcp.json",
-    "mcp.json.example",
-]);
-/** Maximum lengths per Agent Skills spec */
-const MAX_NAME_LENGTH = 64;
-const MAX_DESCRIPTION_LENGTH = 1024;
-const MAX_COMPATIBILITY_LENGTH = 500;
-/** Allowed frontmatter fields per Agent Skills spec */
-export const SKILL_FRONTMATTER_FIELDS = [
-    "name",
-    "description",
-    "license",
-    "compatibility",
-    "allowed-tools",
-    "argument-hint",
-    "builtin-tools",
-    "model",
-    "mode",
-    "isolatedContext",
-    "metadata",
-    // Legacy fields (deprecated but supported for backwards compatibility)
-    "tags",
-    "author",
-    "version",
-    "triggers",
-];
-/** Allowed frontmatter fields per Agent Skills spec plus Maestro package hints. */
-const ALLOWED_FIELDS = new Set(SKILL_FRONTMATTER_FIELDS);
-/**
- * Hash a single bundled resource file. Errors (missing file,
- * unreadable) yield a sentinel marker so the parent hash changes —
- * an unhashable resource invalidates the approval rather than
- * silently dropping out of the hash.
- */
-function hashSkillResourceFile(filePath) {
-    try {
-        return createHash("sha256").update(readFileSync(filePath)).digest("hex");
-    }
-    catch {
-        return "UNHASHABLE";
-    }
-}
-/**
- * Walk a directory tree and feed every regular file's (relative path,
- * content) pair into `hash` in a deterministic, alpha-sorted order.
- * Used by `computeSkillTrustSha` to bind every spec-layout resource
- * directory (`scripts/`, `toolbox/`, `assets/`, …) into the trust
- * digest, so swapping a bundled script while keeping the same skill
- * name and `SKILL.md` body invalidates the prior approval.
- *
- * Symlinks are followed: the runtime executes them, so the digest
- * should reflect what would actually run. The skills loader enforces
- * path confinement (#2746) separately, so any escape attempt is
- * rejected before we get here.
- */
-function hashSkillDirectoryInto(hash, rootDir, currentDir) {
-    let entries;
-    try {
-        entries = readdirSync(currentDir).sort();
-    }
-    catch {
-        return;
-    }
-    for (const entry of entries) {
-        const fullPath = join(currentDir, entry);
-        let stat;
-        try {
-            stat = statSync(fullPath);
-        }
-        catch {
-            continue;
-        }
-        const relPath = fullPath.slice(rootDir.length);
-        if (stat.isDirectory()) {
-            hash.update(`\0dir:${relPath}\0`);
-            hashSkillDirectoryInto(hash, rootDir, fullPath);
-        }
-        else if (stat.isFile()) {
-            hash.update(`\0file:${relPath}\0`);
-            hash.update(hashSkillResourceFile(fullPath));
-        }
-    }
-}
-/**
- * Bind the trust hash to (name + content + bundled resources + spec-
- * layout resource directories), not just content. The adversarial
- * review (#2629) showed that hashing content alone enables a
- * name-substitution attack: an attacker ships a malicious skill whose
- * BODY is byte-identical to a popular approved skill but registers a
- * different name and ships malicious scripts in `scripts/` (which the
- * agent invokes via the runtime activation manifest).
- *
- * A follow-up review (#2749) pointed out that the previous fix only
- * covered the legacy flat resources list — files under `scripts/`,
- * `toolbox/`, `assets/`, the reference dirs, and `mcp.json` were all
- * still excluded from the trust digest, so swapping any of those
- * while keeping the SKILL.md body identical left `contentSha`
- * unchanged and the prior user approval still applied. We now hash
- * every resource-bearing path so a swap of any bundled file
- * invalidates the approval.
- *
- * Resources and directories are sorted so the hash is deterministic.
- */
-export function computeSkillTrustSha(name, body, resources, resourceDirs) {
-    const sortedResources = [...resources].sort((a, b) => a.path.localeCompare(b.path));
-    const hash = createHash("sha256");
-    hash.update("name:");
-    hash.update(name, "utf8");
-    hash.update("\0body:");
-    hash.update(body, "utf8");
-    hash.update("\0resources:");
-    for (const resource of sortedResources) {
-        hash.update(`\0${resource.name}\0${resource.type}\0`);
-        hash.update(hashSkillResourceFile(resource.path));
-    }
-    hash.update("\0resourceDirs:");
-    const dirEntries = [
-        ["assetsDir", resourceDirs.assetsDir, "dir"],
-        ["mcpJsonPath", resourceDirs.mcpJsonPath, "file"],
-        ["referenceDir", resourceDirs.referenceDir, "dir"],
-        ["referencesDir", resourceDirs.referencesDir, "dir"],
-        ["scriptsDir", resourceDirs.scriptsDir, "dir"],
-        ["toolboxDir", resourceDirs.toolboxDir, "dir"],
-    ];
-    for (const [label, path, kind] of dirEntries) {
-        if (!path) {
-            continue;
-        }
-        hash.update(`\0${label}\0`);
-        if (kind === "file") {
-            hash.update(hashSkillResourceFile(path));
-        }
-        else {
-            hashSkillDirectoryInto(hash, path, path);
-        }
-    }
-    return hash.digest("hex");
-}
-/**
- * Skill loading error.
- */
-export class SkillLoadError extends Error {
-    constructor(message, path, code) {
-        super(message);
-        this.path = path;
-        this.code = code;
-        this.name = "SkillLoadError";
-    }
-}
-function stringValue(value) {
-    return typeof value === "string" ? value : undefined;
-}
-export function stringArrayValue(value) {
-    if (Array.isArray(value)) {
-        if (value.length === 0 ||
-            value.some((entry) => typeof entry !== "string" || entry.trim() === "")) {
-            return undefined;
-        }
-        const values = value
-            .map((entry) => entry.trim())
-            .filter((entry) => entry.length > 0);
-        return values.length > 0 ? values : undefined;
-    }
-    if (typeof value === "string") {
-        const values = value
-            .split(/[,\s]+/)
-            .map((entry) => entry.trim())
-            .filter((entry) => entry.length > 0);
-        return values.length > 0 ? values : undefined;
-    }
-    return undefined;
-}
-function validateStringArrayField(value, field) {
-    if (value === undefined) {
-        return null;
-    }
-    if (typeof value === "string") {
-        return stringArrayValue(value)
-            ? null
-            : `${field} must be a non-empty string or list of non-empty strings`;
-    }
-    if (Array.isArray(value)) {
-        return stringArrayValue(value)
-            ? null
-            : `${field} entries must all be non-empty strings`;
-    }
-    return `${field} must be a non-empty string or list of non-empty strings`;
-}
-function booleanValue(value) {
-    if (typeof value === "boolean")
-        return value;
-    if (typeof value === "string") {
-        const normalized = value.toLowerCase();
-        if (normalized === "true")
-            return true;
-        if (normalized === "false")
-            return false;
-    }
-    return undefined;
-}
-function metadataRecordValue(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        return undefined;
-    }
-    const metadata = {};
-    for (const [key, entry] of Object.entries(value)) {
-        if (typeof entry !== "string" &&
-            typeof entry !== "number" &&
-            typeof entry !== "boolean") {
-            continue;
-        }
-        const normalized = String(entry).trim();
-        if (normalized.length > 0) {
-            metadata[key] = normalized;
-        }
-    }
-    return Object.keys(metadata).length > 0 ? metadata : undefined;
-}
-/**
- * Validate skill name per Agent Skills spec.
- */
-function validateName(name, dirName) {
-    if (!name || typeof name !== "string") {
-        return "Name must be a non-empty string";
-    }
-    if (name.length > MAX_NAME_LENGTH) {
-        return `Name exceeds ${MAX_NAME_LENGTH} characters (got ${name.length})`;
-    }
-    if (name !== name.toLowerCase()) {
-        return "Name must be lowercase";
-    }
-    if (name.startsWith("-") || name.endsWith("-")) {
-        return "Name cannot start or end with a hyphen";
-    }
-    if (name.includes("--")) {
-        return "Name cannot contain consecutive hyphens";
-    }
-    if (!/^[a-z0-9-]+$/.test(name)) {
-        return "Name can only contain lowercase letters, numbers, and hyphens";
-    }
-    // Directory name must match skill name (skip for 'skills' root dir)
-    if (dirName !== "skills" && dirName !== name) {
-        return `Directory name '${dirName}' must match skill name '${name}'`;
-    }
-    return null;
-}
-/**
- * Validate description per Agent Skills spec.
- */
-function validateDescription(description) {
-    if (!description || typeof description !== "string") {
-        return "Description must be a non-empty string";
-    }
-    if (description.length > MAX_DESCRIPTION_LENGTH) {
-        return `Description exceeds ${MAX_DESCRIPTION_LENGTH} characters (got ${description.length})`;
-    }
-    return null;
-}
-/**
- * Validate compatibility per Agent Skills spec.
- */
-function validateCompatibility(compatibility) {
-    if (typeof compatibility !== "string") {
-        return "Compatibility must be a string";
-    }
-    if (compatibility.length > MAX_COMPATIBILITY_LENGTH) {
-        return `Compatibility exceeds ${MAX_COMPATIBILITY_LENGTH} characters (got ${compatibility.length})`;
-    }
-    return null;
-}
-/**
- * Check for unexpected fields in frontmatter.
- */
-function validateFields(frontmatter) {
-    const unexpected = [];
-    for (const key of Object.keys(frontmatter)) {
-        if (!ALLOWED_FIELDS.has(key)) {
-            unexpected.push(key);
-        }
-    }
-    return unexpected;
-}
-/**
- * Find SKILL.md file (case-insensitive per spec).
- */
-export function findSkillMd(dir) {
-    // Prefer uppercase
-    const uppercase = join(dir, "SKILL.md");
-    if (existsSync(uppercase)) {
-        return uppercase;
-    }
-    // Fall back to lowercase
-    const lowercase = join(dir, "skill.md");
-    if (existsSync(lowercase)) {
-        return lowercase;
-    }
-    return null;
-}
-/**
- * Parse YAML frontmatter from markdown content.
- */
-export function parseFrontmatter(content) {
-    if (!content.trimStart().startsWith("---")) {
-        throw new Error("Missing frontmatter delimiters");
-    }
-    const frontmatterRegex = /^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/;
-    const match = content.match(frontmatterRegex);
-    if (!match) {
-        throw new Error("Frontmatter not properly closed");
-    }
-    const [, yamlContent, body] = match;
-    const parsed = loadYaml(yamlContent ?? "") ?? {};
-    if (typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new Error("Frontmatter must be a YAML object");
-    }
-    const frontmatter = parsed;
-    return { frontmatter, body: body };
-}
-/**
- * Determine resource type from file extension.
- */
-function getResourceType(filename) {
-    const ext = filename.split(".").pop()?.toLowerCase() ?? "";
-    const scriptExtensions = ["sh", "bash", "py", "js", "ts", "rb", "pl"];
-    const templateExtensions = ["hbs", "ejs", "mustache", "j2", "jinja", "tmpl"];
-    const referenceExtensions = ["md", "txt", "json", "yaml", "yml", "toml"];
-    if (scriptExtensions.includes(ext))
-        return "script";
-    if (templateExtensions.includes(ext))
-        return "template";
-    if (referenceExtensions.includes(ext))
-        return "reference";
-    return "other";
-}
-/**
- * Load a single skill from a directory.
- */
-function loadSkillFromDirectory(skillDir, sourceType) {
-    const skillFile = findSkillMd(skillDir);
-    const dirName = basename(skillDir);
-    if (!skillFile) {
-        return new SkillLoadError(`No SKILL.md found in ${skillDir}`, skillDir, "READ_ERROR");
-    }
-    try {
-        const rawContent = readFileSync(skillFile, "utf-8");
-        let frontmatter;
-        let body;
-        try {
-            ({ frontmatter, body } = parseFrontmatter(rawContent));
-        }
-        catch (err) {
-            return new SkillLoadError(`Invalid frontmatter: ${err instanceof Error ? err.message : String(err)}`, skillFile, "INVALID_YAML");
-        }
-        // Check for unexpected fields (per Agent Skills spec)
-        const unexpectedFields = validateFields(frontmatter);
-        if (unexpectedFields.length > 0) {
-            return new SkillLoadError(`Unexpected fields: ${unexpectedFields.join(", ")}. Only ${Array.from(ALLOWED_FIELDS).join(", ")} are allowed.`, skillFile, "UNEXPECTED_FIELDS");
-        }
-        // Validate name
-        const name = frontmatter.name;
-        const nameError = validateName(name, dirName);
-        if (nameError) {
-            return new SkillLoadError(nameError, skillFile, "INVALID_NAME");
-        }
-        // Validate description
-        const description = frontmatter.description;
-        const descError = validateDescription(description);
-        if (descError) {
-            return new SkillLoadError(descError, skillFile, "INVALID_DESCRIPTION");
-        }
-        // Validate compatibility if present
-        if (frontmatter.compatibility !== undefined) {
-            const compatError = validateCompatibility(frontmatter.compatibility);
-            if (compatError) {
-                return new SkillLoadError(compatError, skillFile, "INVALID_COMPATIBILITY");
-            }
-        }
-        for (const field of ["allowed-tools", "builtin-tools"]) {
-            const toolListError = validateStringArrayField(frontmatter[field], field);
-            if (toolListError) {
-                return new SkillLoadError(toolListError, skillFile, "INVALID_TOOL_LIST");
-            }
-        }
-        // Discover resource directories
-        const resourceDirs = {};
-        const scriptsDir = join(skillDir, "scripts");
-        const referenceDir = join(skillDir, "reference");
-        const referencesDir = join(skillDir, "references");
-        const assetsDir = join(skillDir, "assets");
-        const toolboxDir = join(skillDir, "toolbox");
-        const mcpJsonPath = join(skillDir, "mcp.json");
-        if (existsSync(scriptsDir) && statSync(scriptsDir).isDirectory()) {
-            resourceDirs.scriptsDir = scriptsDir;
-        }
-        if (existsSync(referenceDir) && statSync(referenceDir).isDirectory()) {
-            resourceDirs.referenceDir = referenceDir;
-        }
-        if (existsSync(referencesDir) && statSync(referencesDir).isDirectory()) {
-            resourceDirs.referencesDir = referencesDir;
-        }
-        if (existsSync(assetsDir) && statSync(assetsDir).isDirectory()) {
-            resourceDirs.assetsDir = assetsDir;
-        }
-        if (existsSync(toolboxDir) && statSync(toolboxDir).isDirectory()) {
-            resourceDirs.toolboxDir = toolboxDir;
-        }
-        if (existsSync(mcpJsonPath) && statSync(mcpJsonPath).isFile()) {
-            resourceDirs.mcpJsonPath = mcpJsonPath;
-        }
-        // Discover bundled resources (legacy flat structure)
-        const resources = [];
-        try {
-            const files = readdirSync(skillDir);
-            for (const file of files) {
-                if (file.toLowerCase() === "skill.md")
-                    continue;
-                if (LEGACY_FLAT_RESOURCE_EXCLUDES.has(file.toLowerCase())) {
-                    continue;
-                }
-                const filePath = join(skillDir, file);
-                const stat = statSync(filePath);
-                if (stat.isFile()) {
-                    resources.push({
-                        name: file,
-                        path: filePath,
-                        type: getResourceType(file),
-                    });
-                }
-            }
-        }
-        catch (err) {
-            logger.debug("Error scanning skill resources", {
-                skillDir,
-                error: err instanceof Error ? err.message : String(err),
-            });
-        }
-        const skill = {
-            name,
-            description,
-            license: stringValue(frontmatter.license),
-            compatibility: stringValue(frontmatter.compatibility),
-            allowedTools: stringArrayValue(frontmatter["allowed-tools"]),
-            builtinTools: stringArrayValue(frontmatter["builtin-tools"]),
-            argumentHint: stringValue(frontmatter["argument-hint"]),
-            model: stringValue(frontmatter.model),
-            mode: stringValue(frontmatter.mode),
-            isolatedContext: booleanValue(frontmatter.isolatedContext),
-            metadata: metadataRecordValue(frontmatter.metadata),
-            // Legacy fields for backwards compatibility
-            tags: Array.isArray(frontmatter.tags)
-                ? frontmatter.tags
-                : undefined,
-            author: typeof frontmatter.author === "string" ? frontmatter.author : undefined,
-            version: typeof frontmatter.version === "string"
-                ? frontmatter.version
-                : undefined,
-            triggers: Array.isArray(frontmatter.triggers)
-                ? frontmatter.triggers
-                : undefined,
-            sourcePath: skillDir,
-            sourceType,
-            content: body.trim(),
-            contentSha: computeSkillTrustSha(name, body.trim(), resources, resourceDirs),
-            resources,
-            resourceDirs,
-        };
-        logger.debug("Loaded skill", {
-            name: skill.name,
-            sourceType,
-            resourceCount: resources.length,
-        });
-        return skill;
-    }
-    catch (err) {
-        return new SkillLoadError(`Error loading skill: ${err instanceof Error ? err.message : String(err)}`, skillDir, "READ_ERROR");
-    }
-}
-/**
- * Scan a directory for skill subdirectories.
- */
-function scanSkillsDirectory(dir, sourceType) {
-    if (!existsSync(dir)) {
-        return { skills: [], errors: [] };
-    }
-    const skills = [];
-    const errors = [];
-    try {
-        // Check for SKILL.md in root (single skill in skills dir)
-        const rootSkillFile = findSkillMd(dir);
-        if (rootSkillFile) {
-            const result = loadSkillFromDirectory(dir, sourceType);
-            if (result instanceof SkillLoadError) {
-                errors.push(result);
-            }
-            else {
-                skills.push(result);
-            }
-        }
-        // Check subdirectories
-        const entries = readdirSync(dir);
-        for (const entry of entries) {
-            const entryPath = join(dir, entry);
-            const stat = statSync(entryPath);
-            if (stat.isDirectory()) {
-                const result = loadSkillFromDirectory(entryPath, sourceType);
-                if (result instanceof SkillLoadError) {
-                    errors.push(result);
-                }
-                else {
-                    skills.push(result);
-                }
-            }
-        }
-    }
-    catch (err) {
-        logger.warn("Error scanning skills directory", {
-            dir,
-            error: err instanceof Error ? err.message : String(err),
-        });
-    }
-    return { skills, errors };
-}
-/**
- * Get the system skills directory bundled with the package.
- *
- * Resolves the `skills/` directory relative to the package root,
- * which works whether running from source (repo) or installed via npm.
- */
-function getSystemSkillsDir() {
-    // Allow explicit override for non-standard packaging layouts
-    const override = process.env.MAESTRO_SYSTEM_SKILLS_DIR;
-    if (override && existsSync(override)) {
-        return override;
-    }
-    // import.meta.url points to this file — either src/skills/loader.ts (dev)
-    // or dist/cli.js (bundled). Walk up to find the package root by looking
-    // for a directory that contains both package.json and skills/.
-    const thisFile = fileURLToPath(import.meta.url);
-    let dir = dirname(thisFile);
-    for (let i = 0; i < 5; i++) {
-        const skillsDir = join(dir, "skills");
-        if (existsSync(join(dir, "package.json")) && existsSync(skillsDir)) {
-            return skillsDir;
-        }
-        const parent = dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    // Fallback: assume 3 levels up (src/skills/loader.ts layout)
-    const packageRoot = dirname(dirname(dirname(thisFile)));
-    return join(packageRoot, "skills");
-}
-/**
- * Load all available skills from system, user, and project directories.
- *
- * Priority (highest wins): project > user > system.
- * System skills are bundled with the package and provide default capabilities.
- *
- * @param workspaceDir - The current workspace/project directory
- * @returns Object with loaded skills and any errors
- */
-export function loadSkills(workspaceDir, options) {
-    const includeSystem = options?.includeSystem ?? true;
-    const systemSkillsDir = includeSystem ? getSystemSkillsDir() : null;
-    const userSkillsDir = join(PATHS.MAESTRO_HOME, "skills");
-    const projectSkillsDir = join(workspaceDir, ".maestro", "skills");
-    const packageResources = loadConfiguredPackageResources(workspaceDir, {
-        profileName: options?.profileName,
-        cliOverrides: options?.cliOverrides,
-    });
-    const userPackageSkillDirs = packageResources.skills.user;
-    const projectPackageSkillDirs = packageResources.skills.project;
-    logger.debug("Scanning for skills", {
-        systemSkillsDir: systemSkillsDir ?? "(disabled)",
-        userSkillsDir,
-        projectSkillsDir,
-        userPackageSkillDirs,
-        projectPackageSkillDirs,
-    });
-    const systemResult = systemSkillsDir
-        ? scanSkillsDirectory(systemSkillsDir, "system")
-        : { skills: [], errors: [] };
-    const userResult = [...userPackageSkillDirs, userSkillsDir].reduce((result, dir) => {
-        const next = scanSkillsDirectory(dir, "user");
-        result.skills.push(...next.skills);
-        result.errors.push(...next.errors);
-        return result;
-    }, { skills: [], errors: [] });
-    const projectResult = [...projectPackageSkillDirs, projectSkillsDir].reduce((result, dir) => {
-        const next = scanSkillsDirectory(dir, "project");
-        result.skills.push(...next.skills);
-        result.errors.push(...next.errors);
-        return result;
-    }, { skills: [], errors: [] });
-    // Priority: project > user > system (last writer wins)
-    const skillMap = new Map();
-    for (const skill of systemResult.skills) {
-        skillMap.set(skill.name.toLowerCase(), skill);
-    }
-    for (const skill of userResult.skills) {
-        const existing = skillMap.get(skill.name.toLowerCase());
-        if (existing) {
-            logger.debug("User skill overrides system skill", {
-                name: skill.name,
-            });
-        }
-        skillMap.set(skill.name.toLowerCase(), skill);
-    }
-    for (const skill of projectResult.skills) {
-        const existing = skillMap.get(skill.name.toLowerCase());
-        if (existing) {
-            logger.debug("Project skill overrides existing skill", {
-                name: skill.name,
-                overridden: existing.sourceType,
-            });
-        }
-        skillMap.set(skill.name.toLowerCase(), skill);
-    }
-    const allSkills = Array.from(skillMap.values());
-    const allErrors = [
-        ...systemResult.errors,
-        ...userResult.errors,
-        ...projectResult.errors,
-    ];
-    logger.info("Finished loading skills", {
-        total: allSkills.length,
-        errors: allErrors.length,
-        system: systemResult.skills.length,
-        user: userResult.skills.length,
-        project: projectResult.skills.length,
-        userPackages: userPackageSkillDirs.length,
-        projectPackages: projectPackageSkillDirs.length,
-    });
-    return { skills: allSkills, errors: allErrors };
-}
-/**
- * Find a skill by name (case-insensitive).
- */
-export function findSkill(skills, name) {
-    const normalizedName = name.toLowerCase();
-    return skills.find((s) => s.name.toLowerCase() === normalizedName);
-}
-/**
- * Find skills that match a given query (checks name, description, tags, triggers).
- */
-export function searchSkills(skills, query) {
-    const normalizedQuery = query.toLowerCase();
-    return skills.filter((skill) => {
-        // Check name
-        if (skill.name.toLowerCase().includes(normalizedQuery))
-            return true;
-        // Check description
-        if (skill.description.toLowerCase().includes(normalizedQuery))
-            return true;
-        // Check tags
-        if (skill.tags?.some((t) => t.toLowerCase().includes(normalizedQuery))) {
-            return true;
-        }
-        // Check triggers
-        if (skill.triggers?.some((t) => t.toLowerCase().includes(normalizedQuery))) {
-            return true;
-        }
-        return false;
-    });
-}
-/**
- * Convert skill to dictionary (per Agent Skills SDK).
- * Excludes undefined values.
- */
-export function skillToDict(skill) {
-    const result = {
-        name: skill.name,
-        description: skill.description,
-    };
-    if (skill.license) {
-        result.license = skill.license;
-    }
-    if (skill.compatibility) {
-        result.compatibility = skill.compatibility;
-    }
-    if (skill.allowedTools) {
-        result["allowed-tools"] = skill.allowedTools;
-    }
-    if (skill.builtinTools) {
-        result["builtin-tools"] = skill.builtinTools;
-    }
-    if (skill.argumentHint) {
-        result["argument-hint"] = skill.argumentHint;
-    }
-    if (skill.model) {
-        result.model = skill.model;
-    }
-    if (skill.mode) {
-        result.mode = skill.mode;
-    }
-    if (skill.isolatedContext !== undefined) {
-        result.isolatedContext = skill.isolatedContext;
-    }
-    if (skill.metadata && Object.keys(skill.metadata).length > 0) {
-        result.metadata = skill.metadata;
-    }
-    return result;
-}
-/**
- * Convert skill to JSON string.
- */
-export function skillToJson(skill) {
-    return JSON.stringify(skillToDict(skill), null, 2);
-}
-/**
- * Escape XML special characters.
- */
-function escapeXml(str) {
-    return str
-        .replace(/&/g, "&amp;")
-        .replace(/</g, "&lt;")
-        .replace(/>/g, "&gt;")
-        .replace(/"/g, "&quot;")
-        .replace(/'/g, "&#39;");
-}
-/**
- * Generate XML prompt block for available skills (per Agent Skills SDK).
- *
- * This generates the <available_skills> XML block that should be included
- * in system prompts to make skills discoverable by the agent.
- */
-export function skillsToPrompt(skills) {
-    if (skills.length === 0) {
-        return "<available_skills>\n</available_skills>";
-    }
-    const lines = ["<available_skills>"];
-    for (const skill of skills) {
-        const description = promptSafeText(skill.description, MAX_DESCRIPTION_LENGTH);
-        lines.push("<skill>");
-        lines.push(`  <name>${escapeXml(skill.name)}</name>`);
-        lines.push(`  <description>${escapeXml(description ?? "")}</description>`);
-        lines.push(`  <location>${escapeXml(join(skill.sourcePath, "SKILL.md"))}</location>`);
-        lines.push("</skill>");
-    }
-    lines.push("</available_skills>");
-    return lines.join("\n");
-}
-/**
- * Format skill for display in a list.
- */
-export function formatSkillListItem(skill) {
-    const sourceLabels = {
-        service: "(service)",
-        system: "(system)",
-        user: "(user)",
-        project: "(project)",
-    };
-    const source = sourceLabels[skill.sourceType];
-    const tags = skill.tags?.length ? ` [${skill.tags.join(", ")}]` : "";
-    return `${skill.name} ${source}${tags} - ${skill.description}`;
-}
-/**
- * Format skill content for injection into conversation.
- */
-export function formatSkillForInjection(skill) {
-    const lines = [];
-    lines.push(`# Skill: ${skill.name}`);
-    lines.push("");
-    lines.push(`> ${skill.description}`);
-    lines.push("");
-    // Provenance line: lets the model and any human reading the transcript
-    // correlate this skill activation to a specific prompt body. `source`
-    // distinguishes built-in / project / user / service. `contentSha` is
-    // stable per body (see #2629 — trust UX keys on this).
-    lines.push(`<!-- source=${skill.sourceType} sha=${skill.contentSha} -->`);
-    lines.push("");
-    if (skill.tags?.length) {
-        lines.push(`**Tags:** ${skill.tags.join(", ")}`);
-        lines.push("");
-    }
-    if (skill.resources.length > 0) {
-        lines.push("## Bundled Resources");
-        lines.push("");
-        lines.push("You can access these bundled resources using the Read tool:");
-        lines.push("");
-        for (const resource of skill.resources) {
-            lines.push(`- \`${resource.path}\` (${resource.type})`);
-        }
-        lines.push("");
-    }
-    if (skill.resourceDirs.referenceDir || skill.resourceDirs.referencesDir) {
-        lines.push("## Reference Resources");
-        lines.push("");
-        lines.push("Load detailed references only when needed:");
-        if (skill.resourceDirs.referenceDir) {
-            lines.push(`- \`${skill.resourceDirs.referenceDir}\``);
-        }
-        if (skill.resourceDirs.referencesDir) {
-            lines.push(`- \`${skill.resourceDirs.referencesDir}\``);
-        }
-        lines.push("");
-    }
-    if (skill.resourceDirs.toolboxDir || skill.resourceDirs.mcpJsonPath) {
-        lines.push("## Tool Package");
-        lines.push("");
-        if (skill.resourceDirs.toolboxDir) {
-            lines.push(`- Toolbox executables are bundled under \`${skill.resourceDirs.toolboxDir}\`.`);
-        }
-        if (skill.resourceDirs.mcpJsonPath) {
-            lines.push(`- Bundled MCP config: \`${skill.resourceDirs.mcpJsonPath}\`.`);
-        }
-        lines.push("");
-    }
-    lines.push("## Instructions");
-    lines.push("");
-    lines.push(skill.content);
-    return lines.join("\n");
-}
-/**
- * Get skill summary for system prompt (lists available skills).
- * @deprecated Use skillsToPrompt for XML format per Agent Skills SDK
- */
-export function getSkillsSummary(skills) {
-    if (skills.length === 0) {
-        return "";
-    }
-    const lines = [];
-    lines.push("## Available Skills");
-    lines.push("");
-    lines.push("When you recognize that a task matches one of the available skills listed below, " +
-        "use the Skill tool to load the full skill instructions.");
-    lines.push("");
-    for (const skill of skills) {
-        const tags = skill.tags?.length ? ` [${skill.tags.join(", ")}]` : "";
-        const description = promptSafeText(skill.description, MAX_DESCRIPTION_LENGTH) ?? "";
-        lines.push(`- **${skill.name}**${tags}: ${description}`);
-        if (skill.triggers?.length) {
-            lines.push(`  - Triggers: ${skill.triggers.join(", ")}`);
-        }
-    }
-    lines.push("");
-    return lines.join("\n");
-}
-/**
- * Progressive Skill Disclosure (#857)
- *
- * Format skill metadata only (name + description) for system prompt injection.
- * The agent can then use the `read` tool to load full SKILL.md content on-demand.
- *
- * Benefits:
- * - Context efficiency: ~10 tokens per skill vs ~500+ for full content
- * - Scalability: 20 skills use ~200 tokens instead of ~10,000
- * - Self-directed: Agent loads what it needs when it needs it
- */
-/**
- * Format a single skill's metadata for system prompt (XML format).
- *
- * Returns only name and description in a self-closing XML tag.
- * Follows the Agent Skills specification's progressive disclosure pattern.
- *
- * @param skill - The loaded skill
- * @returns XML-formatted skill metadata
- *
- * @example
- * ```xml
- * <skill name="test-runner" description="Run and debug test suites" />
- * <!-- source: ~/.maestro/skills/test-runner -->
- * ```
- */
-export function formatSkillMetadataOnly(skill) {
-    // Escape XML special characters
-    const escapeName = skill.name
-        .replace(/&/g, "&amp;")
-        .replace(/</g, "&lt;")
-        .replace(/>/g, "&gt;")
-        .replace(/"/g, "&quot;");
-    const description = promptSafeText(skill.description, MAX_DESCRIPTION_LENGTH);
-    const escapeDesc = (description ?? "")
-        .replace(/&/g, "&amp;")
-        .replace(/</g, "&lt;")
-        .replace(/>/g, "&gt;")
-        .replace(/"/g, "&quot;");
-    // Include source path as XML comment for debugging
-    return `<skill name="${escapeName}" description="${escapeDesc}" />\n<!-- source: ${skill.sourcePath} -->`;
-}
-/**
- * Format multiple skills for system prompt with on-demand loading instructions.
- *
- * Returns XML list of skill metadata plus instructions for the agent to load
- * full skill content using the `read` tool when needed.
- *
- * This is the primary function for progressive skill disclosure.
- *
- * @param skills - Array of loaded skills
- * @returns XML-formatted skills list with loading instructions, or empty string if no skills
- *
- * @example
- * ```xml
- * <available_skills>
- *   <skill name="test-runner" description="..." />
- *   <skill name="git-workflow" description="..." />
- * </available_skills>
- *
- * When a skill is relevant to the user's request, use the `read` tool to load
- * the full skill instructions from the source path shown in the comment.
- * ```
- */
-export function formatSkillsForSystemPrompt(skills) {
-    if (skills.length === 0) {
-        return "";
-    }
-    const lines = [];
-    lines.push("<available_skills>");
-    for (const skill of skills) {
-        lines.push(`  ${formatSkillMetadataOnly(skill)}`);
-    }
-    lines.push("</available_skills>");
-    lines.push("");
-    lines.push("When a skill is relevant to the user's request, use the `read` tool to load " +
-        "the full SKILL.md from the skill's source directory (shown in comments above). " +
-        "For example: `read ~/.maestro/skills/test-runner/SKILL.md` or " +
-        "`read .maestro/skills/custom-skill/SKILL.md`. " +
-        "This progressive loading keeps the system prompt lean while making all skill " +
-        "capabilities available on-demand.");
-    return lines.join("\n");
-}
-//# sourceMappingURL=loader.js.map