huawei-cloud-find-skills

重要

当用户想要搜索、发现或安装华为云 Agent 技能时：

1. 搜索 — 使用此技能（huawei-cloud-find-skills）查找相关技能。
2. 安装 — 安装匹配的技能（见步骤 3）。
3. 执行 — 按照已安装技能的说明完成请求。

此技能仅负责技能发现和安装 — 不会自行执行华为云资源管理/查询任务；这些任务由其安装的技能处理。

概述

此技能可帮助用户高效地搜索、发现和安装华为云技能。

依赖项：Python 3.6+，以及访问 gitcode.com（用于技能索引的 API v5）和 github.com / raw.githubusercontent.com（用于技能详情）的网络连接。系统会通过 skill-quality-cli 自动收集质量遥测数据（若未安装，则由 scripts/ensure_cli.sh 安装）— 无需其他 CLI 或凭证。

隐私与遥测

透明披露：此 skill 在搜索和安装过程中会产生以下对外遥测上报。上报数据均为匿名聚合数据（技能名/类目/服务等元信息），不包含用户输入内容、凭证、云资源数据或个人身份信息。质量上报默认开启（opt-out）：如需关闭，设置环境变量 export SKILL_QUALITY_REPORT=0 即可整体关闭。

上报内容	触发点	目的地	是否含敏感数据
搜索 top-3 曝光计数	scripts/search-skills.py（每次搜索）	devdata2.huaweicloud.com install-count API	否（仅技能名/类目/服务）
安装计数	Step 3.1 curl（每次安装前）	devdata2.huaweicloud.com install-count API	否（仅 skill_id，即 skills/<category>/<service>/<name>）
质量上报	skill-quality-cli run 包装执行	quality 上报 APIG（测试环境）	否（执行状态/耗时/技能名）

• 默认开启 / 关闭方式：以上三类上报默认开启（未设置该环境变量即会上报）；如需关闭，执行 export SKILL_QUALITY_REPORT=0（skill-quality-cli 与 search-skills.py 均遵循该开关）。
• 上报均为 fire-and-forget，绝不会阻塞搜索/安装主流程。

场景说明

此技能可帮助用户：

• 搜索技能：按关键词、类目或两者查找技能（匹配名称、描述和触发词）
• 浏览类目：探索可用的技能类目
• 查看技能详情：从 GitHub 获取特定技能的完整 SKILL.md 内容
• 安装技能：引导用户通过 npx skills add（默认使用 GitCode）、npx skills add https://clawhub.ai/huaweicloudskill/skills/<skill-name>（ClawHub）或备用的 GitHub 方法安装技能

架构：GitCode API v5（index.json + cn-en-map.json）→ HTTP GET（base64 解码）→ 内存搜索 → 从 GitHub 获取原始内容以查看详情 → 安装

使用场景

• “查找用于管理 ECS 实例的技能”
• “OBS 有哪些华为云技能？”
• “华为云有哪些与 VPC 相关的 skill？”
• “浏览所有可用的华为云技能”
• “安装用于 RDS 管理的技能”
• “帮我找一个华为云网络相关的 skill”

前提条件

• 必须安装 Python 3.6+，并能通过 PATH 中的 python（或 python3）访问
• 需要网络连接，以访问 gitcode.com（用于索引的 API v5）和 github.com / raw.githubusercontent.com（用于技能详情）
• skill-quality-cli — 强制要求（步骤 0.1）：通过 bash scripts/ensure_cli.sh 确保已安装 （可重复执行；若已存在则跳过）。在运行任何搜索/安装命令前，每次执行此 技能时都必须触发。
  • 升级：手动运行 skill-quality-cli upgrade（不会自动升级）
  • 质量上报：每次搜索（步骤 1）和安装（步骤 3）命令都必须使用 skill-quality-cli run --skill-name huawei-cloud-find-skills -- 包装执行，以确保每次执行都会触发质量上报

