Alicloud Billing Ops

> This skill follows the Agent Skill OpenSpec.

Alibaba Cloud Billing Operations Skill

Runtime Rules

| Area | Rule | Reference | | --- | --- | --- | | CLI path | MANDATORY: Always prefer the SkillOpt wrapper ./scripts/billing-skillopt-wrapper.sh for all Billing CLI operations to enable automated self-repair and dynamic optimization; fallback to native aliyun billing only when the wrapper is unavailable or skillopt-lib.sh is missing. | [CLI](references/cli-usage.md), [SkillOpt](references/skillopt-integration.md) |

Overview

BSSOpenApi (Billing Support System Open API) is Alibaba Cloud's unified billing management service. This skill is an operational runbook for agents: explicit scope, credential rules, pre-flight checks, dual-path execution (official aliyun CLI primary, JIT Go SDK fallback), response validation, and failure recovery. All operations are read-only — this skill does not perform resource CRUD or billing modifications.

> UX Compliance: This skill follows the [User Experience Specification](../alicloud-skill-generator/references/user-experience-spec.md). All operations include onboarding guidance, minimal prompts, smart defaults, clear feedback, and user-friendly error handling.

CLI applicability (repository policy)

• cli_applicability: dual-path: Official aliyun fully supports BSSOpenApi. CLI is the primary execution path for all billing queries. JIT Go SDK is the fallback for edge cases or when Go-based data processing pipelines are needed. Both paths are documented for each operation below.

Five Core Standards (Quality Gates)

Every generated skill MUST satisfy these five standards. Use them as a design checklist during population:

| # | Standard | How This Skill Fulfills It | |---|----------|---------------------------| | 1 | Clear Boundaries | SHOULD/SHOULD NOT use with billing trigger keywords (CN/EN), explicit delegation to RAM, resource-manager, CMS, and product-specific skills | | 2 | Structured I/O | {{env.*}} for credentials, {{user.*}} for billing cycle filters, {{output.*}} for API response capture per OpenAPI JSON paths | | 3 | Explicit Actionable Steps | Every operation: Pre-flight (credential + param check) → Execute (CLI primary + SDK fallback) → Validate (response code + data presence) → Recover (error taxonomy) | | 4 | Complete Failure Strategies | 14 error codes with retry/HALT distinction; throttling backoff; pagination recovery; credential validation | | 5 | Absolute Single Responsibility | One product (BSSOpenApi), one domain (billing/financial). Cross-product delegation: RAM for permissions, CMS for alarms, product skills for resource CRUD |

