/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 pre-installed in MassGen environments:

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

In MassGen, 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 in MassGen Docker containers 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 $NAM