/tipkit-generator

name: tipkit-generator
description: Generate TipKit infrastructure with inline/popover tips, rules, display frequency, and testing utilities. Use when adding contextual tips or feature discovery to an iOS/macOS app.
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

TipKit Generator

Generate a complete TipKit setup for contextual tips and feature discovery, including tip definitions, rules, display frequency, inline and popover presentation, and testing utilities.

When This Skill Activates

Use this skill when the user:

• Asks to "add tips" or "add TipKit"
• Mentions "contextual tips" or "feature discovery"
• Wants "popover tips" or "inline tips"
• Asks about "coach marks" or "user education"
• Mentions "onboarding hints" or "tip prompts"
• Wants to "highlight new features" or "guide users"

Pre-Generation Checks

1. Project Context Detection

• [ ] Check deployment target (TipKit requires iOS 17+ / macOS 14+)
• [ ] Identify if SwiftUI or UIKit project
• [ ] Find App entry point location for Tips.configure()
• [ ] Check for existing TipKit implementations

2. Conflict Detection

Search for existing TipKit usage:

Glob: **/*Tip*.swift
Grep: "import TipKit" or "Tips.configure"

If found, ask user:

• Extend existing tip infrastructure?
• Replace existing tips?

Configuration Questions

Ask user via AskUserQuestion:

1. **What features need tips?**

• List the features or UI elements that should have tips
• Example: "search bar, filter button, swipe-to-delete gesture"

2. **Tip presentation style?** (per tip or general preference)

• Inline (TipView embedded in layout)
• Popover (attached to a control)
• Both

3. **Rule types needed?**

• Parameter-based (show after user meets condition, e.g., has viewed a screen 3 times)
• Event-based (show after user performs an action N times)
• Both

4. **Display frequency?**

• Immediate (tips show as soon as eligible)
• Hourly
• Daily
• Weekly
• Monthly

5. **Tip ordering?**

• Independent (tips show whenever eligible)
• Ordered (use TipGroup to show tips in sequence)

Generation Process

Step 1: Read Templates

Read the templates file for code patterns:

Read("skills/generators/tipkit-generator/templates.md")

Step 2: Create Core Files

Generate these files based on configuration: 1. `Tips/` directory with one file per tip (e.g., `SearchTip.swift`, `FilterTip.swift`) 2. `Tips/TipEvents.swift` - Centralized event definitions 3. `Tips/TipsConfiguration.swift` - Tips.configure() setup and testing utilities

Step 3: Determine File Location

Check project structure:

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

Step 4: Integrate Tips

• Add `Tips.configure()` call in App entry point
• Add `TipView` or `.popoverTip()` at the appropriate view locations
• Wire up event donation at action sites
• Wire up tip invalidation where appropriate

Output Format

After generation, provide:

Files Created

Sources/Tips/
├── SearchTip.swift            # Tip with rules and options
├── FilterTip.swift            # Another tip definition
├── TipEvents.swift            # Centralized event definitions
└── TipsConfiguration.swift    # Tips.configure() + testing helpers

Integration Steps

**App Entry Point (Required):**

import TipKit

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .task {
                    try? Tips.configure([
                        .displayFrequency(.daily),
                        .datastoreLocation(.applicationDefault)
                    ])
                }
        }
    }
}

**Inline Tip:**

import TipKit

struct SearchView: View {
    let searchTip = SearchTip()

    var body: some View {
        VStack {
            TipView(searchTip)
            SearchBar()
        }
    }
}

**Popover Tip:**

import TipKit

struct ToolbarView: View {
    let filterTip = FilterTip()

    var body: some View {
        Button("Filter", systemImage: "line.3.horizontal.decrease.circle") {
            // action
        }
        .popoverTip(filterTip)
    }
}

**Event Donation (at action site):**

Button("Search") {
    performSearch()
    SearchTip.searchPerformed.donate()
}

**Tip Invalidation (when tip is no longer relevant):**

func onFeatureUsed() {
    // User discovered the feature, invalidate the tip
    searchTip.invalidate(reason: .actionPerformed)
}

Testing Instructions

1. **Reset DataStore between runs:**

   // Add to a debug menu or call in preview
   try? Tips.resetDatastore()

2. **Show all tips for testing:**

   // Ignores rules and frequency -- shows everything
   Tips.showAllTipsForTesting()

3. **Show specific tips for testing:**

   Tips.showTipsForTesting([SearchTip.self])

4. **Test scenarios:**

• Launch app fresh -- eligible tips should appear per display frequency
• Perform actions that donate events -- event-based tips should appear when thresholds met
• Tap tip close button -- tip should not reappear
• Invalidate tip programmatically -- tip should dismiss and not reappear

Common Gotchas

1. **Forgetting Tips.configure()** -- Tips will never appear if you do not call `Tips.configure()` before any tip is displayed. This must happen early, typically in the App `body` or `.task`.

2. **Rules not evaluating** -- Parameter-based rules require you to set the parameter value explicitly. If you define `@Parameter static var hasSeenFeature = false` but never set it to `true`, the rule never passes.

3. **DataStore conflicts in tests** -- If you run unit tests and the app simultaneously, they may share the same DataStore. Use `.datastoreLocation(.url(...))` to isolate them.

4. **Disp