Agent skill

whats-new

Generates a "What's New" / changelog screen shown after app updates with version tracking, feature highlights, and one-time display per version. Use when user wants release notes UI, update notifications, or feature announcements.

View SKILL.md on GitHub Repository
Stars 127
Forks 10

Install this agent skill to your Project

npx add-skill https://github.com/rshankras/claude-code-apple-skills/tree/main/skills/generators/whats-new

SKILL.md

What's New Generator

Generate a complete "What's New" screen that displays after app updates — highlights new features, changes, and improvements with version tracking to ensure it only shows once per update.

When This Skill Activates

Use this skill when the user:

  • Asks to "add a what's new screen" or "show what's new"
  • Mentions "changelog" or "changelog UI"
  • Wants an "app update screen" or "update notification"
  • Asks about "new features screen" or "feature announcements"
  • Mentions "release notes UI" or "release notes screen"
  • Wants a "version update notification" or "post-update screen"

Pre-Generation Checks

1. Project Context Detection

  • Check deployment target (iOS 16+ / macOS 13+ minimum; iOS 17+ / macOS 14+ for @Observable)
  • Check Swift version (requires Swift 5.9+)
  • Identify source file locations and project structure
  • Determine how app version is accessed (Bundle.main.infoDictionary, custom build config, etc.)

2. Conflict Detection

Search for existing what's new or changelog implementations:

Glob: **/*WhatsNew*.swift, **/*Changelog*.swift, **/*ReleaseNotes*.swift, **/*VersionTracker*.swift
Grep: "WhatsNew" or "whatsNew" or "lastShownVersion" or "changelog"

If found, ask user:

  • Replace existing implementation?
  • Keep existing, integrate alongside?

3. Version Access Pattern

Detect how the app reads its version:

Grep: "CFBundleShortVersionString" or "Bundle.main.infoDictionary" or "appVersion"

Use whichever pattern the project already employs. If none found, default to Bundle.main.infoDictionary?["CFBundleShortVersionString"].

Configuration Questions

Ask user via AskUserQuestion:

  1. Presentation style?

    • Sheet (recommended — .sheet(item:) auto-dismiss)
    • Full-screen cover (.fullScreenCover)
    • Inline (embedded in a view hierarchy)

  2. Content source?

    • Hardcoded in Swift (simplest, no network needed)
    • Local JSON file bundled in app
    • Remote JSON endpoint (fetched on launch)

  3. Dismiss behavior?

    • "Continue" button (explicit acknowledgment)
    • Swipe to dismiss (sheet default)
    • Both (button + swipe)

  4. Page indicators?

    • Dot indicators (TabView page style)
    • Page count label ("1 of 3")
    • None (single scrollable view)

Generation Process

Step 1: Read Templates

Read templates.md for production Swift code.

Step 2: Create Core Files

Generate these files:

  1. WhatsNewFeature.swift — Model for a single feature (title, description, SF Symbol, tint color)
  2. WhatsNewRelease.swift — Groups features by version string with date
  3. VersionTracker.swift — Tracks last-shown version in UserDefaults, compares against current bundle version
  4. WhatsNewProvider.swift — Protocol + local implementation (optional remote)

Step 3: Create UI Files

  1. WhatsNewView.swift — Paged view with TabView(.page) showing features
  2. WhatsNewSheet.swift — Wrapper that auto-presents via .sheet(item:) when new version detected

Step 4: Create Optional Files

Based on configuration:

  • RemoteWhatsNewProvider.swift — If remote content source selected
  • WhatsNewJSON.swift — If local JSON source selected

Step 5: Determine File Location

Check project structure:

  • If Sources/ exists -> Sources/WhatsNew/
  • If App/ exists -> App/WhatsNew/
  • Otherwise -> WhatsNew/

Output Format

After generation, provide:

Files Created

