Original skill document
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
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 |
| Apply rule packs (security/lint, taint) | semgrep | regex CI checks |
| 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 → rg | structural → sg | rule packs → semgrep | filenames → fd | PDFs/archives → rga | LOC → tokei/scc
Quick Examples
bash
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 + COCOMOBest Practices
- Start narrow. Specify types (
-t,--lang,-e), scope dirs, count first (rg -c). - Exclude noise (
-g '!vendor/',fd -E node_modules). - Batch independent queries. Union patterns with
rg -e P1 -e P2 -e P3(one walk), or issue distinct queries as parallel tool calls in one message — never sequential&&chains. - `--json` for programmatic processing.
- rg ≠ fd types.
rg -t tsincludes.tsx;fd -e tsdoes NOT. No-t tsxin 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
| Topic | File |
|---|---|
| rg flags, patterns, recipes | references/ripgrep-patterns.md |
| ast-grep patterns by language | references/ast-grep-patterns.md |
| semgrep rules and taint mode | references/semgrep-patterns.md |
| fd flags, usage, fd+rg combos | references/fd-guide.md |
| rga formats, usage, caching | references/rga-guide.md |
| tokei and scc usage | references/code-metrics.md |
| PreToolUse nudge (ships with plugin) | references/enforcement-hook.md |
| Search targeting strategies | references/search-strategies.md |
| Remote context handoff guide | references/remote-handoff.md |
| Modern CLI tools comparison (legacy→modern, all domains) | cli-tools SKILL.md#preferred-modern-tools |