huawei-cloud-find-skills

Summary

---
name: huawei-cloud-find-skills
description: |
  Invoke this skill to search, list, query, discover, browse, find and install any Huawei Cloud (华为云) agent skill. Triggers include: "华为云", "华为云有什么skill", "华为云相关skill", "华为云agent skill 市场", "华为云skill类目", "explore Huawei Cloud skills", "show Huawei Cloud skill categories", "does a Huawei Cloud skill exist for...", "which Huawei Cloud skills exist", "搜索华为云技能", "查询华为云skill列表", "有没有管理ECS/OBS/RDS的skill", "帮我找 XX 华为云skill", "介绍 XX Skill 内容", "华为云 XX Skill 具体做什么", "安装华为云Skill".
---

> [!IMPORTANT]
> **For any Huawei Cloud query or management task:**
> 1. **Search** — use this skill (`huawei-cloud-find-skills`) to find the relevant Skill.
> 2. **Install** — install the matched Skill (see [Step 3](#step-3-install-skill)).
> 3. **Execute** — follow the installed Skill's instructions to fulfill the request.

# Overview

This skill enables users to efficiently search, discover, and install Huawei Cloud skills. 

## Scenario Description

This skill enables users to:

- **Search Skills**: Find skills by keyword, category, or both (matched against name, description, and triggers)
- **Browse Categories**: Explore available skill categories
- **View Skill Details**: Fetch full SKILL.md content from GitHub for specific skills
- **Install Skills**: Guide users through skill installation via `npx skills add` (GitCode default), `npx clawhub install`, or fallback GitHub method

**Architecture**: GitCode API v5 (`index.json` + `cn-en-map.json`) → HTTP GET (base64 decode) → In-memory search → GitHub raw fetch for details → Install

### Use Cases

- "Find a skill for managing ECS instances"
- "What Huawei Cloud skills are available for OBS?"
- "华为云有哪些 VPC 相关的 skill?"
- "Browse all available Huawei Cloud skills"
- "Install a skill for RDS management"
- "帮我找一个华为云网络相关的skill"

## Prerequisites

- **Python 3.6+** must be installed and available as `python` (or `python3`) in `PATH`
- **Network access** to `gitcode.com` (API v5 for index) and `github.com` / `raw.githubusercontent.com` (for skill details)

### Step 0: Check Python Environment

> **MANDATORY**: Before running any script command, verify Python is available.

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

If the command fails or returns Python 2.x:

1. **Install Python 3**: Download from [python.org](https://www.python.org/downloads/) or use a package manager:
   ```bash
   # macOS
   brew install python3
   # Ubuntu/Debian
   sudo apt-get install python3
   # Windows — download installer from python.org, check "Add Python to PATH"
   ```
2. **Verify after install**: Run `python --version` again to confirm Python 3.6+ is available
3. **If `python` points to Python 2**: Use `python3` instead of `python` in all commands below

## Repository Info

```
INDEX_REPO=2501_91318609/skills-for-index
INDEX_BRANCH=main
SKILLS_REPO=huaweicloud/huaweicloud-skills
SKILLS_BRANCH=master
RAW_BASE=https://raw.githubusercontent.com/$SKILLS_REPO/$SKILLS_BRANCH
```

## Index Source

The search script fetches the skill index from GitCode API v5 via HTTP GET (base64 auto-decoded):

```
SKILLS_INDEX_URL=https://gitcode.com/api/v5/repos/2501_91318609/skills-for-index/contents/skills-index/index.json?ref=main
SKILLS_CN_EN_MAP_URL=https://gitcode.com/api/v5/repos/2501_91318609/skills-for-index/contents/skills-index/cn-en-map.json?ref=main
```


## Core Workflow and Core Commands

### Step 1: Search Skills

> **MANDATORY**: The agent MUST execute the search script to search the skill index. Do NOT read the JSON file directly — always use the script.

Given `keyword` (from AI-understood user intent) and optional `category`, run the search script:

```powershell
# PowerShell
python scripts/search-skills.py -k "<keyword>"
python scripts/search-skills.py -k "<keyword>" -c "<category>"
python scripts/search-skills.py -c "<category>"
```

```bash
# Bash
python scripts/search-skills.py -k "<keyword>"
python scripts/search-skills.py -k "<keyword>" -c "<category>"
python scripts/search-skills.py -c "<category>"
```

→ [scripts/search-skills.py](scripts/search-skills.py) (Python — cross-platform)

**What the script does**:
1. Fetches `index.json` and `cn-en-map.json` via HTTP GET from GitCode API v5 (auto-decodes base64 content)
2. Expands keywords via `cn-en-map.json` (bidirectional CN↔EN, e.g., "ECS" → "ECS, 弹性云服务器, 云服务器")
3. Scores each skill: name match **+10**, trigger match **+8**, description match **+5**, service match **+3**
4. Sorts by score descending, outputs formatted results with matched keywords

**Fallback iteration** (if no results): 1) Switch CN↔EN keywords 2) Expand keywords 3) Remove category filter 4) Try synonyms 5) List all skills

