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 '確定申告 2025' | head -50

Search within one directory:

mdfind -onlyin "$HOME/Documents" '確定申告 2025' | head -50

Filename search:

mdfind 'kMDItemFSName == "*invoice*"cd' | head -50

PDF search:

mdfind 'kMDItemContentTypeTree == "com.adobe.pdf" && (* == "確定申告 2025"cd)' | head -50

Kind search examples:

mdfind 'kMDItemKind == "*PDF*"cd && (* == "契約書"cd)' | head -50
mdfind 'kMDItemContentTypeTree == "public.image" && (* == "logo"cd)' | head -50
mdfind 'kMDItemContentTypeTree == "public.movie" && (* == "demo"cd)' | head -50

Date filters:

mdfind 'kMDItemFSContentChangeDate >= $time.today(-30) && (* == "invoice"cd)' | head -50
mdfind 'kMDItemFSCreationDate >= $time.iso(2026-01-01T00:00:00Z) && (* == "proposal"cd)' | head -50

Metadata inspection:

mdls -name kMDItemDisplayName -name kMDItemKind -name kMDItemContentTypeTree -name kMDItemFSContentChangeDate -- "$path"

Check whether a directory is excluded from indexing:

mdutil -s "$HOME/Documents"

Query Rules

• Use quoted predicates for metadata searches.
• Add c for case-insensitive and d for diacritic-insensitive matches, for example "*term*"cd.
• Use kMDItemFSName for filename, kMDItemTextContent or * for indexed content, and kMDItemContentTypeTree for broad file type families.
• Search short known terms first. If nothing appears, try filename fragments, Japanese/English variants, and likely date or directory scopes.
• For code inside the current repo, start with rg; Spotlight is more useful for broad personal/project asset discovery than exact source navigation.

Safety and Privacy

• Prefer mdfind -onlyin <directory> over whole-home searches unless the user explicitly asks for a broad search.
• Treat paths returned by Spotlight as candidates, not authorization to read file contents.
• Do not open or summarize sensitive-looking files unless the user asked for that category or the file is clearly task-relevant.
• Show candidate paths and ask before reading private categories such as finances, medical, identity documents, credentials, personal messages, or legal files when the user's intent is ambiguous.
• Do not run sudo mdutil, rebuild indexes, or change Spotlight privacy settings unless the user explicitly asks.
• If a path includes cloud storage, external drives, backups, or app containers, verify existence with test -e or stat; Spotlight can return stale or unavailable paths.

When Spotlight Fails

Spotlight may miss files that are unindexed, newly created, excluded by privacy settings, inside packages/archives, on unavailable volumes, or in formats without text importers.

Fallback sequence:

1. Use rg --files or find inside the likely root.
2. Use rg -i for exact text across plain text files.
3. Use format-specific extraction for PDFs, DOCX, mail exports, archives, or databases.
4. Report that Spotlight was attempted, what query was used, and why fallback was needed.