activitykit
Implement, review, or improve Live Activities and Dynamic Island experiences in iOS apps using ActivityKit
Install / Use
npx skills add dpearson2699/swift-ios-skills --skill activitykitInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Our assessment of activitykit
activitykit scores 86/100 on our quality scale, 2425th of 4,698 Development & Engineering skills we index.
Its SKILL.md is 18 KB long, well organised into 31 sections with 13 code examples: a thorough specification that gives an agent plenty to work with.
With 1,143 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
- Our last check on 2026-11-03 found the source still online.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 86/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-06. Automated pattern scan on 2026-10-05. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
activitykit compared with similar skills
All 4 of these similar skills score higher than activitykit; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| activitykit (this skill)by dpearson2699 | 86 | 1.1k | 4mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.6k | today | MCP Server |
Frequently asked questions
- How do I install activitykit?
- Run
npx skills add dpearson2699/swift-ios-skills --skill activitykit. The install tabs above show the steps for each supported agent. - Which AI agents does activitykit work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is activitykit safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 86/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is activitykit still maintained?
- The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
Skill content
View source on GitHubname: activitykit description: "Implement, review, or improve Live Activities and Dynamic Island experiences in iOS apps using ActivityKit. Use when building real-time updating widgets for the Lock Screen and Dynamic Island — delivery tracking, sports scores, ride-sharing status, workout timers, media playback, or any time-sensitive information that updates in real time. Also use when working with ActivityKit, ActivityAttributes, Activity lifecycle (request/update/end), Dynamic Island layouts (compact/minimal/expanded), push-to-update Live Activities, or Lock Screen live widgets."
ActivityKit
ActivityKit owns real-time, glanceable Live Activities displayed on the Lock
Screen and Dynamic Island. Ordinary timeline widgets belong in widgetkit, and
generic APNs setup belongs in push-notifications; ActivityKit owns the Live
Activity lifecycle and payload contract. aps.content-state must decode into
the exact ActivityAttributes.ContentState shape, including any coordinated
custom date/range encoding. Modern ActivityContent lifecycle examples require
iOS 16.2+ unless noted.
See references/activitykit-patterns.md for complete code patterns including push payload formats, concurrent activities, state observation, and testing.
Contents
- Workflow
- ActivityAttributes Definition
- Activity Lifecycle
- Lock Screen Presentation
- Dynamic Island
- Push-to-Update
- Recent Additions
- Common Mistakes
- Review Checklist
- References
Workflow
1. Create a new Live Activity
- Verify the host app capability and
NSSupportsLiveActivities = YES. - Define
ActivityAttributes.ContentState; encode and decode a representative fixture that matches the server payload contract. - Create
ActivityConfigurationand preview Lock Screen and Dynamic Island states, including stale and terminal content. - Check
ActivityAuthorizationInfo.areActivitiesEnabled, then request and observe the activity lifecycle. - Exercise local update and every terminal end path.
- For remote updates, validate a complete reference payload before registering rotating update or push-to-start tokens with the server.
2. Review existing Live Activity code
Run through the Review Checklist at the end of this document.
ActivityAttributes Definition
Define both static data (immutable for the activity lifetime) and dynamic
ContentState (changes with each update). Keep ContentState small because
the entire struct is serialized on every update and push payload.
import ActivityKit
struct DeliveryAttributes: ActivityAttributes {
// Static -- set once at activity creation, never changes
var orderNumber: Int
var restaurantName: String
// Dynamic -- updated throughout the activity lifetime
struct ContentState: Codable, Hashable {
var driverName: String
var estimatedDeliveryTime: ClosedRange<Date>
var currentStep: DeliveryStep
}
}
enum DeliveryStep: String, Codable, Hashable, CaseIterable {
case confirmed, preparing, pickedUp, delivering, delivered
var icon: String {
switch self {
case .confirmed: "checkmark.circle"
case .preparing: "frying.pan"
case .pickedUp: "bag.fill"
case .delivering: "box.truck.fill"
case .delivered: "house.fill"
}
}
}
Stale Date
Set staleDate on ActivityContent to tell the system when content becomes outdated. The system sets context.isStale to true after this date; show fallback UI (e.g., "Updating...") in your views.
let content = ActivityContent(
state: state,
staleDate: Date().addingTimeInterval(300), // stale after 5 minutes
relevanceScore: 75
)
Activity Lifecycle
Starting
Use Activity.request to create and display a Live Activity. Pass .token as
the pushType to enable remote updates via APNs. The ActivityContent request
shown here requires iOS 16.2+.
let attributes = DeliveryAttributes(orderNumber: 42, restaurantName: "Pizza Place")
let state = DeliveryAttributes.ContentState(
driverName: "Alex",
estimatedDeliveryTime: Date()...Date().addingTimeInterval(1800),
currentStep: .preparing
)
let content = ActivityContent(state: state, staleDate: nil, relevanceScore: 75)
do {
let activity = try Activity.request(
attributes: attributes,
content: content,
pushType: .token
)
print("Started activity: \(activity.id)")
} catch {
print("Failed to start activity: \(error)")
}
Updating
Update the dynamic content state from the app. Use AlertConfiguration to
trigger a visible banner and sound alongside the update.
let updatedState = DeliveryAttributes.ContentState(
driverName: "Alex",
estimatedDeliveryTime: Date()...Date().addingTimeInterval(600),
currentStep: .delivering
)
let updatedContent = ActivityContent(
state: updatedState,
staleDate: Date().addingTimeInterval(300),
relevanceScore: 90
)
// Silent update
await activity.update(updatedContent)
// Update with an alert
await activity.update(updatedContent, alertConfiguration: AlertConfiguration(
title: "Order Update",
body: "Your driver is nearby!",
sound: .default
))
Ending
End the activity when the tracked event completes. Choose a dismissal policy to control how long the ended activity lingers on the Lock Screen.
let finalState = DeliveryAttributes.ContentState(
driverName: "Alex",
estimatedDeliveryTime: Date()...Date(),
currentStep: .delivered
)
let finalContent = ActivityContent(state: finalState, staleDate: nil, relevanceScore: 0)
// System decides when to remove (up to 4 hours)
await activity.end(finalContent, dismissalPolicy: .default)
// Remove immediately
await activity.end(finalContent, dismissalPolicy: .immediate)
// Remove after a specific time (max 4 hours from now)
await activity.end(finalContent, dismissalPolicy: .after(Date().addingTimeInterval(3600)))
Always end activities on all terminal code paths -- success, user/app
cancellation, sign-out/session stop, unrecoverable app error, and terminal server
failure. If the server says the tracked event can no longer continue or be
represented accurately, apply or send a final terminal state and end the activity
instead of leaving stale progress visible. When reviewing duration claims,
distinguish the active lifetime (up to 8 hours unless the app or user ends it
sooner), system-ended Lock Screen presence (up to 4 additional hours, for 12
hours total from start), and app-ended .default dismissal linger (up to 4 hours
after ending).
Lock Screen Presentation
The Lock Screen is the primary Live Activity display surface. Every device with iOS 16.1+ displays Live Activities here. Design this layout first, then adapt for Dynamic Island where available.
struct DeliveryActivityWidget: Widget {
var body: some WidgetConfiguration {
ActivityConfiguration(for: DeliveryAttributes.self) { context in
VStack(alignment: .leading) {
Text(context.attributes.restaurantName).font(.headline)
if context.isStale {
Label("Updating...", systemImage: "arrow.trianglehead.2.clockwise")
.foregroundStyle(.secondary)
} else {
Text(timerInterval: context.state.estimatedDeliveryTime, countsDown: true)
.monospacedDigit()
}
}
.padding()
} dynamicIsland: { context in
DynamicIsland {
DynamicIslandExpandedRegion(.center) {
Text(context.attributes.restaurantName).font(.headline)
}
DynamicIslandExpandedRegion(.trailing) {
Text(timerInterval: context.state.estimatedDeliveryTime, countsDown: true)
}
} compactLeading: {
Image(systemName: "box.truck.fill")
} compactTrailing: {
Text(timerInterval: context.state.estimatedDeliveryTime, countsDown: true)
} minimal: {
Image(systemName: "box.truck.fill")
}
}
}
}
Supplemental Activity Families
The Lock Screen presentation has limited vertical space. Avoid layouts taller
than roughly 160 points. On iOS 18+, use supplementalActivityFamilies when
you provide adaptive layouts beyond the default: .medium for iOS/macOS
Live Activity sizing and .small for watchOS Live Activity sizing.
ActivityConfiguration(for: DeliveryAttributes.self) { context in
// Lock Screen content
} dynamicIsland: { context in
// Dynamic Island
}
.supplementalActivityFamilies([.medium, .small])
Dynamic Island
Dynamic Island presentations appear only on devices that include Dynamic Island. Design all three modes, but treat the Lock Screen as the primary surface since not all devices have a Dynamic Island.
Compact (Leading + Trailing)
Used when one Live Activity occupies Dynamic Island compact space. Space is extremely limited -- show only the most critical information.
| Region | Purpose |
|---|---|
| compactLeading | Icon or tiny label identifying the activity |
| compactTrailing | One key value (timer, score, status) |
Minimal
Shown when multiple Live Activities compete for space. Only one activity gets the minimal slot. Display a single icon or glyph.
Expanded Regions
Shown when the user long-presses the Dynamic Island.
| Region | Position |
|---|---|
| .leading | Left of the TrueDepth camera; wraps below |
| .trailing | Right of the TrueDepth camera; wraps below |
| .center | Directly below the camera |
| .bottom | Below all other regions |
Keyline Tint
Apply a subtle tint to the Dynamic Island border:
DynamicIsland { /* expanded */ }
compactLeading: { /* ... */ }
compactTrailing: { /* ... */ }
minimal: { /* ... */ }
.keylineTint(.blue)
Push-to-Update
Push-to-update sends Live Activity updates through APNs, which is more efficient than polling from the app and works when the app is suspended, subject to APNs delivery, priority, budget, and throttling.
Setup
Pass .token as the pushType when starting the activity, then forward the
per-activity update token to your server. Update tokens can rotate, so observe
activity.pushTokenUpdates and re-register every emitted token:
let activity = try Activity.request(
attributes: attributes,
content: content,
pushType: .token
)
// Observe token changes -- tokens can rotate
Task {
for await token in activity.pushTokenUpdates {
let tokenString = token.map { String(format: "%02x", $0) }.joined()
try await ServerAPI.shared.registerActivityToken(
tokenString, activityID: activity.id
)
}
}
APNs Payload Format
Send an HTTP/2 POST to APNs with these headers and JSON body:
Required device-token HTTP headers:
apns-push-type: liveactivityapns-topic: <bundle-id>.push-type.liveactivityapns-priority: 5(lower priority) or10(immediate, counts against budget)
The aps.alert payload controls visible alert/banner/sound behavior; priority
alone does not create an alert.
Put timestamp, event, and the full content-state inside aps. Validate
update, end, and push-to-start bodies against the complete examples in
Push-to-Update Payloads,
including the exact Codable date/range representation.
Push-to-Start
Start a Live Activity remotely without the app running (iOS 17.2+). Push-to-start tokens are ActivityKit-spec
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.6k🤯 LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
