wwcai-find-skills

#Find Skills（场景驱动 · 多源 · 国内优先）

帮用户从多个技能市场 + 本地已装 + GitHub 开源中找到最合适的技能并一键安装。国内网络优先：主力源国内裸连可用，海外源作为回退。跨 Agent 通用：自动识别当前客户端并安装到正确目录。

#何时触发

• "找个 xxx 的技能 / 有没有 xxx 的 skill / 推荐一个 xxx"
• "我想做海报 / 帮我写公众号 / 分析今天的大盘"（自然语言场景，需映射到技能）
• "这个需求有现成技能吗 / xxx 怎么搞"（能力缺口 → 找技能补齐）
• "按分类看 / 办公效率类有哪些"（浏览分类）

#数据源（按国内友好度排序）

来源标注规范：上表「标记」列是各源的唯一官方徽章，召回、去重、输出、安装全程统一使用，不得自创别名（如不要写「skillhub.cn」「Coze 商店」「GH」）。同一技能跨多层命中时，按命中层全部列出，徽章之间用 · 分隔（例：📦 多源：🟦SkillHub · 🐙GitHub · 🏠本地）。

各源完整 API 参数、示例、Token 申请、限制说明见 references/api.md。

⚠️ Coze 关键坑：商店网页 URL 里的 product_id 不能用于 API；API 用的是搜索结果里的 metainfo.entity_id。

#核心流程（6 步）

#Step 1 · 理解场景

从用户自然语言提取三要素：

1. 任务意图：用户要解决什么问题？
2. 领域 → category：映射到 SkillHub 12 个一级标签（详见 references/categories.md）；映射不准时打开对应类目详情文件。
3. 中英文关键词：2~4 个，含同义词/上位词扩展。

示例：

• "帮我自动写周报发给老板" → 意图：报告生成+发送；category=office-efficiency；关键词：周报/工作汇报/日报/weekly report
• "我想做一个海报" → 意图：图片生成/排版；category=design-media；关键词：海报/poster/design/封面

#Step 2 · 多源联合搜索

并行调用各层（独立请求互不阻塞），任何一层失败记录原因后继续：

# L1 SkillHub API（主力，多候选词循环）
for kw in 周报 工作汇报 "weekly report"; do
  curl -s "https://api.skillhub.cn/api/skills?keyword=${kw}&sortBy=score&pageSize=8" \
    | jq '.data.skills[]'
done
 
# L3 字节 Coze（如有 COZE_API_TOKEN）
curl -s "https://api.coze.cn/v1/stores/plugins?keyword=周报&sort_type=relative&page_size=10" \
  -H "Authorization: Bearer $COZE_API_TOKEN" | jq '.data.items[]'
 
# L4 GitHub（如有 GITHUB_TOKEN）
curl -s -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.github.com/search/code?q=filename:SKILL.md+周报&per_page=10"
 
