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:

ripgrep (rg): Ultra-fast text search with regex support for finding strings, patterns, and text matches
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

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:

python

# 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:

Specify File Types/Languages: Always filter by language

bash

# Ripgrep
rg "function" --type py --type js

# AST-grep
sg --pattern 'function $NAME($$$) { $$$ }' --lang js

Target Specific Directories: Search in likely locations first

bash

# Ripgrep
rg "LoginService" src/services/

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

Use Specific Patterns: Make patterns as specific as possible

bash

# 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

Limit Result Count: Use head to cap results

bash

# 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:

bash

# 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:

bash

# 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

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

Example of refinement:

bash

# 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)

bash

# 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)

bash

# 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

bash

# 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

cpp

html

css

json

yaml

md

Use

--type-list

to see all available types, or define custom types:

bash

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

Performance Tips

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

bash

# 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

Start Narrow, Then Broaden: Use specific patterns, file types, and directory scope from the start
Count Before Viewing: Use
```
--count
```
or
```
| head -N
```
to preview result volume
Always Specify File Types: Use
```
--type
```
(rg) or
```
--lang
```
(sg) to filter by language

Exclude Common Noise: Add

--glob '!{node_modules,venv,.git,dist,build}'

habitually

Combine Tools: Use
```
rg
```
for text patterns,
```
sg
```
for structural code patterns
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

file-search

NPX Install

Tags

SKILL.md Content

File Search Skill

Purpose

When to Use This Skill

Invoking Search Tools

Targeting Your Searches

Scope-Limiting Strategies

Progressive Search Refinement

When You Get Too Many Results

How to Use

Ripgrep (rg)

AST-Grep (sg)

Common Search Patterns

File Type Filters

Performance Tips

Best Practices

Troubleshooting

Resources