Skill导航

概述

Skill 导航

帮你导航手里的每个 Skill——装了什么、用哪个、怎么用对。

Overview

Skill 导航是「Skill 可见性 + 效能优化层」——不是又一层推荐器（WorkBuddy 原生已在隐式匹配，纯推荐无增量），而是把匹配过程显性化：谁在为你服务、为什么选它、怎么用出它的全力。

对应客户两问：

1. 「我不知道是哪个 Skill 在为我服务」→ 看得见（能力地图 / 服务可见 / 使用盘点）
2. 「不知道能不能让 Skill 作用最好地为我服务」→ 用得好（选对 / 用对 / 组合好）

两问顺序即优先级：先看得见，才谈得上用得好。

何时使用

你不需要先搞清楚该用哪个 Skill。 只要说要做的事，或直接点名 Skill，导航都会接住：

• 不知道用哪个：「我要做 XX，用什么 Skill？」「有没有能做 XX 的 Skill」「帮我选个 Skill」→ 走「显性化推荐」。
• 知道用哪个：「用 xxx Skill 做 XX」→ 走「指定执行」，确认存在就转交，并明示当前在服务的 Skill。
• 想盘点：「我装了什么 Skill」「我的技能有哪些」「盘点一下我的 Skill」→ 走「能力地图 / 使用盘点」。
• 想弄清原理：「刚才 / 这个任务是谁在干活」「为什么选了它」。
• 想用好：问某个 Skill 的「最佳用法」「怎么用出效果」。

能力（V1.1）

1. 能力地图（看得见）

扫描四层已安装 Skill → 生成 registry.json 缓存 → 按「分类 + 场景」呈现：我装了什么、各自管什么。

• 槽位制分类：不按 skill 名字写死归类（每台机器装的都不一样），而是每个分类配领域关键词集，拿 skill 的 name + description 现场打分归位；零分的进「待识别」，由 agent 运行时读它的 SKILL.md 语义兜底——用户装什么，地图就长什么样。

2. 服务可见（看得见 · 事中）

用户在任务中或完成后问「刚才用了什么 Skill」「现在是哪个 Skill 在干活」→ 明示正在 / 已经服务的 Skill。

• 经导航「指定执行」的任务：直接知道用了什么，稳定可答。
• 未经导航（WorkBuddy 原生隐式匹配）的任务：查 ~/.workbuddy/usage-log.json（WorkBuddy 维护的调用日志，含每个 skill 的 lastUsedDate / recentDates）可答「最近用了哪些」；但它是天粒度、非实时，当下这一条「正在用哪个」仍只能基于对话上下文尽力推断。

3. 显性化推荐（用得好 · 选对）

把需求映射到 registry，给出「最优 + 备选 + 推荐理由 + 最佳用法提示」。

• 候选功能相近时，一句话点明「为什么选 A 不选 B」的区别——这个对比在运行时现场读两个候选的 SKILL.md 生成，不预存。
• 推荐必须多说一句「要发挥它的最佳效果，注意这几点」——很多 Skill 效果打折是因为用法不对，不是 Skill 不行。
• 缺口提示：需求映射不到任何已装 Skill 时，明说「这个场景你还没装对应 Skill」，并给出可从市场补充的方向（少而准，不为凑数推荐）。

4. 指定执行

「用 xxx Skill 做…」→ 确认目标存在后转交该 skill，并明示当前在服务的 Skill。

5. 使用盘点（基础版）

交叉 registry.json（装了哪些）与 ~/.workbuddy/usage-log.json（用了哪些、最后使用日、使用频率），呈现哪些被真正用到、哪些在吃灰、吃灰多久。

6. 元数据体检（V1.1 新增）

description 是 skill 能否被触发、被选中的命门（实证：触发失败最常见原因就是 description 空泛）。体检 registry 中 meta_flags 标记的 skill（无 frontmatter / 描述过简），告诉用户：哪些 skill 因为「自我介绍没写好」可能永远触发不了，并给出改写建议。

7. 新装播报（V1.1 新增）

每次重建 registry 自动与上一份对比，呈现「自上次盘点以来新装了什么、卸载了什么」（changes_since_last）——好 skill 容易丢，装了什么自己未必记得住。

8. 撞车预警（V1.1 新增 · 运行时）

同类中 description 语义相近的 skill 会让模型选错（撞车是常态不是例外）。呈现地图或推荐时，发现两个候选边界模糊，主动提示「这两个功能相近、容易选错」，并一句话划清各自边界（现场读两者 SKILL.md 生成），帮用户决定是分工还是只留一个。

扫描与注册表缓存

• 生成缓存：运行 scripts/build_registry.py（纯 Python，无第三方依赖）。
• 四层全扫：用户级 ~/.workbuddy/skills/、连接器 ~/.workbuddy/plugins/cache/workbuddy-connector-plugins-official/、项目级 {workspace}/.workbuddy/skills/、内置/插件 cache（默认关闭，--include-builtin 开启）。
• 产物 registry.json（项目根），结构：{ generated_at, total, by_layer, by_category, merged_duplicates, unclassified, meta_issues, changes_since_last, skills[] }，每条含 id / name / layer / category / category_score / description / meta_flags / path；跨层同名已合并（sources + alternatives 标双来源）。
• 分类采用槽位打分（领域关键词 × name+description），与具体 skill 名解耦；「待识别」由运行时语义兜底。
• 最佳用法提示不预生成，运行时现场提炼（读对应 SKILL.md 正文）。

合规边界

• 本 skill 只做「盘点、呈现、推荐、指导用法」，不替用户做最终判断。选哪个、用不用，决定权始终在用户。
• 推荐基于描述匹配，非权威背书；跨层同名 Skill 会标注「存在多个同名，注意区分」。

版本规划

• V1.0：能力地图 + 显性化推荐 + 指定执行 + 使用盘点（基础版）。
• V1.1（当前）：分类改槽位打分（与 skill 名解耦，适配任意机器）+ 元数据体检 + 新装播报 + 撞车预警 + 缺口提示。依据：2026-09-26 用户 skill 使用需求调研（触发失败多因 description 空泛 / 撞车是常态 / 好 skill 易丢 / 少而准胜过大而全）。
• V2.0：工作流模板（固化调用顺序 / 每步指令 / 触发口令）、使用中沉淀、反馈加权排序。

参考

• references/项目概念文档.md — 完整产品设计（需求锚点 / 定位 / 8 条关键决策 / 命名历程）。