core-spotlight-ref

Index app content with Core Spotlight and NSUserActivity for search and Handoff.

1.1k|81|Updated Nov 30, 2025
One-click install
npx skills add https://github.com/CharlesWiltgen/Axiom --skill core-spotlight-ref
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: core-spotlight-ref
Source: https://github.com/CharlesWiltgen/Axiom/tree/main/.claude-plugin/plugins/axiom/skills/core-spotlight-ref
Command: npx skills add https://github.com/CharlesWiltgen/Axiom --skill core-spotlight-ref

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill provides a comprehensive reference for Core Spotlight and NSUserActivity usage, helping you decide when to index content vs. use user activities for prediction, handoff, and search.

Core Features & Use Cases

  • Indexing vs activity: Choose between Core Spotlight indexing and NSUserActivity based on the use case.
  • Handoff & prediction: Use NSUserActivity to enable seamless handoff and Siri predictions.
  • Batch indexing & deletion: Efficiently index, update, and delete items with stable identifiers.
  • Debugging discoverability: Diagnose why content isn't searchable or suggested.

Quick Start

Create a brief plan to index a set of notes for Spotlight and enable NSUserActivity for handoff.

Frequently Asked Questions about core-spotlight-ref

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I index app content for Spotlight search and Siri predictions?

Index content using Core Spotlight's CSSearchableItem and CSSearchableIndex APIs with stable uniqueIdentifier and domainIdentifier, CSSearchableItemAttributeSet metadata, and optional location and rating attributes. Batch indexing enables efficient updates and deletions while maintaining searchability across your app's documents, notes, orders, and messages.

When should I use NSUserActivity instead of Core Spotlight indexing?

Use NSUserActivity to enable handoff between devices and Siri predictions for user-initiated actions and navigation states. Use Core Spotlight indexing for static or frequently updated content that should appear in system search results. NSUserActivity captures intent and context; Spotlight indexes persistent, discoverable content.

How do I enable handoff and Siri suggestions in my app?

Integrate NSUserActivity into your app's view controllers and navigation flows, setting appropriate activity types and userInfo dictionaries. NSUserActivity enables seamless handoff between devices and feeds Siri suggestions. Combine with Core Spotlight indexing to make content both searchable and predictable.

What's the best way to batch index and delete Spotlight items?

Use CSSearchableIndex with batch operations: call indexSearchableItems(_:completionHandler:) to add or update multiple CSSearchableItem objects at once, and deleteSearchableItems(withDomainIdentifiers:completionHandler:) to remove by domainIdentifier. Stable identifiers and domain organization simplify efficient updates and deletions at scale.

Why isn't my content appearing in Spotlight search results?

Verify that CSSearchableItem has a valid, stable uniqueIdentifier and domainIdentifier, CSSearchableItemAttributeSet includes searchable metadata (title, contentDescription, keywords), and indexing completed without errors. Debug using CSSearchableIndex.default() queries and check that content type and visibility settings allow indexing.

Can I use Core Spotlight for documents, notes, orders, and messages in the same app?

Yes. Use distinct domainIdentifier values for each content type (documents, notes, orders, messages) to organize indexing, enable targeted deletion, and maintain separate Spotlight search namespaces. CSSearchableItemAttributeSet metadata adapts to each content type's attributes and searchable fields.