@evalops/maestro 0.10.50 → 0.10.53

package/dist/skills/loader.d.ts

@@ -1,252 +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 type { ComposerConfig } from "../config/toml-config.js";
-/** Allowed frontmatter fields per Agent Skills spec */
-export declare const SKILL_FRONTMATTER_FIELDS: readonly ["name", "description", "license", "compatibility", "allowed-tools", "argument-hint", "builtin-tools", "model", "mode", "isolatedContext", "metadata", "tags", "author", "version", "triggers"];
-/**
- * Skill definition from SKILL.md frontmatter (per Agent Skills spec).
- */
-export interface SkillDefinition {
-    /** Skill name (1-64 chars, lowercase alphanumeric + hyphens) */
-    name: string;
-    /** Description of what the skill does (1-1024 chars) */
-    description: string;
-    /** License identifier */
-    license?: string;
-    /** Compatibility/environment requirements (max 500 chars) */
-    compatibility?: string;
-    /** Pre-approved MCP/toolbox tools this skill can use */
-    allowedTools?: string[];
-    /** Built-in Maestro tools this skill needs */
-    builtinTools?: string[];
-    /** Argument hint shown by authoring surfaces */
-    argumentHint?: string;
-    /** Preferred model while this skill is active */
-    model?: string;
-    /** Preferred agent mode while this skill is active */
-    mode?: string;
-    /** Whether the skill should run in isolated context when supported */
-    isolatedContext?: boolean;
-    /** Additional key-value metadata */
-    metadata?: Record<string, string>;
-    /** @deprecated Use metadata instead */
-    tags?: string[];
-    /** @deprecated Use metadata.author instead */
-    author?: string;
-    /** @deprecated Use metadata.version instead */
-    version?: string;
-    /** @deprecated Use description for trigger keywords instead */
-    triggers?: string[];
-}
-/**
- * Loaded skill with full content.
- */
-export interface LoadedSkill extends SkillDefinition {
-    /** Source directory path */
-    sourcePath: string;
-    /** Source type: 'user', 'project', 'system', or 'service' */
-    sourceType: "user" | "project" | "system" | "service";
-    /** Full markdown content (without frontmatter) */
-    content: string;
-    /**
-     * SHA-256 of the prompt body. Stable identifier for the skill's
-     * instructions independent of its source path. Trust UX (see #2629)
-     * keys on this: a non-builtin skill whose `contentSha` changes between
-     * loads is a "skill content changed; approve" trigger.
-     */
-    contentSha: string;
-    /** List of bundled resource files */
-    resources: SkillResource[];
-    /** Resource directories */
-    resourceDirs: SkillResourceDirs;
-}
-/**
- * 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 declare function computeSkillTrustSha(name: string, body: string, resources: SkillResource[], resourceDirs: SkillResourceDirs): string;
-/**
- * Resource directories per Agent Skills spec.
- */
-export interface SkillResourceDirs {
-    /** Path to scripts directory if it exists */
-    scriptsDir?: string;
-    /** Path to Sourcegraph/Amp-style singular reference directory if it exists */
-    referenceDir?: string;
-    /** Path to legacy/plural references directory if it exists */
-    referencesDir?: string;
-    /** Path to assets directory if it exists */
-    assetsDir?: string;
-    /** Path to toolbox executable directory if it exists */
-    toolboxDir?: string;
-    /** Path to bundled MCP config if it exists */
-    mcpJsonPath?: string;
-}
-/**
- * A bundled resource file within a skill.
- */
-export interface SkillResource {
-    /** Resource file name */
-    name: string;
-    /** Full path to the resource */
-    path: string;
-    /** Resource type based on extension */
-    type: "script" | "template" | "reference" | "other";
-}
-/**
- * Skill loading error.
- */
-export declare class SkillLoadError extends Error {
-    readonly path: string;
-    readonly code: "MISSING_FRONTMATTER" | "INVALID_YAML" | "INVALID_NAME" | "INVALID_DESCRIPTION" | "INVALID_COMPATIBILITY" | "INVALID_TOOL_LIST" | "UNEXPECTED_FIELDS" | "NAME_MISMATCH" | "READ_ERROR";
-    constructor(message: string, path: string, code: "MISSING_FRONTMATTER" | "INVALID_YAML" | "INVALID_NAME" | "INVALID_DESCRIPTION" | "INVALID_COMPATIBILITY" | "INVALID_TOOL_LIST" | "UNEXPECTED_FIELDS" | "NAME_MISMATCH" | "READ_ERROR");
-}
-export declare function stringArrayValue(value: unknown): string[] | undefined;
-/**
- * Find SKILL.md file (case-insensitive per spec).
- */
-export declare function findSkillMd(dir: string): string | null;
-/**
- * Parse YAML frontmatter from markdown content.
- */
-export declare function parseFrontmatter(content: string): {
-    frontmatter: Record<string, unknown>;
-    body: string;
-};
-/**
- * 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 declare function loadSkills(workspaceDir: string, options?: {
-    includeSystem?: boolean;
-    profileName?: string;
-    cliOverrides?: Partial<ComposerConfig>;
-}): {
-    skills: LoadedSkill[];
-    errors: SkillLoadError[];
-};
-/**
- * Find a skill by name (case-insensitive).
- */
-export declare function findSkill(skills: LoadedSkill[], name: string): LoadedSkill | undefined;
-/**
- * Find skills that match a given query (checks name, description, tags, triggers).
- */
-export declare function searchSkills(skills: LoadedSkill[], query: string): LoadedSkill[];
-/**
- * Convert skill to dictionary (per Agent Skills SDK).
- * Excludes undefined values.
- */
-export declare function skillToDict(skill: LoadedSkill): Record<string, string | string[] | boolean | Record<string, string>>;
-/**
- * Convert skill to JSON string.
- */
-export declare function skillToJson(skill: LoadedSkill): string;
-/**
- * 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 declare function skillsToPrompt(skills: LoadedSkill[]): string;
-/**
- * Format skill for display in a list.
- */
-export declare function formatSkillListItem(skill: LoadedSkill): string;
-/**
- * Format skill content for injection into conversation.
- */
-export declare function formatSkillForInjection(skill: LoadedSkill): string;
-/**
- * Get skill summary for system prompt (lists available skills).
- * @deprecated Use skillsToPrompt for XML format per Agent Skills SDK
- */
-export declare function getSkillsSummary(skills: LoadedSkill[]): string;
-/**
- * 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 declare function formatSkillMetadataOnly(skill: LoadedSkill): string;
-/**
- * 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 declare function formatSkillsForSystemPrompt(skills: LoadedSkill[]): string;
-//# sourceMappingURL=loader.d.ts.map

package/dist/skills/loader.d.ts.map

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