/app-clip

name: app-clip
description: Generates App Clip targets with invocation URL handling, lightweight experiences, and full app upgrade prompts. Use when user wants NFC/QR/Safari banner invocation, instant app experiences, or App Clip Card setup.
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

App Clip Generator

Generate production App Clip infrastructure — a lightweight version of your app invoked from NFC tags, QR codes, Safari banners, or Messages. Includes App Clip target setup, invocation URL handling, experience routing, location confirmation, and full app upgrade flow.

When This Skill Activates

Use this skill when the user:

• Asks to "add an app clip" or "create an app clip target"
• Mentions "instant app" or "lightweight app experience"
• Wants to set up "App Clip Card" metadata
• Mentions "NFC tag" invocation or "QR code" launching an app
• Asks about "app clip invocation" or "invocation URL handling"
• Wants a "lightweight app experience" for a physical location

Pre-Generation Checks

1. Project Context Detection

• [ ] Check deployment target (iOS 14+ required for App Clips, iOS 16+ recommended)
• [ ] Check Swift version (requires Swift 5.9+)
• [ ] Check for @Observable support (iOS 17+ / macOS 14+)
• [ ] Identify Xcode project structure (.xcodeproj or .xcworkspace)

2. Conflict Detection

Search for existing App Clip targets:

Glob: **/*AppClip*/*.swift, **/*Clip*/*.swift
Grep: "NSUserActivityTypeBrowsingWeb" or "AppClipExperience" or "SKOverlay"

If existing App Clip target found:

• Ask if user wants to replace or extend it
• If extending, identify which components are missing

3. Project Structure

Identify where the main app target lives and where to place the App Clip target alongside it.

Configuration Questions

Ask user via AskUserQuestion:

1. **Invocation method?**

• NFC tag only
• QR code only
• Safari banner (Smart App Banner)
• Messages
• All of the above — recommended

2. **Primary experience?**

• Order food (restaurant/cafe)
• Reserve (booking/reservation)
• Check in (event/location)
• Preview content (article/product)

3. **Include location confirmation?**

• Yes — verifies user is physically at the expected location (recommended for physical-world invocations)
• No — skip location verification

4. **Include full app upgrade prompt?**

• Yes — show SKOverlay banner to download full app (recommended)
• No — App Clip only, no upgrade path

Generation Process

Step 1: Read Templates

Read `templates.md` for production Swift code. Read `patterns.md` for constraints, testing, and best practices.

Step 2: Create Core Files

Generate these files: 1. `AppClipApp.swift` — @main App struct handling invocation via `.onContinueUserActivity` 2. `InvocationHandler.swift` — Parses invocation URL, extracts parameters, validates against registered experiences 3. `AppClipExperience.swift` — Protocol and concrete experience implementations

Step 3: Create Location Files (if selected)

4. `LocationConfirmationView.swift` — CLLocationManager-based location verification for physical invocations

Step 4: Create Upgrade Files (if selected)

5. `FullAppUpgradeView.swift` — SKOverlay-based banner prompting full app download 6. `SharedDataManager.swift` — App Group data sharing between App Clip and full app

Step 5: Determine File Location

Check project structure:

• If `Sources/` exists -> `Sources/AppClip/`
• If main app target folder exists -> `AppClip/` at the same level
• Otherwise -> `AppClip/`

Output Format

After generation, provide:

Files Created

AppClip/
├── AppClipApp.swift              # @main entry point with invocation handling
├── InvocationHandler.swift       # URL parsing and parameter extraction
├── AppClipExperience.swift       # Experience protocol and implementations
├── LocationConfirmationView.swift # Location verification (optional)
├── FullAppUpgradeView.swift      # SKOverlay upgrade prompt (optional)
└── SharedDataManager.swift       # App Group data sharing (optional)

Xcode Target Setup Instructions

1. **Add App Clip Target:**

• File > New > Target > App Clip
• Set bundle ID to `{main-app-bundle-id}.Clip`
• Set deployment target to iOS 16.0

2. **Configure Associated Domains:**

• Add `appclips:{your-domain.com}` to both main app and App Clip entitlements

3. **Set Up App Group:**

• Add `group.{your-bundle-id}` to both targets for shared data

4. **Apple-App-Site-Association (AASA) file:**

• Host at `https://{your-domain.com}/.well-known/apple-app-site-association`

Integration

**Handle invocation in the App Clip:**

@main
struct MyAppClip: App {
    @State private var handler = InvocationHandler()

    var body: some Scene {
        WindowGroup {
            ContentView(experience: handler.currentExperience)
                .onContinueUserActivity(
                    NSUserActivityTypeBrowsingWeb
                ) { activity in
                    handler.handle(activity)
                }
        }
    }
}

**Route to the correct experience:**

struct ContentView: View {
    let experience: (any AppClipExperience)?

    var body: some View {
        if let experience {
            AnyView(experience.makeView())
        } else {
            DefaultExperienceView()
        }
    }
}

**Share data with the full app:**

// In App Clip — save order before user upgrades
SharedDataManager.shared.save(order, forKey: "pendingOrder")

// In Full App — restore after install
if let order: Order = SharedDataManager.shared.load(forKey: "pendingOrder") {
    showOrder(order)
}

**Prompt full app download:**

FullAppUpgradeView(
    appStoreID: "123456789",
    benefits: [
        "Order history and favorites",
        "Loyalty rewards program",
        "Push notification for order updates"
    ]
)