🏗️ Architecture

Paywall Pilot is not just a Claude Code skill (though it works as one). It's a 4-layer framework, designed to be used whole or per-layer.

Runtime behavior is intentionally smaller than this README: agents should start from SKILL.md, then use runtime/ for input contracts, routing, and source lookup rules.

┌─────────────────────────────────────────────────────────────┐
│  🤖 SKILL LAYER          SKILL.md + modules/*.md            │
│  Entry point for AI assistants (Claude / GPT / Cursor)      │
│  Thin core + lazy modules + runtime contracts               │
├─────────────────────────────────────────────────────────────┤
│  📚 KNOWLEDGE LAYER      sources.json + outputs/            │
│  Every numeric claim sourced. Research briefs.              │
│  Use standalone or referenced by Skill layer.               │
├─────────────────────────────────────────────────────────────┤
│  🔧 TOOL LAYER           tools/ltv-calculator.py            │
│  Executable utilities. CLI + JSON I/O.                      │
│  Callable by Skill layer OR from Bash.                      │
├─────────────────────────────────────────────────────────────┤
│  📘 REFERENCE LAYER      docs/ + examples/                  │
│  Human-readable playbooks, checklists, migrations, examples │
│  Works without any AI tool.                                 │
└─────────────────────────────────────────────────────────────┘

Which layer do you need?

⚡ Use this when…

Concrete jobs-to-be-done. Match your situation; the framework activates the relevant modules automatically.

If your situation isn't on this list, just send a screenshot and say "Audit my paywall". You get a concise screenshot-first audit by default; ask for a deep audit when you want the full breakdown.

🎁 What you get

🚫 The problem this solves

Most paywall advice is one of three things, all of them broken in 2026:

1. Generic web CRO — ignores App Store rules and gets your app rejected.
2. Hype-driven single-app case studies — no methodology, no sample size, may not transfer.
3. Outdated tactics — toggle paywalls were the 2024 gold standard; Apple started mass-rejecting them in January 2026.

And most AI assistants compound the problem: they recommend whatever pattern they saw most often in 2023 training data, with no source, no compliance check, and no awareness of category economics.

✅ The fix

Paywall Pilot Framework grounds every recommendation in published evidence with confidence labels, never invents data, and explicitly states when to ignore benchmarks (e.g., when N<1,000 subs/variant or when your category is niche).

Modules

The Skill layer is split into a core SKILL.md plus deep-dive modules under modules/, an executable Python calculator, worked examples, and migration playbooks. Load on demand based on the task.

Plus standalone documentation, executable tools, worked examples, and research:

• docs/audit-checklist.md -- printable 50+ item checklist for manual review before App Store submission
• docs/migrations/from-toggle-paywall.md -- migration playbook for apps caught in Apple's Jan 2026 toggle ban, with 4 compliant alternatives
• examples/ -- worked audit examples: H&F app, AI app, Productivity app. Use as deep-output references; default runtime answers stay shorter.
• tools/ltv-calculator.py -- backward-compatible CLI wrapper for the calculator
• tools/ltv_calculator.py -- importable calculator library with validation + JSON-safe output helpers
• Local validation -- validates sources.json structure, all internal links resolve, calculator smoke tests, SKILL.md size guard

• outputs/2026-paywall-research-v2.md -- canonical research brief with current methodology, sample sizes, and evidence class for every benchmark used
• outputs/2026-paywall-research.md -- legacy v1 research brief retained for historical references and changelog continuity
• outputs/2026-paywall-research-v2.provenance.md -- provenance ledger: sources consulted vs accepted vs rejected, cross-references, weak-signal flags

What's Inside

Every recommendation carries a confidence label. Higher = more reliable.

Plus two academic-foundation classes used in pricing-psychology.md: academic (peer-reviewed papers) and platform_capability (documented features).

The paywall system has four independent axes. Separate them when analyzing or recommending.

Axis 1: Access Model -- What we sell (8 types)

Axis 2: Placement -- When we show it (13 types)

Onboarding, Post-aha, Feature gate, Usage limit, Post-close offer, Transaction abandon, Session-start, Renewal-risk, Billing issue / grace period, Win-back, Push marketing, Plan-upgrade, Value primer / bridge.

Axis 3: Presentation Pattern -- How we show it (9 types)

One-screen paywall, Value stack, Social-proof-led, Comparison table, Trial timeline, Video/demo paywall, Long-form landing, Interactive/gamified, Contextual mini-paywall.

Axis 4: Surface / Rendering Layer -- Where it renders (6 types)

Native StoreKit sheet, Provider remote paywall (Adapty/RevenueCat), Custom native screen, WebView hybrid, System-provided sheet (grace period, price increase consent), Push / notification deep-link surface.

Different categories have different economics. Do not apply one playbook to all apps. Full per-category deep-dives in modules/category-deep-dives.md.

Per AppsFlyer 2026 (1.7B installs, 2,900 apps): subscription UA spend grew 24% YoY but the growth is not where you might think.

• Android growing 4x faster than iOS in subscription UA
• Indian Subcontinent: 49% of net Android paid install growth; LATAM: 18%
• North America: essentially flat
• Top 5 apps per category control >90% of UA spend (high concentration risk)
• Western Europe charges 29-39% more than North America -- huge under-priced opportunity

Strategic implication: NA-only apps face flat user pool; emerging markets are where Android growth happens. Geo-tier pricing (ChatGPT Go @ $8 for India) is increasingly important.

6-Phase Process

Discovery & Audit --> Paywall Strategy --> Screen Design
        |                                        |
        v                                        v
iOS Compliance  <-- Implementation  <-- Testing Plan

1. Discovery & Audit -- understand the app, audit existing paywall, Apple Analytics benchmarks
2. Paywall Strategy -- access model, trigger points, plan architecture
3. Screen Design -- value block, pricing, CTA, trust/legal
4. Testing Plan -- what to test first (structure > polish)
5. Implementation -- Adapty, RevenueCat, StoreKit 2, Google Billing
6. iOS Compliance -- pre-ship checklist with Apple Rule vs Apple Guidance distinction

10-Stage Lifecycle Monetization

6 Screen Templates + 5 New Paywall Types

Plus: Metered Paywall, Reverse Trial, One-Time Unlock, Renewal-Risk / Churn-Save, Intent-Tiered Paywall.

Big-App Teardowns

Annotated breakdowns of 11 high-revenue subscription apps in modules/teardowns.md. One-line summary:

Benchmark Tables (April 2026)

Key insight: Structure tests beat copy tests by ~2x. Don't start with polish. Localize first -- highest win rate of any test category.

EU charges 29-39% more than NA. IN/SEA RLTV is ~46% of NA on annual.

Short trials = aggressive (more conversions, more refunds). 7-day is the balanced default.

Trial length impact, Revenue per install (D14 + D60), Plan architecture by category, Revenue share by plan type, 12-month retention by plan, RLTV per payer by category / region / price tier, Superwall aggregate data (32M views, 18-company abandon study), AppsFlyer 2026 (1.7B installs, Android 4x growth), Apple Analytics benchmarks.

Design Patterns with Evidence

Apple Compliance (2026)

• Toggle paywall ban (killed Jan 2026, Guideline 3.1.2): Apple-cited reason: "This design is confusing and may prevent users from understanding that they are committing to an auto-renewing subscription."
• Billed amount must be most prominent pricing element
• Trial duration + post-trial price required if trial offered
• Restore Purchases, Terms, Privacy links required
• Apple Rule vs Apple Guidance distinction for subscription groups, freemium, metered models
• Family Sharing as trust lever
• Field reports (RevenueFlo): pricing fonts <16pt, delayed close >5s, two paywalls back-to-back, guilt decline copy = high rejection risk
• Full "Must Have" + "Must NOT Have" checklists inside

Pricing Psychology -- Academic Foundations

Mobile paywall pricing isn't invented in vendor blogs. The foundational research:

• Tversky & Kahneman 1981 -- Framing effects (gain vs loss). Science, 17,000+ citations.
• Anderson & Simester 2003 -- $9 endings outsell $4 endings in field experiments. Quantitative Marketing and Economics.
• Thomas & Morwitz 2005 -- Left-digit effect: $9.99 anchors on "9". Journal of Consumer Research.
• Ariely 2008 -- Decoy effect (Economist subscription experiment). Predictably Irrational.
• Cialdini 1984 + Pre-Suasion 2016 -- 7 principles of influence. Springer 2024 mobile-app study: Social Proof + Authority test as most influential.

Full mobile-application mapping in modules/pricing-psychology.md.

How to Use

Claude Code

Quickest start (clone the whole skill including modules):

git clone https://github.com/Nikolai-Iakubovskii/app-paywall-pilot \
  ~/.claude/skills/app-paywall-pilot

Then run /app-paywall-pilot in your project. The core SKILL.md loads first; modules load on demand when relevant.

Single-file install (core only):

mkdir -p ~/.claude/skills/app-paywall-pilot
curl -o ~/.claude/skills/app-paywall-pilot/SKILL.md \
  https://raw.githubusercontent.com/Nikolai-Iakubovskii/app-paywall-pilot/main/SKILL.md

Codex CLI

Add SKILL.md content to your project's AGENTS.md or custom instructions. Reference modules via raw GitHub URLs.

ChatGPT / GPT-5 / GPT-5.3

Paste SKILL.md as a system prompt, then ask: "Audit my paywall" with a screenshot. For deeper analysis, also paste the relevant module (e.g. teardowns.md when comparing to Calm).

Cursor / Windsurf / AI IDEs

Add SKILL.md to your project root or AI rules config. Modules in modules/ will be findable in workspace.

Standalone (no AI tool)

Read SKILL.md and the modules directly -- they're a structured knowledge base that works without any AI tool. Designed to be human-readable.

Example Output

Ask your AI: "Audit my paywall" with a screenshot. The default output is 12 sections:

1. Current state           -- app context, placement, plan config
2. Main problem            -- plain language
3. Recommended access model -- from taxonomy
4. Recommended placements   -- from taxonomy
5. Recommended presentation -- from taxonomy
6. Screen content           -- headline, benefits, pricing, CTA, trust
7. Copy variants            -- 2-3 short and long versions, Copy Ladder rung
8. Layout sketch            -- ASCII or block diagram, thumb-zone confirmed
9. Localization notes       -- pricing per market, CTA length budget per locale
10. Tests to run            -- ranked by Adapty 2026 win rate (localization first)
11. iOS review risks        -- Apple Rules + Field Reports
12. Android delta           -- Play Billing differences if cross-platform

Each finding labeled with its evidence level.

Data Sources

Full source manifest with every numeric claim: sources.json (50+ entries with URL, date, scope, evidence class).

Independent paywall screenshot libraries used for teardowns:
Adapty Paywall Library •
Mobbin •
ScreensDesign •
Paywallscreens.com •
NamiML •
Growth.Design •
Funnel Teardowns

What This Is NOT

• Not a web pricing page optimizer -- in-app subscription flows only
• Not a guarantee -- benchmarks are directional; SKILL.md has an explicit "WHEN TO IGNORE BENCHMARKS" section for when not to trust them
• Not a dark patterns toolkit -- flags anti-patterns, prioritizes user trust
• Not affiliated with Adapty, RevenueCat, Superwall, AppsFlyer, Apphud, or Apple

🗺️ Roadmap — Framework Expansion

Paywall is the flagship domain. Framework will expand into adjacent subscription-app domains. Full detail in ROADMAP.md.

The 20-concept academic foundation (Kahneman + Layer 2) already applies cross-domain — it's in the shared layer. Each new domain gets its own modules while inheriting the foundations.

Non-goals: generic web CRO, enterprise B2B sales, original academic research, competing with vendor SDKs. See ROADMAP.md for full scope.

What's New

• v4.0.0 (current): Reframed as Framework. Positioning upgraded from "single Claude skill" to "4-layer framework" (Skill + Knowledge + Tool + Reference). New ROADMAP.md documents planned expansion to Onboarding, Retention, Growth, Pricing, Reviews domains. No breaking changes — all v3.x installations continue to work.
• v3.8.0: Academic foundation Layer 2. Added 9 additional rigorous behavioral-science concepts to pricing-psychology.md beyond the Kahneman base — Fogg B=MAT, Iyengar Choice Overload (jam study), IKEA Effect, Hyperbolic Discounting (Laibson), Goal-Gradient (Kivetz), Negativity Bias (Baumeister 2001), Costly Signaling (Spence/Nobel), Reactance Theory (Brehm), Sunk Cost (Arkes & Blumer). Plus explicit warning on ego-depletion replication failure (Hagger 2016 + Vohs 2016 multi-lab studies). 11 new sources.json academic entries. Total academic concepts: 20.
• v3.7.0: Kahneman foundation expansion. Added 11 Kahneman concepts to pricing-psychology.md, each mapped to a specific paywall design choice: Prospect Theory & Loss Aversion, Anchoring (1974), System 1/2, Endowment Effect, Peak-End Rule, Default Effect, Mental Accounting, WYSIATI, Substitution Heuristic, Planning Fallacy, Hedonic Adaptation. Cross-referenced from copy-library, decision-trees, screen-anatomy, glossary. 11 new sources.json entries (academic class).
• v3.6.0: Data refresh — ChatGPT teardown updated to current 6-tier pricing structure (Free/Go/Plus/Pro/Business/Enterprise) without model-version trivia. Redesigned README header with concrete jobs-to-be-done table.
• v3.5.0: Phase 3 — refund management, cohort analysis, audit checklist, migration playbooks, worked examples (3 categories), CI validation.
• v3.4.0: Phase 2 — onboarding-paywall handoff, lifecycle messaging, glossary, executable Python LTV calculator.
• v3.3.0: Phase 1 — unit-economics calculator, indie dev FAQ, CAC + acquisition module, response modes.
• v3.2.0: Initial modular split + AppsFlyer + academic foundations + 11 big-app teardowns.

See CHANGELOG.md for full release notes.

Contributing

PRs welcome. Ground rules:

1. Every benchmark needs a source and date. No unsourced numbers.
2. Label every recommendation with its evidence level (Apple Rule through Hypothesis).
3. Check against App Store guidelines before adding UI patterns.
4. Keep SKILL.md lean -- put deep content in a module under modules/ and reference from SKILL.md. Every line in the core costs tokens for every user.
5. Open an issue first for structural changes.

License

MIT