agentsclimarketplace

Core spotlight ask

Skill dbmrq/agent-skills/skills/core-spotlight-ask

Personal Agent Skills for AI coding agents — install and update with gh skill

Install
npx -y skills add dbmrq/agent-skills --skill core-spotlight-ask

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
  • 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Index app content in Core Spotlight and build on-device “Ask” search with Foundation Models (CSSearchableItem, CSUserQuery, SpotlightSearchTool, search-then-summarize fallbacks, indexing progress, progressive results). Use when adding Spotlight indexing, reindex extensions, keyword/date search, or Apple Intelligence Ask over local notes/documents in Swift/SwiftUI apps.

SKILL.md

6.1 KB, ~1.3k tokens by cl100k_base, as published. Nobody here has run it

Core Spotlight + Ask

Ship local searchable content with Core Spotlight, then optionally ground Apple Intelligence Ask in that index. Prefer Spotlight for discovery; use the language model only to summarize or answer against retrieved hits.

Related skills:

  • apple-foundation-models — sessions, availability, prompting, tool-calling rules (not Spotlight-specific)
  • native-swiftui — search UI, ContentUnavailableView, redacted placeholders
  • swiftui-project-structure — split indexing vs search packages/targets

Agent workflow

  1. Split ownership — indexing (build/sync/delete items + reindex extension) separate from query/Ask UI.
  2. Choose stable IDs — uniqueIdentifier must round-trip to an app model; use one domainIdentifier per content kind.
  3. Index for how users ask — put titles, plain text, short snippets, modification dates, and date/tag keywords into attributes users will query.
  4. Sync incrementally — index only changed items (isUpdate), delete removed IDs, report progress to the UI.
  5. Add a Spotlight index extension — implement CSIndexExtensionRequestHandler for system-requested reindex.
  6. Query with CSUserQuery — call CSUserQuery.prepare() once per process; request the fetchAttributes you need to map results.
  7. Filter stale hits — drop Spotlight results whose IDs are unknown to the live vault/library.
  8. Fallback ladder — if Spotlight returns nothing: date-aware local scan → keyword scan of on-disk content; label the fallback in UI.
  9. Gate Ask on the model — default UX to Ask when SystemLanguageModel is available, else keyword Search.
  10. Orchestrate Ask in tiers — iOS 27+ SpotlightSearchTool when available; else search-then-summarize with compact excerpts in the prompt (iOS 26+).
  11. Progressive UI — stream note hits as they arrive; keep a Summary section with a redacted placeholder until the model finishes; render summary markdown with AttributedString.

Hard-won rules

Indexing

  • Strip markup before indexing (textContent / contentDescription should be plain language).
  • Prefixed date prose in textContent (“Date: 4 July 2026 (2026-07-04). …”) plus date keywords (ISO day, year, month name, “Month Year”) makes natural-language date asks work.
  • Set contentCreationDate to the semantic document day when that matters more than file birth time (journals, diaries).
  • Keep contentDescription short (~snippet length); put the full plain body in textContent.
  • Track last-indexed modification times in memory (or durable store) so resync is cheap.
  • Spotlight index/delete can fail on Simulator — don’t fail the whole library sync because of that.
  • Reindex extension principal class: CSIndexExtensionRequestHandler subclass; extension point com.apple.spotlight.index. Always call the acknowledgement handler.
  • Share App Group / bookmarks with the extension when content lives outside the app container.

Query

  • Map uniqueIdentifier → app reference; reject unknowns (isKnownNote / knownPaths).
  • Prefer ranked CSUserQuery with explicit fetchAttributes (title, textContent, contentDescription, dates).
  • Surface indexing progress while the index is incomplete (“Indexing… N of M”); empty Ask results may mean “still indexing,” not “no notes.”

Ask / Foundation Models

  • Don’t dump the whole library into the prompt. Retrieve first, then summarize.
  • iOS 27+ (when SDK has it): SpotlightSearchTool + LanguageModelSession(tools:) with a short trusted instructions string; observe tool.searchResults to update the notes list before session.respond returns.
  • iOS 26 fallback: run the same Spotlight/vault search the Search mode uses, onResultsUpdate immediately, then one-shot LanguageModelSession over numbered title/date/snippet excerpts.
  • Wrap 27-only APIs in #if compiler(>=…) and #available(iOS 27, *) so older toolchains still compile.
  • Ask instructions: one task (search + brief summary), mention how content is organized/dated, prefer plain language; models may emit light markdown — render it, don’t show raw **.
  • Product states: model unavailable, indexing in progress, no hits, tool/search failure, Search-only fallback.

UX

  • Show Summary while generating (.redacted(reason: .placeholder) dummy lines), not only after the answer arrives.
  • Parse summary with AttributedString(markdown:options: .inlineOnlyPreservingWhitespace) (or equivalent) so bold/italic display correctly.
  • Debounce typing for Search; Ask usually runs on submit.
  • Demo/screenshot seeds should set query + summary + results without waiting on the model.

Shipping checklist

  • Stable uniqueIdentifier + domainIdentifier
  • Incremental sync + delete for removed items
  • Spotlight index extension handles reindex-all and reindex-by-ID
  • CSUserQuery.prepare() once; fetchAttributes cover mapping needs
  • Stale-hit filter against live library IDs
  • Fallback when Spotlight is empty (with user-visible label)
  • Indexing progress exposed to search UI
  • Ask gated on model availability; Search still works without AI
  • Tiered Ask (Spotlight tool vs search-then-summarize)
  • Progressive results + redacted Summary + markdown rendering

Additional resources

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.