/**
 * Skill 系统类型定义
 *
 * Skill 是可复用的提示模板，类似于 Claude Code 的 Skills 功能。
 * 与 Agent 不同，Skill 不是独立的执行单元，而是预定义的提示模板，
 * 可以被 Agent 调用来执行特定任务。
 */

/**
 * Skill 参数定义
 */
export interface SkillParameter {
  /** 参数类型 */
  type: 'string' | 'number' | 'boolean' | 'array' | 'object';
  /** 参数描述 */
  description: string;
  /** 是否必需 */
  required?: boolean;
  /** 默认值 */
  default?: unknown;
  /** 枚举值（仅 string 类型） */
  enum?: string[];
}

/**
 * Skill 定义
 */
export interface Skill {
  /** Skill 唯一标识 */
  name: string;
  /** Skill 显示名称 */
  displayName?: string;
  /** Skill 描述 */
  description: string;
  /** Skill 分类 */
  category?: string;
  /** 提示模板（支持变量插值 {{variable}}） */
  promptTemplate: string;
  /** Skill 参数定义 */
  parameters?: Record<string, SkillParameter>;
  /** 关键词（用于搜索） */
  keywords?: string[];
  /** 来源（内置/用户定义/项目） */
  source: 'builtin' | 'user' | 'project';
  /** 来源路径（用户定义或项目 Skill 的文件路径） */
  sourcePath?: string;
  /** 是否启用 */
  enabled?: boolean;
  /** 版本 */
  version?: string;
  /** 作者 */
  author?: string;
}

/**
 * Skill 执行上下文
 */
export interface SkillContext {
  /** 当前工作目录 */
  workdir: string;
  /** 额外的上下文变量 */
  variables?: Record<string, string>;
}

/**
 * Skill 执行结果
 */
export interface SkillExecutionResult {
  /** 是否成功 */
  success: boolean;
  /** 渲染后的提示 */
  prompt?: string;
  /** 错误信息 */
  error?: string;
}

/**
 * Skill 文件格式（YAML/JSON）
 */
export interface SkillFile {
  /** 文件版本 */
  version?: string;
  /** Skill 定义 */
  skill: Omit<Skill, 'source' | 'sourcePath'>;
}

/**
 * Skill 搜索结果
 */
export interface SkillSearchResult {
  /** Skill */
  skill: Skill;
  /** 匹配分数 */
  score: number;
  /** 匹配原因 */
  matchReason: string;
}

/**
 * Skill 注册表配置
 */
export interface SkillRegistryConfig {
  /** 用户 Skills 目录 */
  userSkillsDir?: string;
  /** 项目 Skills 目录 */
  projectSkillsDir?: string;
  /** 是否自动加载 */
  autoLoad?: boolean;
}