File Search Skill

Efficient CLI search tools for AI agents.

Tool Selection Guide

Task	Use	Instead of
Search text in code files	`rg` (ripgrep)	`grep`, `grep -r`
Find files by name/path	`fd`	`find`, `ls -R`
Structural/syntax-aware code search	`sg` (ast-grep)	regex hacks
Search PDFs, Office docs, archives	`rga` (ripgrep-all)	manual extraction
Count lines of code by language	`tokei`	`cloc`, `wc -l`
Code stats with complexity metrics	`scc`	`cloc`, `tokei`

Decision flow: text/regex → rg | code structure (empty catches, function sigs, multi-line patterns) → sg | files by name → fd | PDFs/archives → rga | codebase stats → tokei/scc

Quick Examples

rg 'def \w+\(' -t py src/          # rg: text search in Python files
rg -c 'TODO' -t js | wc -l         # rg: count first, then drill down
sg --pattern 'console.log($$$)' --rewrite 'logger.info($$$)' --lang js  # sg: structural replace
fd -g '*.test.ts' --changed-within 1d  # fd: -g for compound suffixes (NOT -e)
fd -g '*_test.go' -X rg 'func Test'   # fd+rg: find files, verify contents
rga 'quarterly revenue' docs/       # rga: search inside PDFs/archives
tokei --sort code                   # tokei: language stats
scc --wide                          # scc: complexity + COCOMO

Best Practices

Start narrow. Specify types (-t, --lang, -e), scope dirs, count first (rg -c).
Exclude noise (-g '!vendor/', fd -E node_modules).
--json for programmatic processing.
rg ≠ fd types. rg -t ts includes .tsx; fd -e ts does NOT. No -t tsx in rg.

See references/search-strategies.md.

Beyond Local Files

If local search finds nothing and context lives in issues/PRs/external docs — hand off (gh, Jira, WebFetch). Issue keys in comments signal this.

See references/remote-handoff.md.

References