/**
 * Agent Skills Standard Type Definitions
 * Compliant with https://agentskills.io/ specification
 *
 * Also supports Claude Code extension fields for compatibility
 */
/**
 * Skill frontmatter as defined in SKILL.md YAML header
 */
interface SkillFrontmatter {
    /** Skill name in kebab-case, max 64 characters */
    name: string;
    /** Skill description, max 1024 characters, should include trigger conditions */
    description: string;
    /** Whether to disable automatic model invocation (default: false) */
    disableModelInvocation?: boolean;
    /** Whether skill appears in / menu (default: true) */
    userInvocable?: boolean;
    /** Tool restrictions, e.g., "Read, Grep, Bash(python:*)" */
    allowedTools?: string;
    /** Execution context - 'fork' for sub-agent execution */
    context?: 'fork';
    /** Sub-agent type: Explore, Plan, general-purpose, etc. */
    agent?: string;
    /** Argument hint for UI, e.g., "[file] [format]" */
    argumentHint?: string;
    /** Model preference: haiku, sonnet, opus, or a provider-specific model id */
    model?: string;
    /** Hooks scoped to this skill's lifecycle */
    hooks?: SkillHooks;
    license?: string;
    compatibility?: string;
    metadata?: Record<string, unknown>;
}
interface SkillHook {
    matcher?: string;
    command: string;
}
interface SkillHooks {
    SessionStart?: SkillHook[];
    UserPromptSubmit?: SkillHook[];
    PreToolUse?: SkillHook[];
    PostToolUse?: SkillHook[];
    Stop?: SkillHook[];
    SubagentStop?: SkillHook[];
    Notification?: SkillHook[];
}
/**
 * Lightweight skill metadata for system prompt injection
 * Loaded at startup for progressive disclosure
 */
interface SkillMetadata {
    name: string;
    description: string;
    userInvocable: boolean;
    argumentHint?: string;
    path: string;
    source: SkillSource;
    /** If true, exclude from system prompt (only invokable via /skill:name) */
    disableModelInvocation: boolean;
}
/**
 * Complete skill definition with all content loaded
 */
interface Skill extends SkillFrontmatter {
    /** Skill directory absolute path */
    path: string;
    /** SKILL.md absolute path */
    skillFilePath: string;
    /** Markdown content (with variables resolved) */
    content: string;
    /** Raw markdown content (before variable resolution) */
    rawContent: string;
    /** Support files */
    scripts?: SkillFile[];
    references?: SkillFile[];
    assets?: SkillFile[];
    templates?: SkillFile[];
    resources?: SkillFile[];
    /** Runtime state */
    loaded: boolean;
    source: SkillSource;
}
/**
 * File within a skill directory
 */
interface SkillFile {
    name: string;
    path: string;
    relativePath: string;
    content?: string;
}
type SkillSource = 'project' | 'user' | 'plugin' | 'builtin';
/**
 * Skill registry interface for managing discovered skills
 */
interface ISkillRegistry {
    /** Read-only view of discovered skill metadata */
    readonly skills: ReadonlyMap<string, SkillMetadata>;
    /** Discover skills from all configured paths */
    discover(): Promise<void>;
    /** Get skill metadata by name */
    get(name: string): SkillMetadata | undefined;
    /** Load full skill content */
    loadFull(name: string): Promise<Skill>;
    /** Invoke a skill with arguments */
    invoke(name: string, args: string, context: SkillContext): Promise<SkillResult>;
    /** Reload skills from disk */
    reload(): Promise<void>;
    /** List all discovered skills */
    list(): ReadonlyArray<SkillMetadata>;
    /** List skills that can be invoked directly by users */
    listUserInvocable(): ReadonlyArray<SkillMetadata>;
    /** Check whether a skill exists */
    has(name: string): boolean;
    /** Number of discovered skills */
    readonly size: number;
}
/**
 * v0.7.42 — SDK-embedder hook for `!`cmd`` dynamic context resolution.
 *
 * Receives the literal command string and the working directory the resolver
 * would have used. Must return the command's text output (which the resolver
 * splices into the skill markdown in place of the `!`cmd`` token), or throw
 * to deny.
 *
 * **Trust boundary**: when the KodaX SDK is embedded inside a host app
 * (e.g. KodaX Space, IDE extensions), the host typically mediates shell
 * execution through a permission broker so the end user can approve / deny
 * each command. Without this hook, `VariableResolver` directly `execSync`s
 * commands using its own built-in whitelist — bypassing the host's broker
 * and producing OS side-effects the user never saw.
 *
 * Embedders should route here to:
 *   - prompt the user via their own UI,
 *   - log execution to their audit trail,
 *   - apply policy (e.g. block network commands),
 *   - or refuse outright (throw).
 *
 * @example
 * ```ts
 * const context: SkillContext = {
 *   workingDirectory: '/repo',
 *   executeDynamicContext: async (cmd, cwd) => {
 *     const approved = await brokerAskUser({ kind: 'skill-cmd', command: cmd, cwd });
 *     if (!approved) throw new Error('user denied');
 *     return await brokerExecute(cmd, cwd);
 *   },
 * };
 * ```
 */
