billing-finance-calculator
Skill4 starsChanged 6 months agoMITView on GitHub
Use when checking subscription unit economics, pricing margins, Apple fee tiers, power-user risk, OCR/LLM variable costs, or rate limits before changing IAP pricing or paywall strategy.
In this repository76 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .cursor/rules/components.mdcCursor rule
- .cursor/rules/currency.mdcCursor rule
- .cursor/rules/design-system.mdcCursor rule
- .cursor/rules/file-structure.mdcCursor rule
- .cursor/rules/forbidden-patterns.mdcCursor rule
- .cursor/rules/mvvm-architecture.mdcCursor rule
- .cursor/rules/pricing-display.mdcCursor rule
- .cursor/rules/scope.mdcCursor rule
- .cursor/rules/swift-conventions.mdcCursor rule
- accessibilitySkill
- animationsSkill
- apple-developer-authSkill
- apple-signinSkill
- app-store-preflightSkill
- asc-app-create-uiSkill
- asc-aso-auditSkill
- asc-build-lifecycleSkill
- asc-cli-usageSkill
- asc-crash-triageSkill
- asc-id-resolverSkill
- asc-localize-metadataSkill
- asc-metadata-syncSkill
- asc-metadata-yamlSkill
- asc-notarizationSkill
- asc-ppp-pricingSkill
- asc-release-flowSkill
- asc-revenuecat-catalog-syncSkill
- asc-screenshot-resizeSkill
- asc-shots-pipelineSkill
- asc-signing-setupSkill
- ascSkill
- asc-submission-healthSkill
- asc-subscription-localizationSkill
- asc-testflight-orchestrationSkill
- asc-wall-submitSkill
- asc-whats-new-writerSkill
- asc-workflowSkill
- asc-xcode-buildSkill
- buildSkill
- business-modelSkill
- chartsSkill
- consolidate-errorsSkill
- content-composerSkill
- crashSkill
- debuggingSkill
- feature-directory-structureSkill
- feedback-statesSkill
- fix-errorSkill
- formsSkill
- foundation-modelsSkill
- hapticsSkill
- healthkitSkill
- layoutSkill
- listsSkill
- navigationSkill
- notificationsSkill
- onboarding-questionnaireSkill
- onboardingSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 3 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 27
Before computing anything, read .Codex/config/finance.md.
- Very specific: line 36
If .Codex/config/finance.md doesn't exist, point the user to reference/finance-template.md and stop.
- Very specific: line 58
If worst_case_loss_per_abuser > $0, the rate limit is too loose for the chosen price tier — surface this and recommend a tighter cap.
- Distinctive: line 86
Before changing any price live in ASC
- Very specific: line 87
After a competitor changes their pricing (the aso-keywords agent flags this)
- Distinctive: line 88
When variable costs change ≥20% (e.g.
- Distinctive: line 89
When real usage data shifts the P95 / P99 by ≥30% from the estimate
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Billing Finance Calculator
The math layer the billing agent calls before it touches App Store Connect or RevenueCat. Pricing is a one-way door — once a tier is live and users have purchased, you can't materially raise it without grandfathering chaos. So we model first, ship second.
What this skill does
Given a project's .Codex/config/finance.md (variable costs, Apple fee tier, usage distribution, target margin) and a competitor table from ASO research, produce a pricing recommendation that:
- Survives power users. P95 / P99 cost-of-service stays below price after Apple's cut.
- Beats or matches the most-used competitor tier without racing to the bottom.
- Has rate-limit guardrails sized so the absolute worst case (top 0.1% abuse) is bounded.
- Caps the LTV/CAC math at sane assumptions so you don't price a tier on fantasy retention.
What it does NOT do:
- Touch ASC. The
ascagent does that, after this skill outputs the recommended tier. - Touch RevenueCat. The
revenuecatagent does that. - Decide whether to offer a free trial. That's a conversion question, not a unit-economics one — defer to the
business-modelskill. - Set marketing prices (page rendering). That's the paywall + content-composer skills.
Per-project config
Before computing anything, read .Codex/config/finance.md. It contains:
- Variable costs: OCR call $/req, LLM completion $/req, hosted service cost $/active-user/month
- Apple fee tier:
small_business(15%) orstandard(30%) — seereference/apple-fees.md - Usage distribution: P50 / P75 / P95 / P99 calls/month (estimate from analytics or the
reference/power-user-risk-model.mddefaults if greenfield) - Hard rate-limit caps: requests-per-day per device — defines the floor cost on the worst case
- Competitor pricing table: yearly / monthly / weekly / lifetime per competitor (sourced from the
aso-keywordsagent's research CSV) - Target margin: gross margin minimum (default 70%), net margin target (default 65%)
If .Codex/config/finance.md doesn't exist, point the user to reference/finance-template.md and stop. The template is the source of truth for the schema; this skill's body documents the math, not the values.
Workflow
- Read inputs:
.Codex/config/finance.md+ the most recent competitor CSV atmetadata/aso-keywords-research.csv(if present). - Compute per-tier unit economics for each candidate price point. For each tier:
gross_revenue_per_user_year = price × renewals_per_year × retention_rate apple_take = gross_revenue × apple_fee_pct net_revenue_per_user = gross_revenue − apple_take variable_cost_per_user = (avg_ocr_calls × ocr_cost) + (avg_llm_calls × llm_cost) + infra_amortized variable_cost_p95 = (p95_ocr × ocr_cost) + (p95_llm × llm_cost) + infra_amortized gross_margin_per_user = (net_revenue − variable_cost) / net_revenue gross_margin_p95 = (net_revenue − variable_cost_p95) / net_revenue - Project worst case for each tier with hard rate-limits applied:
Ifworst_case_cost = (rate_limit_ocr_day × 365 × ocr_cost) + (rate_limit_llm_day × 365 × llm_cost) + infra_amortized worst_case_loss_per_abuser = max(0, worst_case_cost − net_revenue)worst_case_loss_per_abuser > $0, the rate limit is too loose for the chosen price tier — surface this and recommend a tighter cap. - Compare against competitors:
Flag if we're priced >50% below median (race to the bottom) or >100% above (overpriced for the niche).competitor_median_yearly = median(competitor_yearly_prices) our_yearly_gap_pct = (our_yearly − competitor_median_yearly) / competitor_median_yearly - Output the recommendation report as markdown. See
reference/report-format.mdfor the exact shape. - Persist the analysis at
.Codex/billing/finance-analysis-<YYYY-MM-DD>.mdso the billing agent can cite it when setting ASC tiers, and so future re-pricing has the prior analysis to diff against.
How to invoke
# Run the calculator script with the candidate tier set
python3 .Codex/skills/billing-finance-calculator/calculator.py \
--config .Codex/config/finance.md \
--competitors metadata/aso-keywords-research.csv \
--tiers "yearly:9.99,weekly:0.99" \
--output .Codex/billing/finance-analysis-$(date +%Y-%m-%d).mdOr pass a single tier set via env vars + invoke without flags — the script defaults to .Codex/config/finance.md and writes to .Codex/billing/.
When to re-run
- Before changing any price live in ASC
- After a competitor changes their pricing (the
aso-keywordsagent flags this) - When variable costs change ≥20% (e.g. OpenRouter price drop, model swap)
- When real usage data shifts the P95 / P99 by ≥30% from the estimate
- Annually as a hygiene check, even if nothing changed
Reference files
reference/unit-economics.md— formulas, definitions, worked examplesreference/apple-fees.md— Small Business Program qualification (≤$1M annual proceeds), 15% vs 30% rules, when each applies, how the tier flipsreference/competitor-research.md— how to source pricing data (Sensor Tower, Astro right-click, App Store reviews mention prices), what numbers to capturereference/power-user-risk-model.md— typical P50/P95/P99 distribution for OCR-style apps, how to size rate limits, abuse vs heavy-use distinctionreference/pricing-frameworks.md— Van Westendorp, anchored pricing, weekly-vs-yearly tradeoffs, decoy effect, intro offer mathreference/report-format.md— exact markdown shape of the recommendation outputreference/finance-template.md— drop-in for new projects to copy to.Codex/config/finance.mdcalculator.py— the actual math; reads finance.md, writes the report
Hard rules
- Always include the worst-case row. Even if the recommendation is "yearly $9.99 / weekly $0.99", the report must show what a rate-limited abuser costs and what an unlimited one would cost. Hidden risk = future write-down.
- Never set a tier where P99 unit cost > net revenue. That's not a business, that's a charity for the top 1%. Either raise the price or tighten the rate limit until P99 is profitable.
- Don't price below 50% of the median competitor's yearly unless the brief explicitly says "we're pricing as a loss leader to take share". Cheap pricing trains users to expect cheap; you can't walk it back.
- Don't price above 50% of the most expensive direct competitor's yearly plan unless the brief says the app is positioned as a luxury or professional tier.
- Always cite competitor sources in the recommendation. "Rocket Money $39.99/yr" with a link to the ASO research CSV row + the Sensor Tower screenshot. No vibes-based pricing.
- Never recommend a weekly price ≥ yearly_price/52 × 1.5 without flagging it as predatory framing. The user explicitly rejected the MonoBoost-style $3.99/wk = $207/yr pattern. Weekly should be priced as a low-commitment entry point, not a trap.
Cost discipline (skill-meta)
This skill itself doesn't cost anything to run — it's pure local math. The expensive part is the COMPETITOR RESEARCH that feeds it. Don't re-run the aso-keywords agent every time you tweak a price; cache the research CSV and only refresh quarterly.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

