file-search

name	file-search
description	This skill should be used when agents need to search codebases for text patterns or structural code patterns. Provides fast search using ripgrep for text and ast-grep for syntax-aware code search.
license	MIT

File Search Skill

Search code efficiently using ripgrep for text patterns and ast-grep for structural code patterns.

Purpose

The file-search skill provides access to two powerful search tools:

1. ripgrep (rg): Ultra-fast text search with regex support for finding strings, patterns, and text matches
2. ast-grep (sg): Syntax-aware structural search for finding code patterns based on abstract syntax trees

Use these tools to understand codebases, find usage patterns, analyze impact of changes, and locate specific code constructs. Both tools are significantly faster than traditional grep or find commands.

When to Use This Skill

Use the file-search skill when:

• Understanding a new codebase (finding entry points, key classes)
• Finding all usages of a function, class, or variable before refactoring
• Locating specific code patterns (error handling, API calls, etc.)
• Searching for security issues (hardcoded credentials, SQL queries, eval usage)
• Analyzing dependencies and imports
• Finding TODOs, FIXMEs, or code comments

Choose ripgrep for:

• Text-based searches (strings, comments, variable names)
• Fast, simple pattern matching across many files
• When the exact code structure doesn't matter

Choose ast-grep for:

• Structural code searches (function signatures, class definitions)
• Syntax-aware matching (understanding code semantics)
• Complex refactoring (finding specific code patterns)

Invoking Search Tools

Use the execute_command tool to run ripgrep and ast-grep:

# Using ripgrep
execute_command("rg 'pattern' --type py src/")

# Using ast-grep
execute_command("sg --pattern 'class $NAME { $$$ }' --lang python")

Both tools are pre-installed and available via shell execution.

Targeting Your Searches

CRITICAL: Always start with targeted, narrow searches to avoid overwhelming results. Getting thousands of matches makes analysis impossible and wastes tokens.

These strategies apply to both ripgrep and ast-grep.

Scope-Limiting Strategies

Apply these strategies from the start to target searches effectively:

1. Specify File Types/Languages: Always filter by language

   # Ripgrep
   rg "function" --type py --type js
   
   # AST-grep
   sg --pattern 'function $NAME($$$) { $$$ }' --lang js
   

2. Target Specific Directories: Search in likely locations first

   # Ripgrep
   rg "LoginService" src/services/
   
   # AST-grep
   sg --pattern 'class LoginService { $$$ }' src/services/
   

3. Use Specific Patterns: Make patterns as specific as possible

   # Ripgrep: BAD - too broad
   rg "user"
   # Ripgrep: GOOD - more specific
   rg "class.*User.*Service" --type py
   
   # AST-grep: BAD - too broad
   sg --pattern '$X'
   # AST-grep: GOOD - more specific
   sg --pattern 'class $NAME extends UserService { $$$ }' --lang js
   

4. Limit Result Count: Use head to cap results

   # Ripgrep
   rg "import" --type py | head -20
   rg "TODO" --count
   
   # AST-grep
   sg --pattern 'import $X from $Y' --lang js | head -20
   

Progressive Search Refinement

When exploring unfamiliar code, use this workflow:

Ripgrep example:

# Step 1: Count matches to assess scope
rg "pattern" --count --type py

# Step 2: If too many results, add more filters
rg "pattern" --type py src/ --glob '!tests'

# Step 3: Show limited results to inspect
rg "pattern" --type py src/ | head -30

# Step 4: Once confirmed, get full results or target further
rg "pattern" --type py src/specific_module/

AST-grep example:

# Step 1: Assess scope with broad structural pattern
sg --pattern 'function $NAME($$$) { $$$ }' --lang js | head -10

# Step 2: If too many results, narrow to specific directory
sg --pattern 'function $NAME($$$) { $$$ }' --lang js src/

# Step 3: Make pattern more specific
sg --pattern 'async function $NAME($$$) { $$$ }' --lang js src/