type SkillDynamicContextExecutor = (command: string, cwd: string) => Promise<string>;
interface SkillContext {
    workingDirectory: string;
    projectRoot?: string;
    /**
     * Optional. Used to substitute `${CLAUDE_SESSION_ID}` / `${KODAX_SESSION_ID}`
     * template variables in skill markdown. Tool-invocation callers (e.g. the
     * `skill` tool) may not have a session bound — in that case the resolver
     * falls back to an empty replacement so the substitution doesn't leak the
     * literal `${...}` to the LLM.
     */
    sessionId?: string;
    environment?: Record<string, string>;
    messages?: unknown[];
    /**
     * v0.7.42 — SDK-embedder hook for `!`cmd`` dynamic-context resolution.
     * See {@link SkillDynamicContextExecutor} for the trust-boundary rationale.
     * When present, completely replaces the built-in `execSync`-based path
     * (whitelist + 5s timeout). When absent, the legacy whitelist path runs.
     */
    executeDynamicContext?: SkillDynamicContextExecutor;
    /**
     * v0.7.42 — hard-disable `!`cmd`` resolution.
     * When `true`, encountering a `!`cmd`` token throws
     * `[Dynamic context disabled by host]` regardless of any hook. Useful for
     * embedders that want a single-flag kill switch without writing a hook.
     * `executeDynamicContext` is ignored when this is `true`.
     */
    disableDynamicContext?: boolean;
}
interface SkillResult {
    success: boolean;
    /** Processed prompt content */
    content: string;
    /** Generated artifacts */
    artifacts?: SkillArtifact[];
    error?: string;
}
interface SkillArtifact {
    type: 'file' | 'code' | 'text';
    name: string;
    content: string;
    path?: string;
}
interface IVariableResolver {
    /** Resolve all variables in content */
    resolve(content: string, args: string, context: SkillContext): Promise<string>;
}
interface SkillPathsConfig {
    projectPaths: string[];
    userPaths: string[];
    pluginPaths: string[];
    builtinPath: string;
}
/**
 * Get default skill discovery paths
 *
 * Priority order (highest first):
 * 1. Project - <projectRoot>/.kodax/skills/
 * 2. User - ~/.kodax/skills/
 * 3. User - ~/.agents/skills/ (AgentSkills standard)
 * 4. Plugin - (dynamic)
 * 5. Builtin - packages/skills/src/builtin/
 */
declare function getDefaultSkillPaths(projectRoot?: string): SkillPathsConfig;
/**
 * All skill paths in priority order (highest to lowest)
 *
 * Priority: Project > User > Plugin > Builtin
 * - Project: Project-specific skills override everything else
 * - User: User preferences (~/.kodax/ and ~/.agents/)
 * - Plugin: Third-party plugins
 * - Builtin: Default skills shipped with KodaX
 */
declare function getSkillPathsFlat(config: SkillPathsConfig): Array<{
    path: string;
    source: SkillSource;
}>;

declare function registerPluginSkillPath(skillPath: string): () => void;
declare function unregisterPluginSkillPath(skillPath: string): boolean;
declare function listPluginSkillPaths(): string[];
declare function clearPluginSkillPaths(): void;

/**
 * Skill Loader - YAML Frontmatter Parsing and Skill Loading
 *
 * Parses SKILL.md files with YAML frontmatter and loads skill content.
 * Implements fallback sanitization for non-standard YAML formats.
 */

/**
 * Parse SKILL.md file with YAML frontmatter
 */
declare function parseSkillMarkdown(content: string): {
    frontmatter: SkillFrontmatter;
    body: string;
};
/**
 * Load skill metadata from SKILL.md file
 */
declare function loadSkillMetadata(skillDir: string, source: SkillSource): Promise<SkillMetadata | null>;
/**
 * Load full skill content
 */
declare function loadFullSkill(skillDir: string, source: SkillSource): Promise<Skill | null>;
/**
 * Load a specific support file's content
 */
declare function loadSkillFileContent(file: SkillFile): Promise<string>;

/**
 * Skill Discovery - Multi-path skill scanning
 *
 * Discovers skills from multiple paths with priority handling.
 * Supports nested directory discovery for monorepos.
 */

/**
 * Result of skill discovery
 */
interface DiscoveryResult {
    skills: Map<string, SkillMetadata>;
    errors: Array<{
        path: string;
        error: string;
    }>;
}
/**
 * Discover all skills from configured paths
 */