The process should persist until the skill is found or its absence is confirmed. In the event of total failure, notify the user of the specific steps that were attempted.

### Step 2: View Skill Details (optional)

Fetch the full SKILL.md content from GitHub for intent validation. Skip this step if the search results from Step 1 are sufficiently informative.

```bash
# 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"
```

The agent can fetch this URL using `curl` or its web-fetch tool, then present the skill's full documentation to the user.

### Step 3: Install Skill

> **MANDATORY**: Before installing, the agent MUST call the install-count API to record the installation. Then use one of the install commands below. Option A is the default; Option C is a fallback when Option A is unavailable.

#### Step 3.1: Record Install Count

Before executing the install command, call the install-count API. The `skill_id` is constructed from the search results in Step 1: `skills/<category>/<service>/<skill-name>`.

> **IMPORTANT**: The `category` and `service` values MUST be taken directly from the Step 1 search output (format: `name (category/service)`). Do NOT guess or hardcode them.
>

```bash
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>\"}"
```

> This is a fire-and-forget request. Do NOT block the install flow on its success or failure.

#### Step 3.2: Execute Install Command

```bash
# Option A: npx skills add from GitCode (default)
npx skills add https://gitcode.com/huaweicloud/huaweicloud-skills.git#master --skill <skill-name> -y

# Option B: npx clawhub install (OpenClaw ecosystem)
npx clawhub install <skill-name> -y

# Option C (fallback): npx skills add from GitHub
npx skills add huaweicloud/huaweicloud-skills --skill <skill-name> -y
```

If all installation attempts fail, report the error message to the user. Do NOT attempt any method outside the commands above.

## Parameters

| Parameter | Required/Optional | Description | Default |
|-----------|-------------------|-------------|---------|
| `Keyword` | Optional | Search keyword (matched against name, description, triggers, service) | None |
| `Category` | Optional | Category code for filtering (e.g., "computing", "storage", "network") | None |
| `skill-name` | Required (Step 3) | Exact skill name for installing | None |
| `SKILL_QUALITY_ENDPOINT` | Optional | Quality-report server URL (see Quality Reporting below) | `https://skillsapi.developer.myhuaweicloud.com/api/quality/report` |
| `SKILL_QUALITY_DISABLE` | Optional | Set to `1` to disable quality reporting entirely (local debugging) | `0` |
| `SKILL_QUALITY_TIMEOUT` | Optional | Report HTTP timeout in seconds (non-blocking) | `3` |
| `SKILL_QUALITY_TRIGGER` | Optional | Trigger type reported (`agent` / `workflow` / `auto` / `manual`) | `agent` |


## Quality Reporting

This Skill integrates [scripts/skill_quality_sdk.py](scripts/skill_quality_sdk.py)
(vendored, zero third-party dependency) for execution quality reporting. Every
`search-skills.py` run automatically reports one record — **skill name
(`huawei-cloud-find-skills`), status (`success` / `biz_fail` / `sys_fail`),
error code, cost, keyword/category input and result count** — to the skillsopr
operations console, enabling usage/statistics counting of the skill itself.

### Integration

- **Entry script (`scripts/search-skills.py`):** the main search flow runs inside
  a `quality_context` block (imported from the vendored SDK), which reports on
  every exit path:
  - search with results → `status=success`
  - missing both keyword and category → `status=biz_fail`, `error_code=U02`
  - no matching skills → `status=biz_fail`, `error_code=U03`
  - index / cn-en-map fetch failure → `status=sys_fail`, `error_code=N02`
