Skill

Review

Audit score 70

app-clips

dpearson2699/swift-ios-skills

Build lightweight iOS App Clips with invocation routing, experience configuration, and full-app handoff.

What is app-clips?

App Clips are separate Xcode targets that create instantly-available, focused versions of your iOS app for in-the-moment tasks or demos. Use this skill when setting up App Clip targets, configuring invocation URLs and App Clip Codes, routing NSUserActivity, managing data handoff, or handling notifications and location confirmation.

Create and configure App Clip targets with correct bundle IDs and entitlements
Route invocations from URLs, QR codes, NFC, App Clip Codes, Safari banners, Maps, and Messages
Handle NSUserActivity routing for both cold launch and continuation in SwiftUI and UIKit
Manage data, credential, and keychain handoff between App Clip and full app via App Groups
Configure ephemeral notifications, location confirmation, and SKOverlay promotion
Validate size limits, capability constraints, and App Store Connect experience setup

How to install app-clips

npx skills add https://github.com/dpearson2699/swift-ios-skills --skill app-clips

Prerequisites

Xcode with App Clip target template support
iOS 14.0 or later deployment target
Apple Developer account with App Clip capability enabled
Associated Domains entitlement for custom URL schemes

Claude Code

Cursor

Windsurf

Cline

How to use app-clips

1.Create a new App Clip target via File → New → Target → App Clip in Xcode
2.Verify the App Clip bundle ID is prefixed by the full app's bundle ID (e.g., com.example.MyApp.Clip)
3.Check and correct the three raw entitlement keys: com.apple.developer.on-demand-install-capable, com.apple.developer.parent-application-identifiers, and com.apple.developer.associated-appclip-app-identifiers
4.Implement invocation routing using NSUserActivityTypeBrowsingWeb in SwiftUI (.onContinueUserActivity) or UIKit (scene(_:willConnectTo:options:) and scene(_:continue:))
5.Configure the default App Clip experience in App Store Connect and test with Local Experiences
6.Set up Associated Domains and AASA file for custom URL routing if needed
7.Implement data handoff via App Groups for non-secret state and keychain for credentials
8.Test size limits, capabilities, and full-app migration before submission

Use cases

Good for

Launch an App Clip from a QR code at a physical location and hand off to the full app after installation
Route a user from a Safari Smart App Banner to a specific experience in the App Clip
Share authentication state and user data between an App Clip and its full app using App Groups and keychain
Confirm a user's physical location before allowing access to location-restricted App Clip features
Promote the full app to App Clip users via SKOverlay or notification relaunch

Who it's for

iOS app developers building App Clip experiences
Teams implementing lightweight, on-demand app functionality
Developers integrating App Clips with Maps, Messages, or NFC invocation
QA and product teams reviewing App Clip feasibility and handoff flows

app-clips FAQ

What is the minimum bundle ID format for an App Clip?

The App Clip bundle ID must be prefixed by the full app's bundle ID, e.g., com.example.MyApp.Clip for a full app with ID com.example.MyApp.

How do I route a user from an invocation URL to the correct experience in my App Clip?

Read the invocation URL in NSUserActivity (NSUserActivityTypeBrowsingWeb) and parse it in your routing logic. Keep the router shared with the full app because the full app receives future invocations after installation. Use App Store Connect experiences or Local Experiences for testing.

Can I share data between my App Clip and full app?

Yes. Use App Groups for non-secret handoff state, keychain for credentials and Sign in with Apple, and SKOverlay or ephemeral notifications to promote the full app. App Group storage is not a trust boundary.

What are the App Clip size limits?

Size limits vary by invocation method and iOS version. Refer to the Size, capabilities, and promotion reference for the applicable tier and measurement instructions.

What should I avoid in an App Clip design?

Avoid marketing-only clips, ad-heavy flows, splash screens, launch-blocking downloads, repeated install prompts, and web-view-heavy experiences. App Clips should let users complete a focused task or full demo without installing the app.

Full instructions (SKILL.md)

Source of truth, from dpearson2699/swift-ios-skills.

name: app-clips description: "Build iOS App Clips with invocation URLs, App Clip Codes, NFC, QR codes, Safari banners, Maps, Messages, target setup, App Store Connect experiences, size/capability constraints, NSUserActivity routing, SKOverlay promotion, App Group/keychain handoff, ephemeral notifications, location confirmation, and full-app migration. Use when creating App Clips or wiring App Clip invocation, experience configuration, or full-app handoff."