declare function discoverSkills(projectRoot?: string, customPaths?: Partial<SkillPathsConfig>): Promise<DiscoveryResult>;
/**
 * Get nested skill paths for monorepo support
 * When in a subdirectory, also check parent directories for skills
 */
declare function getNestedSkillPaths(currentDir: string, projectRoot: string): string[];
/**
 * Discover skills with monorepo support
 */
declare function discoverSkillsWithMonorepo(currentDir: string, projectRoot: string): Promise<DiscoveryResult>;

/**
 * Skill Resolver - Variable Replacement System
 *
 * Handles variable replacement in skill content:
 * - $ARGUMENTS - All arguments
 * - $0, $1, $2... - Positional arguments
 * - ${VAR_NAME} - Environment variables
 * - !`command` - Dynamic context injection
 */

/**
 * Split arguments string into positional arguments
 * Handles quoted strings correctly
 */
declare function parseArguments(args: string): string[];
/**
 * Variable resolver implementation
 */
declare class VariableResolver implements IVariableResolver {
    private context;
    constructor(context: SkillContext);
    /**
     * Resolve all variables in content
     */
    resolve(content: string, args: string): Promise<string>;
    /**
     * Replace $0, $1, $2... with positional arguments
     */
    private resolvePositionalArgs;
    /**
     * Replace $ARGUMENTS with all arguments
     */
    private resolveArguments;
    /**
     * Replace ${VAR_NAME} with environment variables
     */
    private resolveEnvVars;
    /**
     * Replace !`command` with command output (dynamic context).
     *
     * Three-tier dispatch (v0.7.42):
     *   1. `context.disableDynamicContext === true` → throw immediately,
     *      surfaced to the LLM as `[Error: …]`. Host-level kill switch.
     *   2. `context.executeDynamicContext` provided → route there. Embedder
     *      mediates shell execution (broker, audit, deny).
     *   3. else → legacy built-in path (`isSafeDynamicContextCommand`
     *      whitelist + `execSync` with 5s timeout).
     *
     * The resolver inlines an `[Error: …]` placeholder for any thrown
     * exception so a single bad token doesn't poison the whole skill load.
     */
    private resolveDynamicContext;
    /**
     * Execute a dynamic context command via the appropriate dispatch tier.
     * See `resolveDynamicContext` JSDoc for the 3-tier ordering rationale.
     */
    private executeDynamicCommand;
}
/**
 * Create a variable resolver for a given context
 */
declare function createResolver(context: SkillContext): IVariableResolver;
/**
 * Resolve skill content with arguments and context
 */
declare function resolveSkillContent(content: string, args: string, context: SkillContext): Promise<string>;

/**
 * Skill Registry - Progressive Disclosure and Skill Management
 *
 * Manages skill discovery, loading, and invocation with progressive disclosure:
 * - Level 1: Metadata preloaded at startup (name, description)
 * - Level 2: Full content loaded on invoke
 * - Level 3: Support files loaded on demand
 */

/**
 * Skill Registry implementation
 */
declare class SkillRegistry implements ISkillRegistry {
    private readonly skillsByName;
    private readonly fullSkillsByName;
    private readonly projectRoot?;
    private readonly customPaths?;
    constructor(projectRoot?: string, customPaths?: Partial<SkillPathsConfig>);
    /**
     * Discover skills from all configured paths
     */
    discover(): Promise<void>;
    /**
     * Get skill metadata by name
     */
    get skills(): ReadonlyMap<string, SkillMetadata>;
    /**
     * Get skill metadata by name
     */
    get(name: string): SkillMetadata | undefined;
    /**
     * Load full skill content
     */
    loadFull(name: string): Promise<Skill>;
    /**
     * Invoke a skill with arguments
     */
    invoke(name: string, args: string, context: SkillContext): Promise<SkillResult>;
    /**
     * Reload skills from disk
     */
    reload(): Promise<void>;
    /**
     * List all available skills
     */
    list(): SkillMetadata[];
    /**
     * List user-invocable skills (for / menu)
     */
    listUserInvocable(): SkillMetadata[];
    /**
     * Get skills formatted for system prompt injection.
     *
     * FEATURE_143 (v0.7.36): manifest wording hardened toward Claude
     * Code-style strong constraints. The previous wording ("when a user
     * request matches a skill description, use read to load the skill")
     * was too soft — the LLM treated skill invocation as one option among
     * many and frequently authored its own answer instead of loading the
     * SKILL.md instructions. Aligns with the
     * `c:/Works/claudecode/src/tools/SkillTool/prompt.ts` ruleset:
     * BLOCKING REQUIREMENT to load the relevant skill BEFORE generating
     * any other response when a skill matches.
     *
     * Filters out skills with disableModelInvocation=true (Issue 056).
     */
    getSystemPromptSnippet(): string;
    /**
     * Check if a name is a valid skill
     */
    has(name: string): boolean;
    /**
     * Get the count of discovered skills
     */
    get size(): number;
}
/**
 * Get the global skill registry instance
 *
 * IMPORTANT: If projectRoot is undefined, returns existing instance without reset.
 * This prevents accidental singleton reset when called without arguments.
 */
