# Searcher

> Use this skill when the user wants to search for files by text content, find files containing specific text, or get a list of file paths related to a search term. The skill searches the codebase and returns matching file paths with context.

- Skill: `majiayu000/searcher` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/searcher`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/searcher/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/searcher

---


# File Searcher Skill

This skill searches for files in the codebase based on text content and returns a list of matching file paths.

## Core Principles

1. **Use Grep tool**: Always use the Grep tool for searching - never use bash grep/rg commands
2. **Return file paths**: Provide a clear list of file paths that match the search criteria
3. **Include context**: Show relevant context (line numbers, matching lines) to help users understand results
4. **Flexible search**: Support different search modes (content, files_only, count)

## Search Workflow

### Step 1: Understand the Search Request

Clarify what the user wants to find:
- **Text/Pattern**: The specific text or regex pattern to search for
- **Scope**: Entire codebase or specific directory
- **File Type**: Optional filter (e.g., only .py, .js files)

### Step 2: Choose the Appropriate Search Mode

Use Grep with these parameters:

| Parameter | Description | Common Values |
|-----------|-------------|---------------|
| `pattern` | The search term or regex | User's search text |
| `output_mode` | What to return | `files_with_matches` (default), `content`, `count` |
| `path` | Directory to search | Current directory or specific path |
| `glob` | Filter by file pattern | `*.py`, `**/*.js`, etc. |
| `type` | Filter by file type | `py`, `js`, `ts`, etc. |
| `-i` | Case insensitive search | `true` or `false` |
| `-C` | Context lines | Number of lines before/after match |

### Step 3: Execute the Search

```markdown
Use Grep tool with:
- pattern: <search term>
- output_mode: "files_with_matches" for just file paths, "content" for lines with context
```

### Step 4: Present Results

Format the output clearly:
- **Matching files**: List all file paths found
- **Match count**: Total number of files
- **Excerpts** (optional): Show relevant lines from matches
- **Next steps**: Suggest actions like "Read specific file", "Narrow search", etc.

## Common Search Patterns

### Find files containing specific text
```
Grep: pattern="search term", output_mode="files_with_matches"
```

### Find text with context (showing matching lines)
```
Grep: pattern="search term", output_mode="content", -C=2
```

### Case-insensitive search
```
Grep: pattern="search term", -i=true
```

### Search specific file types
```
Grep: pattern="search term", type="py"
Grep: pattern="search term", glob="*.md"
```

### Count matches per file
```
Grep: pattern="search term", output_mode="count"
```

## Example Usage

**User request**: "Find all files that contain 'TODO' comments"

**Skill response**:
1. Search: `Grep: pattern="TODO", output_mode="content", -C=1`
2. Results: List file paths with TODO lines and line numbers
3. Summary: "Found 5 files with TODO comments"

**User request**: "Search for 'function' in Python files only"

**Skill response**:
1. Search: `Grep: pattern="function", type="py", output_mode="files_with_matches"`
2. Results: List matching .py files
3. Summary: "Found 3 Python files containing 'function'"

## Tips for Better Searches

- **Start broad**: Use `files_with_matches` first, then drill down with `content` mode
- **Use regex patterns**: Grep supports full regex syntax for complex searches
- **Filter by type**: Use `type` or `glob` to narrow search scope
- **Case sensitivity**: Use `-i=true` when the exact case doesn't matter
- **Context**: Use `-C` to see lines around matches for better understanding