huawei-cloud-smn-dms-message

Huawei Cloud SMN / DMS メッセージングスキル

ステップ 0：skill-quality-cli の準備（必須。初回使用時にインストール）

必須：huawei_* アクションを実行する前に、skill-quality-cli がインストールされ、利用可能であることを確認してください。すべての実行で、同ツールを通じて品質テレメトリが報告されます。このスキルの実行ごとに、この手順を必ず実行してください（ensure_cli.sh は冪等性があり、すべて準備済みの場合は何も出力せず終了します）。

# 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 a pinned version with SHA256
# verification only if absent; no auto-upgrade — upgrade manually with `skill-quality-cli upgrade`)
bash scripts/ensure_cli.sh

# Verify it works
skill-quality-cli version

サプライチェーンに関する開示：ensure_cli.sh は固定バージョン（デフォルトは v1.1.8）をインストールし、SHA256 の許可リストで検証します。チェックサムが一致しない場合は、すべてインストールを拒否します。ダウンロード前にインストール先ディレクトリの正当性も確認します（ディレクトリトラバーサル／ワイルドカードインジェクションを防止）。インストール先は ~/.local/bin で、システムサービスやグローバル設定は変更しません。失敗時（オフライン／検証失敗）は警告を明示した後、通知なしでフォールバックします。業務フローを妨げることは決してありません。テレメトリの報告を無効にするには、export SKILL_QUALITY_REPORT=0 を実行してください。

概要

このスキルは、Huawei Cloud SMN（Simple Message Notification）と DMS（Distributed Message Service）向けに、15 個の huawei_* アクションを提供します。サポート対象は Huawei Cloud のみです。他のクラウドプロバイダーに対する操作は対象外です。SMN はパブリッシュ／サブスクライブ通知（トピック → サブスクリプション → メッセージ）を処理します。DMS は、3 つのメッセージキューエンジン（Kafka、RabbitMQ、RocketMQ）を含む製品群です。

重要なアーキテクチャルール： KooCLI には独立した DMS サービスがありません。DMS は独立した 3 つのサービス Kafka、RabbitMQ、RocketMQ として公開されており、hcloud <service> で呼び出せます。DMS の操作を行う前に、必ずエンジンを特定し、一致するサービスを呼び出してください。DMS コマンドは実行しないでください。

┌────────────────┐     ┌────────────────┐     ┌─────────────────────────────┐
│ hcloud SMN     │     │ hcloud Kafka   │     │ hcloud RabbitMQ / RocketMQ  │
│ topics/subs/   │     │ instances &    │     │ instances & delete ops      │
│ templates/msgs │     │ topics         │     │                             │
└────────────────┘     └────────────────┘     └─────────────────────────────┘

アクションファミリーの優先順位（リスクベースの実行）

ファミリー	アクション	実行方法	リスク
R3 — クエリ／診断（7）	huawei_list_smn_topics、huawei_list_smn_subscriptions、huawei_list_smn_message_templates、huawei_list_dms_instances、huawei_list_dms_topics、huawei_analyze_smn_subscription_confirmation、huawei_analyze_dms_instance_status	自動実行（読み取り専用）	なし
R2 — 管理（5）	huawei_create_smn_topic、huawei_add_smn_subscription、huawei_create_smn_message_template、huawei_publish_smn_message、huawei_create_dms_instance	実行前にコマンドをプレビューし、ユーザーに確認を求める	あり（リソースを作成／費用が発生）
R1 — 破壊的操作（3）	huawei_delete_smn_topic、huawei_confirm_smn_subscription、huawei_delete_dms_instance	一連の操作すべてについて確認：コマンド全体を提示し、取り消せない影響を説明したうえで、ユーザーから明示的な承認を得る	高（削除／状態変更、SMS／メールへの副作用）

アクションのディスパッチ（スクリプト実行）

すべての huawei_* アクションは、同梱スクリプト scripts/smn_dms_skill.py を通じてディスパッチされます。このスクリプトは適切な KooCLI サービス／操作を選択し、--cli-region を挿入して、毎回、品質レポート（成功／biz_fail U02／sys_fail B01）を必ず適用します。実行方法は、下記「コアコマンド」にあるラップ済みの skill-quality-cli run コマンドと同じです。スクリプト形式は、統合されたスクリプト／エージェント（ラッパー）の実行エントリーポイントです。

