huawei-cloud-find-skills

重要

ユーザーが Huawei Cloud のエージェントスキルを検索、発見、またはインストールしたい場合：

1. 検索 — このスキル（huawei-cloud-find-skills）を使って、関連する Skill を見つけます。
2. インストール — 一致した Skill をインストールします（Step 3 を参照）。
3. 実行 — インストールした Skill の指示に従って、リクエストに対応します。

このスキルはスキルの発見とインストールのみを行います。Huawei Cloud のリソース管理やクエリは実行せず、それらはインストールしたスキルが担当します。

概要

このスキルを使うと、Huawei Cloud のスキルを効率的に検索、発見、インストールできます。

依存関係：Python 3.6 以降と、gitcode.com（スキルインデックス用の API v5）、およびスキルの詳細情報を取得するための github.com / raw.githubusercontent.com へのネットワークアクセスが必要です。品質テレメトリは skill-quality-cli によって自動的に収集されます（存在しない場合は scripts/ensure_cli.sh によってインストールされます）。その他の CLI や認証情報は不要です。

プライバシーとテレメトリ

透明性に関する開示：この skill では、検索およびインストールの際に、以下の外部向けテレメトリが送信されます。いずれも匿名の集計データ（スキル名／カテゴリ／サービスなどのメタデータ）であり、ユーザーの入力内容、認証情報、クラウドリソースデータ、個人を特定できる情報は含まれません。品質レポートはデフォルトで有効（オプトアウト方式）です。無効にするには、環境変数 export SKILL_QUALITY_REPORT=0 を設定してください。

送信内容	トリガー	送信先	機密データを含むか
検索結果上位 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 reporting APIG（テスト環境）	いいえ（実行ステータス／所要時間／スキル名）

• デフォルト設定／無効化方法：上記 3 種類のレポートはデフォルトで有効（この環境変数が設定されていない場合は送信されます）。無効にするには、export SKILL_QUALITY_REPORT=0 を実行してください（skill-quality-cli と search-skills.py の両方がこの設定に従います）。
• いずれのレポートも fire-and-forget 方式で送信され、検索／インストールのメイン処理を妨げることはありません。

シナリオの説明

このスキルを使うと、次のことができます。

• スキルを検索：キーワード、カテゴリ、またはその両方でスキルを検索します（名前、説明、トリガーを照合します）
• カテゴリを閲覧：利用可能なスキルカテゴリを確認します
• スキルの詳細を表示：特定のスキルの SKILL.md 全文を GitHub から取得します
• スキルをインストール：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 raw fetch → インストール

ユースケース

• 「ECS インスタンスを管理するスキルを探して」
• 「OBS で利用できる Huawei Cloud のスキルは何ですか？」
• 「Huawei Cloud には VPC 関連のスキルがどのようなものがありますか？」
• 「利用可能な Huawei Cloud のスキルをすべて閲覧する」
• 「RDS 管理用のスキルをインストールして」
• 「Huawei Cloud のネットワーク関連のスキルを探して」

前提条件

• Python 3.6 以降がインストールされており、PATH 上で python（または python3）として利用できること
• ネットワークアクセスがあること。gitcode.com（インデックス用の API v5）および、スキルの詳細情報を取得するための github.com / raw.githubusercontent.com へのアクセスが必要です
• skill-quality-cli — 必須（Step 0.1）：bash scripts/ensure_cli.sh で確実に利用できるようにします （べき等で、すでに存在する場合はスキップします）。検索／インストールコマンドの実行前に、このスキルを実行するたびに必ず起動してください。
  • アップグレード：手動で skill-quality-cli upgrade を実行します（自動アップグレードはありません）
  • 品質レポート：検索（Step 1）とインストール（Step 3）の各コマンドは、実行のたびに品質レポートが送信されるよう、必ず skill-quality-cli run --skill-name huawei-cloud-find-skills -- でラップして実行してください

ステップ 0：Python 環境を確認する

必須：スクリプトコマンドを実行する前に、Python が利用可能であることを確認してください。

⚠️ 必須：このスキルで実行するすべての hcloud コマンドは、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 を指している場合：以下のすべてのコマンドで python の代わりに python3 を使用してください

ステップ 0.1：skill-quality-cli を確実に利用できるようにする（必須）

必須：検索／インストールコマンドを実行する前に、skill-quality-cli が インストールされ、利用可能であることを確認してください。このステップは、このスキルを実行するたびに、 ステップ 0 の直後に必ず実行する必要があります。ステップ 0：Python 環境を確認すると同じ 必須レベルのステップです。CLI がすでに存在すると考えていても、スキップしないでください （ensure_cli.sh はべき等で、すべての準備が整っていれば何も表示せずに終了します）。

開示：この CLI は、本スキルの匿名の品質テレメトリー報告（実行状態／所要時間。Privacy & Telemetry を参照）のみに使用します。インストール先は ~/.local/bin で、システムサービスやグローバル設定は変更しません。無効化する方法は Privacy & Telemetry を参照してください。

