需要搜索、查看或安装华为云 agent skill 时…

当用户想按关键词或类目查找、浏览、了解或安装华为云 agent skill 时，用本技能搜索索引并完成安装。

适用场景

解决思路

1. 先明确目标：用户要搜索/发现/安装华为云 agent skill 时，用本技能找到匹配 Skill，再安装匹配 Skill，最后按已安装 Skill 的说明执行；本技能只负责发现和安装，不直接做华为云资源管理/查询。
2. 确认依赖：需要 Python 3.6+（命令为 python 或 python3）、可访问 gitcode.com（API v5 技能索引）以及 github.com / raw.githubusercontent.com（技能详情）；质量遥测由 skill-quality-cli 自动采集，由 scripts/ensure_cli.sh 在缺失时安装，无需其他 CLI 或凭证。
3. 透明披露/遥测处理：搜索 top-3 曝光计数上报到 devdata2.huaweicloud.com install-count API，安装计数上报 skill_id，质量上报经 skill-quality-cli run 包装；三类上报默认开启（opt-out），如需关闭执行 export SKILL_QUALITY_REPORT=0，上报均为 fire-and-forget，不阻塞搜索/安装。
4. Step 0：运行 python --version 或 python3 --version 检查 Python 可用性；若失败或返回 Python 2.x，安装 Python 3（macOS: brew install python3；Ubuntu/Debian: sudo apt-get install python3；Windows 从 python.org 下载并勾选 Add Python to PATH），安装后再次验证；若 python 指向 Python 2，则所有命令改用 python3。
5. Step 0.1：每次执行本技能时，先运行 export PATH="$HOME/.local/bin:$PATH"，再运行 bash scripts/ensure_cli.sh 确保 skill-quality-cli 就绪（幂等，已存在则静默跳过；缺失则安装最新版到 ~/.local/bin 并打印 skill-quality-cli vX.Y.Z 已就绪；安装失败只告警，绝不阻塞流程），并运行 command -v skill-quality-cli && skill-quality-cli version 验证；ensure_cli.sh 会自动把 CLI 软链到 PATH 中第一个可写目录（如 /usr/local/bin），若仍不可用则 export PATH="$HOME/.local/bin:$PATH"；手动一次性安装兜底：bash scripts/install_cli.sh。
6. skill-quality-cli 升级：运行 skill-quality-cli upgrade 手动升级，本技能不自动升级。
7. Step 0.5（可选、非阻塞）：运行 python scripts/check-koocli.py 检查 KooCLI hcloud 可用性和版本；已安装且 ≥3.0.0 静默通过，已安装但过旧提示 hcloud update -y，未安装提示官方 KooCLI 安装指南；脚本始终退出 0，不中断搜索或安装。
8. 记录仓库信息：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。
9. 索引来源：从 GitCode API v5 通过 HTTP GET 获取 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，base64 自动解码。
10. Step 1 搜索：必须执行搜索脚本，不要直接读 JSON；用 skill-quality-cli run --skill-name huawei-cloud-find-skills -- 包装 python scripts/search-skills.py 命令，禁止裸调。示例：skill-quality-cli run --skill-name huawei-cloud-find-skills -- python scripts/search-skills.py -k "<keyword>"；可加 -c "<category>"，或仅用 -c "<category>" 列类目。
11. 搜索脚本行为：获取 index.json 和 cn-en-map.json 并 base64 解码；用 cn-en-map.json 做中英双向关键词扩展（如 ECS → ECS, 弹性云服务器, 云服务器）；按 name +10、trigger +8、description +5、service +3 打分；按分数降序输出匹配关键词；仅把 top-3 结果技能名上报 install-count API（skills/<category>/<service>/<name>）作为曝光计数，fire-and-forget。
12. 搜索命令注入防护：keyword/category 来自用户输入，严禁未转义拼接进 shell；首选用 Python subprocess 参数数组 subprocess.run([sys.executable, "scripts/search-skills.py", "-k", keyword, "-c", category])；必须在 shell 中执行时用单引号包裹并按需转义（将 ' 替换为 '\''）或 shlex.quote；遇到 $(), 反引号, ;, | 等元字符优先参数数组或脱敏展示。
13. 搜索无结果时按顺序迭代：1) 中英文关键词互换 2) 扩展关键词 3) 去掉 category 过滤 4) 尝试同义词 5) 列出所有技能；持续直到找到或确认不存在；完全失败时告知用户已尝试的具体步骤。
14. Step 2 查看技能详情（可选）：搜索结果信息足够时可跳过；URL 模式为 https://raw.githubusercontent.com/huaweicloud/huaweicloud-skills/master/skills/${category}/${service}/${name}/SKILL.md，用 curl 或 web-fetch 工具拉取后向用户展示完整文档以验证意图。
15. Step 3 安装技能：安装前必须记录安装计数，再执行安装命令；默认 Option A，Option C 为 Option A 不可用时备用。
16. Step 3.1 记录安装计数：在执行安装命令前调用 install-count API；skill_id 由 Step 1 搜索结果构造为 skills/<category>/<service>/<skill-name>；category 和 service 必须直接取 Step 1 输出（格式 name (category/service)），不得猜测或硬编码；请求也必须用 skill-quality-cli 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>\"}"；该请求 fire-and-forget，不阻塞安装。
17. Step 3.2 执行安装命令（三选一）：必须用 skill-quality-cli run --skill-name huawei-cloud-find-skills -- sh -c '...' 包装以触发质量上报，sh -c 内 printf "\n" 自动确认 npx skills add 的 scope 交互提示。Option A 默认：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 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 兜底 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'。
18. 安装安全：<skill-name> 必须来自 Step 1 搜索结果规范技能名（name 字段），禁止拼接未经校验的用户输入到 sh -c '...' 内；若技能名含 ' 等 shell 元字符，先转义（' → '\''）或改用 npx skills add ... -y 裸调用，此时安装完成后手动运行 skill-quality-cli report --skill-name huawei-cloud-find-skills。
19. 若所有安装尝试失败，向用户报告错误信息；不要尝试以上命令之外的安装方法。
20. 参数确认：Keyword 可选，搜索关键词，匹配 name/description/triggers/service；Category 可选，类目代码过滤，如 computing、storage、network；skill-name 在 Step 3 必填，为安装用的精确技能名。
21. 参考资料处理：GitCode API v5 index.json/cn-en-map.json 用 HTTP GET 并 base64 解码；scripts/search-skills.py 为搜索脚本；scripts/check-koocli.py 为非阻塞 KooCLI 检查；scripts/ensure_cli.sh 为强制幂等安装 skill-quality-cli；scripts/install_cli.sh 为手动一次性安装；references/iam-policies.md 说明仅访问公开接口无需 IAM 凭证/策略；references/verification-method.md 提供验证步骤；references/acceptance-criteria.md 提供验收项；references/cli-installation-guide.md 说明 CLI 安装/升级/遥测关闭。
22. 搜索启发式（可选）：云基础设施关键词（ecs, bms, vpc, obs, rds 等）通常对应 computing、network、storage 等；工具关键词（cli, terraform, koo）通常对应 devtools；管理关键词（monitoring, alarm, log）通常对应 monitoring。
23. 故障处理：python 未识别时安装 Python 3.6+ 并加入 PATH，或改用 python3；skill-quality-cli: command not found (exit 127) 时重跑 bash scripts/ensure_cli.sh 自动链接，或 export PATH="$HOME/.local/bin:$PATH"，缺失时 ensure_cli.sh 会幂等安装且不阻塞；SyntaxError 时用 python3 运行；Failed to fetch index.json 时检查到 gitcode.com 的网络；GitCode API v5 404 时核对 category/service/name 和分支 test-for-index；搜索无结果时放宽关键词、中英切换（如 对象存储 → obs）、或 python scripts/search-skills.py -c "computing" 列出所有技能。
24. 注意事项：本技能只读、不创建云资源；无需缓存管理，每次从 GitCode API v5 重新获取索引；必须联网；必须用脚本搜索，不要直接读 index.json；索引仓库 https://gitcode.com/developer-skill/skills-group-contribution (branch test-for-index)，技能仓库 https://github.com/huaweicloud/huaweicloud-skills (branch master)；搜索/安装流程本身是纯 Python + HTTP，无服务级 hcloud 命令、无 --cli-region，Step 0.5 仅非阻塞检查 KooCLI 以提醒缺失/过旧。

适用边界 · 注意事项

• 用户要直接管理/查询华为云资源（ECS/OBS/RDS 等）时，本技能只负责发现和安装技能，不执行资源操作。
• 环境不满足 Python 3.6+、无法访问 gitcode.com 或 github.com/raw.githubusercontent.com 时，搜索/详情获取不可用。
• 要搜索或安装的不是华为云 agent skill，或不允许引入 npx/skills、skill-quality-cli 等外部依赖时，不适用。