# R3 — Query / Diagnose (read-only, auto-execute)
python3 scripts/smn_dms_skill.py huawei_list_smn_topics --region={region}
python3 scripts/smn_dms_skill.py huawei_list_smn_subscriptions --region={region}
python3 scripts/smn_dms_skill.py huawei_list_smn_message_templates --region={region}
python3 scripts/smn_dms_skill.py huawei_list_dms_instances --engine=kafka --region={region}
python3 scripts/smn_dms_skill.py huawei_list_dms_topics --instance_id={instance_id} --preview
python3 scripts/smn_dms_skill.py huawei_analyze_smn_subscription_confirmation --region={region}
python3 scripts/smn_dms_skill.py huawei_analyze_dms_instance_status --engine=kafka --region={region}

# R2 — Manage (preview + confirm; --preview prints the command without executing)
python3 scripts/smn_dms_skill.py huawei_create_smn_topic --name=test-topic --display_name=test --preview
python3 scripts/smn_dms_skill.py huawei_add_smn_subscription --topic_urn=urn:smn:test --protocol=email [email protected] --preview
python3 scripts/smn_dms_skill.py huawei_create_smn_message_template --message_template_name=test --content=hello --preview
python3 scripts/smn_dms_skill.py huawei_publish_smn_message --topic_urn=urn:smn:test --message=hello --preview
python3 scripts/smn_dms_skill.py huawei_create_dms_instance --engine=kafka --name=test --engine_version=2.7 --product_id=test --available_zones=cn-north-4a --broker_num=3 --vpc_id=vpc-test --subnet_id=subnet-test --security_group_id=sg-test --storage_space=100 --storage_spec_code=dms.physical.storage.high.v2 --preview

# R1 — Destructive (end-to-end confirm; --preview prints the command without executing)
python3 scripts/smn_dms_skill.py huawei_delete_smn_topic --topic_urn=urn:smn:test --preview
python3 scripts/smn_dms_skill.py huawei_confirm_smn_subscription --token=test-token --preview
python3 scripts/smn_dms_skill.py huawei_delete_dms_instance --engine=kafka --instance_id=test-id --preview

• {region} は自動で解決されます（デフォルトは cn-north-4）。R2／R1 コマンドはデフォルトで --preview を付けて実行され、表示されたコマンドをユーザーが確認した後にのみ実際に実行されます。
• huawei_list_dms_topics --instance_id={instance_id} は、実在する Kafka インスタンス ID が必要なため、--preview を使用します。実際に実行するには、huawei_list_dms_instances で取得した ID に置き換えてください。

前提条件

前提条件の確認 1/3：KooCLI（hcloud）2.x 以降がインストールされ、認証済みであること

Huawei Cloud KooCLI をインストールして設定します。

curl -O https://cn-north-4-hcli.obs.cn-north-4.myhuaweicloud.com/hcli_install.sh && bash hcli_install.sh
# verify: hcloud --help should print the KooCLI version banner

前提条件の確認 2/3：認証 — AK/SK または hcloud プロファイル（どちらも使用できます）

認証モード	設定方法	使用する場面
ローカル hcloud プロファイル	hcloud configure set --cli-mode=AKSK --cli-region=cn-north-4 を対話形式で実行し、AK/SK を入力します	推奨。コマンドは以下のドキュメントどおりに実行できます
AK/SK 環境変数	export HUAWEICLOUD_SDK_AK=<ak> および export HUAWEICLOUD_SDK_SK=<sk>（任意で HUAWEICLOUD_SDK_SECURITY_TOKEN）	CI／一時的なランタイム。KooCLI がこれらを自動的に読み取ります

プロファイルが存在することを確認します（値は表示されません）。

# hcloud configure list | head -5   (only metadata is shown, keys are masked)

KooCLI がプロファイル／認証情報から --project_id と --cli-region を自動解決するため、通常はこれらを指定する必要はありません。

前提条件の確認 3/3：IAM 権限

アカウントには、references/iam-policies.md に記載された SMN および DMS の権限が必要です（例：SMN Administrator、DMS User、または同じファイルに記載された最小権限ポリシー）。

• インストール／認証の詳細は、references/cli-installation-guide.md を参照してください。
• スキルが動作することの確認方法は、references/verification-method.md を参照してください。

認証

セキュリティルール（必ず遵守してください）：

