CamilleScholtz/swmpc / .agents/skills/app-intents-whats-new-27
app-intents-whats-new-27
VerifiedNew App Intents APIs and behaviors for iOS 27 and macOS 27: SnippetIntent, LongRunningIntent, execution modes, and interactive snippets.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.8 KB |
| references/convenience-properties.md | markdown | 6.6 KB |
| references/cross-device-and-ownership.md | markdown | 7.8 KB |
| references/entity-collection.md | markdown | 8.7 KB |
| references/execution-modes.md | markdown | 10.6 KB |
| references/interactive-snippets.md | markdown | 13.9 KB |
| references/onscreen-entities.md | markdown | 6.4 KB |
| references/relevance-and-context.md | markdown | 6.8 KB |
| references/requestchoice.md | markdown | 5.3 KB |
| references/schema-adoption.md | markdown | 14.9 KB |
| references/spotlight-indexing.md | markdown | 7.1 KB |
| references/system-shortcuts.md | markdown | 3.1 KB |
| references/testing.md | markdown | 14.9 KB |
| references/union-values.md | markdown | 10.0 KB |
| references/visual-intelligence.md | markdown | 6.1 KB |
references/relevance-and-context.md
View on GitHub# Proactively Surfacing Relevant Entities
**SDK Version:** iOS 27.0 and later
If the user's deployment target is below iOS 27 / macOS 27 / watchOS 27 / tvOS 27 / visionOS 27, the new APIs in this reference (`RelevantEntities` and its `.shared` singleton, `updateEntities(_:for:)`, `removeEntities(_:)`, `removeAllEntities()`, `removeEntities(_:from:)`, `removeAllEntities(for:)`, `AppEntityContext`, and the `AudioContext` factories `.nowPlaying` / `.workout` / `.workout(activityType:)` / `.workout(intensityLevel:)`) require availability gating. `RelevantIntent` and `RelevantIntentManager` are older (iOS 17.0) and do not need iOS 27 gating.
`RelevantEntities` is a **narrow, media-focused** API: your app **donates the playable media items it owns — songs, albums, artists, playlists, radio stations, podcasts, and the like — so the system can suggest something to *play* (including items the person hasn't searched for or played before) in an audio scenario such as a workout or Now Playing.** It is **not** a general-purpose relevance or discovery mechanism, and it does **not** surface arbitrary entities: the only shipping contexts are audio (`AudioContext`), and your donations are candidates for the system's *media-playback* suggestions. (Making content *searchable* is Spotlight indexing; teaching the system *patterns from actions people took* is interaction donation via `IntentDonationManager` — different surfaces for different purposes. Don't reach for `RelevantEntities` for either.) You donate the full current set with `updateEntities(_:for:)` — each call replaces the previous set for that context — and retract it when it no longer applies; if the person doesn't open your app, the system expires the donations after roughly four weeks. The shipping contexts are **Now Playing** (`.audio(.nowPlaying)`) and **workout** (`.audio(.workout)` and its activity-type / intensity variants) — for example, surfacing a running playlist the moment someone starts a run. The running example is **TravelTracking**, whose travel-podcast feature donates the `EpisodeEntity` a person is currently listening to.
## Relevant entities
`RelevantEntities` is a `Sendable` struct reached through its `static let shared` singleton. `updateEntities(_:for:)` registers an array of `any AppEntity` as relevant for a given `AppEntityContext`; the call *replaces* the entities previously registered for that context, so pass the full current set each time rather than appending. Register when the context genuinely applies — when the person is listening to something, or has started a workout — so the set reflects what's relevant now.
```swift
import AppIntents
@available(iOS 27.0, *)
func updateNowPlaying(_ episode: EpisodeEntity) async throws {
// Replaces whatever was previously published for the now-playing context.
try await RelevantEntities.shared.updateEntities([episode], for: .audio(.nowPlaying))
}
```
**Availability:** iOS 27, macOS 27, watchOS 27, tvOS 27, visionOS 27 (`anyAppleOS 27.0`).
## Removing relevant entities
`RelevantEntities` offers four retraction calls so nothing lingers in system surfaces once it is no longer relevant. `removeEntities(_:from:)` retracts specific entities from one context; `removeAllEntities(for:)` clears an entire context; `removeEntities(_:)` and `removeAllEntities()` operate across every context your app published. Pair every publish with a matching removal.
```swift
import AppIntents
@available(iOS 27.0, *)
func retireNowPlaying(_ episode: EpisodeEntity) async throws {
// Retract a specific entity from one context...
try await RelevantEntities.shared.removeEntities([episode], from: .audio(.nowPlaying))
// ...clear the whole context...
try await RelevantEntities.shared.removeAllEntities(for: .audio(.nowPlaying))
// ...or clear everything TravelTracking published, across all contexts.
try await RelevantEntities.shared.removeAllEntities()
}
```
**Availability:** iOS 27, macOS 27, watchOS 27, tvOS 27, visionOS 27 (`anyAppleOS 27.0`).
## App entity context
`AppEntityContext` names the situation an entity is relevant to. It is a `Hashable`, `Sendable` value type, so you can store it, compare it, and key collections on it. It's produced by `AppEntityContext.audio(_:)`, which takes an `AudioContext`; the shipping `AudioContext` values are `.nowPlaying` (the system's Now Playing control or complication) and — from the HealthKit overlay — `.workout` (a workout of any type), `.workout(activityType:)` for a specific `HKWorkoutActivityType`, and `.workout(intensityLevel:)` for a `.low` / `.medium` / `.high` intensity. A more specific workout context is a stronger hint than the broad one, and you can register entities for several contexts at once.
```swift
import AppIntents
@available(iOS 27.0, *)
func nowPlayingContext() -> AppEntityContext {
.audio(.nowPlaying) // the system's Now Playing control / complication
}
// Workout contexts need the HealthKit overlay.
import HealthKit
@available(iOS 27.0, *)
func runningContext() -> AppEntityContext {
.audio(.workout(activityType: .running)) // e.g. surface a running playlist when a run starts
}
```
**Availability:** iOS 27, macOS 27, watchOS 27, tvOS 27, visionOS 27 (`anyAppleOS 27.0`). `.nowPlaying` is in AppIntents; the `.workout` factories and `WorkoutIntensityLevel` come from the HealthKit overlay (`import HealthKit`), same availability.
## Relevant intents (widget configuration)
`RelevantIntent` is the adjacent, older surface for marking a *widget-configuration* intent as relevant — it dates to iOS 17.0, so don't describe it as new in iOS 27 or conflate it with the iOS 27 `RelevantEntities` entity API (the two are easy to mix up by name). Its initializer `init(_:widgetKind:relevance:)` takes a `WidgetConfigurationIntent`, a `widgetKind` string, and a `relevance` of type `RelevantContext`, which originates in the **RelevanceKit** framework but is re-exported by AppIntents, so `import AppIntents` resolves it — an explicit `import RelevanceKit` is optional. You submit the results through `RelevantIntentManager.shared.updateRelevantIntents(_:)`. Use it only for widget-configuration intents, not for arbitrary intents.
```swift
import AppIntents
import RelevanceKit // optional — RelevantContext is re-exported by AppIntents
@available(iOS 17.0, *)
@available(tvOS, unavailable)
func publishRelevantWidgets(_ intents: [TravelGalleryWidgetIntent],
relevance: RelevantContext) async throws {
let relevant = intents.map {
RelevantIntent($0, widgetKind: "TravelGallery", relevance: relevance)
}
try await RelevantIntentManager.shared.updateRelevantIntents(relevant)
}
```
**Availability:** `RelevantIntent` / `RelevantIntentManager`: iOS 17.0, macOS 14.0, watchOS 10.0, tvOS 17.0. The `init(_:widgetKind:relevance:)` initializer is iOS 17.0 / macOS 14.0 / watchOS 10.0 and is **unavailable on tvOS**.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |