{"id":19311,"plugin_id":"plugins_6a9669d9e57c8191a04a3c8951e44401","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:15:29.464Z","digest":"66fb446429afe2e0c184fd942f67b17887ba25f84f737b360ecff04b172af4fd","against":null,"payload":{"description":"Design, implement locally, or evaluate retrieval and interpretation of the YCloud account balance. Use for the single Balance read operation or a balance-to-readiness evidence handoff; exclude plugin readiness checks, billing history, top-ups, and real API operations.","included_files":[{"relative_path":"agents/openai.yaml","size_in_bytes":269},{"relative_path":"references/openapi.md","size_in_bytes":2327},{"relative_path":"references/runtime.md","size_in_bytes":12993},{"relative_path":"references/shared/integration-boundaries.md","size_in_bytes":8401}],"name":"ycloud-balance","skill_md_contents":"---\nname: ycloud-balance\ndescription: Design, implement locally, or evaluate retrieval and interpretation of the YCloud account balance. Use for the single Balance read operation or a balance-to-readiness evidence handoff; exclude plugin readiness checks, billing history, top-ups, and real API operations.\n---\n\n# YCloud Balance\n\nDesign or implement contract-aware retrieval of the current account balance.\nUse synthetic responses and a mock transport only; never call YCloud, read a\ncredential, expose customer financial data, or claim a live balance was checked.\n\n## Execution boundary\n\nThese restrictions govern Skill execution: do not call a YCloud Provider API, access real credentials, or read real business data. The Skill may generate server-side adapter code for an application's runtime, but must not start it or make a live request. Reading public official documentation as contract evidence is allowed and is not a Provider API call or business-data access. A live smoke test is outside the default workflow and requires separate, explicit authorization naming the target/environment, allowed operations, credential boundary, and required result evidence.\n\nHonor an Architect handoff for scope, deliverable, mutation, capability ID,\nproject seams, and evidence. Without one, default to focused read-only guidance\nunless the user explicitly requests local implementation. Local-write\nauthorization permits a trusted-server adapter, typed response mapping,\nmock-only handler/service bindings, fixtures, and no-network tests in the scoped\nproject. It never authorizes a live balance request or production readiness\ndecision.\n\n## Scope and handoffs\n\nAfter this Skill is selected, read the generated [OpenAPI\ncontract](references/openapi.md) and reviewed [runtime\nbehavior](references/runtime.md). If retry, error translation, rate limiting, or\nproduction architecture is requested, also read\n`references/shared/integration-boundaries.md`. If either generated reference is\nmissing, stale, or conflicts with the pinned source, report the drift and stop\ninstead of guessing.\n\nThis Skill owns exactly `GET /balance`, operationId `balance-retrieve`. It does\nnot own transactions, billing history, invoices, spending forecasts, top-ups,\ncurrency conversion, or account mutation. API-key configuration belongs to\n`ycloud-api-authentication`; broad planning belongs to\n`ycloud-integration-architect`.\n\nBalance may provide one synthetic or observed-at-runtime input to an\napplication's operational-readiness policy, but this Skill does not define a\nminimum sufficient balance and cannot certify plugin, deployment, account, or\nproduction readiness. Route an explicit Developer Kit installation/readiness\ncheck to the readiness/smoke workflow. Keep any application threshold, alert,\nreservation, or fail-open/fail-closed rule labeled as project policy.\n\n## Contract-first workflow\n\n1. Confirm the source hash, exact method/path, `operationId`, lack of parameters\n   and request body, and response schema in the generated reference. Do not\n   infer an SDK method from `balance-retrieve`.\n2. Preserve the documented `200 Balance` shape: required numeric `amount` and\n   required string `currency`, where currency is an ISO 4217 code. Do not assume\n   `amount` is an integer, minor units, non-negative, available credit, or a\n   promise that a future operation will succeed. Preserve decimal precision\n   according to the target project's established money strategy; if none\n   exists, surface that decision instead of silently rounding through binary\n   floating-point arithmetic.\n3. Keep provider-generated identifiers and future opaque strings\n   case-sensitive and unparsed. Preserve unknown response properties and an\n   explicit unknown branch for future enum-like values. Do not convert currency\n   or combine balances unless a separate, authoritative project contract is in\n   scope.\n4. At the provider adapter, retain the standard error envelope and\n   `YCloud-Request-ID` (or `error.requestId`) for redacted correlation. The\n   operation itself declares only `200`; use reviewed cross-cutting runtime\n   behavior for generic failures and do not invent balance-specific status\n   codes or error meanings. Branch on HTTP status and `error.code`, never\n   diagnostic `error.message`.\n5. On `429`, honor `Retry-After` before another request and parse beta\n   `RateLimit-*` headers defensively. Do not assign an invented balance quota.\n   Because retrieval is read-only, a bounded transient retry may be proposed as\n   project policy, but no retry count, backoff, cache lifetime, or staleness\n   tolerance is a YCloud guarantee unless `runtime.md` says so.\n6. Keep the API key on a trusted server and use placeholders only. A local\n   handler or readiness consumer must call a fake adapter and visibly\n   label its data synthetic; it must not offer a control that reaches YCloud.\n\n## Illustrative raw HTTP\n\nThis shape is documentation only; do not execute it:\n\n```http\nGET <YCLOUD_API_BASE_URL>/balance\nX-API-Key: <YCLOUD_API_KEY>\n```\n\nSynthetic response fixture:\n\n```json\n{\"amount\": 190.0765, \"currency\": \"USD\"}\n```\n\nDo not put a real key, account identifier, response, or customer financial data\nin examples, fixtures, logs, or generated artifacts.\n\n## Outcome requirements\n\nAdapt the result to planning, implementation, or evaluation, while making these\nitems explicit:\n\n1. **Matched contract** — source hash, `GET /balance`, `balance-retrieve`, no\n   request body, `200 Balance`, and required `amount`/`currency` fields.\n2. **Interpretation** — numeric/precision strategy, ISO 4217 treatment, unknown\n   property handling, freshness label, and every project-owned threshold or\n   policy clearly separated from YCloud facts.\n3. **Integration placement** — trusted-server adapter, placeholder\n   Authentication handoff, mock transport seam, and redacted request-ID\n   observability.\n4. **Response and rate handling** — standard error envelope, no invented\n   balance-specific statuses, defensive rate headers, `Retry-After`, and any\n   bounded GET retry labeled as project policy.\n5. **Tests** — no-parameter/no-body request construction; decimal and currency\n   preservation; missing/wrong-typed fields; unknown fields/currency-like\n   values; synthetic error/request-ID fixtures; `429` scheduling; timeout and\n   bounded-retry policy; readiness handoff without a readiness claim; and proof\n   that no network call occurs.\n6. **CANNOT** — live balance retrieval, credentials or real financial data,\n   mutations/top-ups/history, currency conversion, affordability or readiness\n   guarantees, inferred SDK methods, invented quotas/errors, or unlabelled\n   caching and threshold policy.\n7. **Handoff** — provide Balance evidence with provenance and freshness to the\n   Architect or project-owned readiness consumer, which owns the final policy\n   decision. Return capability-row status, artifacts, tests/results, and\n   unknowns; state when no handoff is needed.\n\n## Safety and source priority\n\nUse the pinned OpenAPI source first, generated references second, and this\nworkflow third. Keep provider contract, reviewed runtime facts, and project\npolicy visibly separate. External reads and mutations remain prohibited even\nwhen local implementation is authorized.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}