/spotlight-indexing

name: spotlight-indexing
description: Generates Core Spotlight indexing infrastructure for making app content searchable via system Spotlight with rich attributes and deep link integration. Use when user wants to index content for Spotlight search, Siri suggestions, or system-wide searchability.
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
last_verified: 2026-07-16
review_by: 2027-06-22
os_version: iOS 27 / macOS 27

Spotlight Indexing Generator

Generate production Core Spotlight indexing infrastructure — makes app content searchable via Spotlight (and Siri suggestions). Indexes items with rich attributes, handles search continuation into your app, and manages index lifecycle.

When This Skill Activates

Use this skill when the user:

• Asks to "add spotlight search" or "spotlight indexing"
• Mentions "core spotlight" or "CSSearchableItem"
• Wants to make "searchable content" or "index content" for system search
• Asks about "system search" integration or "Siri suggestions"
• Wants content to appear in Spotlight results
• Mentions "NSUserActivity" for search or handoff

Pre-Generation Checks

1. Project Context Detection

• [ ] Check deployment target (iOS 16+ / macOS 13+)
• [ ] Check Swift version (requires Swift 5.9+)
• [ ] Check for @Observable support (iOS 17+ / macOS 14+)
• [ ] Identify source file locations

2. Existing CoreSpotlight Detection

Search for existing Spotlight code:

Glob: **/*Spotlight*.swift, **/*Searchable*.swift, **/*CSSearchable*.swift
Grep: "CoreSpotlight" or "CSSearchableIndex" or "CSSearchableItem"

If existing Spotlight code found:

• Ask if user wants to replace or augment it
• If augmenting, identify what's missing and generate only those pieces

3. Deep Linking Detection

Search for existing deep link or navigation setup:

Grep: "NavigationPath" or "onOpenURL" or "NSUserActivity" or "DeepLink"

If deep linking exists:

• Integrate SpotlightSearchHandler with existing router
• If not, generate standalone handler with guidance on wiring it up

4. Entitlements Check

Verify CoreSpotlight doesn't require special entitlements (it doesn't — it's a standard framework), but check if the app uses App Groups for shared index across extensions.

Configuration Questions

Ask user via AskUserQuestion:

1. **Content types to index?**

• Articles / blog posts (titles, body text, authors)
• Products (name, description, price, images)
• Contacts / people (name, phone, email)
• Tasks / reminders (title, due date, priority)
• Custom (user describes their model)

2. **Include thumbnails?**

• Yes — index thumbnail images alongside text attributes
• No — text-only attributes (smaller index, faster)

3. **Indexing strategy?**

• Batch indexing (index all content at once, e.g., on first launch or sync)
• Incremental indexing (index items as they're created/updated/deleted)
• Both (batch for initial load, incremental for changes)

4. **Include Siri suggestions / shortcuts?**

• Yes — make content eligible for Siri suggestions and predictions
• No — Spotlight search only

Generation Process

Step 1: Read Templates

Read `templates.md` for production Swift code. Read `patterns.md` for architecture guidance and best practices.

Step 2: Create Core Files

Generate these files: 1. `SpotlightIndexable.swift` — Protocol any model can conform to 2. `SpotlightIndexManager.swift` — Actor wrapping CSSearchableIndex with batching 3. `SpotlightAttributeBuilder.swift` — Fluent builder for CSSearchableItemAttributeSet

Step 3: Create Integration Files

4. `SpotlightSearchHandler.swift` — Handles NSUserActivity continuation from Spotlight taps

Step 4: Create Optional Files

Based on configuration:

• `SpotlightSyncModifier.swift` — If incremental indexing selected (ViewModifier for auto index/deindex)
• Add NSUserActivity + eligibleForSearch if Siri suggestions selected

Step 5: Determine File Location

Check project structure:

• If `Sources/` exists -> `Sources/SpotlightIndexing/`
• If `App/` exists -> `App/SpotlightIndexing/`
• Otherwise -> `SpotlightIndexing/`

Output Format

After generation, provide:

Files Created

SpotlightIndexing/
├── SpotlightIndexable.swift        # Protocol for indexable models
├── SpotlightIndexManager.swift     # Actor-based index management
├── SpotlightAttributeBuilder.swift # Fluent attribute builder
├── SpotlightSearchHandler.swift    # Handle Spotlight tap continuation
└── SpotlightSyncModifier.swift     # Auto index/deindex ViewModifier (optional)

Integration with Content Creation/Update

**Make a model searchable:**

// Conform your model to SpotlightIndexable
struct Article: SpotlightIndexable {
    let id: UUID
    let title: String
    let body: String
    let author: String
    let tags: [String]

    var spotlightID: String { id.uuidString }
    var spotlightTitle: String { title }
    var spotlightDescription: String { String(body.prefix(300)) }
    var spotlightKeywords: [String] { tags + [author] }
    var spotlightThumbnailData: Data? { nil }
    var spotlightDomainIdentifier: String { "com.myapp.articles" }
}

**Index on create, remove on delete:**

func createArticle(_ article: Article) async throws {
    try await repository.save(article)
    await SpotlightIndexManager.shared.index(items: [article])
}

func deleteArticle(_ article: Article) async throws {
    try await repository.delete(article)
    await SpotlightIndexManager.shared.remove(identifiers: [article.spotlightID])
}

**Batch reindex (e.g., on first launch):**

func reindexAllContent() async {
    let articles = await repository.fetchAll()
    await SpotlightIndexManager.shared.reindexAll(items: articles, domain: "com.myapp.articles")
}

**Handle Spotlight tap (App or Scene delegate):**

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .onC