# Step 4: Target exact location
sg --pattern 'async function $NAME($$$) { $$$ }' --lang js src/services/

When You Get Too Many Results

If a search returns hundreds of matches (applies to both rg and sg):

1. Add file type/language filters: --type py (rg) or --lang python (sg)
2. Narrow directory scope: Search src/ instead of .
3. Make pattern more specific: Add context around the pattern
4. Use word boundaries: -w flag for whole words only (rg)
5. Pipe to head: Limit output with | head -50
6. Exclude test files: --glob '!*test*' (rg) or avoid test directories (sg)

Example of refinement:

# Step 1: Too broad (10,000+ matches)
rg "error"

# Step 2: Add file type (1,000 matches)
rg "error" --type py

# Step 3: Add directory scope (200 matches)
rg "error" --type py src/

# Step 4: Make pattern specific (20 matches)
rg "raise.*Error" --type py src/

# Step 5: Target exact location (5 matches)
rg "raise.*Error" --type py src/services/

How to Use

Ripgrep (rg)

# Basic text search
rg "pattern" --type py --type js

# Common flags
-i              # Case-insensitive
-w              # Match whole words only
-l              # Show only filenames
-n              # Show line numbers
-C 3            # Show 3 lines of context
--count         # Count matches per file
--glob '!dir'   # Exclude directory

# Examples
rg "function.*login" --type js src/
rg -i "TODO" --count
rg "auth|login|session" --type py

AST-Grep (sg)

# Structural code search
sg --pattern 'function $NAME($$$) { $$$ }' --lang js

# Metavariables
$VAR     # Matches single AST node
$$$      # Matches zero or more nodes

# Examples
sg --pattern 'class $NAME { $$$ }' --lang python
sg --pattern 'import $X from $Y' --lang js
sg --pattern 'async function $NAME($$$) { $$$ }' src/

Common Search Patterns

# Security issues
rg -i "password\s*=\s*['\"]" --type py
rg "\beval\(" --type js

# TODOs and comments
rg "TODO|FIXME|HACK"

# Code structures
sg --pattern 'class $NAME { $$$ }' --lang python
sg --pattern 'try { $$$ } catch ($E) { $$$ }' --lang js

# Dependencies
rg "from requests import" --type py
rg "require\(['\"]" --type js

# Refactoring
rg "\.old_method\(" --type py
rg "@deprecated" -A 5

File Type Filters

Common ripgrep file types: py, js, ts, rust, go, java, c, cpp, html, css, json, yaml, md

Use --type-list to see all available types, or define custom types:

rg --type-add 'config:*.{yml,yaml,toml,ini}' --type config "pattern"

Performance Tips

See "Targeting Your Searches" section for comprehensive strategies. Key tips:

# Limit scope to specific directories
rg "pattern" src/

# Filter by file type
rg "pattern" --type py --type js

# Exclude large directories
rg "pattern" --glob '!{node_modules,venv,.git}'

# Use fixed strings (no regex) for speed
rg -F "exact string"

# Count before viewing full results
rg "pattern" --count --type py

Best Practices

1. Start Narrow, Then Broaden: Use specific patterns, file types, and directory scope from the start
2. Count Before Viewing: Use --count or | head -N to preview result volume
3. Always Specify File Types: Use --type (rg) or --lang (sg) to filter by language
4. Exclude Common Noise: Add --glob '!{node_modules,venv,.git,dist,build}' habitually
5. Combine Tools: Use rg for text patterns, sg for structural code patterns
6. Use Context Strategically: Add -C N for surrounding lines, but be mindful of output volume

Troubleshooting

• No matches found: Check file type filters, try -i for case-insensitive, search partial pattern first
• Too slow: Exclude directories with --glob, limit file types with --type, narrow search path
• AST-grep issues: Verify --lang is correct, try simpler pattern, use rg to verify code exists

Resources

• Ripgrep docs
• AST-grep docs