双源 Skill 搜索助手

为什么需要专门的 Skill 搜索工作流

在使用 Agent 时，开发者往往只知道自己想要实现的任务（例如“帮我找个能写简历的 skill”），却不清楚确切的仓库名。GitHub 的文本匹配机制对同义词极其敏感，单一关键词极易漏掉高相关度的结果。同时，技能安装涉及本地环境检查、多源降级和文件校验，手动拼凑命令不仅繁琐，还容易破坏 Agent 的 skills 目录结构。这个工作流旨在将“意图理解、多源检索、安全安装”串联为一套标准化的自动化流程。

核心机制：从关键词发散到双源检索

该技能的核心工作流分为检索与安装两个阶段。

1. 意图解析与关键词发散
当接收到用户的中文描述时，Agent 会先将其翻译为英文，并利用大模型发散出 2-3 组近义词或不同侧重点的关键词变体（如 resume builder、resume optimizer、cv generator）。这种多角度覆盖能显著提高 GitHub REST API 和 SkillHub CLI 的召回率。

2. 并行检索与去重排序
脚本会针对每组关键词并行发起双源搜索。所有结果按 name 去重后，依据相关性分数降序排列，截取 TOP 5 输出给用户。Agent 需严格信任脚本的排序结果，不进行二次主观干预。

3. 确认与本地校验
在用户明确选择之前，技能绝对不会执行安装。安装前，必须检查 {skills_dir}/{name}/SKILL.md 是否存在以避免重复下载。对于 GitHub 源，采用浅克隆并辅以压缩包下载兜底；安装完成后，必须校验 SKILL.md 的有效性，无效则自动清理。

适用边界与异常处理

• 不适用场景：当用户已知确切的 skill 名称并希望直接调用，或者正在开发/编辑新 skill 时，不应触发此搜索流程。
• 静默降级与限流保护：若 SkillHub 不可用，系统会静默降级为纯 GitHub 搜索。针对 GitHub 匿名接口的限流，技能不会主动要求配置，仅在触发异常时，才向用户提示设置 GITHUB_TOKEN。
• 友好的报错翻译：所有底层脚本抛出的原始错误都会被拦截，并转化为符合用户当前语言环境的友好提示，避免向最终用户暴露技术栈细节。