What does this skill do, and when should you use it?
cmux-billing is one of 25 skills bundled in the manaflow-ai/cmux monorepo, located at skills/cmux-billing/SKILL.md. It is a domain-knowledge document for AI coding agents covering Stripe Checkout, the customer portal, idempotent subscription recording, Pro entitlement resolution, admin routes, and test tooling. The skill performs no actions itself; its value is that an agent loads its constraints—idempotent recording, environment gates, the price catalog, and migration ordering—before touching billing code. It is useful to engineers or agents working on cmux server-side billing (web/) and has no applicability outside this repository.
- Maps the billing architecture: responsibilities of /api/billing/checkout, portal, subscription, /api/stripe/webhook, and the shared idempotent recorder web/services/billing/purchase.ts
- Explains entitlement resolution: the cmuxVmPlan operator override takes precedence over the Stripe-mirrored cmuxPlan; billingManagement stays Stripe-only
- Lists the full price catalog with Stripe product/price/portal-configuration IDs for test and live modes, legacy grandfathered prices, and env override variable names
- Documents the dev workflow: dev-stack.sh, dev-grant.sh, dev-reset.sh, the CMUXDEV100 test coupon, and Docker Postgres --db-port etiquette
- Gives the production runbook: provision-live.sh, Vercel env additions, and migration order (preflight → staging → production)
- Records gotchas: bun mock.module is process-global, DrizzleQueryError requires reading error.cause, and non-locale pages like /app-pricing need a proxy.ts bypass
- An engineer editing or debugging /api/billing/* or /api/stripe/webhook code in cmux who needs the idempotency and signature-verification constraints first
- An operator granting, switching, or downgrading a paid plan who must understand cmuxVmPlan overrides and admin_plan_grants activation conditions
- Someone investigating webhooks that fired but entitlements did not update, needing the insert-first idempotency and 2xx/500 return policy
- A developer changing pricing or adding annual plans who must handle immutable Stripe amounts and LEGACY_PRICE_LOOKUP_KEYS correctly
- A contributor standing up a local billing test environment who needs the dev scripts and the 100%-off coupon checkout flow
- Stripe projects outside the cmux repo: every route, script, and env variable name is hard-bound to cmux and not reusable
- cmux contributors not touching billing or entitlements: this document says nothing about end-user features, CLI, or notifications
- Readers seeking a general Stripe integration tutorial: this is an internal runbook, not Stripe education
How do you install this skill?
- This is a billing runbook for internal cmux contributors; it is not directly usable by outside users — invoke only when your task actually involves modifying or debugging cmux billing code.
- The workflow depends entirely on overseas services (Stripe, Vercel, Stack); reachability and usability from mainland-China networks are unverified.
- The document embeds many internal product/price/endpoint IDs (including a staging webhook endpoint); not secrets, but sensitive internal identifiers — mind exposure when reusing or quoting.
- License metadata is NOASSERTION and web/ is under BUSL-1.1 (commercial license required for production use); verify licensing boundaries before any secondary use of billing-related code.
- All script and implementation claims come from static document reading, not execution; cross-check referenced files before following the runbook.
- Shell / CLI
- Local filesystem
BunStripe CLIDocker (Postgres)
The source documents no separate install command; the skill ships inside the manaflow-ai/cmux repo. Obtain it by cloning and reading skills/cmux-billing/SKILL.md:
git clone https://github.com/manaflow-ai/cmux.gitPlace it in your agent's skills directory (e.g. the Claude Code skills path) for automatic discovery; the exact directory path is not documented in the source.
How do you use this skill?
Once installed, send your agent any of these to trigger it:
- I need to change the team fallback logic in /api/billing/checkout — load the cmux-billing skill and map the current paths before editing
- A paying customer's Pro status didn't activate; investigate stripe_webhook_events idempotency per the cmux-billing webhook section
- Raise the Pro annual price from $480 to $528 and follow the skill's guidance on immutable Stripe amounts and LEGACY_PRICE_LOOKUP_KEYS
- Simulate a Pro purchase for [email protected] locally and undo it, using the dev-grant and dev-reset flow from the cmux-billing skill
The skill is triggered by its description: any task involving editing or debugging billing, pricing, Stripe Checkout, subscription recording, Pro plan status, webhooks, entitlement metadata, or pricing dev/prod tooling should load this document first. The core usage is having the agent absorb its constraints before coding (e.g. idempotent recording, webhook returning 2xx only after durable writes) and following the Dev workflow scripts locally:
web/scripts/stripe/dev-stack.sh
web/scripts/stripe/dev-reset.sh <email>
web/scripts/stripe/dev-grant.sh <email>Production operations follow the Prod runbook:
web/scripts/stripe/provision-live.sh
bun run cloud-vm:preflight
bun run cloud-vm:migrate -- staging
bun run cloud-vm:migrate -- productionWhat are this skill's strengths and limitations?
- Exceptionally complete coverage: routing architecture, entitlement resolution, full price catalog IDs, env variables, and migration order in one place
- Contains hard-won gotchas (mock.module globals, Drizzle error wrapping, proxy.ts bypass) that prevent rework directly
- States security boundaries explicitly: webhook signature verification, idempotency, and never cross-granting on unverified email
- Tightly bound to the cmux repo; zero reuse value for other projects
- Packed with internal IDs (products, prices, portal configs, staging webhook endpoint) that carry high staleness risk and must be maintained in sync with code
- The skill itself is documentation only — no scripts or automation; correctness depends on the agent following it rather than enforcement
How does this skill compare with similar options?
Side by side with related skills; every score comes from the same FSRS standard.
| Skill | FS score | Stars | Last updated | License |
|---|---|---|---|---|
| cmux Billing Runbook Skill this page | 50 · Use with care | ★ 28k | 1d ago | NOASSERTION |
| cmux Workspace Skill | 64 · Recommended | ★ 28k | 1d ago | NOASSERTION |
| cmux-browser: Browser Automation Skill for cmux | 60 · Recommended | ★ 28k | 1d ago | NOASSERTION |
| cmux Settings Management Skill (cmux-settings) | 58 · Recommended | ★ 28k | 1d ago | NOASSERTION |
| Stripe AI Developer Toolkit | Not yet reviewed | ★ 1.9k | 3d ago | MIT |
How did FollowSkills review this skill?
The described billing flow shows real security engineering: signature-verified webhooks, insert-first idempotency, no cross-granting from unverified email, admin gating (requireAdmin plus domain/membership checks), 403 for non-admins, and fairly transparent data-flow disclosure. Deductions: the doc embeds many internal Stripe product/price IDs and a staging webhook endpoint (exposure surface, though not secrets); the local-dev auto-Pro grant depends on four env vars aligning, a fragile boundary; no explicit rollback guidance; publisher unverified.
The document is self-consistent and describes abnormal paths well (Stripe 500 retries, 503 before migration, typed resource-pool errors, DrizzleQueryError cause unwrapping, Stripe CLI format compatibility). Deductions: static review cannot execute any referenced script (dev-stack.sh, dev-grant.sh, provision-live.sh not provided); key paths are not reproducible and failure-feedback quality rests on description alone, capping below the static ceiling.
Frontmatter trigger conditions are precise (editing/debugging billing, pricing, Stripe, webhooks, Pro status), with clear boundaries; the audience is contributors/agents working in this codebase. Deductions: this is an internal runbook skill of limited value to outside users; core function depends entirely on overseas services (Stripe, Vercel, Stack), a mainland-China reachability risk; no Chinese-language support.
Information architecture is well layered (architecture map, dev workflow, catalog, flags, prod runbook, gotchas) with known-limitation disclosure and migration steps. Deductions: the skill itself has no version/changelog; license metadata is NOASSERTION and the repo's licensing is complex (GPL plus BUSL-1.1 for web/), with no self-declared license for the skill; maintenance responsibility and update path are only inferable indirectly.
For the target user (an agent or developer editing cmux billing code) the marginal value is clear: routes, scripts, price catalog, env vars and gotchas are centralized, avoiding scattered retrieval. Deductions: no verified representative outputs; several critical scripts and implementation files are outside the evidence set, so completeness and direct usability rest on description, capped at the static ceiling of 7.
All SKILL.md claims (IDs, scripts, migrations, gating logic) cannot be independently verified — the referenced source files are not in evidence. The repository has extensive real CI workflows and tests (app-host tests, auth tests), but none shown covering billing key paths. Deductions: single-source narrative with no fact/inference separation, yielding a low score under static review.
Open a dimension to read why it scored that way
Evidence confidence：Low — Mostly static review, author material or a limited demo; useful for discovery, not high-risk decisions.
See the full review method →