---
name: code-searcher
description: Delegates codebase searches to a lightweight agent. Use when searching for existing implementations, classes, or functions without loading search results into context.
---

# Code Searcher Skill

This skill delegates codebase searches to a specialized lightweight agent, keeping your context lean.

## When to Invoke This Skill

Invoke this skill when ANY of these conditions are true:

1. **Before implementing**: You need to check if a class, function, or service already exists
2. **Finding reusable code**: You want to find existing implementations to reuse or extend
3. **Duplicate prevention**: You need to verify you're not creating something that exists
4. **Pattern discovery**: You want to find how similar functionality is implemented elsewhere
5. **Dependency tracing**: You need to find where a class or function is used

## Why Use This Skill?

**Without this skill**: You would use Grep/Glob directly, loading potentially hundreds of lines of search results into your context.

**With this skill**: The code-searcher agent (haiku model) performs targeted searches and returns a concise summary with file:line references.

**Context savings**: 70-90% reduction in search-related context usage.

## Invocation

When you need to find existing implementations, invoke the agent:

```
Task(subagent_type="code-searcher", prompt="
Search for: User authentication service
Purpose: Handle login, logout, session management
Patterns to check: auth, login, session, authenticate, AuthService
")
```

For specific class/function searches:

```
Task(subagent_type="code-searcher", prompt="
Search for: EmailValidator class or function
Purpose: Validate email format
Patterns to check: email, validate, validator, EmailValidator, isValidEmail
")
```

For repository/data access searches:

```
Task(subagent_type="code-searcher", prompt="
Search for: Order repository or data access
Purpose: CRUD operations for orders
Patterns to check: order, OrderRepo, OrderRepository, order_repository, OrderDAO
")
```

## What code-searcher Will Do

The agent will:

1. **Identify search terms**: Extract key terms and naming variations
2. **Search for exact matches**: Find class/function definitions with exact names
3. **Search for similar implementations**: Find related code that could be reused
4. **Analyze findings**: Determine if existing code can be used directly or extended
5. **Return summary**: Concise results with file:line locations and recommendations

## Expected Output

You will receive a structured summary like:

```
## Code Search Results

### Exact Matches
- [src/services/auth_service.py:15] `AuthService` - Handles authentication with JWT tokens

### Similar Implementations
- [src/services/user_service.py:8] `UserService` - User CRUD, has `verify_password` method
- [src/utils/session.py:22] `SessionManager` - Session storage and retrieval

### Recommendation
- **MODIFY_EXISTING**: [src/services/auth_service.py:15] - AuthService exists but missing logout

### Notes
- Project uses JWT tokens (see auth_service.py)
- Sessions stored in Redis (see session.py)
- Follow existing pattern: services return Result objects
```

## Recommendation Types

The agent returns one of three recommendations:

| Recommendation | Meaning | Action |
|----------------|---------|--------|
| **USE_EXISTING** | Exact match found | Import and use directly |
| **MODIFY_EXISTING** | Similar found | Extend or modify existing code |
| **CREATE_NEW** | Nothing found | Implement from scratch |

## Example Usage

**Scenario**: You need to implement a payment processing service.

**Without skill**: Run multiple Grep searches, read through results, manually identify matches.

**With skill**:
```
Task(subagent_type="code-searcher", prompt="
Search for: Payment processing service
Purpose: Handle payment transactions, refunds, webhooks
Patterns to check: payment, PaymentService, transaction, stripe, checkout
")
```

**Result**: You know there's a `StripeClient` at `src/clients/stripe.py:10` you can use, saving implementation time.

## Do NOT Invoke When

- You already know exactly which file to read (use Read directly)
- You're searching for a specific string in a known file (use Grep directly)
- The search is very simple (single term, obvious location)
- You just ran code-searcher for the same or similar query

## Consumers

This skill is particularly useful for:
- `coder` - Before implementing new functionality
- `codebase-analyst` - Finding reuse opportunities in specs
- `verifier` - Checking if implementations exist
- `refactorer` - Finding code to consolidate
- `architect` - Understanding existing capabilities