# L0 本地已装（跨平台目录探测，见 platforms.md）
ls "$TARGET_SKILLS_DIR"/*/SKILL.md 2>/dev/null

Windows 用 Invoke-RestMethod，详见 references/api.md 与 references/platforms.md。

召回策略：

• SkillHub 单关键词召回有限，每个候选词都搜一遍再合并；
• 命中过多 → 叠加 category/labels 收窄；
• 为空 → 去掉 category、换同义/上位词放宽；
• L3 Coze 仅当环境变量 COZE_API_TOKEN 存在时调用（PAT 申请见 references/api.md），缺 Token 直接跳过不报错；
• L5 skills.sh 仅当 L1–L4 全空时回退，国内可能不通，挂代理用。

#Step 3 · 合并去重（保留全部来源）

按 slug / repo / 小写 name 三键去重，合并为一条记录但保留命中的全部来源——不要把跨源同名技能删成只剩一个来源。

每条去重后的记录必须携带以下来源信息：

• sources[]：命中的所有来源徽章数组，按层号升序（例：["🏠本地","🟦SkillHub","🐙GitHub"]）。
• 每个来源各自的元数据都保留（downloads / stars / version / URL / 是否官方），不要互相覆盖。
• primary_source：信息最全或总分最高的那个来源，作为对外展示的主来源。
• is_multi_source：sources.length ≥ 2 时为真，输出时标 📦 多源可用。

示例：用户搜"周报"，weekly-report 在本地已装、SkillHub 有 v1.2、GitHub 有镜像 → 合并成一条，sources=["🏠本地","🟦SkillHub","🐙GitHub"]，primary_source=🟦SkillHub（信息最全），并附注"本地已装 v1.0，SkillHub 可升级到 v1.2"。

跨源同名是正面信号（被多个市场收录/镜像，通常更可信），但不直接加分，仅作为展示标记 📦；评分仍按 references/scoring.md 的五信号执行，避免"被收录多=排名高"的循环。

#Step 4 · 多信号评分 + 置信分层

不要把原始列表直接丢给用户。按 references/scoring.md 算总分：

S = 0.45·relevance + 0.20·popularity + 0.10·freshness + 0.15·quality + 0.10·cnfit
硬门槛：relevance < 0.3 一律剔除

按总分分三档：🟢 ≥0.70 强烈推荐 / 🟡 0.50–0.69 可试 / 🟠 0.30–0.49 备选。

多样性约束：同一来源占比 ≤60%；同一 category 最多连续 2 条；本地已装且匹配的强制置顶标 ✅。

#Step 5 · 输出推荐（多源 · 表格 · 注明来源）

输出必须让用户一眼看清每个结果来自哪些源。用 Markdown 表格列示（来源单独成列，便于横向对比），匹配理由用表格下方的分点说明（不放进单元格，避免行高失控）。模板：

🔍 为你找到 {N} 个相关技能
📊 命中分布：🏠本地 {a} · 🟦SkillHub {b} · 🟧Coze {c} · 🐙GitHub {d} · 🌐skills.sh {e}
{若有源未响应：}⚠️ 本次未响应：{源徽章列表}（已跳过）
 
| # | 技能 | 置信 | 来源 | 热度/指标 | 主页 |
|---|------|------|------|----------|------|
| 1 | AI 图片生成 ✅ | — | 🏠本地 | 已装 v1.0 | 本地 |
| 2 | poster-maker | 🟢 强烈推荐 | 🟦SkillHub | ↓2.3K · 装 420 | link |
| 3 | design-poster 📦 | 🟡 可试 | 🟧Coze（官方）· 🐙GitHub · 🏠本地 | 调用 1.2K | link |
 
💡 推荐理由
- **#2 poster-maker**：专为海报场景设计，SkillHub 高下载，相关度最高。
- **#3 design-poster**：字节官方插件，📦 跨 Coze/GitHub/本地三源；本地 v1.0 旧版可升级。
- **#1**：本地已装，免下载直接用。
 
都不合适？我再换词搜，或调整 category。
回复"安装第 N 个"即可；📦 多源可指定来源，如"安装第 3 个，从 GitHub"。

列规范：

• #：序号；本地已装项强制排最前。
• 技能：名称；已装追 ✅，跨 ≥2 源追 📦。
• 置信：🟢 强烈推荐 / 🟡 可试 / 🟠 备选；本地行用 —。
• 来源：核心列。主来源徽章在前（带官方/版本标识），其他可用源用 · 跟后；单源只写一个徽章。绝不留空。
• 热度/指标：按主来源给（SkillHub=下载/安装、Coze=调用数、GitHub=⭐ stars、本地=已装版本）。
• 主页：主来源主页 URL；本地行写"本地"或相对路径。

来源标注铁律：

1. 每行「来源」列必填——空来源视为不合规，禁止输出。
2. 徽章唯一：只用第「数据源」表的官方标记，不自创；多源用 · 分隔。
3. 主来源在前：主来源带元数据（官方/版本），其他来源至少给徽章 + 差异点（镜像/旧版）。
4. 本地强制置顶：本地命中的行排到表格最前并标 ✅，即便跨源。
5. 命中分布行不可省略：顶部展示各源命中数；未响应源用 ⚠️ 单列（如"⚠️ 本次未响应：🟧Coze（未配置 Token）"）。
6. 📦 多源显式标：跨 ≥2 源的技能，名称列追 📦，来源列展开全部可用源——这是"多源提供 + 注明来源"的核心。
7. 推荐理由必给：表格下方为 Top 2–3 写一句话理由；超过 5 条结果时表格可省略 🟠 备选行，仅保留 🟢/🟡。

⛔ 推荐列表严禁出现 curl/skillhub install/sh -c 等命令——那是给用户看的，命令属于 Step 6 且由你执行而非展示。

#Step 6 · 一键安装（用户选定后）

1. 客户端检测：按 references/platforms.md 探测 <target-skills-dir>（OpenCode / Claude Code / Cursor / Codex / Windsurf / Gemini / Trae / WorkBuddy / 通义灵码 / Comate / ~/.agents/skills 等主流 Agent，跨平台）。
2. 确定安装来源：
   • 用户未指定来源 → 用该技能的 primary_source（Step 3 中信息最全/总分最高者）。
   • 用户指定来源（如"从 GitHub 装""用 Coze 的"）→ 用指定源，前提是它在 sources[] 里；不在则回退 primary_source 并告知。
   • 本地已装（🏠本地 ∈ sources）→ 不重装，仅当用户指定了更高版本的远程源时升级。
3. 按来源选安装方式：
   • 🟦 SkillHub → skillhub install <slug> --dir <目标目录>（CLI 未装先 install.sh --cli-only，Windows 用 PowerShell 等价命令）
   • 🐙 GitHub → git clone --depth 1 到 <目标目录>/<name>；clone 失败（超时 / 连接拒绝 / EOF / DNS）自动换实测可用的镜像 ghfast.top 重试一次（每源限 20s 快速失败，不堆砌死站拖慢）。完整脚本与失败特征见 references/platforms.md「从 GitHub 安装」。镜像属第三方：仅用于公开仓库、勿登录或输入 Token；敏感场景 clone 后比对官方 commit hash 校验。
   • 🟧 Coze → Coze 插件无文件可装，仅记录 entity_id + MCP 端点供 MCP 客户端引用；若用户客户端非 MCP，提示"该源为插件市场，需在 Coze 内使用"并建议改选其他可用源。
   • 🌐 skills.sh → npx skills add <owner/repo@skill> -g -y 再 cp 到目标目录
4. 验证：必检 <目标目录>/<name>/SKILL.md 存在（Coze 源除外，见上）；缺则回滚并报错。
5. 提示重启：「✅ 已安装（来源：），重启 后生效」。

命令由你直接执行，不贴给用户看。

#支持的 AI Agent

自动探测下列任一客户端的 skills 目录并安装（探测顺序与各 Agent 专属说明见 references/platforms.md）：

未识别到上述任一目录时，默认落到 ~/.agents/skills/ 并创建。Windows / macOS / Linux 均支持，bash 与 PowerShell 命令双提供。

#输出语言

跟随用户。用户中文 → 全程中文输出（推荐理由、字段名翻译）；用户英文 → 英文。

#参考

• references/api.md — 各数据源 API 详细参数与示例
• references/categories.md — 12 个一级标签索引
• references/scoring.md — 评分与筛选算法
• references/platforms.md — 跨平台客户端检测与安装命令
• 各 category 详情文件：references/<category-key>.md