• AK/SK の値を読み取ったり、反復したり、表示したりすることは禁止されています。
• ユーザーに会話内で AK/SK を直接入力するよう求めることは禁止されています。
• チャットに貼り付けられた平文の認証情報を hcloud configure set で使用することは禁止されています。
• スクリプトやコマンドラインに AK/SK をハードコードすることは禁止されています。
• 許可されている方法：設定済みの hcloud プロファイルを参照するか、別経路で設定された HUAWEICLOUD_SDK_AK／HUAWEICLOUD_SDK_SK 環境変数を使用します。

ユーザーが AK/SK をメッセージに直接記載した場合は、丁寧に断り、上記の 2 つの認証モードを案内してください。

ワークフロー

1. 対象範囲を特定する — SMN か DMS かを確認します。DMS の場合は、エンジン（kafka、rabbitmq、rocketmq）を質問または確認し、対応する KooCLI サービスを選択します。
2. 操作を振り分ける — 以下の 15 個の huawei_* アクションのいずれかに振り分けます。
3. リスク判定：
   • R3 の照会／診断 → 直ちに実行し、結果を要約します。
   • R2 の管理 → 正確な hcloud コマンドを組み立ててユーザーに提示し、実行前に確認を待ちます。
   • R1 の破壊的操作 → 影響（削除されるもの／確認が送られるエンドポイント）とともに正確なコマンドを提示し、最初から最後まで明示的な確認を求めてから実行します。
4. 出力を解釈する — SMN コマンドは JSON を返します。サブスクリプションの status フィールドは、0＝未確認、1＝確認済み、2＝確認不要、3＝キャンセル済み、4＝削除済みです。DMS の status 値には、RUNNING（正常）、CREATING／ERROR／DELETING／FROZEN／EXTENDING などがあります。
5. 報告する — 作成／更新／削除したリソースを要約し、出力に認証情報が含まれていないことを確認します。

主なコマンド

コマンドを組み立てる前に、必ず hcloud <Service> <Operation> --help を実行し、特に作成操作ではパラメーター名を再確認してください。

R3 — 照会（自動実行）

huawei_list_smn_topics — SMN トピックの一覧表示

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud SMN ListTopics --cli-region={region} --limit=20 --offset=0

パラメーター	必須	説明
--cli-region	はい（自動）	リージョン。エージェントが自動的に入力します
--limit	いいえ	1～100、デフォルトは 100
--offset	いいえ	ページオフセット、デフォルトは 0
--name	いいえ	トピック名の完全一致
--fuzzy_name	いいえ	トピック名のあいまい検索

huawei_list_smn_subscriptions — SMN サブスクリプションの一覧表示

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud SMN ListSubscriptions --cli-region={region} --limit=20 --offset=0

パラメーター	必須	説明
--cli-region	はい（自動）	リージョン
--protocol	いいえ	http | https | sms | email | functionstage
--status	いいえ	0=未確認 1=確認済み 2=確認なし 3=キャンセル済み 4=削除済み
--limit / --offset	いいえ	ページネーション

huawei_list_smn_message_templates — SMN メッセージテンプレートの一覧表示

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud SMN ListMessageTemplates --cli-region={region} --limit=20

パラメーター	必須	説明
--cli-region	はい（自動）	リージョン
--message_template_name	いいえ	テンプレート名、1～64 文字
--protocol	いいえ	default | email | sms | functionstage | http | https

huawei_list_dms_instances — エンジン別の DMS インスタンス一覧表示

# Kafka
skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud Kafka ListInstances --engine=kafka --cli-region={region} --limit=20 --offset=0
# RabbitMQ
skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud RabbitMQ ListInstancesDetails --engine=rabbitmq --cli-region={region} --limit=20 --offset=0
# RocketMQ
skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud RocketMQ ListInstances --engine=rocketmq --cli-region={region} --limit=20 --offset=0

パラメーター	必須	説明
--engine	はい	kafka | rabbitmq | rocketmq（エンジンごとに固定）
--cli-region	はい（自動）	リージョン
--status	いいえ	RUNNING | CREATING | ERROR | DELETING | ...

huawei_list_dms_topics — インスタンスの Kafka トピック一覧表示

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud Kafka ListInstanceTopics --instance_id={instance_id} --cli-region={region} --limit=20 --offset=0

パラメーター	必須	説明
--instance_id	はい	Kafka インスタンス ID（huawei_list_dms_instances から取得）
--cli-region	はい（自動）	リージョン

R3 — 診断（自動実行）

huawei_analyze_smn_subscription_confirmation — サブスクリプション確認ステータスの分析

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud SMN ListSubscriptions --cli-region={region}