declare function getSkillRegistry(projectRoot?: string, customPaths?: Partial<SkillPathsConfig>): SkillRegistry;
/**
 * Initialize the skill registry and discover skills
 */
declare function initializeSkillRegistry(projectRoot?: string, customPaths?: Partial<SkillPathsConfig>): Promise<SkillRegistry>;
/**
 * Reset the global registry (for testing or hot reload)
 */
declare function resetSkillRegistry(): void;

/**
 * Skill Executor - Execution Engine
 *
 * Handles skill execution with support for:
 * - Inline execution (default)
 * - Fork execution (sub-agent)
 * - Tool restrictions
 */

/**
 * Execution mode
 */
type ExecutionMode = 'inline' | 'fork';
/**
 * Execution options
 */
interface ExecutionOptions {
    /** Force a specific execution mode */
    mode?: ExecutionMode;
    /** Override model */
    model?: string;
    /** Override agent type (for fork mode) */
    agent?: string;
    /** Override allowed tools */
    allowedTools?: string[];
    /** Callback for inline execution */
    onExecute?: (content: string, skill: Skill) => Promise<string>;
}
/**
 * Skill executor class
 */
declare class SkillExecutor {
    private context;
    constructor(context: SkillContext);
    /**
     * Execute a skill
     */
    execute(skillName: string, args: string, options?: ExecutionOptions): Promise<SkillResult>;
    /**
     * Execute skill inline (in current context)
     */
    private executeInline;
    /**
     * Execute skill in fork mode (sub-agent)
     */
    private executeFork;
    /**
     * Build the execution prompt
     */
    private buildPrompt;
    /**
     * Parse allowed tools string into array
     */
    private parseAllowedTools;
}
/**
 * Create a skill executor
 */
declare function createExecutor(context: SkillContext): SkillExecutor;
/**
 * Execute a skill with default context
 */
declare function executeSkill(skillName: string, args: string, context: SkillContext, options?: ExecutionOptions): Promise<SkillResult>;

/**
 * Skill Expander - Expand skill commands for LLM context injection
 *
 * Takes a skill invocation and produces content that can be injected
 * into the user message for LLM execution.
 *
 * Design based on pi-mono's _expandSkillCommand:
 * - Wraps content in XML blocks for clear context
 * - Includes skill metadata (name, location)
 * - Resolves all variables ($ARGUMENTS, $0, etc.)
 * - Handles dynamic context (!`command`)
 */

/**
 * Result of skill expansion
 */
interface SkillExpansionResult {
    /** The expanded skill content ready for LLM injection */
    content: string;
    /** Whether the skill has model invocation disabled */
    disableModelInvocation: boolean;
    /** Original skill metadata */
    skill: Skill;
}
/**
 * Expand a skill into LLM-ready content
 *
 * This function:
 * 1. Resolves all variables in the skill content ($ARGUMENTS, $0, $1, etc.)
 * 2. Executes dynamic context commands (!`command`)
 * 3. Wraps the content in an XML block for clear context boundaries
 *
 * @param skill - The full skill object with content
 * @param args - Raw arguments string from user input
 * @param context - Execution context (working directory, session ID, etc.)
 * @returns Expansion result with content ready for LLM injection
 */
declare function expandSkillForLLM(skill: Skill, args: string, context: SkillContext): Promise<SkillExpansionResult>;
/**
 * Format skill activation message for user display
 */
declare function formatSkillActivationMessage(skillName: string, args: string): string;

export { SkillExecutor, SkillRegistry, VariableResolver, clearPluginSkillPaths, createExecutor, createResolver, discoverSkills, discoverSkillsWithMonorepo, executeSkill, expandSkillForLLM, formatSkillActivationMessage, getDefaultSkillPaths, getNestedSkillPaths, getSkillPathsFlat, getSkillRegistry, initializeSkillRegistry, listPluginSkillPaths, loadFullSkill, loadSkillFileContent, loadSkillMetadata, parseArguments, parseSkillMarkdown, registerPluginSkillPath, resetSkillRegistry, resolveSkillContent, unregisterPluginSkillPath };
export type { DiscoveryResult, ExecutionMode, ExecutionOptions, ISkillRegistry, IVariableResolver, Skill, SkillArtifact, SkillContext, SkillDynamicContextExecutor, SkillExpansionResult, SkillFile, SkillFrontmatter, SkillHook, SkillHooks, SkillMetadata, SkillPathsConfig, SkillResult, SkillSource };
