Skill Recommender

帮用户解决一个具体痛点：很多人不知道有哪些 skill 适合自己的工作。

这个 skill 通过两种输入方式构建用户的工作画像，然后到 skill 生态里实际搜索并校验，给出有针对性的安装推荐。

使用流程

第 1 步：确认输入方式

优先判断用户是否已经提供足够信息，只有在用户没有提供职业、任务、需求或 git 路径时，才询问输入方式。

支持的输入方式：

1. 自然语言描述：用户用一两段话讲清楚"我是做什么的，平时主要做哪些事"
2. git 仓库路径：用户给一个或多个本地 git 仓库的绝对路径，由 skill 自动分析提交历史
3. 两者都给：效果最好，文字提供职业上下文，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 组搜索关键词。

关键词生成规则（必须遵守）：

1. 从任务推，不从职位推

   • ❌ 搜 game designer（职位名，生态里没人这么标）
   • ✅ 搜 game document、game balance、level design（具体任务）

2. 英文优先

   • skill 生态以英文为主，中文职业名要先翻译成对应的英文任务描述
   • 例外：写作类 skill 可以试中文关键词（中文写作、humanizer）

3. 每组关键词语义独立

   • 避免同义词重复搜（game design 和 game designer 是浪费）
   • 每组关键词覆盖一个不同的工作场景

4. references/skill-categories.md 只作为参考样本

   • 表里没有的职业，根据上述规则自由推导
   • 不要局限于表里列出的关键词，可以根据用户的具体任务自行扩展

5. 从具体到抽象

   • 先搜最具体的（如 game balance），没结果再退到更宽泛的（game design）

第 9 步：搜索候选 skill

源 1：skills.sh（精选目录，质量有保证）

npx skills find "" 2>&1 | head -40

源 2：GitHub（覆盖更广，找到冷门但专业的 skill）

仅在第 7 步确认 gh 可用时执行，否则跳过。

# 按 topic 精准搜
gh search repos "" --topic claude-skill --limit 10 --json fullName,description,stargazersCount,url

# 按仓库内含 SKILL.md 补充搜
gh search code "filename:SKILL.md " --limit 10 --json repository,path,url

如果 GitHub 搜索命令失败、返回字段不完整或触发速率限制，跳过该源，不中断流程。

两个源的结果合并去重：同一个 skill 在两个源都出现，优先用 skills.sh 的安装量数据。

第 10 步：质量校验

不要看到搜索结果就直接推荐。每个候选 skill 必须过三关：

安装量三档规则（skills.sh）：

GitHub 来源三档规则：

歧义名称校验：当 skill 的名称与其搜索关键词存在明显语义落差时（例如搜 narrative 找到 narrative-text-visualization，名字混合了多个语义），不要靠猜测判断，需用以下命令拉取详情页确认其实际功能：

npx skills info  2>&1 | head -60

如详情与用户需求不符，直接排除，不出现在推荐列表。

如果某个搜索方向没有 skill 通过校验，就不要在那个方向硬推——告诉用户"这个方向当前生态里还没有成熟 skill"。

第 11 步：输出格式

## 你的工作画像

[2-4 句话，描述角色 / 主要做什么 / 技术栈]

## 推荐安装的 Skill

**1. [skill 全名]**
[一两句话说明这个 skill 做什么]
来源：skills.sh｜安装量：1.2K｜匹配词：game design
`npx skills add  -g -y`

**2. ⚠️ [skill 全名]**
[一两句话说明这个 skill 做什么]
来源：skills.sh｜安装量：479｜匹配词：game document
安装量偏低，建议先查看 skill 详情再决定是否安装。
`npx skills add  -g -y`

---

## 生态空白说明（按需出现）

**触发条件**：当推荐列表中超过一半是通用工具（非该职业专属），或某个用户明确关心的工作方向完全没有通过校验的 skill 时，必须加这一节，主动解释原因。

> **[方向名称]方向当前生态较稀薄**
> 搜索到的 skill 安装量均低于推荐门槛（最高 xxx），暂无成熟专属工具。
> 目前推荐列表中的 [skill 名] 是通用工具，可覆盖部分需求，但不是专为该场景设计的。
> 如果你对这个方向有强需求，可以考虑用 `/skill-creator` 自己创建一个。

**注意**：不需要时不写这一节，不要为了格式完整而硬凑。

---

## 基础推荐

**find-skills**
Skill 生态的搜索入口，装了之后可以随时让 Claude 帮你找更多 skill。
`npx skills add anthropics/skills@find-skills -g -y`

注意：基础推荐区只在 find-skills 未安装时出现。

如果用户想直接安装，先列出将要执行的命令，获得用户确认后再运行（因为这会修改用户的全局环境）。

重要原则

1. 基于证据，不要瞎编：每个推荐都要能对应到具体的搜索结果
2. 少而精：宁可推荐 3 个高质量的，也不要堆 10 个泛泛的
3. 校验三件套（安装量、来源、匹配度）任何一项不过关就不推
4. 找不到就承认：某个方向没有合适 skill 时，明说"这块生态空白"，不要硬凑
5. 降级不中断：gh 不可用、npx 不可用等任何工具缺失，都要有兜底路径，不能卡死