結果を分析します。status=0 のサブスクリプションは未確認です。HTTP/HTTPS エンドポイントでは ping-back による確認を実装する必要があり、メールエンドポイントではユーザーが確認リンクをクリックする必要があります。未確認のサブスクリプションと、各プロトコルで必要な操作を一覧表示します。

パラメーター	必須	説明
--cli-region	はい（自動）	リージョン
--topic_urn	いいえ	単一のトピックを分析
--protocol	いいえ	1 つのプロトコルに絞る

huawei_analyze_dms_instance_status — DMS インスタンスの健全性と容量の分析

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud Kafka ListInstances --engine=kafka --cli-region={region}     # then per instance:
skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud Kafka ShowInstance --instance_id={instance_id} --cli-region={region}

次の項目を分析します。インスタンスのステータス（RUNNING は正常、ERROR／FROZEN／CREATEFAILED は異常）、ストレージ使用量、再起動／メンテナンス状態、ブローカー数。ほかのエンジンについては、同じパターンで RabbitMQ／RocketMQ を使用します。

パラメーター	必須	説明
--engine	はい	エンジン
--instance_id	はい（ShowInstance 用）	インスタンス ID

R2 — 管理（プレビュー＋確認）

huawei_create_smn_topic — トピックの作成

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud SMN CreateTopic --name={name} --display_name={display_name} --cli-region={region}

パラメーター	必須	説明
--name	はい	1～255 文字。英字／数字／-／_ を使用でき、英字または数字で始める必要があります
--display_name	はい	メールの送信者として表示される名前（空文字列でも可）
--enterprise_project_id	いいえ	エンタープライズプロジェクト

huawei_add_smn_subscription — トピックへのサブスクリプション追加

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud SMN AddSubscription --topic_urn={topic_urn} --protocol={protocol} --endpoint={endpoint} --cli-region={region}

パラメーター	必須	説明
--topic_urn	はい	トピックのリソース識別子
--protocol	はい	email | sms | http | https | functionstage | dingding | wechat | feishu | welink
--endpoint	はい	プロトコルごとに、メールアドレス、電話番号、http(s):// URL、FunctionGraph ARN、チャットボットの Webhook を指定
--remark	いいえ	備考、128 バイト以下

⚠️ 追加後、HTTP/HTTPS サブスクリプションではエンドポイントからの ping-back 確認が必要です。メールサブスクリプションではユーザーが確認リンクをクリックする必要があります — その後まで、サブスクリプションは status=0 のままです。

huawei_create_smn_message_template — メッセージテンプレートを作成する

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud SMN CreateMessageTemplate --message_template_name={message_template_name} --content={content} --cli-region={region}

パラメーター	必須	説明
--message_template_name	はい	1～64 文字。英字または数字で始める必要があります
--content	はい	プレーンテキスト形式のテンプレート内容。最大 256 KB。${variable} プレースホルダーをサポートします
--protocol	いいえ	default | email | sms | functionstage | http | https

⚠️ SMS は配信されたメッセージごとに課金されます — SMS 向けテンプレートを使用して公開すると、メッセージごとに料金が発生します。

huawei_publish_smn_message — トピックにメッセージを公開する

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud SMN PublishMessage --topic_urn={topic_urn} --message={message} --cli-region={region}

パラメーター	必須	説明
--topic_urn	はい	トピックのリソース識別子
--message	はい（または --message_structure／--message_template_name）	最大 256 KB。SMS は最大 490 文字で、[] は使用できません
--subject	いいえ	メールの件名。最大 512 バイト
--message_template_name	いいえ	テンプレートを使用して公開します
--tags.*	いいえ	テンプレート変数の置換。例：--tags.name=value
--time_to_live	いいえ	保持期間は最大 86400 s。デフォルトは 3600

huawei_create_dms_instance — DMS インスタンスを作成する（エンジン別）

# Kafka
skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud Kafka CreatePostPaidKafkaInstance --name={name} --engine=kafka --engine_version={engine_version} --product_id={product_id} --available_zones.1={zone} --broker_num={broker_num} --vpc_id={vpc_id} --subnet_id={subnet_id} --security_group_id={security_group_id} --storage_space={storage_space} --storage_spec_code={storage_spec_code} --cli-region={region}

# RabbitMQ
skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud RabbitMQ CreatePostPaidInstanceByEngine --name={name} --engine=rabbitmq --engine_version={engine_version} --product_id={product_id} --available_zones.1={zone} --access_user={access_user} --password={password} --vpc_id={vpc_id} --subnet_id={subnet_id} --security_group_id={security_group_id} --storage_space={storage_space} --storage_spec_code={storage_spec_code} --cli-region={region}