App Clips

Build lightweight, instantly available versions of an iOS app for focused in-the-moment experiences or demos.

App Clip Target Setup
Invocation and Experience Routing
Size and Capability Decisions
Data, Notifications, and Location
Common Mistakes
Review Checklist
References

App Clip Target Setup

An App Clip is a separate target in the same Xcode project as your full app:

File → New → Target → App Clip — Xcode creates the App Clip target, adds the Embed App Clip build phase to the full app target, and wires the association entitlements.
The App Clip bundle ID must be prefixed by the full app's bundle ID: com.example.MyApp.Clip.
Verify raw entitlement keys when diagnosing archive, signing, or App Store Connect failures:
- App Clip target: com.apple.developer.on-demand-install-capable
- App Clip target parent app link: com.apple.developer.parent-application-identifiers
- Full app target associated App Clip link: com.apple.developer.associated-appclip-app-identifiers

Use Swift packages or shared source files for code needed by both targets. Add App Clip-specific compile branches with the APPCLIP active compilation condition, and avoid linking full-app-only frameworks into the App Clip target.

Validation checkpoint: Archive both targets and inspect their archived entitlements. If signing or validation fails, correct the three raw key/target assignments above and rearchive until both pass.

Invocation and Experience Routing

Read references/routing-and-experiences.md when implementing invocation URL routing, App Store Connect experiences, Local Experiences, Safari Smart App Banners, QR/NFC/App Clip Codes, AASA, or associated domains.

App Clips receive NSUserActivityTypeBrowsingWeb activities. Keep the invocation router shared with the full app because, after installation, the full app replaces the App Clip and receives future invocations.

SwiftUI: use .onContinueUserActivity(NSUserActivityTypeBrowsingWeb).
UIKit cold launch: inspect connectionOptions.userActivities in scene(_:willConnectTo:options:).
UIKit continuation: handle the actual NSUserActivity in scene(_:continue:).
scene(_:willContinueUserActivityWithType:) is only advance notice and does not provide the URL.

Configure the required default App Clip experience in App Store Connect. Use advanced experiences for Maps integration, location association, production App Clip Codes, per-location cards, and precise physical-place routing; demo App Clip Codes can use the short demo App Clip link.

For custom URLs, add appclips:example.com to Associated Domains on both the full app and App Clip targets, and host an AASA file with the App Clip app identifier. For Safari banners, use app-id, app-clip-bundle-id, and optional app-clip-display=card; do not rely on app-argument for App Clip launches.

Validation checkpoint: Exercise each URL with _XCAppClipURL and a Local Experience, fix routing/AASA/experience mismatches, and repeat until the App Clip and installed full app reach the same destination.

Size and Capability Decisions

Use Size, capabilities, and promotion as the authoritative checklist for feasibility reviews, size tiers and measurement, Background Assets, CloudKit, Live Activities, unsupported features, and full-app promotion. Load it whenever any of those topics is in scope.

Keep product reviews at the boundary level: state the size basis, invocation and download fit, capability exclusions, and handoff destination. Add implementation APIs only when the user asks for implementation.

Data, Notifications, and Location

Read references/data-handoff-notifications-location.md when implementing App Group/full-app migration, keychain or Sign in with Apple handoff, ephemeral notifications, notification relaunch routing, or physical location confirmation.

Treat App Group storage as non-secret handoff state, not a trust boundary. The reference owns the iOS 15.4+ one-way keychain rule, Sign in with Apple verification, ephemeral-notification permission and relaunch routing, and physical-location confirmation—including their required raw keys and targets.

Common Mistakes

Exceeding the applicable App Clip size limit

Choose and measure the applicable limit using Size Limits.

Designing a marketing-only or web-view-heavy App Clip

App Clips should let people complete a focused task or full demo without installing the app. Avoid marketing-only clips, ad-heavy flows, splash screens, launch-blocking downloads, repeated install prompts, and web-view-heavy experiences that would work better as a website.

Review Checklist

Do not ship until every applicable gate passes; fix failures and rerun the same gate.

Target IDs, all three raw entitlement keys, and shared-code boundaries are correct.
Invocation works for SwiftUI/UIKit cold launch and continuation, then hands off to the full app.
Associated domains, AASA, App Store Connect experiences, and local invocation tests pass.
Size, capability, UX, Live Activity, and promotion decisions pass the feasibility review.
Data, credential, notification, and location flows pass the detailed handoff checks.