Skill Recommender
帮用户解决一个具体痛点：很多人不知道有哪些 skill 适合自己的工作。
这个 skill 通过两种输入方式构建用户的工作画像，然后到 skill 生态里实际搜索并校验，给出有针对性的安装推荐。
使用流程
第 1 步：确认输入方式
优先判断用户是否已经提供足够信息，只有在用户没有提供职业、任务、需求或 git 路径时，才询问输入方式。
支持的输入方式：
- 自然语言描述：用户用一两段话讲清楚"我是做什么的，平时主要做哪些事"
- git 仓库路径：用户给一个或多个本地 git 仓库的绝对路径，由 skill 自动分析提交历史
- 两者都给：效果最好，文字提供职业上下文，git 提供真实技术栈证据
第 2 步：收集数据
如果是 git 路径：在开始分析前，先简短说明：
- 只分析提交历史、文件类型、目录名和提交信息关键词
- 不读取完整代码内容，不上传仓库内容
- 如果提交信息或目录名包含敏感信息，用户可改用自然语言描述
然后调用 scripts/analyze_git.py，传入仓库路径。脚本会输出 JSON，包含：
- commit_count：总提交数
- time_range：时间跨度
- top_file_types：最常修改的文件类型 Top 10（看技术栈）
- top_directories：最常修改的目录 Top 10（看项目结构 / 工作焦点）
- commit_keywords：提交信息高频关键词（看工作类型）
路径安全要求：repo path 必须作为独立参数传给脚本，不要拼接进 shell 字符串；路径需正确转义或使用参数数组传递；如果路径不存在、不是 git 仓库或无权限读取，跳过该仓库并提示用户。
python scripts/analyze_git.py "$repo_path" --max-commits 1000
如果用户给了多个仓库，循环调用并合并分析（取各仓库 top_file_types 的并集，commit_keywords 按频率加权合并）。
如果是文字描述：直接读取用户的描述，提取职业、领域、典型任务。
第 3 步：深化画像（追问）
判断用户输入是否足够具体：
跳过追问的条件（满足任意一条）：
- 用户已经描述了具体的日常任务（不只是职位名）
- 用户提供了 git 路径（代码会说话）
触发追问的条件：用户只说了职位名或一句话描述（如"我是游戏策划""我做运营"）
触发时，只问 1 个问题，用选择题形式，不要开放问答：
> 你主要做哪类工作？（可多选）
> A. 写文档 / 策划案 / 需求
> B. 数据分析 / 报表
> C. 创意 / 内容 / 文案
> D. 流程管理 / 跨团队协作
> E. 技术工具 / 脚本 / 自动化
> F. 其他（请简单描述）
根据用户的职业方向调整选项，让选项贴近他们的实际场景。收到回答后，进入第 4 步。
如果用户拒绝补充信息或说"你直接推荐吧"：
- 基于已有信息生成低置信度画像
- 推荐数量控制在 1-3 个
- 在输出中明确说明"由于画像信息较少，推荐偏通用"
第 4 步：构建工作画像
把收集到的信息整理成一个内部画像（不用完整展示给用户，但你心里要有数）：
- 角色 / 职业：开发者？产品经理？运营？数据分析师？内容创作者？
- 主要技术栈 / 工具（如果适用）
- 典型工作内容：3-5 个最常做的事（从追问回答或 git 数据中提取）
第 5 步：检测 npx / skills CLI 可用性
在进入搜索前，先检测 npx 是否可用：
npx --version 2>&1
如果 npx 不可用（退出码非 0）：
- 告知用户当前环境无法使用 skills.sh 目录，也无法检查已安装 skill
- 继续执行第 7 步检测 gh
- 如果 gh 可用，则仅使用 GitHub 源搜索，输出时省略 npx skills add 安装命令
- 如果 gh 也不可用，停止安装推荐，仅输出工作画像和建议搜索关键词
如果 npx 可用，继续检测 skills CLI：
npx skills --version 2>&1
- 如果 skills CLI 失败，禁用 skills.sh 源，仅使用 gh 源（如可用）
- 如果可用，继续第 6 步
第 6 步：检查已安装的 skill
在搜索之前先拿已安装列表，避免对已安装方向做无效搜索：
npx skills ls -g 2>&1
- 已安装的 skill 记录下来，后续搜索结果中遇到直接跳过，不出现在推荐列表
find-skills单独标记：如果没装，固定在最后的基础推荐区出现；如果已装，跳过- 如果某个搜索方向的 skill 全部已安装，可以在关键词生成时跳过该方向，节省搜索次数
如果 npx skills ls -g 失败：
- 不中断流程，仅跳过"已安装过滤"
- 输出中不要声称已排除所有已安装 skill
- find-skills 改为不在基础推荐区出现，或标注"无法确认是否已安装"
第 7 步：检测 gh 可用性
先检测 gh 是否安装：
gh --version 2>&1
如果失败，GitHub 源不可用，静默跳过，进入第 8 步。
如果成功，再检测登录状态：
gh auth status 2>&1
- 退出码为 0 → GitHub 源可用，继续
- 其他情况（未登录 / 网络问题）→ 静默跳过 GitHub 源，不提示用户
原则：gh 不可用就跳过，不打扰用户。
第 8 步：生成搜索关键词
参考 references/skill-categories.md 的示例，生成 4-6 组搜索关键词。
关键词生成规则（必须遵守）：
-
从任务推，不从职位推
- ❌ 搜game designer（职位名，生态里没人这么标）
- ✅ 搜game document、game balance、level design（具体任务） -
英文优先
- skill 生态以英文为主，中文职业名要先翻译成对应的英文任务描述
- 例外：写作类 skill 可以试中文关键词（中文写作、humanizer） -
每组关键词语义独立
- 避免同义词重复搜（game design和game designer是浪费）
- 每组关键词覆盖一个不同的工作场景 -
references/skill-categories.md只作为参考样本
- 表里没有的职业，根据上述规则自由推导
- 不要局限于表里列出的关键词，可以根据用户的具体任务自行扩展 -
从具体到抽象
- 先搜最具体的（如game balance），没结果再退到更宽泛的（game design）
第 9 步：搜索候选 skill
源 1：skills.sh（精选目录，质量有保证）
npx skills find "<keyword>" 2>&1 | head -40
源 2：GitHub（覆盖更广，找到冷门但专业的 skill）
仅在第 7 步确认 gh 可用时执行，否则跳过。
# 按 topic 精准搜
gh search repos "<keyword>" --topic claude-skill --limit 10 --json fullName,description,stargazersCount,url
# 按仓库内含 SKILL.md 补充搜
gh search code "filename:SKILL.md <keyword>" --limit 10 --json repository,path,url
如果 GitHub 搜索命令失败、返回字段不完整或触发速率限制，跳过该源，不中断流程。
两个源的结果合并去重：同一个 skill 在两个源都出现，优先用 skills.sh 的安装量数据。
第 10 步：质量校验
不要看到搜索结果就直接推荐。每个候选 skill 必须过三关：
| 维度 | 标准 |
|---|---|
| 安装量 / star 数 | 见下方三档规则 |
| 来源 | 官方源、知名组织、该领域高可信维护者权重高（如 anthropics 或相关工具的官方组织）；未知个人作者要谨慎 |
| 匹配度 | skill 描述要和用户的真实需求对得上，不要为了凑数硬塞 |
安装量三档规则（skills.sh）：
| 档位 | 安装量 | 处理方式 |
|---|---|---|
| 强推荐 | 1K+ | 直接推荐，无警告 |
| 谨慎推荐 | 200–1K | 可推荐，输出时加 ⚠️ + 提示 |
| 不推荐 | < 200 | 不进推荐列表，不给安装命令；最多在"生态空白说明"中概括说明搜索结果质量不足，不提具体 skill 名 |
GitHub 来源三档规则：
| 档位 | star 数 | 处理方式 |
|---|---|---|
| 强推荐 | 500+ | 可推荐，无警告 |
| 谨慎推荐 | 50–500 | 可推荐，输出时加 ⚠️ + 提示 |
| 不推荐 | < 50 | 不进推荐列表，不给安装命令 |
歧义名称校验：当 skill 的名称与其搜索关键词存在明显语义落差时（例如搜 narrative 找到 narrative-text-visualization，名字混合了多个语义），不要靠猜测判断，需用以下命令拉取详情页确认其实际功能：
npx skills info <owner/repo@skill> 2>&1 | head -60
如详情与用户需求不符，直接排除，不出现在推荐列表。
如果某个搜索方向没有 skill 通过校验，就不要在那个方向硬推——告诉用户"这个方向当前生态里还没有成熟 skill"。
第 11 步：输出格式
## 你的工作画像
[2-4 句话，描述角色 / 主要做什么 / 技术栈]
## 推荐安装的 Skill
**1. [skill 全名]**
[一两句话说明这个 skill 做什么]
来源：skills.sh｜安装量：1.2K｜匹配词：game design
`npx skills add <owner/repo@skill> -g -y`
**2. ⚠️ [skill 全名]**
[一两句话说明这个 skill 做什么]
来源：skills.sh｜安装量：479｜匹配词：game document
安装量偏低，建议先查看 skill 详情再决定是否安装。
`npx skills add <owner/repo@skill> -g -y`
---
## 生态空白说明（按需出现）
**触发条件**：当推荐列表中超过一半是通用工具（非该职业专属），或某个用户明确关心的工作方向完全没有通过校验的 skill 时，必须加这一节，主动解释原因。
> **[方向名称]方向当前生态较稀薄**
> 搜索到的 skill 安装量均低于推荐门槛（最高 xxx），暂无成熟专属工具。
> 目前推荐列表中的 [skill 名] 是通用工具，可覆盖部分需求，但不是专为该场景设计的。
> 如果你对这个方向有强需求，可以考虑用 `/skill-creator` 自己创建一个。
**注意**：不需要时不写这一节，不要为了格式完整而硬凑。
---
## 基础推荐
**find-skills**
Skill 生态的搜索入口，装了之后可以随时让 Claude 帮你找更多 skill。
`npx skills add anthropics/skills@find-skills -g -y`
注意：基础推荐区只在 find-skills 未安装时出现。
如果用户想直接安装，先列出将要执行的命令，获得用户确认后再运行（因为这会修改用户的全局环境）。
重要原则
- 基于证据，不要瞎编：每个推荐都要能对应到具体的搜索结果
- 少而精：宁可推荐 3 个高质量的，也不要堆 10 个泛泛的
- 校验三件套（安装量、来源、匹配度）任何一项不过关就不推
- 找不到就承认：某个方向没有合适 skill 时，明说"这块生态空白"，不要硬凑
- 降级不中断：gh 不可用、npx 不可用等任何工具缺失，都要有兜底路径，不能卡死