# RocketMQ
skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud RocketMQ CreateInstanceByEngine --name={name} --engine=rocketmq --engine_version={engine_version} --product_id={product_id} --available_zones.1={zone} --broker_num={broker_num} --vpc_id={vpc_id} --subnet_id={subnet_id} --security_group_id={security_group_id} --storage_space={storage_space} --storage_spec_code={storage_spec_code} --cli-region={region}

パラメーター	必須	説明
--engine	はい	kafka | rabbitmq | rocketmq
--name	はい	インスタンス名
--engine_version	はい	例：Kafka 2.7／3.3、RabbitMQ 3.8.35、RocketMQ 4.8.0
--product_id	はい	エンジン／バージョンで公開されているインスタンスのフレーバー（ListEngineProducts を参照）
--available_zones.1	はい	AZ ID
--vpc_id / --subnet_id / --security_group_id	はい	ネットワーク設定
--storage_space	はい	ストレージ容量（GB）
--storage_spec_code	はい	dms.physical.storage.high.v2 | dms.physical.storage.ultra.v2 | dms.physical.storage.general | dms.physical.storage.extreme
--broker_num	はい（Kafka／RocketMQ）	ブローカー数
--access_user / --password	はい（RabbitMQ）	RabbitMQ コンソールの認証情報

作成前に hcloud Kafka ListEngineProducts --engine=kafka --cli-region={region} を実行し、有効な --product_id／--engine_version の組み合わせを取得してください。実行前にコマンド全体をプレビューし、見積もり費用をユーザーに確認してください。

R1 — 破壊的操作（エンドツーエンドでの確認が必要）

huawei_delete_smn_topic — トピックを削除する（サブスクリプションも削除）

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud SMN DeleteTopic --topic_urn={topic_urn} --cli-region={region}

パラメーター	必須	説明
--topic_urn	はい	トピックのリソース識別子

⚠️ トピックを削除すると、そのトピックのすべてのサブスクリプションとメッセージ履歴が削除されます — トピック名を含めて、ユーザーから明示的な確認を得てください。

huawei_confirm_smn_subscription — 保留中のサブスクリプションを確認する

skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud SMN ConfirmSubscription --token={token} --cli-region={region}

パラメーター	必須	説明
--token	はい	確認トークン（HTTP ping-back リクエスト本文、またはメール確認リンクから取得）
--topic_urn	いいえ	トピックのリソース識別子
--endpoint	いいえ	サブスクリプションのエンドポイント IP

トークンは通常、サブスクリプション先のエンドポイントに届きます（HTTP／HTTPS ping-back の本文、またはメール確認リンクの URL）。エージェントはユーザーまたはエンドポイントからトークンを取得し、実行前に確認操作の内容を正確に提示する必要があります。

huawei_delete_dms_instance — DMS インスタンスを削除する

# Kafka
skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud Kafka DeleteInstance --instance_id={instance_id} --cli-region={region}
# RabbitMQ
skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud RabbitMQ DeleteInstance --instance_id={instance_id} --cli-region={region}
# RocketMQ
skill-quality-cli run --skill-name huawei-cloud-smn-dms-message -- hcloud RocketMQ DeleteInstance --instance_id={instance_id} --cli-region={region}

パラメーター	必須	説明
--instance_id	はい	DMS インスタンス ID
--cli-region	はい（自動）	リージョン

⚠️ メッセージキューインスタンスの削除は取り消せません。保存されているすべてのメッセージ（トピック、キュー、オフセット）が削除されます。実行前に、インスタンス ID、エンジン、およびデータ損失の影響について、ユーザーから明示的な確認を得てください。

パラメーターの確認

• すべてのコマンドで、hcloud <Service> <Operation> --help で確認した正確なパラメーター名を使用してください。パラメーター名を推測してはいけません。
• --cli-region と --project_id は hcloud のプロファイル／認証情報から自動的に解決されるため、ユーザー入力は不要です。
• 必須パラメーターは各表で「Yes」と示されています。任意パラメーターは各表に記載されており、値が必要な場合にのみコマンドに追加してください。
• --help の内容を正としてください。重要なコマンドを実行する前に、hcloud <Service> <Operation> --cli-region={region} --help を実行してください。

KooCLI コマンド形式の標準

