Skill 搜索与安装工作流

Overview

双源 skill 发现与安装工作流：同时搜索 GitHub 和 SkillHub，按相关性排序取 TOP 5，用户确认后安装。核心原则：多关键词覆盖、先搜后装、用户确认、本地检查、翻译优先。

语言匹配规则：所有面向用户的输出（推荐表格、提示信息、错误消息、确认语句）必须匹配用户使用的语言。用户说中文则中文输出，用户说英文则英文输出。

When to Use

触发场景：

• 用户说"帮我找 X 的 skill""搜索/推荐 skill""有什么好用的 skill"
• 用户描述了一个任务，需要匹配合适的 skill
• 用户想发现尚未安装的能力

不适用场景：

• 用户已知确切 skill 名称，只想直接使用（非搜索行为）
• 用户在创建/编辑 skill

工作流概览（2 步）

1. Skill 检索：按用户任务描述，翻译为英文后发散 2-3 组关键词变体，双源搜索（GitHub + SkillHub）匹配的 skill，合并去重取 TOP 5
2. 决策 + 下载安装：用户确认选择后，按来源执行安装

双源架构

• 默认同时搜索两个源，合并归一化排序，取 TOP 5
• SkillHub 不可用时静默降级为纯 GitHub 搜索
• 支持 --source github|skillhub|all 精确控制

Step 1：Skill 检索

1.1 判断用户意图

• 描述明确：直接按描述发起检索
• 描述模糊（如"找个 skill""推荐个技能"）：
• 先检查对话上下文中是否有可推断的需求
• 如有则基于上下文发起检索
• 如无则追问用户想找什么方向的 skill

1.2 中文 → 英文翻译 + 关键词发散

用户使用中文描述时，使用大模型翻译为 2-3 组英文关键词变体，覆盖不同角度和近义词，避免单关键词遗漏。

为什么需要多关键词？ GitHub 搜索依赖文本匹配（仓库名、描述、README）。同义词和不同表述方式会命中完全不同的仓库。例如：
- "resume builder" 搜不到 resume-jd-optimizer-cn（用了 "optimizer" 而非 "builder"）
- "resume optimizer" 就能搜到

关键词发散规则：
1. 将中文描述翻译为 1 组核心英文关键词
2. 至少再发散 1-2 组变体，考虑：近义词替换（builder → optimizer/ generator / writer）、功能侧重切换（编辑 → 优化 / 匹配 / 评分）、场景补充（通用 → Chinese / ATS / JD-driven）
3. 关键词保持简洁（2-4 个单词），不做长句查询

> 翻译和发散在 Agent 层完成，搜索脚本接收英文关键词作为参数。

1.3 Agent 类型识别

调用搜索/安装脚本时需传入当前 Agent 类型（--agent-type），用于 SkillHub 的平台过滤（--platform）。

按以下优先级识别：

1. System Prompt：若运行环境提供 system prompt（如 Catdesk、Hermes 等），从中识别 Agent 框架名
2. IDENTITY.md：若运行环境无 system prompt（如 Claude 等），检查本地是否存在 IDENTITY.md，从中读取 Agent 框架标识
3. 自行判断：若以上均无法识别，根据你所在的运行时框架自行判断

> 若确实无法识别，可省略该参数。SkillHub 支持以下 platform：claude、codex、cursor、gemini-cli、windsurf、openhands。不在此列表内的值将被忽略。

1.4 调用检索脚本（多关键词）

对每组关键词变体分别调用搜索脚本：

{python} {skill_dir}/scripts/skill_search.py "<关键词变体1>" --agent-type <Agent类型> --limit 5
{python} {skill_dir}/scripts/skill_search.py "<关键词变体2>" --agent-type <Agent类型> --limit 5
{python} {skill_dir}/scripts/skill_search.py "<关键词变体3>" --agent-type <Agent类型> --limit 5

> 可并行执行（互不依赖），提升搜索速度。

合并与去重规则：

1. 合并所有变体的搜索结果，按 name 去重（保留 score 最高的）
2. 按 score 重新降序排列
3. 取 TOP 5 作为最终结果

可选参数：

• --source github：仅搜索 GitHub
• --source skillhub：仅搜索 SkillHub
• --source all：双源搜索（默认）
• --limit 5：返回条数（默认 5）

> {python} 按本机实际选择：macOS / Linux 通常为 python3，Windows 通常为 python 或 py。下同。

1.5 脚本输出

脚本输出 JSON 数组到 stdout，每条结果包含：

{
  "name": "skill 名称",
  "source": "github | skillhub",
  "repo_url": "https://github.com/...  (GitHub 源有值，SkillHub 源为 null)",
  "description": "技能描述",
  "score": 0.92,
  "stars": 128  (仅 GitHub 源有值)
}

1.6 输出规则

• 输出 TOP 5：按 score 从高到低推荐，最多 5 个（不足就少输出）
• 0 条结果时告知用户："没有找到完全匹配的 skill，建议换个关键词或更简短的描述再试一次。"
• 展示格式：# | Skill | 推荐理由（中文用户）或 # | Skill | Why Recommended（英文用户）。仅此三列，不要自行添加额外信息
• 推荐理由：结合 description 字段和 stars（GitHub 源）汇总
• 最优推荐：返回结果的第 1 条即为最优推荐，已由脚本按 score 排序，直接推荐即可。不要自行重新分析或排序，不要添加"综合你的需求，我比较推荐 XXX"等自行分析的结论

1.7 输出模板

> 严格参照以下格式，将 {...} 占位符替换为实际值：

为你找到以下相关 skill：

| # | Skill | 推荐理由 |
|---|-------|---------|
| 1 | {name} | {reason} |
| 2 | {name} | {reason} |