步骤 0：检查 Python 环境

MANDATORY：运行任何脚本命令之前，请确认 Python 可用。

⚠️ Mandatory：此 skill 中的每条 hcloud 命令都 MUST 使用 skill-quality-cli run --skill-name huawei-cloud-find-skills -- 包装——严禁直接调用 hcloud。

# Check Python availability
python --version   # or: python3 --version

如果命令失败或返回 Python 2.x：

1. 安装 Python 3：从 python.org 下载，或使用包管理器：

   # macOS
   brew install python3
   # Ubuntu/Debian
   sudo apt-get install python3
   # Windows — download installer from python.org, check "Add Python to PATH"
   

2. 安装后验证：再次运行 python --version，确认 Python 3.6+ 可用
3. 如果 python 指向 Python 2：在以下所有命令中使用 python3 代替 python

步骤 0.1：确保 skill-quality-cli（MANDATORY）

MANDATORY：运行任何搜索或安装命令之前，请确保已安装且可用 skill-quality-cli。每次执行此 skill 时都 MUST 触发此步骤，并且要紧接在步骤 0 之后。此步骤与 步骤 0：检查 Python 环境 具有同等强制级别——即使你认为 CLI 已存在，也不要跳过（ensure_cli.sh 具有幂等性，一切就绪时会静默退出）。

披露：该 CLI 仅用于本 skill 的匿名质量遥测上报（执行状态/耗时，见 隐私与遥测）；安装位置为 ~/.local/bin，不会修改系统 服务或全局配置；关闭方式见 隐私与遥测。

# Ensure ~/.local/bin is on PATH (where skill-quality-cli is installed)
export PATH="$HOME/.local/bin:$PATH"

# Ensure skill-quality-cli is ready (idempotent: installs only if absent;
# also auto-links the CLI into a writable PATH dir so the bare command works)
bash scripts/ensure_cli.sh

# Verify availability
command -v skill-quality-cli && skill-quality-cli version

结果	行为
CLI 已安装且可用	静默通过——脚本立即退出
CLI 缺失	将最新版本安装到 ~/.local/bin/（输出 skill-quality-cli vX.Y.Z 已就绪）
安装失败（无网络等）	输出警告；绝不会阻塞流程

ensure_cli.sh 会自动将 skill-quality-cli 软链到 PATH 中第一个可写目录 （如 /usr/local/bin），因此通常可以直接调用 skill-quality-cli。如果仍不可用 （没有任何可写的 PATH 目录），请在当前 shell 中执行：

export PATH="$HOME/.local/bin:$PATH"

手动单次安装的备用方式：bash scripts/install_cli.sh。

步骤 0.5：检查 KooCLI 版本（NON-BLOCKING）

OPTIONAL：检查 KooCLI（hcloud）是否可用及其版本，绝不会阻塞流程。 后续安装的 skills 可能依赖 KooCLI；此步骤会提前发出警告，然后无论结果如何，始终继续执行步骤 1。

# Check KooCLI availability & version (non-blocking)
python scripts/check-koocli.py

→ scripts/check-koocli.py（Python——跨平台）

结果	行为
已安装 hcloud，且版本符合要求（≥ 3.0.0）	静默通过——不输出内容
已安装 hcloud，但版本过旧	输出升级提醒（hcloud update -y）
未安装 hcloud	输出安装提醒（官方 KooCLI 指南链接）

脚本始终以 0 退出——仅提供信息，不会中断搜索或安装。

仓库信息

INDEX_REPO=developer-skill/skills-group-contribution
INDEX_BRANCH=test-for-index
SKILLS_REPO=huaweicloud/huaweicloud-skills
SKILLS_BRANCH=master
RAW_BASE=https://raw.githubusercontent.com/$SKILLS_REPO/$SKILLS_BRANCH

索引来源

搜索脚本通过 HTTP GET 从 GitCode API v5 获取 skill 索引（自动进行 base64 解码）：

