Paywall Upgrade Cro

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

.codex/skills/a11y-audit

.codex/skills/ab-test-setup

.codex/skills/account-executive

.codex/skills/ad-creative

.codex/skills/aeo

│  - Full access resumes when you upgrade │

Audit 0.4.1 · source sha 6e3fcbdbb5cf · 19 Oct 2026Report an issue or request a re-scan

• Publisherborghei GitHub userOwner of the repository this skill is read from
• Source folderborghei/Claude-Skills/business-growth/paywall-upgrade-croThe exact folder we audited
• LicenceNOASSERTIONAs the repository states it
• Commit pinned for this verdict6e3fcbdbb5cfA new audit runs when the source changes
• Repository statusNot archivedLast push 12 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: In-app paywall and upgrade screen optimization covering feature gate design, usage limit UX, trial expiration flows, upgrade trigger timing, save offer strategy, and ethical monetization patterns.

---
name: paywall-upgrade-cro
description: >
  In-app paywall and upgrade screen optimization covering feature gate design,
  usage limit UX, trial expiration flows, upgrade trigger timing, save offer
  strategy, and ethical monetization patterns.
license: MIT + Commons Clause
metadata:
  version: 1.0.0
  author: borghei
  category: business-growth
  updated: 2026-03-31
  tags: [cro, paywall, upgrade, freemium, monetization, upsell]
---
# Paywall & Upgrade Screen CRO

Production-grade framework for in-product upgrade flows. Covers feature gate design, usage limit UX, trial expiration sequences, upgrade trigger timing, dark pattern avoidance, and ethical monetization. Distinct from public pricing pages (use page-cro for those) -- this focuses on in-product moments where users have already experienced value.

---

## Table of Contents

- [Initial Assessment](#initial-assessment)
- [The Value-First Principle](#the-value-first-principle)
- [Paywall Trigger Architecture](#paywall-trigger-architecture)
- [Paywall Screen Design](#paywall-screen-design)
- [Feature Gate Patterns](#feature-gate-patterns)
- [Usage Limit UX](#usage-limit-ux)
- [Trial Expiration Flows](#trial-expiration-flows)
- [Timing and Frequency Rules](#timing-and-frequency-rules)
- [Upgrade Flow Optimization](#upgrade-flow-optimization)
- [Dark Pattern Avoidance](#dark-pattern-avoidance)
- [Platform-Specific Considerations](#platform-specific-considerations)
- [Metrics and Benchmarks](#metrics-and-benchmarks)
- [A/B Test Framework](#ab-test-framework)
- [Output Artifacts](#output-artifacts)
- [Related Skills](#related-skills)

---

## Clarify First

Before designing the paywall, confirm these inputs. If any is unknown or vague, ASK — do not assume:

- [ ] **Upgrade model** — freemium-to-paid, trial-to-paid, or tier upgrade (determines the paywall type and trigger architecture)
- [ ] **Free vs paid boundary** — what is gated (defines the value gap the paywall communicates)
- [ ] **Aha moment** — so triggers fire only after value is experienced (the value-first principle)
- [ ] **Platform** — web, iOS, or Android (IAP rules and commissions constrain web vs app flows)

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the deliverable.

## Initial Assessment

### Required Context

| Question | Why It Matters |
|----------|---------------|
| What is the upgrade model? (freemium to paid, trial to paid, tier upgrade) | Determines the paywall type |
| What is free vs paid? | Defines the value gap to communicate |
| What triggers upgrade prompts today? | Identifies current trigger points |
| What is the current free-to-paid conversion rate? | Baseline for improvement |
| What is the aha moment for users? | Determines when the paywall should appear |
| What pricing model? (per seat, usage, flat) | Affects paywall messaging |
| Mobile app, web app, or both? | Platform-specific requirements |

---

## The Value-First Principle

The single most important rule in paywall design: **The user must have experienced real value before seeing an upgrade prompt.**

### Value-First Checklist

- [ ] User has completed the activation event (aha moment reached)
- [ ] User has used the product at least 2-3 times
- [ ] User has created or stored data they would lose
- [ ] The upgrade feels like a natural next step, not a trap

### When to Show vs When NOT to Show

| Show | Do Not Show |
|------|------------|
| After aha moment is reached | During onboarding |
| When user hits a genuine limit | On first login |
| When user clicks a paid feature | When user is in the middle of a task |
| After milestone completion | Immediately after a frustrating experience |
| On session start (gentle reminder) | After every action |

---

## Paywall Trigger Architecture

### Trigger Types

| Trigger | When It Fires | Best For |
|---------|--------------|----------|
| Feature gate | User clicks a locked feature | Feature-differentiated tiers |
| Usage limit | User reaches a quota | Usage-based pricing |
| Trial expiration | Trial period ending | Time-limited trial models |
| Time-based | After N days of active use | Freemium nurture |
| Milestone-based | After user achieves X | Upsell at success moments |
| Team-based | When team grows past free seat limit | Per-seat models |

### Trigger Priority Map

| User State | Primary Trigger | Timing |
|-----------|----------------|--------|
| Activated, under limits | Feature gate (when they try paid feature) | On click |
| Approaching limit | Soft warning (80% of limit) | Proactive |
| Hit limit | Usage limit paywall | On action that exceeds limit |
| Trial day 7 of 14 | Trial ending reminder | Session start |
| Trial day 13 of 14 | Urgent trial expiration | Session start + email |
| Trial day 14 | Trial expired | On login |
| Active for 30+ days, free | Value-based upgrade prompt | Session start, once per week |

---

## Paywall Screen Design

### Screen Anatomy

```
┌─────────────────────────────────────┐
│ [X Close / "Not now"]               │  Escape hatch (always visible)
│                                     │
│ HEADLINE: Value-focused             │  "Unlock [feature] to [benefit]"
│                                     │
│ [Feature preview / screenshot]      │  Show what they are missing
│                                     │
│ KEY BENEFITS:                       │
│ - Benefit 1                        │
│ - Benefit 2                        │
│ - Benefit 3                        │
│                                     │
│ PRICE: $X/month                    │  Clear, simple pricing
│ (or plan comparison)               │
│                                     │
│ [UPGRADE CTA - Primary]           │  "Start Pro Plan"
│ [Maybe Later - Secondary]          │  Clear secondary action
│                                     │
│ "Join 5,000+ teams on Pro"        │  Social proof
└─────────────────────────────────────┘
```

### Copy Patterns by Trigg

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/borghei/Claude-Skills
git -C Claude-Skills checkout 6e3fcbdbb5cf

Works in

1. 2026-10-19
   !CAUTION B 89 / 100

   first audit · source 6e3fcbdbb5cf

Questions about Paywall Upgrade Cro

• github.com/borghei/Claude-Skills/tree/main/business-growth/paywa — the audited source at commit 6e3fcbdbb5cf and every finding aboveObserved · 19 Oct 2026

Spotted something wrong? Report a correction · Methodology