Refer to the [meta-skill](../alicloud-skill-generator/SKILL.md#five-core-standards-quality-gates) for detailed descriptions of each standard.

---

Advanced Analytics

以下深度分析文档仅在用户明确需要时加载，不要在常规操作中读取：

| 场景 | 文档 | |------|------| | 成本最佳实践、FinOps 策略 | [advanced/finops-best-practices.md](references/advanced/finops-best-practices.md) |

---

Well-Architected Framework Integration (卓越架构)

In addition to the Five Core Standards, every generated skill MUST map its operations to Alibaba Cloud's Well-Architected Framework five pillars:

| Pillar | Skill Integration | Reference | |--------|-------------------|-----------| | 安全 (Security) | IAM permissions with least privilege; credential masking MANDATORY; RAM policy templates | references/well-architected-assessment.md §1 | | 稳定 (Stability) | Retry/backoff for throttling; pagination recovery; data freshness awareness | references/well-architected-assessment.md §2 | | 成本 (Cost) | Cost anomaly detection; RI/SCU coverage analysis; waste detection patterns; FinOps runbook | references/well-architected-assessment.md §3 | | 效率 (Efficiency) | Batch pagination; pipeline-friendly JSON output; CI/CD cost tracking | references/well-architected-assessment.md §4 | | 性能 (Performance) | API latency characteristics; filter-first strategy; cache guidelines | references/well-architected-assessment.md §5 |

See [references/well-architected-assessment.md](references/well-architected-assessment.md) for the complete specification.

Trigger & Scope (Agent-Readable)

SHOULD Use This Skill When

• User mentions "Alibaba Cloud BSSOpenApi" OR "BSS" OR "Billing" OR "账单" OR "费用"
• Task involves querying account balance (QueryAccountBalance)
• Task involves bill queries — overview, detail, instance-level, settlement, account, or split billing
• Task involves order queries and order details
• Task involves RI/SCU/SP — reserved instances utilization, savings plans, storage capacity units
• Task involves resource packages — listing, status check, remaining amount
• Task involves financial tools — transactions, prepaid cards, cash coupons
• Task involves FinOps — cost anomaly detection, budget tracking, expiration warnings, coverage analysis
• Task keywords: bill, invoice, balance, order, RI, SCU, savings plan, resource package, coupon, prepaid, transaction, 账单, 费用, 订单, 预留实例, 储蓄计划, 资源包, 代金券, 储值卡, cost optimization, FinOps, bssopenapi, QueryBill, QueryAccountBalance
• User asks to analyze, monitor, or optimize costs via API, CLI, or automation
• Even without naming BSSOpenApi explicitly: user says "查一下账户余额", "这个月花多少钱了", "ECS费用明细", "代金券还有多少"

SHOULD NOT Use This Skill When

• Task is resource CRUD (create/modify/delete ECS, RDS, SLB, etc.) → delegate to: alicloud-ecs-ops, alicloud-rds-ops, alicloud-slb-ops, etc.
• Task is RAM / permission management → delegate to: alicloud-ram-ops
• Task is account / resource group management → delegate to: alicloud-resourcemanager-ops
• Task is monitoring / alert configuration → delegate to: alicloud-cms-ops
• Task is network / VPC / NAT → delegate to: alicloud-nat-ops, alicloud-vpc-ops
• User insists on console-only flows with no API → state limitation; do not invent undocumented HTTP steps

Delegation Rules

| 能力 | 委托目标 | 说明 | |------|----------|------| | GCL 质量门禁 | N/A | 只读操作，不触发 GCL 质量门禁 |

Variable Convention (Agent-Readable)

Structured placeholders reduce injection ambiguity and unsafe prompts:

| Placeholder | Meaning | Agent Action | |-------------|---------|--------------| | {{env.ALIBABA_CLOUD_ACCESS_KEY_ID}} | From runtime environment | NEVER ask the user; fail if unset | | {{env.ALIBABA_CLOUD_ACCESS_KEY_SECRET}} | From runtime environment | NEVER ask the user; fail if unset | | {{env.ALIBABA_CLOUD_REGION_ID}} | From runtime environment | Default to cn-hangzhou (billing is region-independent) | | {{user.billing_cycle}} | Billing cycle (YYYY-MM) | Ask once; default to current month | | {{user.product_code}} | Product code filter (e.g., ecs, rds) | Ask once; optional filter | | {{user.order_id}} | Order ID for detail query | Ask once | | {{user.sp_instance_id}} | Savings Plan instance ID | Ask once | | {{output.balance}} | From QueryAccountBalance response | Parse per $.Data.AvailableAmount | | {{output.bill_items}} | From QueryBill response | Parse per $.Data.Items.Item[] | | {{output.total_count}} | Pagination counter | Parse per $.Data.TotalCount |

> {{env.*}} MUST NOT be collected from the user. {{user.*}} MUST be collected interactively when missing.

> Security Warning (Credential Masking — MANDATORY): NEVER log, print, or expose ALIBABA_CLOUD_ACCESS_KEY_SECRET, access_key_secret, AccessKeySecret, or any credential field value in console output, debug messages, error messages, or logs. > > Masking rules across all execution paths: > | Execution Path | Safe Pattern | Unsafe Pattern | > |----------------|-------------|----------------| > | Console output | ALIBABA_CLOUD_ACCESS_KEY_SECRET= | ALIBABA_CLOUD_ACCESS_KEY_SECRET=LTAI5t... | > | Error messages | Error: API call failed (credential omitted) | Error: InvalidAccessKeySecret.XXX ... actual secret... | > | Verification | test -n "$ALIBABA_CLOUD_ACCESS_KEY_SECRET" && echo "Secret is set" | echo "Secret=$ALIBABA_CLOUD_ACCESS_KEY_SECRET" | > | JIT Go SDK | AccessKeySecret: tea.String(os.Getenv("...")) (env read is safe) | fmt.Printf("Config: %+v", config) | > > If any execution flow violates this rule, the skill SHALL be blocked from merge as a security incident.

API and Response Conventions (Agent-Readable)

• OpenAPI is canonical for path, query, body fields, enums, and response shapes
• BillingCycle format: YYYY-MM (e.g., 2026-05)
• Timezone: All timestamps are UTC+8 (Asia/Shanghai)
• Endpoint: business.aliyuncs.com (region-independent)
• API version: 2017-12-14

Response Field Table (Key Operations)

| Operation | JSON Path | Type | Description | |-----------|-----------|------|-------------| | QueryAccountBalance | $.Data.AvailableAmount | string | Available cash balance | | QueryBillOverview | $.Data.Items.Item[] | array | Product-level bill summary | | QueryBill | $.Data.Items.Item[] | array | Bill detail records | | QueryInstanceBill | $.Data.Items.Item[] | array | Instance-level bill records | | QueryOrders | $.Data.OrderList.Order[] | array | Order list | | GetOrderDetail | $.Data | object | Single order detail | | QueryRIUtilizationDetail | $.Data.Items[] | array | RI utilization records | | QuerySavingsPlansInstance | $.Data.Items[] | array | Savings plans list | | QueryResourcePackageInstances | $.Data.Instances.Instance[] | array | Resource packages list | | QueryAccountTransactions | $.Data.AccountTransactionsList | object | Transaction records | | QueryPrepaidCards | $.Data.PrepaidCard[] | array | Prepaid card list | | QueryCashCoupons | $.Data.CashCoupon[] | array | Cash coupon list |

All bill/item arrays support pagination via $.Data.TotalCount, $.Data.PageNum, $.Data.PageSize.

Quick Start

What This Skill Does

This skill enables you to query and analyze Alibaba Cloud billing data — account balance, bills, orders, reservations, savings plans, resource packages, transactions, coupons — using the aliyun CLI (primary) or JIT Go SDK (fallback).

Prerequisites

• [ ] aliyun CLI installed (or Go runtime for JIT fallback)
• [ ] Credentials configured: ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET
• [ ] RAM policy includes bssapi:Query* permissions

Verify Setup

# Check CLI and billing permissions
aliyun bssopenapi QueryAccountBalance

Your First Command

# Check account balance
aliyun bssopenapi QueryAccountBalance

# Monthly bill overview
aliyun bssopenapi QueryBillOverview --BillingCycle "2026-05"

Next Steps

• [Core Concepts](references/core-concepts.md) — Understand billing architecture
• [Common Operations](#execution-flows-agent-readable) — Query bills, orders, savings
• [CLI Usage](references/cli-usage.md) — Complete CLI command map with JSON paths
• [Troubleshooting](references/troubleshooting.md) — Fix common errors
• [FinOps Best Practices](references/advanced/finops-best-practices.md) — Cost optimization runbooks

Capabilities at a Glance

| Operation | Description | Complexity | Risk Level | |-----------|-------------|------------|------------| | QueryAccountBalance | Check account balance | Low | None | | QueryBillOverview | Monthly bill by product | Low | None | | QueryBill | Bill details with filters | Low | None | | QueryInstanceBill | Instance-level billing | Low | None | | QuerySettleBill | Post-settlement bills (large datasets) | Low | None | | QueryAccountBill | Bill by account/resource owner | Low | None | | QuerySplitItemBill | Split/shared billing items | Low | None | | QueryOrders + GetOrderDetail | Order list and details | Low | None | | QueryRIUtilizationDetail | RI utilization analysis | Medium | None | | QuerySavingsPlans* | Savings plans info and deduct logs | Medium | None | | QueryResourcePackageInstances | Resource package status | Low | None | | QueryAccountTransactions | Transaction history | Low | None | | QueryPrepaidCards | Prepaid card inventory | Low | None | | QueryCashCoupons | Voucher inventory and balance | Low | None | | Cost Anomaly Detection | MoM cost comparison | Medium | None | | Resource Expiry Warning | 30-day expiration check | Medium | None | | FinOps Optimization | RI/SP coverage analysis | High | None |

Changelog

| Version | Date | Changes | |---------|------|---------| | 1.0.0 | 2026-05-30 | Initial billing skill: 14 APIs + 3 FinOps patterns, dual-path execution, 14 error codes, Well-Architected five-pillar integration |

---

> EXECUTION MANDATORY RULE: 所有 control-plane CLI 执行步骤 必须 通过 SkillOpt wrapper ./scripts/billing-skillopt-wrapper.sh 运行。 > 以下所有代码块中的 aliyun bss ... 命令在执行时应替换为 ./scripts/billing-skillopt-wrapper.sh ...。 > 仅在 wrapper 脚本不可用或 skillopt-lib.sh 缺失时，才退回到原生 aliyun bss CLI 调用。 > 参考 ## Runtime Rules 中的 CLI path 规则。

Execution Flows (Agent-Readable)

Every operation: Pre-flight → Execute (CLI primary + SDK fallback) → Validate → Recover. Do not skip phases.

Preference hint: CLI is the primary path for all billing queries. JIT Go SDK is used when Go-based data processing is needed or for complex multi-API pipelines.

Common Pre-flight Checks (All Operations)

| Check | Method | Expected | On Failure | |-------|--------|----------|------------| | CLI availability | aliyun version 2>&1 | Exit code 0 | Document CLI install; redirect to [Prerequisites](#prerequisites) | | Credentials | test -n "$ALIBABA_CLOUD_ACCESS_KEY_ID" && test -n "$ALIBABA_CLOUD_ACCESS_KEY_SECRET" | Both set | HALT; user configures env | | Billing permission | aliyun bssopenapi QueryAccountBalance 2>&1 | Valid JSON response (no NotAuthorized) | HALT; check RAM policy includes bssapi:QueryAccountBalance |

---

Operation 1: QueryAccountBalance — 账户余额查询

When to use:

• Check available account balance
• Verify billing account health
• Pre-operation balance check before any cost-incurring activity

What to expect: Returns AvailableAmount, CreditAmount, Currency in one API call.

Execution — CLI (Primary Path)

# JSON output by default
BALANCE=$(aliyun bssopenapi QueryAccountBalance)
AVAILABLE=$(echo "$BALANCE" | jq -r '.Data.AvailableAmount')
CREDIT=$(echo "$BALANCE" | jq -r '.Data.CreditAmount')
CURRENCY=$(echo "$BALANCE" | jq -r '.Data.Currency')
echo "Balance: $AVAILABLE $CURRENCY (Credit: $CREDIT $CURRENCY)"

Execution — JIT Go SDK (Fallback)

See [references/api-sdk-usage.md](references/api-sdk-usage.md) for complete Go SDK client initialization.

response, err := client.QueryAccountBalance()
if err != nil {
    panic(err)
}
available := tea.StringValue(response.Body.Data.AvailableAmount)
credit := tea.StringValue(response.Body.Data.CreditAmount)
currency := tea.StringValue(response.Body.Data.Currency)
fmt.Printf("Balance: %s %s (Credit: %s %s)\n", available, currency, credit, currency)

Post-execution Validation

1. Verify response contains $.Data.AvailableAmount
2. Validate Currency is expected (typically CNY)
3. Report balance to user in human-readable format

Failure Recovery

| Error pattern | Max retries | Agent Action | UX Feedback | |--------------|-------------|--------------|-------------| | NotAuthorized | 0 | HALT | [ERROR] NotAuthorized: Verify RAM policy includes bssapi:QueryAccountBalance | | Throttling.User | 3, exponential | Retry with backoff | Rate limited. Retrying in {backoff}s... (Attempt {current}/{max}) | | InternalError | 3, 2s/4s/8s | Retry then HALT with RequestId | [ERROR] InternalError: Server error. Retry or escalate with RequestId: {RequestId} |

---

Operation 2: QueryBillOverview — 账单总览

Gets monthly bill overview grouped by product. Required parameter: BillingCycle (YYYY-MM forma

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: buhaiqing
• Source: buhaiqing/aliyun-skills
• License: MIT

Install and usage instructions live in the source repository linked above.