{"id":103321,"plugin_id":"plugin_asdk_app_6aedf6ea2fac819180910f8b98663c77","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-11-18T06:19:20.548Z","digest":"100e4c35161f9edf197e79fdee1a202bc7d00c5f44cde9daeed0098187f11c53","against":null,"payload":{"description":"Use when the user asks how to upgrade or change their Clay plan, where to manage billing, or about credits, quotas, or plan limits — including upgrade requests when credits remain. Provides the workspace’s direct plan-selector link and handles data-credit balances, action-execution balances, search caps, period quotas, and verified spending limits before paid work.","included_files":[],"name":"credits-quotas-plans","skill_md_contents":"---\nname: credits-quotas-plans\ndescription: Use when the user asks how to upgrade or change their Clay plan, where to manage billing, or about credits, quotas, or plan limits — including upgrade requests when credits remain. Provides the workspace’s direct plan-selector link and handles data-credit balances, action-execution balances, search caps, period quotas, and verified spending limits before paid work.\n---\n\n# Credits, quotas, and plans\n\nBefore using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.\n\nFollow the shared cost policy in `workflows-discover-actions/cost-and-budget.md`. Check headroom internally before paid work;\ndo not announce balances or suggest purchases just because a tool returned billing data.\nStop and explain a verified shortfall rather than knowingly starting a partial run.\nAn unknown cost does not establish a shortfall or require a cost-only approval.\n\n## Upgrade or change plan\n\nWhen the user asks how to upgrade, give their workspace’s plan-selector link below,\neven when credits remain. Do not require a shortfall or recommend waiting because of\nthe remaining balance. Product documentation can supplement the answer, but must not\nreplace the direct upgrade link with a docs link or general settings directions.\n\n## Triage\n\nAfter checking what remains (below), route by what is short:\n\n- **`balance` short** — CLI top-up or billing UI (`addCredits`). Prefer auto top-up.\n- **`actionExecutionBalance` short** (when the field is present) — plan selector only.\n  There is no top-up for action executions. Do not offer `once`, `auto`, or\n  `addCredits`.\n- **`user.balance` short** (when `user.limit` is not null) — the\n  user's personal monthly credit limit. A top-up does not raise it; a workspace admin\n  does, from the MCP page in Clay. It applies only to runs billed to the user, so\n  mention it as a possible blocker rather than refusing the run on it alone.\n- **Search `quota_exceeded` or period cap exhausted** — plan selector and/or wait for\n  the named reset in the error message. Defer shrink/retry rules to the `search`\n  skill; do not invent a top-up path for result caps.\n\nPlan selector URL (upgrade or change plan):\n\n```bash\nclay whoami | jq -r '.workspace.id'\n```\n\n`https://app.clay.com/workspaces/<workspaceId>/billing/plan-selector`\n\n## Check what remains\n\n```bash\nclay credits balance | jq '{ balance, actionExecutionBalance, user }'\n```\n\n`balance` is the data-credit pool. `actionExecutionBalance` is optional — present\nonly on action-execution pricing plans; omit or ignore it when the field is null\nor absent (legacy billing). Plenty of one does not cover the other.\n\nFor routine runs, `clay routines get <id>` includes per-item cost estimates.\nWhen the estimate applies to the configured execution and its counts are known, multiply\neach cost by the number of items and compare against the matching balance. See the\n`routines` skill for estimate limitations and the stop-before-partial-run rule.\n\n`user` identifies the user (`id`, `name`, `email`) and carries their personal monthly\ncredit `limit` and remaining `balance`, both null when they have no personal limit. That limit can also stop a run billed to the user while\nworkspace credits remain. These fields are not a complete capacity check: a credit budget\nassigned to the user can also stop a run, and this command does not report it.\n\nRead `clay credits balance --help` for field semantics.\n\n## CLI top-up\n\nApplies to data-credit `balance` only — not `actionExecutionBalance`.\n\n**Prefer auto top-up.** Lead with enabling (or confirming) auto so the workspace\nstays funded without another interrupt. Only offer a one-time purchase if the\nuser pushes back against auto, or if auto is unavailable.\n\nRead `clay credits top-up <subcommand> --help` for the exact JSON output shape,\nflags, and examples; that help is the contract.\n\n```bash\nclay credits top-up auto get\nclay credits top-up auto enable --threshold <n> --credits <n> [--daily-spend-limit-cents <n|none>]\nclay credits top-up auto disable\nclay credits top-up once --credits <n> [--open]   # only if user declines auto, or auto unavailable\n```\n\n**Auto enable limits:**\n\n- `--credits`: at least 250 data credits; the plan-specific maximum is the number\n  of credits currently equivalent to $1000\n- `--daily-spend-limit-cents`: optional rolling 24-hour cap, 3000–500000, or\n  `none` to clear; must cover the current price of one top-up\n- `--threshold`: credit balance that triggers a top-up; must be at least 15% of\n  the workspace subscription-cycle credit allowance (the server error includes\n  the exact minimum when too low)\n\nIf the current `balance` is already at or below `--threshold` when auto is\nenabled, a top-up runs **immediately** — it does not wait for the next charge.\nTell the user that enabling auto can purchase credits right away when they are\nalready under the threshold.\n\n**Auto get/disable** return the same policy shape as enable.\n\n**Once (fallback):** `--credits` must be at least 250. Returns a checkout `url`;\n`--open` launches it in the browser. Credits land only after checkout completes —\ndo not treat command exit as a topped-up balance.\n\n**Errors worth knowing** (from `credits balance` / `credits top-up`):\n\n- `auth_forbidden` (exit 3) — billing-management access required\n- `not_found` (exit 6) — auto top-up unavailable for this workspace, or disable\n  when not currently enabled; fall back to `once` or the billing UI\n\n**Do not run top-up without explicit user confirmation.** `credits top-up`\ncommands are gated from auto-approval in the plugin — present options and wait\nfor the user before `auto enable`, `once`, or checkout `--open`.\n\n## Billing UI\n\nPrefer automatic top-up first. Use the billing UI when the user wants the browser, or as\nthe one-time fallback after they decline auto / auto is unavailable:\n\n```bash\nclay whoami | jq -r '.workspace.id'\n```\n\n`https://app.clay.com/workspaces/<workspaceId>/home?addCredits=true`\n\nThe `addCredits=true` query opens the buy-credits modal directly.\n\n## Search and result-cap quotas\n\nThese operations do not top up search result caps or period quotas. Auto top-up only\nreplenishes **credit** shortfalls — it does not raise per-search or per-period\nresult limits.\n\n`quota_exceeded` (exit 1, HTTP 402) is a plan result cap or credit/usage limit —\nnot a transient failure (do not retry with backoff). Prefer the plan selector over top-up unless the\nmessage is clearly a data-credit shortfall that top-up can fix. When the error\nis about results already requested vs a cap, or a named period reset, stop\npaging; for shrink/retry rules follow the `searches` skill's Quotas section — do\nnot invent a top-up path for result caps.\n\nPlan selector:\n\n```bash\nclay whoami | jq -r '.workspace.id'\n```\n\n`https://app.clay.com/workspaces/<workspaceId>/billing/plan-selector`\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}