SKILLS_INDEX_URL=https://gitcode.com/api/v5/repos/developer-skill/skills-group-contribution/contents/skills-index/index.json?ref=test-for-index
SKILLS_CN_EN_MAP_URL=https://gitcode.com/api/v5/repos/developer-skill/skills-group-contribution/contents/skills-index/cn-en-map.json?ref=test-for-index

核心工作流和核心命令

步骤 1：搜索技能

MANDATORY：Agent 必须执行搜索脚本来搜索技能索引。不要直接读取 JSON 文件——务必使用脚本。

根据 keyword（由 AI 理解的用户意图得出）和可选的 category，运行搜索脚本：

⚠️ MANDATORY (质量上报)：搜索命令必须用 skill-quality-cli run --skill-name huawei-cloud-find-skills -- 包装，确保每次搜索都会触发质量上报。严禁直接裸调 python scripts/search-skills.py。

# PowerShell
skill-quality-cli run --skill-name huawei-cloud-find-skills -- python scripts/search-skills.py -k "<keyword>"
skill-quality-cli run --skill-name huawei-cloud-find-skills -- python scripts/search-skills.py -k "<keyword>" -c "<category>"
skill-quality-cli run --skill-name huawei-cloud-find-skills -- python scripts/search-skills.py -c "<category>"

# Bash
skill-quality-cli run --skill-name huawei-cloud-find-skills -- python scripts/search-skills.py -k "<keyword>"
skill-quality-cli run --skill-name huawei-cloud-find-skills -- python scripts/search-skills.py -k "<keyword>" -c "<category>"
skill-quality-cli run --skill-name huawei-cloud-find-skills -- python scripts/search-skills.py -c "<category>"

⚠️ 安全（命令注入防护）：keyword/category 来自用户输入，严禁未经转义就直接拼接到 shell 命令字符串中。若输入包含 $(), $(...), 反引号 , ;, | 等 shell 元字符，在 Bash/PowerShell 双引号字符串中会触发命令注入。必须按以下方式调用，避免将外部输入拼入 shell 字符串：

1. 首选（推荐）：使用 Python subprocess 参数数组方式调用，不经过 shell：subprocess.run([sys.executable, "scripts/search-skills.py", "-k", keyword, "-c", category])；
2. 必须在 shell 中执行时，用单引号包裹用户输入（'<keyword>'），并先进行转义（将输入中的 ' 替换为 '\''），或使用 shell 转义工具（shlex.quote）；
3. 遇到包含 $(), 反引号, ;, | 等元字符的输入时，优先改用参数数组方式，或在展示给用户前对输入进行脱敏处理。

→ scripts/search-skills.py（Python — 跨平台）

脚本执行的操作：

1. 通过 HTTP GET 从 GitCode API v5 获取 index.json 和 cn-en-map.json（自动解码 base64 内容）
2. 通过 cn-en-map.json 扩展关键词（中英文双向映射，例如，“ECS” → “ECS, 弹性云服务器, 云服务器”）
3. 为每项技能评分：名称匹配 +10、触发词匹配 +8、描述匹配 +5、服务匹配 +3
4. 按分数降序排序，输出包含匹配关键词的格式化结果
5. 仅将排名前 3 的结果的技能名称报告给安装计数 API（skills/<category>/<service>/<name>），作为曝光展示次数——发起请求后不等待结果，且不会阻塞或导致搜索失败

回退迭代（无结果时）：1）切换中英文关键词 2）扩展关键词 3）移除类别筛选 4）尝试同义词 5）列出所有技能

搜索流程应持续进行，直到找到技能或确认其不存在。如果所有方法均失败，应告知用户具体尝试过的步骤。

步骤 2：查看技能详情（可选）

从 GitHub 获取完整的 SKILL.md 内容，以验证意图。如果步骤 1 的搜索结果信息已足够，则跳过此步骤。

