Skills

/**
 * Loader for git-installable skills.
 *
 * Accepted source formats:
 *   git+https://github.com/me/my-skill.git
 *   git+https://github.com/me/my-skill.git#v1.2.3       (tag)
 *   git+https://github.com/me/my-skill.git#main          (branch / ref)
 *   git+ssh://git@github.com/me/my-skill.git
 *
 * The repository must contain a `skill.json` manifest at the root (or in a
 * subdir specified via `?subdir=path/in/repo`).
 */
export declare class GitSkillLoader implements SkillLoader {
    constructor(config?: GitSkillLoaderConfig);
    canLoad(source: string): boolean;
    load(source: string): Promise<Skill>;
}

export interface GitSkillLoaderConfig {
    /**
     * Local directory where cloned skills are cached. Defaults to a tempdir per process.
     * Setting an explicit path lets you cache skills across runs.
     */
    cacheDir?: string;
    /** Default ref to checkout when none is specified in the URL. */
    defaultRef?: string;
}

/** Convenience function — loads a skill from any source type. */
export declare function loadSkill(source: SkillSource): Promise<Skill>;

export declare function parseSkillMd(text: string, fallbackName?: string): Omit<SkillMd, "dir"> | null;

/**
 * A Skill is a pre-packaged bundle of tools and optional instructions.
 * It encapsulates domain expertise that can be loaded from various sources.
 */
export interface Skill {
    /** Unique name for this skill. */
    name: string;
    /** Human-readable description. */
    description: string;
    /** Semver version string. */
    version: string;
    /** Tools provided by this skill. */
    tools: ToolDef[];
    /** Optional instructions fragment injected into the system prompt when this skill is active. */
    instructions?: string;
    /** Metadata — author, license, tags, etc. */
    metadata?: Record<string, unknown>;
}

/**
 * Interface for skill loaders. Each loader knows how to load skills from a
 * specific source type (filesystem, npm, remote URL).
 */
export interface SkillLoader {
    /** Returns true if this loader can handle the given source string. */
    canLoad(source: string): boolean;
    /** Load a skill from the source. */
    load(source: string): Promise<Skill>;
}

/**
 * Orchestrates skill loading from multiple sources.
 * Skills are loaded lazily on first access.
 */
export declare class SkillManager {
    constructor(sources: Array<Skill | SkillSource>);
    /** Get all tools from all loaded skills. Triggers lazy loading. */
    getTools(): Promise<ToolDef[]>;
    /** Get combined instruction fragments from all loaded skills. */
    getInstructions(): Promise<string>;
    /** Get all loaded skills. Triggers lazy loading. */
    getSkills(): Promise<Skill[]>;
    /** Add a skill or source dynamically after construction. */
    addSkill(source: Skill | SkillSource): Promise<Skill>;
}

/**
 * Manifest file (skill.json) loaded from a skill directory.
 */
export interface SkillManifest {
    name: string;
    description: string;
    version: string;
    /** Relative path to the main module that exports tools. */
    main: string;
    /** Optional instructions text or path to an instructions file. */
    instructions?: string;
    metadata?: Record<string, unknown>;
}

export interface SkillMd {
    name: string;
    description: string;
    body: string;
    dir: string;
    version?: string;
}

/**
 * Loads Agent Skills (`SKILL.md`) with progressive disclosure:
 * the prompt only gets name + description until the agent asks for the body.
 */
export declare class SkillMdManager {
    constructor(config: SkillMdManagerConfig);
    ensureLoaded(): Promise<void>;
    list(): Promise<Array<Pick<SkillMd, "name" | "description">>>;
    get(name: string): Promise<SkillMd | null>;
    /** ~100-token index injected into the system prompt. */
    getIndexPrompt(): Promise<string>;
    getTools(): ToolDef[];
}

export interface SkillMdManagerConfig {
    /** Directories to scan for skill folders that contain SKILL.md */
    dirs: string[];
}

/** Input type for loadSkill — a source string (path, package name, or URL). */
export type SkillSource = string;