# 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 内に書き込み可能なディレクトリが ない場合）は、現在のシェルで次を実行してください：

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

手動で一度だけインストールする場合の代替手段：bash scripts/install_cli.sh。

ステップ 0.5：KooCLI のバージョンを確認する（処理をブロックしません）

任意：KooCLI（hcloud）の利用可否／バージョンを確認します。この確認によって処理がブロックされることはありません。 後からインストールするスキルが 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 からスキルのインデックスを取得します（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：スキルを検索する

必須：エージェントは、スキルインデックスを検索するために検索スクリプトを実行する必要があります。JSON ファイルを直接読まないでください。必ずスクリプトを使用してください。

AI が理解したユーザーの意図から得られる keyword と、任意の category を指定して、検索スクリプトを実行します。

⚠️ 必須（品質報告）：検索コマンドは 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 はユーザー入力に由来するため、エスケープせずにシェルコマンド文字列へ連結することは固く禁じられています。入力に $(), $(...), バッククォート , ;, | などのシェルメタ文字が含まれている場合、Bash／PowerShell の二重引用符文字列でコマンドインジェクションが発生する可能性があります。外部入力をシェル文字列に埋め込まないよう、次の方法で呼び出してください。

1. 最優先（推奨）：Python の subprocess 引数配列を使って、シェルを経由せずに呼び出します：subprocess.run([sys.executable, "scripts/search-skills.py", "-k", keyword, "-c", category])；
2. シェルで実行する必要がある場合は、ユーザー入力を単一引用符（'<keyword>'）で囲み、事前にエスケープします（入力中の ' を '\'' に置き換える）。または、シェルエスケープツール（shlex.quote）を使用します；
3. 入力に $(), バッククォート, ;, | などのメタ文字が含まれている場合は、引数配列方式に切り替えるか、ユーザーに表示する前に入力をマスキングしてください。

→ scripts/search-skills.py（Python — クロスプラットフォーム）

スクリプトの動作：

1. GitCode API v5 から HTTP GET で 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"

エージェントは curl またはウェブ取得ツールを使ってこの URL を取得し、スキルのドキュメント全体をユーザーに提示できます。

ステップ 3：スキルをインストールする

必須：インストール前に、エージェントはインストール数 API を呼び出してインストールを記録する必要があります。その後、以下のインストールコマンドのいずれかを使用してください。オプション A がデフォルトです。オプション C は、オプション A を利用できない場合の代替手段です。

ステップ 3.1：インストール数を記録する

インストールコマンドを実行する前に、インストール数 API を呼び出します。skill_id は、ステップ 1 の検索結果から次の形式で構成します：skills/<category>/<service>/<skill-name>。

重要：category と service の値は、ステップ 1 の検索結果（形式：name (category/service)）から直接取得する必要があります。推測したり、ハードコードしたりしないでください。

⚠️ 必須（品質報告）：インストール数リクエストも 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：インストールコマンドを実行する

⚠️ 必須（品質報告）：インストールコマンドは 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 '...' 内に連結することは禁止されています。スキル名に ' などのシェルメタ文字が含まれる場合は、事前にエスケープ（' → '\''）するか、npx skills add ... -y を直接呼び出してください（この場合、品質報告はインストール完了後に skill-quality-cli report --skill-name huawei-cloud-find-skills を手動で実行します）。

すべてのインストール試行に失敗した場合は、エラーメッセージをユーザーに報告してください。上記以外の方法を試さないでください。

パラメーターの確認

パラメーター	必須／任意	説明	デフォルト
Keyword	任意	検索キーワード（名前、説明、トリガー、サービスを対象に照合）	なし
Category	任意	絞り込み用のカテゴリコード（例：「computing」、「storage」、「network」）	なし
skill-name	必須（ステップ 3）	インストールするスキルの正確な名前	なし

参照資料

ドキュメント	説明
GitCode API v5 index.json	HTTP GET で取得したスキルインデックス（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 のインストール／アップグレード／テレメトリー無効化に関する説明

検索のヒューリスティクス

キーワードからカテゴリを推測する際に使える任意の参考情報です。エージェントは、これらがなくても index.json からカテゴリを推測できます。

• クラウドインフラストラクチャのキーワード（ecs、bms、vpc、obs、rds など）→ computing、network、storage などが候補です
• ツール関連のキーワード（cli、terraform、koo）→ devtools が候補です
• 管理関連のキーワード（monitoring、alarm、log）→ monitoring が候補です

トラブルシューティング

問題：python がコマンドとして認識されない

原因：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）に自動リンクされるため、コマンド名だけで実行できます。 手動での代替策として、現在のシェルで 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 ではありません。 解決策：検索結果からスキルの category、service、name を確認してください。

問題：検索結果がありません

原因：キーワードがどのスキルにも一致していません。 解決策：

1. より広いキーワードを試してください
2. 中国語と英語のキーワードを切り替えてください（例：「对象存储」→「obs」）
3. すべてのスキルを一覧表示します：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 が見つからない場合や古い場合に警告します。