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