最优推荐是 #1 {name}（{reason}）。你想安装哪一个？告诉我编号或名字就行。

英文模板（用户说英文时使用）：

Here are the matching skills I found:

| # | Skill | Why Recommended |
|---|-------|-----------------|
| 1 | {name} | {reason} |
| 2 | {name} | {reason} |

The top recommendation is #1 {name} ({reason}). Which one would you like to install? Tell me the number or name.

1.8 异常处理

> 脚本执行出错或返回非零退出码时，禁止将原始错误信息直接展示给用户，需按以下规则处理：

英文错误消息（用户说英文时使用）：

1.9 GitHub Token 配置

搜索过程中，若遇到 GitHub 限流（退出码 2），仅在此时提示用户：

GitHub API 请求次数已达上限（匿名 60 次/小时）。
设置环境变量 GITHUB_TOKEN 可提升至 5000 次/小时。

获取方式：GitHub → Settings → Developer settings → Personal access tokens → Generate new token（无需勾选任何权限）。
设置方法：export GITHUB_TOKEN=<你的token>

> 日常使用中 60 次/小时足够，仅在触发限流时才提示。不要主动检查或要求用户预先设置。

英文提示（用户说英文时）：

GitHub API rate limit reached (60 req/hr anonymous).
Set the GITHUB_TOKEN environment variable for 5,000 req/hr.

How to get one: GitHub → Settings → Developer settings → Personal access tokens → Generate new token (no permissions needed).
How to set: export GITHUB_TOKEN=<your-token>

Step 2：决策 + 下载安装

2.1 确认用户选择

当用户通过以下方式确认时，进入安装流程：

• 说编号：如 "1""第一个"（英文： "1" "the first one"）
• 说名称：如 "装 resume-builder"（英文： "install resume-builder"）
• 说意图：如 "安装""装这个""就它了""用这个"（英文： "install" "this one" "let's go with this" "use this"）

2.2 本地检查

检查 {skills_dir}/{name}/SKILL.md 是否存在（{skills_dir} 为当前 Agent 的 skills 目录，{name} 为用户选择的 skill 名称（即 GitHub 仓库名））。

• 已安装：告知用户 "该 skill 已安装，无需重复安装，是否直接运行？"（英文： "This skill is already installed. Would you like to run it directly?"）
• 未安装：执行安装流程

2.3 执行安装

按搜索结果的 source 字段选择安装方式：

GitHub 源（source: "github"）：

{python} {skill_dir}/scripts/skill_install.py <name> --dir <当前Agent的skills目录> --source github --repo-url <repo_url>

安装策略：

1. 尝试 git clone --depth 1 <repo_url> <skills_dir>/<name>
2. 若 git 不可用，fallback 为 ZIP 下载（GitHub archive API）
3. 安装完成后校验 SKILL.md 是否存在，不存在则清理并报错

SkillHub 源（source: "skillhub"）：

{python} {skill_dir}/scripts/skill_install.py <name> --dir <当前Agent的skills目录> --source skillhub --agent-type <Agent类型>

2.4 安装结果

英文安装结果（用户说英文时）：

核心工具

完整使用示例

用户：找个写简历的 skill

Agent 内部：翻译+发散为 3 组关键词变体 → "resume builder"、"resume optimizer chinese"、"cv generator"，识别 Agent 类型

Agent 执行（并行）：

python3 {skill_dir}/scripts/skill_search.py "resume builder" --agent-type claude
python3 {skill_dir}/scripts/skill_search.py "resume optimizer chinese" --agent-type claude
python3 {skill_dir}/scripts/skill_search.py "cv generator" --agent-type claude

合并去重后，按 score 降序取 TOP 5。

Agent 输出：

为你找到以下相关 skill：

最优推荐是 #1 resume-jd-optimizer-cn（JD 驱动中文简历优化，⭐135）。你想安装哪一个？告诉我编号或名字就行。

用户：1 → Agent 确认本地未安装 → 执行安装

英文示例：

User: find me a skill for writing resumes

Agent: translates + diverges → "resume builder", "resume optimizer chinese", "cv generator"; searches in parallel; merges & deduplicates

Agent outputs:

Here are the matching skills I found:

The top recommendation is #1 resume-builder (Smart resume generator, ⭐234). Which one would you like to install? Tell me the number or name.

User: 1 → Agent confirms not installed → installs → "resume-builder has been installed successfully. Would you like to use it for your task?"

Common Mistakes

Red Flags - 自查清单

以下想法出现时，STOP 并回到规则：

• "这个中文描述够清楚了，不需要翻译" → 翻译为英文再搜
• "翻译一组关键词就够了" → 至少 2-3 组变体，覆盖近义词
• "就装第 1 个吧，不用问了" → 等用户确认
• "SkillHub 挂了，我直接用 GitHub" → 可以，但告知用户
• "这个 skill 肯定没装过" → 先检查本地
• "脚本输出有点奇怪，我重新排个序" → 信任脚本排序
• "我先帮用户检查下 GITHUB_TOKEN" → 仅在限流时提示
• "clone 成功了，应该没问题" → 校验 SKILL.md

注意事项

1. 多关键词覆盖：中文→英文翻译后必须发散 2-3 组关键词变体，覆盖近义词和不同角度
2. 本地优先：安装前须确认本地是否已安装该 skill，避免重复下载
3. 安装确认：需等用户选择后才安装，不自动安装
4. CN→EN 翻译：调用搜索脚本前，先由大模型将用户中文描述翻译为英文关键词
5. GitHub 目录名：安装到 {skills_dir}/{仓库名}/，不做重命名
6. 安装校验：GitHub 源安装后须校验 SKILL.md 存在性，无效则自动清理
7. SkillHub 可选：SkillHub CLI 不可用或未认证时静默跳过，不影响 GitHub 搜索