/permission-priming

name: permission-priming
description: Generates pre-permission priming screens that explain benefits before showing iOS system permission dialogs. Use when user wants to increase permission grant rates, add pre-permission screens, or explain why the app needs access.
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
last_verified: 2026-07-16
review_by: 2027-06-22
os_version: iOS 27 / macOS 27

Permission Priming Generator

Generate pre-permission priming screens — shown before iOS system permission dialogs to explain WHY the app needs access. Dramatically increases permission grant rates vs. cold-prompting users with the system alert.

When This Skill Activates

Use this skill when the user:

• Asks to "add permission priming" or "pre-permission screen"
• Mentions "explain permissions" or "permission request screen"
• Wants to "ask for camera permission" or "notification permission"
• Asks about "location permission explanation" or "permission grant rate"
• Wants to "prime before requesting access" or "improve opt-in rates"
• Mentions "permission dialog" or "permission flow"

Pre-Generation Checks

1. Project Context Detection

• [ ] Check deployment target (iOS 16+ / macOS 13+)
• [ ] Check for @Observable support (iOS 17+ / macOS 14+)
• [ ] Identify source file locations

2. Existing Permission Code

Search for existing permission handling:

Glob: **/*Permission*.swift, **/*Authorization*.swift
Grep: "requestAuthorization" or "AVCaptureDevice" or "UNUserNotificationCenter" or "CLLocationManager" or "PHPhotoLibrary"

If existing permission code found:

• Ask if user wants to wrap existing calls with priming screens or replace entirely
• If wrapping, integrate priming views upstream of existing request calls

3. Info.plist Usage Description Strings

Search for required usage description keys:

Grep: "NSCameraUsageDescription" or "NSMicrophoneUsageDescription" or "NSLocationWhenInUseUsageDescription" or "NSPhotoLibraryUsageDescription" or "NSContactsUsageDescription" or "NSHealthShareUsageDescription"

If missing keys found for requested permissions:

• Warn user that the app will crash without the corresponding Info.plist entry
• Provide the required key and a suggested description string

Configuration Questions

Ask user via AskUserQuestion:

1. **Which permissions to prime?** (multi-select)

• Push Notifications
• Camera
• Photo Library
• Location (When In Use)
• Location (Always)
• Microphone
• Contacts
• Health (HealthKit)
• App Tracking Transparency (ATT)

2. **Priming style?**

• Full-screen (dedicated view with illustration, title, benefits, CTA) — recommended
• Alert-style (compact alert-like overlay before system prompt)
• Inline (embedded card within existing content)

3. **Include "Not Now" option?**

• Yes (recommended — reduces user frustration, can re-prompt later)
• No (only "Enable" button — more aggressive)

4. **Show benefits illustration?**

• SF Symbol (simple, matches system style)
• Custom illustration area (placeholder for designer asset)
• None (text only)

Generation Process

Step 1: Read Templates

Read `templates.md` for production Swift code.

Step 2: Create Core Files

Generate these files: 1. `PermissionType.swift` — Enum of all permission types with metadata 2. `PermissionStatus.swift` — Unified status enum wrapping platform-specific statuses 3. `PermissionManager.swift` — @Observable class that checks, requests, and opens Settings

Step 3: Create UI Files

4. `PermissionPrimingView.swift` — Pre-permission screen with benefits and CTA 5. `PermissionStatusTracker.swift` — Monitors status changes from Settings

Step 4: Create Modifier Files

6. `PermissionGatedModifier.swift` — ViewModifier that gates content behind permission check

Step 5: Determine File Location

Check project structure:

• If `Sources/` exists -> `Sources/Permissions/`
• If `App/` exists -> `App/Permissions/`
• Otherwise -> `Permissions/`

Output Format

After generation, provide:

Files Created

Permissions/
├── PermissionType.swift            # Permission enum with metadata
├── PermissionStatus.swift          # Unified status wrapper
├── PermissionManager.swift         # Check, request, open Settings
├── PermissionPrimingView.swift     # Pre-permission priming screen
├── PermissionStatusTracker.swift   # Monitor status changes
└── PermissionGatedModifier.swift   # Gate content behind permission

Integration Steps

**Basic priming before system prompt:**

// Show priming screen, then request system permission on tap
PermissionPrimingView(permissionType: .notifications) {
    // User granted — proceed with feature
    startSendingNotifications()
} onDenied: {
    // User denied or tapped "Not Now"
    showLaterPrompt()
}

**Gate a feature behind permission:**

// Camera feature gated behind permission
CameraView()
    .permissionGated(.camera) {
        // Priming screen shown automatically if not yet authorized
    }

**In onboarding flow:**

struct OnboardingPermissionsView: View {
    @State private var permissionManager = PermissionManager()

    var body: some View {
        VStack(spacing: 32) {
            PermissionPrimingView(permissionType: .notifications) {
                // Move to next permission
            } onDenied: {
                // Skip, ask later
            }
        }
    }
}

**Check status and re-prompt after denial:**

struct SettingsView: View {
    @State private var permissionManager = PermissionManager()

    var body: some View {
        Section("Permissions") {
            ForEach(PermissionType.allCases, id: \.self) { type in
                PermissionRow(
                    type: type,
                    status: permissionManager.status(for: type),
                    onRequest: { permissionManager.openSettings() }
                )
            }
        }
    }
}