# URL pattern — use the skill's category, service, and name from index
DETAIL_URL="https://raw.githubusercontent.com/huaweicloud/huaweicloud-skills/master/skills/${category}/${service}/${name}/SKILL.md"

Agent 可以使用 curl 或其网页抓取工具获取此 URL，然后向用户展示该技能的完整文档。

步骤 3：安装技能

MANDATORY：安装前，Agent 必须调用安装计数 API 记录此次安装。然后使用下面的其中一条安装命令。选项 A 为默认选项；选项 A 不可用时，回退使用选项 C。

步骤 3.1：记录安装次数

执行安装命令前，调用安装计数 API。skill_id 根据步骤 1 的搜索结果构造：skills/<category>/<service>/<skill-name>。

IMPORTANT：category 和 service 值必须直接取自步骤 1 的搜索输出（格式：name (category/service)）。不要猜测或硬编码这些值。

⚠️ MANDATORY (质量上报)：安装计数请求同样必须用 run 包装，确保安装流程会触发质量上报。

skill-quality-cli run --skill-name huawei-cloud-find-skills -- curl -s -X POST "https://devdata2.huaweicloud.com/rest/developer/fwdo/rest/developer/servlet/hdskillservice/v1/obs/findcounts/increment" -H "Accept: application/json, text/plain, */*" -H "Content-Type: application/json" -H "Origin: https://skills.huaweicloud.com" -H "Referer: https://skills.huaweicloud.com/" -d "{\"skill_id\":\"skills/<category>/<service>/<skill-name>\"}"

此请求发起后不等待结果。不要因为请求成功或失败而阻塞安装流程。

步骤 3.2：执行安装命令

⚠️ MANDATORY (质量上报)：安装命令必须用 skill-quality-cli run --skill-name huawei-cloud-find-skills -- sh -c '...' 包装，确保每次安装都会触发质量上报。sh -c 中的 printf "\n" 用于自动确认 npx skills add 的范围交互提示。

# Option A: npx skills add from GitCode (default)
skill-quality-cli run --skill-name huawei-cloud-find-skills -- sh -c 'printf "\n" | npx skills add https://gitcode.com/huaweicloud/huaweicloud-skills.git#master --skill <skill-name> -y'

# Option B: npx skills add from ClawHub
skill-quality-cli run --skill-name huawei-cloud-find-skills -- sh -c 'printf "\n" | npx skills add https://clawhub.ai/huaweicloudskill/skills/<skill-name> -y'

# Option C (fallback): npx skills add from GitHub
skill-quality-cli run --skill-name huawei-cloud-find-skills -- sh -c 'printf "\n" | npx skills add huaweicloud/huaweicloud-skills --skill <skill-name> -y'

⚠️ 安全：<skill-name> 必须来自步骤 1 搜索结果中的规范技能名称（name 字段），禁止将未经验证的用户输入拼接到 sh -c '...' 中；若技能名称包含 ' 等 shell 元字符，须先进行转义（' → '\''），或改用裸调用 npx skills add ... -y（此时质量上报改为在安装完成后手动执行 skill-quality-cli report --skill-name huawei-cloud-find-skills）。

如果所有安装尝试均失败，应向用户报告错误消息。不要尝试上述命令之外的任何方法。

参数确认

参数	必填/可选	说明	默认值
Keyword	可选	搜索关键词（与名称、描述、触发词、服务匹配）	None
Category	可选	用于筛选的类别代码（例如，“computing”“storage”“network”）	None
skill-name	必填（步骤 3）	要安装的确切 Skill 名称	None

参考资料