一般的な呼び出し形式は hcloud <Service> <Operation> --cli-region={region} [--key=value ...] です。 — これは形式の説明のみです。<...> と [...] はプレースホルダーであり、そのまま実行することはありません。

機能	規則	例
サービス名	実際の KooCLI サービス名（大文字と小文字を区別します）：SMN、Kafka、RabbitMQ、RocketMQ。DMS サービスは存在しません	hcloud <Service> <Operation>
オペレーション名	パスカルケース	ListInstanceTopics
リージョン	常に --cli-region={region} を含めます	--cli-region=cn-north-4
スカラー型パラメーター	--param=value	--instance_id=xxx
インデックス付きパラメーター	--param.N=value	--available_zones.1=cn-north-4a

RAM／容量に関する注意事項

• SMN トピックの display_name は API で必須ですが、空文字列でもかまいません。既定値が不明な場合はパラメーター検証で拒否される傾向があります。CreateTopic では必ず --display_name を明示的に渡してください。
• Kafka トピックの一覧表示にはインスタンス ID が必要です。再利用できるよう、huawei_list_dms_instances の出力からインスタンス ID を保持してください。
• メール／SMS／FunctionGraph の通知エンドポイントには、それぞれプロトコル固有の検証があります。AddSubscription の前にエンドポイントの形式を確認してください。

参考ドキュメント

• references/iam-policies.md — 最小権限の IAM ポリシー（必須）
• references/cli-installation-guide.md — KooCLI のインストールと認証設定（必須）
• references/verification-method.md — このスキルの検証方法（推奨）
• references/dataflow-diagram.md — エンドツーエンドのデータフロー（推奨）
• references/acceptance-criteria.md — 受け入れチェック（推奨）
• references/engine-operation-reference.md — SMN および DMS エンジンの全オペレーションカタログ（推奨）
• references/security-audit-guide.md — セキュリティ監査の方法（推奨）

品質レポート（統合 CLI）

CLI のインストールについては、このドキュメントの冒頭にある「Step 0: Ensure skill-quality-cli」を参照してください（冪等で、未インストールの場合に限り、SHA256 検証を行って固定バージョンをインストールします）。

以下のいずれかのモードを使い、このスキルを実行するたびに実行品質をレポートしてください。CLI は session_id／agent を明示的に取得します（--session-id、SKILL_QUALITY_SESSION_ID、または実行ごとの .quality_report.json を使用）。ホストのセッション情報をスクレイピングすることはありません。

⚠️ PATH に関する注意：CLI は ~/.local/bin/ にインストールされます。このディレクトリが一部の環境で $PATH に含まれているとは限りません。skill-quality-cli: command not found（終了コード 127）が表示された場合は、最初に export PATH="$HOME/.local/bin:$PATH" を実行してから再試行してください（ensure_cli.sh がこれを自動で行います）。または、絶対パス ~/.local/bin/skill-quality-cli を直接呼び出してください。

モード 1（推奨、自動）— 実行全体をラップする

スクリプト／コマンド形式のスキルでは、実行するコマンド全体を run でラップしてください：

skill-quality-cli run --skill-name <skill-name> -- <your command>

モード 2（複数ステップ／手順形式のスキル）

各ステップにつき 1 回レポートします（複数回呼び出し可能です）：

skill-quality-cli report --skill-name <skill-name> --status <success|sys_fail|biz_fail|cancel>

⚠️ 必須ルール：このスキルが実行する hcloud コマンドは、必ず skill-quality-cli run でラップしてください。hcloud を直接呼び出すことは固く禁止されています。

CLI のインストール（バージョン固定、SHA256 検証済み）

• 自動インストール：実行前に bash scripts/ensure_cli.sh を実行します（冪等で、インストール済みの場合はスキップします。SHA256 の許可リスト検証を行い、固定バージョンをインストールします）。
• 自動アップグレードなし：CLI は実行時に自動アップグレードされません。skill-quality-cli upgrade で手動アップグレードするか、手動インストールの場合は bash scripts/install_cli.sh を再実行してください。
• オフライン／失敗時：インストールに失敗しても通知は行われず、ビジネスフローが妨げられることはありません。スキルは適切に機能を縮退し、レポートはスキップされます。
• レポートの無効化：SKILL_QUALITY_REPORT=0 を設定します（オプトアウト）。
• 現在のバージョンは ~/.skill-quality/version.json に記録されます。ensure_cli.sh と install_cli.sh はどちらも SHA256 を検証します（検証に失敗した場合は処理を中止します）。