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
:
sh
npx skills add EvanBacon/expo-apple-targets/tree/main/skills/apple-targets
The CLI auto-detects which agents you have installed and copies
(plus the supporting reference docs in this directory) into the agent's skills directory (e.g.
or
). 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
), 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
:
- 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 | | 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 | | 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 | | User wants their app in the system share sheet to receive URLs, images, text, or files from other apps. |
| action.md | | User wants context menu actions in Safari, Photos, or Files that transform content and optionally return modified data. |
| keyboard.md | | User wants a custom system keyboard with specialized input (emoji pickers, GIF search, language-specific layouts, calculators). |
| photo-editing.md | | User wants to add filters, adjustments, or effects to photos/videos directly in the Photos app editing UI. |
| quicklook-preview.md | | User wants rich previews of custom file types in Quick Look with interactive controls and multiple pages. |
| quicklook-thumbnail.md | | 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 | | 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 | | 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 | | User wants Siri voice commands for built-in domains (messaging, payments, workouts, media playback, ride booking). Uses legacy SiriKit framework. |
| intent-ui.md | | User wants custom UI in the Siri interface when confirming or handling intents. Companion to the extension. |
| app-intent.md | | User wants modern App Intents (iOS 16+) for Shortcuts, Spotlight, Siri, Focus Filters, and Control Center widgets. Replaces custom files. |
Networking & VPN
| Skill | Extension Type | When to Read |
|---|
| network-packet-tunnel.md | | 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 | | 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 | | User wants to intercept and respond to DNS queries system-wide, enabling DNS filtering, logging, or custom resolution. |
| network-filter-data.md | | 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 | | 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 | | 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 | | User wants to filter incoming SMS/MMS messages to classify spam, transactions, or promotions into separate tabs. |
| call-directory.md | | User wants to block phone numbers or provide caller ID labels for incoming calls. Updates a system-managed SQLite database. |
| unwanted-communication.md | | 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 | | 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 | | User wants custom UI for configuring a live broadcast (selecting stream key, privacy settings). Companion to broadcast upload extension. |
| safari.md | | User wants Safari Web Extensions (Manifest V3) with content scripts, background pages, and native messaging to the containing app. |
| content-blocker.md | | 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 | | User wants to report student progress in educational apps to Apple's Schoolwork app via ClassKit framework. |
| device-activity-monitor.md | | User wants to monitor app/website usage and trigger actions when Screen Time limits are reached. Parental control and focus apps. |
| shield-action.md | | 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 | | 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 | | User wants AutoFill for passwords and passkeys in Safari and apps. Modern replacement for . Supports passkey creation/assertion (WebAuthn). |
| credentials-provider.md | | User wants legacy password AutoFill (iOS 12+). For new projects, use instead, which supports both passwords and passkeys. |
| smart-card.md | | User wants to authenticate with smart cards or hardware tokens (YubiKey, PIV cards) via the CryptoTokenKit framework. Enterprise use. |
| account-auth.md | | 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 | | 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 | | 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 | | 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 | | 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 | | User wants to index app content in Spotlight, provide rich search results, and handle taps from Spotlight search. Uses Core Spotlight and . |
| spotlight-delegate.md | | 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 | | 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 | | 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 () — uses product type
com.apple.product-type.application.on-demand-install-capable
- watchOS App () — uses product type
com.apple.product-type.application
These are full applications with their own
, 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
.
Quick Reference: Common Use Cases
| User Says... | Read This Skill |
|---|
| "Add a home screen widget" | widget.md |
| "Add a share extension" | share.md |
| "Build an instant app / App Clip" | clip.md |
| "Integrate with Siri" | intent.md or app-intent.md |
| "Modify push notifications" | notification-service.md |
| "Custom notification UI" | notification-content.md |
| "Build a VPN app" | network-packet-tunnel.md |
| "Password manager AutoFill" | authentication-services.md |
| "Block spam calls" | call-directory.md |
| "Filter SMS spam" | message-filter.md |
| "Add to Files app" | file-provider.md |
| "Custom keyboard" | keyboard.md |
| "Photo filter extension" | photo-editing.md |
| "Safari ad blocker" | content-blocker.md |
| "Safari extension" | safari.md |
| "Live streaming / screen recording" | broadcast-upload.md |
| "watchOS app" | watch.md |
| "Screen Time parental controls" | device-activity-monitor.md |
| "Smart home / Matter" | matter.md |
| "Print to network printer" | print-service.md |
| "Spotlight search integration" | spotlight.md |
Creating a New Extension with @bacons/apple-targets
Every skill document includes a "Using with @bacons/apple-targets" section with the three-step setup:
sh
# 1. Run the CLI to scaffold the extension
bunx create-target <type>
# 2. Ensure the plugin is in app.json
{
"expo": {
"plugins": [["@bacons/apple-targets"]]
}
}
# 3. Generate the native project
npx expo prebuild --clean
The
parameter corresponds to the extension type slug shown in each skill document's title (e.g.,
,
,
,
).
When to Run Prebuild
Because target source files live outside the
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.
-
- Initial setup after creating a new target
- Changing (icon, colors, entitlements, bundle ID, frameworks)
- Changing plugin configuration
- Adding or removing targets
- Xcode project corruption or mysterious build failures
-
- You need to regenerate the project but want to preserve manual Xcode modifications
- Updating the plugin version with minor project changes
-
No prebuild needed for:
- Editing Swift code in directories — files are linked, changes appear immediately in Xcode
- Adding/modifying Swift files within an existing target
- Most day-to-day development work on target implementations
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
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
- "My extension can't access UserDefaults from the main app" → Read
- "How does EAS handle App Groups code signing?" → Read
Template for New Skills
If you need to write a new skill document, use
as the starting point. It defines the required frontmatter, section structure, code example format, and quality checklist.
Additional Resources
- CLAUDE.md (project root): Development setup, build instructions, and architecture notes for the plugin itself
- Apple Developer Documentation: Every skill links to official Apple docs and WWDC sessions
- Expo Documentation: https://docs.expo.dev/config-plugins/introduction/
- Continuous Native Generation: https://docs.expo.dev/workflow/continuous-native-generation/