WhatsNew/
├── WhatsNewFeature.swift       # Single feature model
├── WhatsNewRelease.swift       # Version-grouped features
├── VersionTracker.swift        # Version persistence & comparison
├── WhatsNewProvider.swift      # Content provider protocol + local impl
├── WhatsNewView.swift          # Paged feature display
├── WhatsNewSheet.swift         # Auto-presenting sheet wrapper
└── RemoteWhatsNewProvider.swift # Remote content (optional)

Integration Steps

Option 1: View Modifier Style (Recommended)

swift
@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .whatsNewSheet()  // Automatically shows after updates
        }
    }
}

Option 2: Manual Control in Root View

swift
@main
struct MyApp: App {
    @State private var whatsNewRelease: WhatsNewRelease?

    var body: some Scene {
        WindowGroup {
            ContentView()
                .sheet(item: $whatsNewRelease) { release in
                    WhatsNewView(release: release)
                }
                .task {
                    let tracker = VersionTracker()
                    if tracker.shouldShowWhatsNew() {
                        whatsNewRelease = WhatsNewProvider.local.latestRelease()
                    }
                }
        }
    }
}

Option 3: Inline Embedding

swift
struct HomeView: View {
    @State private var tracker = VersionTracker()

    var body: some View {
        VStack {
            if tracker.shouldShowWhatsNew(),
               let release = WhatsNewProvider.local.latestRelease() {
                WhatsNewView(release: release) {
                    tracker.markVersionAsShown()
                }
            }
            // Rest of home content...
        }
    }
}

Adding New Releases

swift
// In LocalWhatsNewProvider.swift — add a new entry per release
static let releases: [WhatsNewRelease] = [
    WhatsNewRelease(
        version: "2.1.0",
        date: Date(timeIntervalSince1970: 1_700_000_000),
        features: [
            WhatsNewFeature(
                title: "Dark Mode Support",
                description: "Full dark mode across all screens.",
                systemImage: "moon.fill",
                tintColor: .indigo
            ),
            WhatsNewFeature(
                title: "Faster Search",
                description: "Search results now appear instantly.",
                systemImage: "magnifyingglass",
                tintColor: .orange
            ),
        ]
    ),
    // Previous releases...
]

Testing

swift
@Test
func showsWhatsNewForNewVersion() {
    let defaults = UserDefaults(suiteName: "TestWhatsNew")!
    defaults.removePersistentDomain(forName: "TestWhatsNew")

    let tracker = VersionTracker(
        defaults: defaults,
        currentVersion: "2.0.0"
    )

    // First launch — no previous version stored
    #expect(tracker.shouldShowWhatsNew() == true)

    tracker.markVersionAsShown()
    #expect(tracker.shouldShowWhatsNew() == false)
}

@Test
func skipsWhatsNewWhenVersionUnchanged() {
    let defaults = UserDefaults(suiteName: "TestWhatsNew2")!
    defaults.removePersistentDomain(forName: "TestWhatsNew2")

    let tracker = VersionTracker(
        defaults: defaults,
        currentVersion: "1.5.0"
    )
    tracker.markVersionAsShown()

    // Same version — should not show
    let tracker2 = VersionTracker(
        defaults: defaults,
        currentVersion: "1.5.0"
    )
    #expect(tracker2.shouldShowWhatsNew() == false)
}

@Test
func showsWhatsNewAfterUpdate() {
    let defaults = UserDefaults(suiteName: "TestWhatsNew3")!
    defaults.removePersistentDomain(forName: "TestWhatsNew3")

    let tracker = VersionTracker(
        defaults: defaults,
        currentVersion: "1.0.0"
    )
    tracker.markVersionAsShown()

    // Simulate update
    let trackerAfterUpdate = VersionTracker(
        defaults: defaults,
        currentVersion: "2.0.0"
    )
    #expect(trackerAfterUpdate.shouldShowWhatsNew() == true)
}

Common Patterns

Define Features Per Version

Group features by release version so older users who skipped updates still see relevant changes:

swift
// Show features for all versions newer than lastShownVersion
func featuresSinceLastShown() -> [WhatsNewFeature] {
    let lastShown = tracker.lastShownVersion ?? "0.0.0"
    return releases
        .filter { $0.version.compare(lastShown, options: .numeric) == .orderedDescending }
        .flatMap(\.features)
}