- The report is **fire-and-forget** (3s HTTP timeout): reporting failure or
  latency never blocks, changes, or fails the search.
- The SDK is Python 3.6+ stdlib only; `python` / `python3` is already a hard
  prerequisite.

### Error Code Convention

| Prefix | Category | Examples |
|--------|----------|---------|
| U | User input | U01 missing param, U02 bad param, U03 no data found |
| C | Configuration | C01 missing AK/SK/env |
| N | Network | N01 timeout, N02 connection refused |
| B | Code bug | B01 null pointer, B04 version mismatch |
| P | Platform | P01 scheduler error, P02 resource insufficient |

Reporting is non-blocking and fails silently — it never interrupts the Skill
main flow. Disable via `SKILL_QUALITY_DISABLE=1` for local testing.

## Reference Documentation

| Document | Description |
|----------|-------------|
| GitCode API v5 `index.json` | Skill index fetched via HTTP GET (base64 decoded) |
| GitCode API v5 `cn-en-map.json` | Chinese-English keyword mapping fetched via HTTP GET (base64 decoded) |
| [scripts/search-skills.py](scripts/search-skills.py) | Search script (Python) — fetches from GitCode API v5, expands keywords, scores, sorts |
| [scripts/skill_quality_sdk.py](scripts/skill_quality_sdk.py) | Vendored execution-quality reporting SDK (see Quality Reporting) |
| [references/iam-policies.md](references/iam-policies.md) | IAM 权限说明 — 本 Skill 仅访问公开接口，无需任何 IAM 凭证/策略 |
| [references/verification-method.md](references/verification-method.md) | 验证方法 — 各场景的验证步骤与预期结果 |
| [references/acceptance-criteria.md](references/acceptance-criteria.md) | 验收标准 — 功能/数据/安全/文件规范验收项 |

## Search Heuristics

> Optional reference for keyword-to-category hints. The agent can infer categories from `index.json` without these.

- Cloud infrastructure keywords (ecs, bms, vpc, obs, rds, ...) → likely `computing`, `network`, `storage`, etc.
- Tool keywords (cli, terraform, koo) → likely `devtools`
- Management keywords (monitoring, alarm, log) → likely `monitoring`

## Troubleshooting

### Issue: `python` is not recognized as a command

**Cause**: Python 3 is not installed or not in `PATH`
**Solution**: Install Python 3.6+ and ensure it is added to `PATH`. On Windows, re-run the installer and check "Add Python to PATH". Alternatively, use `python3` if available.

### Issue: Script fails with `SyntaxError: invalid syntax`

**Cause**: System `python` points to Python 2.x (the script requires Python 3.6+)
**Solution**: Run with `python3` explicitly: `python3 scripts/search-skills.py -k "<keyword>"`

### Issue: Script fails with "Failed to fetch index.json"

**Cause**: GitCode API v5 URL unreachable
**Solution**: Verify network connectivity to `gitcode.com`

### Issue: GitCode API v5 returns 404

**Cause**: File path incorrect or default branch is not `main`
**Solution**: Verify the skill's `category`, `service`, and `name` from search results

### Issue: Search returns no results

**Cause**: Keywords don't match any skill
**Solution**:
1. Try broader keywords
2. Switch between Chinese and English keywords (e.g., "对象存储" → "obs")
3. List all skills: `python scripts/search-skills.py -c "computing"`

## Notes

- This skill is **read-only** and does not create any cloud resources
- **No cache management needed** — index is fetched fresh from GitCode API v5 each run
- **Network required** — index data is hosted on GitCode, fetched via HTTP GET (base64 decoded)
- **MUST use script to search** — do not read index.json directly
- Index repo: `https://gitcode.com/2501_91318609/skills-for-index` (branch: `main`)
- Skills repo: `https://github.com/huaweicloud/huaweicloud-skills` (branch: `master`)
- **不涉及 CLI / 无 `--cli-region`**：本 Skill 是纯 Python 脚本 + HTTP 查询实现，
  不调用 hcloud / KooCLI 命令行，因此不包含 `--cli-region` 参数，也不涉及
  KooCLI 命令格式、CLI 安装指南等 CLI 相关条目（审查项 15/16 按"不涉及 CLI"跳过）。

Security audits