文档	说明
GitCode API v5 index.json	通过 HTTP GET 获取的 Skill 索引（已进行 base64 解码）
GitCode API v5 cn-en-map.json	通过 HTTP GET 获取的中英关键词映射（已进行 base64 解码）
scripts/search-skills.py	搜索脚本（Python）——从 GitCode API v5 获取数据、扩展关键词、评分、排序，并报告搜索结果曝光量排名前 3 的结果
scripts/check-koocli.py	步骤 0.5：非阻塞式 KooCLI（hcloud）可用性/版本检查
scripts/ensure_cli.sh	必须执行（步骤 0.1） skill-quality-cli 的幂等安装程序（仅在缺少时安装，不会自动升级）
scripts/install_cli.sh	skill-quality-cli 的手动单次安装程序（仅由用户触发）
references/iam-policies.md	IAM 权限说明 — 本 Skill 仅访问公开接口，无需任何 IAM 凭证/策略
references/verification-method.md	验证方法 — 各场景的验证步骤与预期结果
references/acceptance-criteria.md	验收标准 — 功能/数据/安全/文件规范验收项
references/cli-installation-guide.md	CLI 安装/升级/遥测关闭说明

搜索提示

关键词到类别提示的可选参考。Agent 无需这些提示，也可以根据 index.json 推断类别。

• 云基础设施关键词（ecs、bms、vpc、obs、rds……）→ 可能对应 computing、network、storage 等类别
• 工具关键词（cli、terraform、koo）→ 可能对应 devtools
• 管理关键词（monitoring、alarm、log）→ 可能对应 monitoring

故障排除

问题：系统无法识别 python 命令

原因：未安装 Python 3，或 Python 3 不在 PATH 中
解决方案：安装 Python 3.6+，并确保已将其添加到 PATH。在 Windows 上，重新运行安装程序并勾选“Add Python to PATH”。也可以在可用时使用 python3。

问题：skill-quality-cli: command not found（退出代码 127）

原因：skill-quality-cli 安装在 ~/.local/bin/ 中，该目录通常 不在默认的 PATH 中。 解决方案：重新运行 bash scripts/ensure_cli.sh——现在它会自动将 CLI 链接到 PATH 中第一个可写目录（例如 /usr/local/bin），因此可以直接运行命令。 作为手动备用方案，在当前 Shell 中运行 export PATH="$HOME/.local/bin:$PATH"。 如果 CLI 完全缺失，ensure_cli.sh 会以幂等方式安装它（若已存在则跳过），且绝不会阻塞业务流程。

问题：脚本报错 SyntaxError: invalid syntax

原因：系统的 python 指向 Python 2.x（脚本要求 Python 3.6+） 解决方案：明确使用 python3 运行：python3 scripts/search-skills.py -k "<keyword>"

问题：脚本报错 “Failed to fetch index.json”

原因：无法访问 GitCode API v5 URL 解决方案：检查与 gitcode.com 的网络连接

问题：GitCode API v5 返回 404

原因：文件路径不正确，或分支不是 test-for-index 解决方案：从搜索结果中确认 Skill 的 category、service 和 name

问题：搜索无结果

原因：关键词与任何 Skill 都不匹配 解决方案：

1. 尝试使用更宽泛的关键词
2. 在中文和英文关键词之间切换（例如，“对象存储” → “obs”）
3. 列出所有 Skill：python scripts/search-skills.py -c "computing"

说明

• 此技能为只读，不会创建任何云资源
• 无需管理缓存——每次运行都会从 GitCode API v5 获取最新索引
• 需要网络——索引数据托管在 GitCode 上，通过 HTTP GET 获取（并进行 base64 解码）
• 必须使用脚本进行搜索——不要直接读取 index.json
• 索引仓库：https://gitcode.com/developer-skill/skills-group-contribution（分支：test-for-index）
• 技能仓库：https://github.com/huaweicloud/huaweicloud-skills（分支：master）
• KooCLI：搜索/安装流程本身只使用 Python + HTTP（不使用服务级别的 hcloud 命令，也不使用 --cli-region）。步骤 0.5 仅执行非阻塞的 KooCLI 可用性/版本检查（通过 scripts/check-koocli.py 执行 hcloud version），以便在安装依赖 KooCLI 的技能之前，对 CLI 缺失或版本过旧发出警告。