---
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:**
```swift
@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:**
```swift
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:**
```swift
// 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:**
```swift
FullAppUpgradeView(
    appStoreID: "123456789",
    benefits: [
        "Order history and favorites",
        "Loyalty rewards program",
        "Push notification for order updates"
    ]
)
```

### Testing

```swift
@Test
func invocationHandlerParsesProductURL() {
    let handler = InvocationHandler()
    let url = URL(string: "https://example.com/clip/product/abc123")!

    let experience = handler.parseURL(url)

    #expect(experience != nil)
    #expect(experience?.experienceType == .previewContent)
    #expect(experience?.parameters["productID"] == "abc123")
}

@Test
func invocationHandlerRejectsInvalidURL() {
    let handler = InvocationHandler()
    let url = URL(string: "https://other-domain.com/something")!

    let experience = handler.parseURL(url)

    #expect(experience == nil)
}

@Test
func sharedDataManagerRoundTrips() {
    let manager = SharedDataManager(suiteName: "group.test")
    let order = Order(id: "order-1", items: ["Latte", "Muffin"])

    manager.save(order, forKey: "testOrder")
    let loaded: Order? = manager.load(forKey: "testOrder")

    #expect(loaded?.id == "order-1")
    #expect(loaded?.items.count == 2)
}
```

## Common Patterns

### Handle Invocation URL
Every App Clip starts from a URL. Parse it to determine what experience to show:
```swift
// URL: https://example.com/clip/order?location=store-42
// -> Route to OrderExperience with locationID = "store-42"
```

### Present Experience Immediately
Users expect instant value. Show the relevant experience within 1-2 seconds, no sign-in required.

### Prompt Full App Install
After the user completes the primary task, show an SKOverlay banner with clear benefits of the full app.

## Gotchas

- **10 MB size limit** — App Clip binary must be under 10 MB. Use SF Symbols, avoid large assets, lazy-load images from network.
- **8-hour data retention** — App Clip data is deleted after 8 hours of inactivity. Use App Group to persist data accessible to the full app.
- **Limited frameworks** — No CallKit, no HealthKit, no CareKit. Limited background processing. Check Apple's framework availability list.
- **No background processing** — App Clips cannot run background tasks, background fetch, or silent push notifications.
- **Must work without sign-in** — App Clips should provide value immediately. Defer sign-in until the full app upgrade.
- **App Clip Card metadata** — Configure in App Store Connect: card image (3000x2000 px), title, subtitle, call-to-action button text.
- **Associated Domains required** — Both the main app and App Clip must have the `appclips:` associated domain configured, and the AASA file must be hosted on the domain.
- **Size budgeting** — Regularly check App Clip size during development with `xcodebuild -exportArchive` or the App Thinning Size Report.

## References

- **templates.md** — All production Swift templates for App Clip infrastructure
- **patterns.md** — Constraints, data lifecycle, testing, and best practices
- Related: `generators/deep-linking` — Universal link and deep link handling
- Related: `generators/onboarding-generator` — Onboarding flow for full app upgrade


---
Source attribution: rshankras
Original project: https://github.com/rshankras/claude-code-apple-skills/blob/9ffb83138209057875698dd11c1720c657c47a92/skills/generators/app-clip/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2025 Ravishankar

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: rshankras
Original project: https://github.com/rshankras/claude-code-apple-skills/blob/9ffb83138209057875698dd11c1720c657c47a92/skills/generators/app-clip/SKILL.md
Attribution basis: Source repository record

Fields of work: Design, Development & Engineering, Product Management
Roles: Mobile Developer, Product Manager, UX Designer
Specialties: API, Mobile
Tools: Swift
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 1c0c6484cef6e1c23d709f7cea402a6a83002021c0c6fed4bb639ede1c25699b