mac-spotlight-search

name	mac-spotlight-search
description	Use macOS Spotlight from the terminal with mdfind and mdls to quickly locate local files by filename, indexed text, metadata, kind, date, or scope before falling back to slower filesystem scans.
metadata	{"short-description":"Search Mac files with Spotlight index"}

Mac Spotlight Search

Use this skill when a user asks an agent to find local Mac files, documents, PDFs, images, notes, emails exported as files, or old project assets, especially outside the current repository.

Spotlight is a fast candidate finder, not a source of truth. Use it to narrow paths, then verify with direct file reads, mdls, rg, file, stat, PDF/text extraction, or the app-specific parser that fits the file.

Default Workflow

1. Confirm the user intent and likely search scope before broad local-file discovery.
2. Start with mdfind when the search may span many folders or the whole Mac.
3. Prefer scoped searches with -onlyin when you know the likely root.
4. Limit output early with head or a small loop; do not dump thousands of paths into context.
5. Inspect metadata with mdls before opening large or private-looking files.
6. Verify the exact file content or filename with a direct tool before citing results.
7. Fall back to rg, find, app indexes, or manual inspection if Spotlight returns nothing or appears stale.

Commands

Basic indexed text or filename search:

mdfind  |  -50