| name | apple-targets |
| description | Build, configure, and debug native Apple extension and target types (widgets, App Clips, share extensions, watchOS apps, Safari extensions, notification extensions, VPN/network extensions, and 40+ more) in an Expo app using the @bacons/apple-targets config plugin. Use when a user wants to add home screen presence, share sheets, custom keyboards, Siri/App Intents, push notification handling, AutoFill/passkeys, Screen Time controls, or any other Apple app extension to a React Native / Expo project. |
Apple Extension Target Skills Reference
This directory contains comprehensive skill documents for all supported Apple extension and target types. Each skill document provides everything an AI agent needs to understand, implement, and troubleshoot a specific Apple extension type, including:
- Apple documentation links and WWDC session references
- Runtime behavior and lifecycle explanation
- Real-world use cases and implementation patterns
- Production-ready Swift code examples
- Platform availability and version requirements
- Common gotchas and debugging tips
Installing This Skill
Install this skill into your coding agent (Claude Code, Cursor, Codex, etc.) with npx skills:
npx skills add EvanBacon/expo-apple-targets/tree/main/skills/apple-targets
The CLI auto-detects which agents you have installed and copies SKILL.md (plus the supporting reference docs in this directory) into the agent's skills directory (e.g. .claude/skills/ or .agents/skills/). Once installed, the agent loads this guidance automatically whenever you ask it to build an Apple extension or target.
How to Use These Skills
For AI Agents:
-
When a user asks about a specific extension type (e.g., "How do I build a widget?" or "I need to add a share extension"), read the corresponding skill document to get complete implementation guidance.
-
When planning a feature that might require an extension (e.g., "Add home screen presence" → read widget.md), consult the skill document to understand requirements and constraints.
-
When debugging extension issues, refer to the "Gotchas" section of the relevant skill document — these capture common pitfalls from Apple Developer Forums and real-world experience.
-
When uncertain which extension type fits a use case, scan the "Use Cases" sections across related skills to find the best match.
Structure of Each Skill Document:
Every skill document follows the template defined in _template.md:
- Frontmatter: Title, one-line description, minimum OS version
- Apple Documentation: Official reference links
- WWDC History: Session links showing evolution of the feature
- What It Does: Step-by-step runtime behavior
- Use Cases: Real-world scenarios organized by industry/app type
- Key Classes: Table of essential framework types
- Implementation: Production-ready Swift code with inline comments
- Using with @bacons/apple-targets: Setup instructions for this plugin
- Platform Availability: OS version matrix
- Gotchas: Common mistakes, memory limits, and silent failure modes
Skills by Category
User Interface Extensions
| Skill | Extension Type | When to Read |
|---|
| widget.md | widget | User wants home screen widgets, Lock Screen widgets, Live Activities, StandBy mode UI, or Control Center controls (iOS 18+). Timeline-based SwiftUI views. |
| clip.md | clip | User wants instant-launch mini-apps triggered by NFC, QR codes, App Clip Codes, Safari banners, or Messages links. Not an extension—a size-constrained application target. |
| share.md | share | User wants their app in the system share sheet to receive URLs, images, text, or files from other apps. |
| action.md | action | User wants context menu actions in Safari, Photos, or Files that transform content and optionally return modified data. |
| keyboard.md | keyboard | User wants a custom system keyboard with specialized input (emoji pickers, GIF search, language-specific layouts, calculators). |
| photo-editing.md | photo-editing | User wants to add filters, adjustments, or effects to photos/videos directly in the Photos app editing UI. |
| quicklook-preview.md | quicklook-preview | User wants rich previews of custom file types in Quick Look with interactive controls and multiple pages. |
| quicklook-thumbnail.md | quicklook-thumbnail | User wants to generate thumbnail images for custom file types shown in Finder, Files app, and Spotlight. |
Notifications
| Skill | Extension Type | When to Read |
|---|
| notification-service.md | notification-service | User wants to download images, decrypt payloads, or modify push notification content before display. Runs in background with 30-second time limit. |
| notification-content.md | notification-content | User wants custom SwiftUI/UIKit UI for expanded push notifications with interactive controls and rich media. |
Siri & Intents
| Skill | Extension Type | When to Read |
|---|
| intent.md | intent | User wants Siri voice commands for built-in domains (messaging, payments, workouts, media playback, ride booking). Uses legacy SiriKit framework. |
| intent-ui.md | intent-ui | User wants custom UI in the Siri interface when confirming or handling intents. Companion to the intent extension. |
| app-intent.md | app-intent | User wants modern App Intents (iOS 16+) for Shortcuts, Spotlight, Siri, Focus Filters, and Control Center widgets. Replaces custom .intentdefinition files. |
Networking & VPN
| Skill | Extension Type | When to Read |
|---|
| network-packet-tunnel.md | network-packet-tunnel | User wants to build a VPN client that tunnels all device traffic through a custom protocol. Classic and modern Personal VPN. |
| network-app-proxy.md | network-app-proxy | User wants app-level network filtering (per-app VPN) where specific apps route traffic through a custom proxy. Requires MDM or supervised devices. |
| network-dns-proxy.md | network-dns-proxy | User wants to intercept and respond to DNS queries system-wide, enabling DNS filtering, logging, or custom resolution. |
| network-filter-data.md | network-filter-data | User wants deep packet inspection for content filtering (parental controls, enterprise security). Requires special Apple entitlement. |
File Management
| Skill | Extension Type | When to Read |
|---|
| file-provider.md | file-provider | User wants to expose cloud storage or remote file systems in the Files app with on-demand download, search, and sync. |
| file-provider-ui.md | file-provider-ui | User wants custom UI for file actions (sharing, permissions) in the document picker. Companion to File Provider extension. |
Communication & Telephony
| Skill | Extension Type | When to Read |
|---|
| message-filter.md | message-filter | User wants to filter incoming SMS/MMS messages to classify spam, transactions, or promotions into separate tabs. |
| call-directory.md | call-directory | User wants to block phone numbers or provide caller ID labels for incoming calls. Updates a system-managed SQLite database. |
| unwanted-communication.md | unwanted-communication | User wants a UI for users to report unwanted calls, messages, or FaceTime attempts to a reporting service. Requires special entitlement. |
Content & Media
| Skill | Extension Type | When to Read |
|---|
| broadcast-upload.md | broadcast-upload | User wants to stream ReplayKit screen recordings to a live streaming service (Twitch, YouTube Live). Receives video/audio buffers in real time. |
| broadcast-setup-ui.md | broadcast-setup-ui | User wants custom UI for configuring a live broadcast (selecting stream key, privacy settings). Companion to broadcast upload extension. |
| safari.md | safari | User wants Safari Web Extensions (Manifest V3) with content scripts, background pages, and native messaging to the containing app. |
| content-blocker.md | content-blocker | User wants rule-based ad blocking, tracker blocking, or content hiding in Safari using JSON declarative rules. No JavaScript execution. |
Education & Screen Time
| Skill | Extension Type | When to Read |
|---|
| classkit-context.md | classkit-context | User wants to report student progress in educational apps to Apple's Schoolwork app via ClassKit framework. |
| device-activity-monitor.md | device-activity-monitor | User wants to monitor app/website usage and trigger actions when Screen Time limits are reached. Parental control and focus apps. |
| shield-action.md | shield-action | User wants custom UI when a user attempts to bypass a Screen Time shield (blocked app/website). Handle or deny the request. |
| shield-config.md | shield-config | User wants custom shield UI (blocking screen) shown when apps or websites are restricted by Screen Time rules. |
Authentication & Security
| Skill | Extension Type | When to Read |
|---|
| authentication-services.md | authentication-services | User wants AutoFill for passwords and passkeys in Safari and apps. Modern replacement for credentials-provider. Supports passkey creation/assertion (WebAuthn). |
| credentials-provider.md | credentials-provider | User wants legacy password AutoFill (iOS 12+). For new projects, use authentication-services instead, which supports both passwords and passkeys. |
| smart-card.md | smart-card | User wants to authenticate with smart cards or hardware tokens (YubiKey, PIV cards) via the CryptoTokenKit framework. Enterprise use. |
| account-auth.md | account-auth | User wants to modify authentication requests for Kerberos or other enterprise single sign-on (SSO) protocols. Requires special entitlement. |
Location & Background Services
| Skill | Extension Type | When to Read |
|---|
| location-push.md | location-push | User wants silent push notifications that wake the app for high-accuracy location updates. Used for fleet tracking, delivery apps, and location-based alerts. |
| bg-download.md | bg-download | User wants on-demand resources or large asset downloads managed by the system's background asset downloader. Used for games and media apps. |
Smart Home & Matter
| Skill | Extension Type | When to Read |
|---|
| matter.md | matter | User wants to add Matter smart home device support for device commissioning via Home app. Requires MFi enrollment and Matter certification. |
Printing
| Skill | Extension Type | When to Read |
|---|
| print-service.md | print-service | User wants to discover and print to network printers without AirPrint, or provide custom print rendering for specialized printers. |
Search & Indexing
| Skill | Extension Type | When to Read |
|---|
| spotlight.md | spotlight | User wants to index app content in Spotlight, provide rich search results, and handle taps from Spotlight search. Uses Core Spotlight and NSUserActivity. |
| spotlight-delegate.md | spotlight-delegate | User wants a background extension for large-scale Spotlight indexing that runs periodically on a system-managed schedule. macOS only (not iOS). |
Collaboration & Conferencing
| Skill | Extension Type | When to Read |
|---|
| virtual-conference.md | virtual-conference | User wants to integrate a video conferencing app with the system call UI and CallKit, enabling Handoff, picture-in-picture, and system call controls. |
Apple Watch
| Skill | Extension Type | When to Read |
|---|
| watch.md | watch | User wants a standalone watchOS app with complications, workout sessions, HealthKit integration, and Watch Connectivity for iPhone sync. Not an extension—a full application target. |
Target Types vs. Extensions
Application Targets (not extensions):
- App Clip (
clip) — uses product type com.apple.product-type.application.on-demand-install-capable
- watchOS App (
watch) — uses product type com.apple.product-type.application
These are full applications with their own Info.plist, app icons, and lifecycle. They do not use NSExtensionPointIdentifier.
All other types are app extensions that use product type com.apple.product-type.app-extension and declare an extension point identifier in their Info.plist.
Quick Reference: Common Use Cases
Creating a New Extension with @bacons/apple-targets
Every skill document includes a "Using with @bacons/apple-targets" section with the three-step setup:
bunx create-target <type>
{
"expo": {
"plugins": [["@bacons/apple-targets"]]
}
}
npx expo prebuild --clean
The <type> parameter corresponds to the extension type slug shown in each skill document's title (e.g., widget, share, clip, notification-service).
When to Run Prebuild
Because target source files live outside the /ios directory and are linked into the Xcode project (not copied), Swift code changes are automatically synchronized. You don't need to re-run prebuild when editing code.
This architecture allows you to iterate on extension code without constantly regenerating the entire Xcode project, speeding up development and preserving manual project customizations.
Entitlements & Capabilities Guides
The entitlements/ directory contains guides for iOS entitlements and capabilities that apply across multiple extension types:
| Guide | When to Read |
|---|
| entitlements/app-groups.md | User needs to share data between the main app and extensions (widgets, share, notifications, App Clips). Covers naming conventions, UserDefaults suite, shared containers, Keychain access groups, and automatic EAS provisioning. |
Common questions answered by entitlements guides:
- "How do I share data between my app and widget?" → Read
app-groups.md
- "My extension can't access UserDefaults from the main app" → Read
app-groups.md
- "How does EAS handle App Groups code signing?" → Read
app-groups.md
Template for New Skills
If you need to write a new skill document, use _template.md as the starting point. It defines the required frontmatter, section structure, code example format, and quality checklist.
Additional Resources
