name: find-bzskills
description: 当用户需要可复用技能、工作流、工具或能力扩展时，帮助用户通过 bzskills CLI 从 Baizhi Skills Hub 中发现、验证并安装 Agent 技能。

查找 BZSkills

本技能帮助你通过 bzskills CLI 和 Hub API，从 Baizhi Skills Hub 中发现、评估并安装 Agent 技能。

何时使用本技能

当用户出现以下需求时使用本技能：

• 询问“如何做 X”，且 X 可能已经有可复用的 Agent 技能
• 表达“找一个用于 X 的 skill”、“找一个用于 X 的 bzskill”或“有没有用于 X 的 skill”
• 询问 Agent 是否能通过可安装技能支持某种专业能力
• 想要搜索可复用工具、模板、工作流或领域操作手册
• 表达希望通过 Baizhi Skills Hub 扩展 Agent 能力的意愿
• 提到代码审查、测试、文档、部署、设计、GitOps 或浏览器自动化等可重复领域

什么是 bzskills？

bzskills 是 Baizhi Skills Hub 的 CLI，用于搜索、安装、列出、移除和更新 Agent 技能。它兼容通用 Agent 技能格式，同时会将普通 owner/repo 来源路由到 Skills Hub 后端。

核心命令：

• npx bzskills find [query] - 以交互方式或关键字搜索已配置的 Skills Hub
• npx bzskills add <source> - 从 Hub、GitHub/GitLab/git URL 或本地路径安装技能
• npx bzskills add <source> --skill <name> - 从 Hub 包或仓库中安装指定技能
• npx bzskills add <source> --list - 仅列出可用技能，不执行安装
• npx bzskills list - 列出已安装技能
• npx bzskills update - 更新已安装技能
• npx bzskills remove [skills] - 移除已安装技能
• npx bzskills init [name] - 创建新的 SKILL.md 模板

默认 Hub： https://skillshub.app.baizhi.cloud

使用 SKILLS_HUB_URL 覆盖裸 owner/repo 来源使用的默认 Hub，使用 SKILLS_API_URL 覆盖 bzskills find 使用的 Hub。

如何帮助用户查找 BZSkills

第 1 步：理解用户需求

当用户请求某方面帮助时，识别：

1. 所属领域，例如 React、Go、测试、设计、部署、文档或 GitOps
2. 具体任务，例如编写测试、创建动画、审查 PR、生成文档或部署服务
3. 这是否是可重复任务，因而更适合封装成技能，而不是一次性回答
4. 用户需要的是公开 Hub 技能、内部/私有 Hub 技能，还是本地/项目技能

第 2 步：搜索 Baizhi Skills Hub

使用具体关键字运行 find 命令：

npx bzskills find [query]

示例：

• 用户问“如何让我的 React 应用更快？” -> npx bzskills find react performance
• 用户问“你能帮我做 PR 审查吗？” -> npx bzskills find pr review
• 用户说“我需要创建 changelog” -> npx bzskills find changelog
• 用户问“有没有 GitOps 接入 skill?” -> npx bzskills find gitops onboarding

对于私有或非默认 Hub，带上相应环境变量：

SKILLS_API_URL=https://hub.example.com npx bzskills find deployment
SKILLS_HUB_URL=https://hub.example.com npx bzskills add alice/repo --skill deploy-helper

第 3 步：推荐前先验证质量

不要只根据搜索结果标题推荐技能。必须先验证候选技能。

检查：