Conditional Display

Only show if there are actually features to display for the current version:

swift
if let release = provider.release(for: currentVersion),
   tracker.shouldShowWhatsNew() {
    // Present What's New
}

Remote Content Loading

Fetch features from a server to update without app releases:

swift
let provider = RemoteWhatsNewProvider(
    endpoint: URL(string: "https://api.example.com/whats-new")!,
    fallback: LocalWhatsNewProvider()  // Offline fallback
)
let release = try await provider.latestRelease()

Gotchas

CFBundleShortVersionString vs CFBundleVersion

  • CFBundleShortVersionString = marketing version (e.g., "2.1.0") — use this for What's New
  • CFBundleVersion = build number (e.g., "47") — changes every build, NOT suitable for What's New tracking
  • Always compare the marketing version, never the build number

First Install vs Update Detection

  • On first install, lastShownVersion is nil
  • Decide whether first-time users should see What's New (usually NO — show onboarding instead)
  • If lastShownVersion is nil, either skip What's New or set the current version without showing:
swift
func shouldShowWhatsNew() -> Bool {
    guard let lastShown = lastShownVersion else {
        // First install — mark current version, don't show
        markVersionAsShown()
        return false
    }
    return currentVersion.compare(lastShown, options: .numeric) == .orderedDescending
}

TestFlight vs App Store Versions

  • TestFlight builds may have the same marketing version but different build numbers
  • If using TestFlight for beta testing, consider including build number in tracking key for testers
  • For production, always track by marketing version only

Version String Comparison

  • Use .numeric option in String.compare(_:options:) so "2.0.0" > "1.10.0" (not lexicographic)
  • Never compare version strings with < or > operators directly — "9.0" would sort after "10.0" lexicographically

Accessibility

  • Ensure all feature images have accessibility labels
  • Support Dynamic Type in feature descriptions
  • VoiceOver should read features sequentially — use .accessibilityElement(children: .combine) on feature cards

References

  • templates.md — All production Swift templates
  • Related: generators/onboarding-generator — First-launch onboarding (complementary — onboarding for first install, What's New for updates)

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

rshankras/claude-code-apple-skills

legal

Legal document generation and compliance guidance for indie Apple developers. Covers privacy policies, terms of service, EULAs, GDPR/CCPA/DPDP compliance, and Apple App Store legal requirements. Use when user needs legal documents or compliance guidance.

127 10
Explore
rshankras/claude-code-apple-skills

privacy-policy

Generate privacy policies, terms of service, and EULAs for Apple platform apps. Detects data collection patterns, third-party SDKs, and generates region-specific legal documents with Apple Privacy Nutrition Label mapping. Use when user needs legal documents or data collection disclosure for App Store submission.

127 10
Explore
rshankras/claude-code-apple-skills

ios-development

Comprehensive iOS development guidance including Swift best practices, SwiftUI patterns, UI/UX review against HIG, and app planning. Use for iOS code review, best practices, accessibility audits, or planning new iOS apps.

127 10
Explore
rshankras/claude-code-apple-skills

assistive-access

Assistive Access implementation for cognitive accessibility including simplified scenes, navigation icons, runtime detection, and design principles. Use when optimizing apps for Assistive Access mode.

127 10
Explore
rshankras/claude-code-apple-skills

ui-review

Review SwiftUI code for iOS/watchOS Human Interface Guidelines compliance, font usage, Dynamic Type support, and accessibility. Use when user mentions UI review, HIG, accessibility audit, font checks, or wants to verify interface design against Apple standards.

127 10
Explore
rshankras/claude-code-apple-skills

navigation-patterns

SwiftUI navigation architecture patterns including NavigationStack, NavigationSplitView, TabView, programmatic navigation, and custom transitions. Use when reviewing or building navigation, fixing navigation bugs, or architecting app flow.

127 10
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results