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/spotlight-indexing.md
View on GitHub# Spotlight Indexing Enhancements
**SDK Version:** iOS 26.0 and later
If the user's deployment target is below iOS 26 / macOS 26 / visionOS 26 (or iOS 27 / macOS 27 / visionOS 27 for the query and cross-link APIs), the new APIs in this reference (`@ComputedProperty(indexingKey:)` and `@DeferredProperty(indexingKey:)`, `IndexedEntityQuery` with `reindexEntities(for:indexDescription:)` / `reindexAllEntities(indexDescription:)`, and `CSSearchableItem.relatedAppEntityIdentifier` / `CSSearchableItemAttributeSet.relatedAppEntityIdentifier`) require availability gating. The baseline `IndexedEntity` conformance and `indexAppEntities`/`deleteAppEntities` are older (iOS 18) and are noted here only for context. See "Deployment target below SDK 27" below for the gating shape to use.
`IndexedEntity` (iOS 18.0) already lets an `AppEntity` project itself into a `CSSearchableItemAttributeSet` so it appears in Spotlight, and `CSSearchableIndex.indexAppEntities(_:priority:)` / `deleteAppEntities(...)` (also iOS 18.0) push and remove those entities. This reference covers what is *new* on top of that baseline: computed and deferred property indexing keys (iOS 26), a query protocol that lets the system drive reindexing (iOS 27), and a way to cross-link an independently indexed searchable item back to an app entity (iOS 27). Running example: a travel app, **TravelTracking**, whose library entity is `LandmarkEntity: IndexedEntity`.
These surfaces attach to *any* `IndexedEntity` — including a **schema-conforming** one, since a schema entity is still an `AppEntity`. CometCal's calendar entity combines both (`@AppEntity(schema: .calendar.event) struct EventEntity: IndexedEntity`), and a music library's `@AppEntity(schema: .audio.song)` entity is pushed to Spotlight the same way (`CSSearchableIndex.indexAppEntities([song])`). Schema adoption and Spotlight indexing are orthogonal — an entity can do both.
## Computed and deferred indexing keys
`@ComputedProperty(indexingKey:)` and `@DeferredProperty(indexingKey:)` map an entity value to a `CSSearchableItemAttributeSet` key path without stored backing, extending the older `@Property(indexingKey:)` (iOS 18.4) to derived values. Use `@ComputedProperty(indexingKey:)` when the value is computed synchronously from other fields, and `@DeferredProperty(indexingKey:)` when producing it is expensive or `async` (network, disk, decode) so it is fetched lazily rather than on every materialization. The key is a `PartialKeyPath<CSSearchableItemAttributeSet>`; both macros also offer a `title:`-prefixed overload. `@ComputedProperty` additionally has a `customIndexingKey:` overload taking a `CSCustomAttributeKey`; `@DeferredProperty` does not.
```swift
@available(iOS 26.0, macOS 26.0, visionOS 26.0, *)
struct LandmarkEntity: AppEntity, IndexedEntity {
let id: UUID
// Synchronous, derived from other fields.
@ComputedProperty(indexingKey: \.title)
var name: String { "\(number). \(rawName)" }
// Expensive / async: fetched lazily, only when indexing needs it.
@DeferredProperty(indexingKey: \.textContent)
var notes: String { get async throws { try await ModelData.notes(for: id) } }
// ...
}
```
**Availability:** `@ComputedProperty(indexingKey:)` / `(title:indexingKey:)` / `(customIndexingKey:)` and `@DeferredProperty(indexingKey:)` / `(title:indexingKey:)` are iOS 26.0, macOS 26.0, visionOS 26.0 (no watchOS/tvOS). The baseline `@Property(indexingKey:)` / `(title:indexingKey:)` is iOS 18.4, macOS 15.4, visionOS 2.4, and is `@available(watchOS, unavailable)` / `@available(tvOS, unavailable)`.
## System-driven reindexing from the query
`IndexedEntityQuery` refines `EntityQuery` (requiring `Self.Entity: IndexedEntity`) and adds `reindexEntities(for:indexDescription:)` and `reindexAllEntities(indexDescription:)`, letting the system ask your query to refresh Spotlight when the backing store changes. Both receive a `CSSearchableIndexDescription` and typically re-push entities through `CSSearchableIndex.indexAppEntities(_:)`.
```swift
@available(iOS 27.0, macOS 27.0, visionOS 27.0, *)
struct LandmarkEntityQuery: IndexedEntityQuery {
func entities(for identifiers: [LandmarkEntity.ID]) async throws -> [LandmarkEntity] {
try await ModelData.landmarks(ids: identifiers)
}
func reindexEntities(
for identifiers: [LandmarkEntity.ID],
indexDescription: CSSearchableIndexDescription
) async throws {
try await CSSearchableIndex.default().indexAppEntities(entities(for: identifiers))
}
func reindexAllEntities(
indexDescription: CSSearchableIndexDescription
) async throws {
try await CSSearchableIndex.default().indexAppEntities(ModelData.all())
}
}
```
**Availability:** iOS 27.0, macOS 27.0, visionOS 27.0 (no watchOS/tvOS).
## Cross-link a searchable item to an app entity
`relatedAppEntityIdentifier` is a settable `EntityIdentifier?` on both `CSSearchableItem` and `CSSearchableItemAttributeSet`. Set it on an item you index directly (content *not* built from an `IndexedEntity`) to associate it with an existing app entity, so Spotlight's own UI can cross-link the two. This is distinct from the older iOS 18.0 `CSSearchableItem(appEntity:)` / `associateAppEntity(_:priority:)`, which build an item *from* an entity; `relatedAppEntityIdentifier` points an *independently* indexed item *at* an entity by identifier.
```swift
@available(iOS 27.0, macOS 27.0, visionOS 27.0, *)
func indexRoutePage(for landmark: LandmarkEntity, html: URL) async throws {
let item = CSSearchableItem(
uniqueIdentifier: "route-\(landmark.id.uuidString)",
domainIdentifier: "routes",
attributeSet: CSSearchableItemAttributeSet(contentType: .html))
item.relatedAppEntityIdentifier = EntityIdentifier(for: landmark)
try await CSSearchableIndex.default().indexSearchableItems([item])
}
```
**Availability:** iOS 27.0, macOS 27.0, visionOS 27.0 (no watchOS/tvOS) on both `CSSearchableItem` and `CSSearchableItemAttributeSet`.
## Deployment target below SDK 27
When the user's deployment target is below the version an API requires, gate the new surface behind `@available`/`if #available` and keep a fallback that uses the baseline iOS 18 indexing path (a plain `@Property(indexingKey:)` and manual `indexAppEntities`), or skip the enhancement on older OS versions:
```swift
if #available(iOS 27, macOS 27, visionOS 27, *) {
item.relatedAppEntityIdentifier = EntityIdentifier(for: landmark) // iOS 27 API
}
try await CSSearchableIndex.default().indexSearchableItems([item]) // iOS 18 baseline
```
Gate the property macros at iOS 26 (`@ComputedProperty`/`@DeferredProperty(indexingKey:)`), and the query protocol and `relatedAppEntityIdentifier` at iOS 27, either with `if #available` around the use or `@available(iOS 26, *)` / `@available(iOS 27, *)` on an enclosing declaration. Do not emit these APIs on watchOS or tvOS — the property indexing keys, `IndexedEntityQuery`, and `relatedAppEntityIdentifier` are unavailable there at every OS version; branch to a plain property or skip indexing on those platforms. Don't emit unconditional calls; the typecheck will fail with `'<API>' is only available in iOS 26.0 or newer` (or 27.0).
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 |