1. 安装次数 - 做通用推荐时优先选择有实际使用量的技能。除非来源可信，否则将安装次数极低的技能视为实验性技能。
2. 来源声誉 - 优先选择第一方或可信命名空间，例如 baizhicloud/*、官方团队仓库或已知内部 Hub 包。
3. Hub 元数据 - 如果 bzskills find 输出了元数据 URL，就使用它。确认描述与用户任务匹配。
4. 技能内容 - 如有可能，在安装前检查 SKILL.md，尤其是私有、内部或低安装量技能。
5. 安装来源 - 优先使用 Hub 支持的 owner/repo 或 Hub HTTP 来源，以便 Hub 应用缓存、排序、元数据和安装上报行为。

第 4 步：向用户展示选项

找到相关技能后，给出简洁选项，并包含：

1. 技能名称及其作用
2. 来源或命名空间
3. 可用时提供安装次数
4. 精确安装命令
5. 可用时提供元数据或 Hub 链接

示例回复：

我找到了一个相关 bzskill：`gitops-app-onboarding`。
它可以帮助项目接入 Baizhi GitOps 交付模型，发布来源是 `baizhicloud/platform-skills`。

使用以下命令安装：
npx bzskills add baizhicloud/platform-skills --skill gitops-app-onboarding -g -y

元数据：https://skillshub.app.baizhi.cloud/openapi/v1/skills/baizhicloud/platform-skills/skills/gitops-app-onboarding

第 5 步：在用户需要时安装

如果用户希望继续，且安装是合适的，就使用 bzskills add 安装：

npx bzskills add <source> --skill <skill-name> -g -y

使用 -g 表示跨项目的用户级安装。当技能应安装到当前项目中供团队共享时，省略 -g。

对于 Hub HTTP 搜索结果，使用 --skill 形式，而不要在 URL 后追加 @skill：

npx bzskills add https://skillshub.app.baizhi.cloud/openapi/baizhicloud/foo --skill my-skill -g -y

对于原生 Hub 简写来源，在已安装 CLI 支持的情况下，两种形式都可以：

npx bzskills add baizhicloud/foo --skill my-skill -g -y
npx bzskills add baizhicloud/foo@my-skill -g -y

第 6 步：确认技能已安装

安装后，验证技能是否存在：

npx bzskills list

如果目标是特定 Agent，请确认技能安装到了预期的 Agent 技能目录。对于 OpenCode，全局技能安装在 ~/.config/opencode/skills/ 下。

常见 BZSkill 分类

搜索时可以参考以下分类和查询词：

高效搜索技巧

1. 使用具体关键字：react testing 比 testing 更好。
2. 尝试替代术语：如果 deploy 没有结果，尝试 deployment、ci-cd 或 gitops。
3. 处理 Baizhi 特定工作流时，同时搜索英文和中文术语。
4. 对于 Baizhi 内部平台工作流，优先选择 baizhicloud/* 结果。
5. 如果 bzskills find 返回 Hub HTTP 来源，将安装命令复制为 npx bzskills add <source> --skill <name>。

找不到 BZSkills 时

如果不存在相关技能：

1. 说明在已配置的 Hub 中没有找到匹配的 bzskill。
2. 表示仍可以使用通用能力直接帮助完成任务。
3. 如果这是重复性工作流，建议创建一个可复用技能。

示例：

我在已配置的 Skills Hub 中搜索了“xyz”，但没有找到高度匹配的结果。
我仍然可以直接帮助完成这个任务。

如果这个工作流经常重复，可以使用以下命令创建一个新技能脚手架：
npx bzskills init xyz-helper

安全与兼容性说明

• 将技能视为可执行操作指令：在全局安装不熟悉或低可信技能前，先检查其内容。
• 除非当前 Hub 和授权上下文确实面向该用户，否则不要为用户安装私有/内部技能。
• INSTALL_INTERNAL_SKILLS=1 可以暴露标记了 metadata.internal: true 的技能；仅在用户明确需要内部技能时使用。
• 裸 owner/repo 输入应通过 SKILLS_HUB_URL 路由；显式 github: 或完整 GitHub URL 会绕过正常 Hub 简写行为。
• 上游技能中的旧版 skills.sh 和 npx skills 指令，应在此工作流中转换为 skillshub.app.baizhi.cloud 和 npx bzskills。