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
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).
- 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 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
| 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/SKILL.md#preferred-modern-tools |
1---2name: file-search3description: Use when searching codebases (text, structural/AST, files by name, PDFs/archives, code stats) or building context before a task.4license: (MIT AND CC-BY-SA-4.0). See LICENSE-MIT and LICENSE-CC-BY-SA-4.05---6
7# File Search Skill
8
9Efficient CLI search tools for AI agents.
10
11## Tool Selection Guide
12
13| Task | Use | Instead of |
14|------|-----|------------|
15| Search text in code files | `rg` (ripgrep) | `grep`, `grep -r` |
16| Find files by name/path | `fd` | `find`, `ls -R` |
17| Structural/syntax-aware code search | `sg` (ast-grep) | regex hacks |
18| Apply rule packs (security/lint, taint) | `semgrep` | regex CI checks |
19| Search PDFs, Office docs, archives | `rga` (ripgrep-all) | manual extraction |
20| Count lines of code by language | `tokei` | `cloc`, `wc -l` |
21| Code stats with complexity metrics | `scc` | `cloc`, `tokei` |
22
23**Decision flow:** text → `rg` | structural → `sg` | rule packs →
24`semgrep` | filenames → `fd` | PDFs/archives → `rga` | LOC →
25`tokei`/`scc`
26
27## Quick Examples
28
29```bash
30rg 'def \w+\(' -t py src/ # rg: text search in Python files
31rg -c 'TODO' -t js | wc -l # rg: count first, then drill down
32sg --pattern 'console.log($$$)' --rewrite 'logger.info($$$)' --lang js # sg: structural replace
33fd -g '*.test.ts' --changed-within 1d # fd: -g for compound suffixes (NOT -e)
34fd -g '*_test.go' -X rg 'func Test' # fd+rg: find files, verify contents
35rga 'quarterly revenue' docs/ # rga: search inside PDFs/archives
36tokei --sort code # tokei: language stats
37scc --wide # scc: complexity + COCOMO
38```
39
40## Best Practices
41
421. **Start narrow.** Specify types (`-t`, `--lang`, `-e`), scope dirs, count first (`rg -c`).
432. **Exclude noise** (`-g '!vendor/'`, `fd -E node_modules`).
443. **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.
454. **`--json`** for programmatic processing.
465. **rg ≠ fd types.** `rg -t ts` includes `.tsx`; `fd -e ts` does NOT. No `-t tsx` in rg.
47
48See [references/search-strategies.md](references/search-strategies.md).
49
50## Beyond Local Files
51
52If local search finds nothing and context lives in issues/PRs/external
53docs — hand off (`gh`, Jira, WebFetch). Issue keys in comments signal this.
54
55See [references/remote-handoff.md](references/remote-handoff.md).
56
57## References
58
59| Topic | File |
60|-------|------|
61| rg flags, patterns, recipes | [references/ripgrep-patterns.md](references/ripgrep-patterns.md) |
62| ast-grep patterns by language | [references/ast-grep-patterns.md](references/ast-grep-patterns.md) |
63| semgrep rules and taint mode | [references/semgrep-patterns.md](references/semgrep-patterns.md) |
64| fd flags, usage, fd+rg combos | [references/fd-guide.md](references/fd-guide.md) |
65| rga formats, usage, caching | [references/rga-guide.md](references/rga-guide.md) |
66| tokei and scc usage | [references/code-metrics.md](references/code-metrics.md) |
67| PreToolUse nudge (ships with plugin) | [references/enforcement-hook.md](references/enforcement-hook.md) |
68| Search targeting strategies | [references/search-strategies.md](references/search-strategies.md) |
69| Remote context handoff guide | [references/remote-handoff.md](references/remote-handoff.md) |
70| Modern CLI tools comparison (legacy→modern, all domains) | [cli-tools-skill/SKILL.md#preferred-modern-tools](https://github.com/netresearch/cli-tools-skill/blob/main/skills/cli-tools/SKILL.md#preferred-modern-tools) |
netresearch