exploring-codebase

Locate code, trace flows, and find usages in codebases. Use proactively for "where is", "how does", "find", "called", "used", or any code search question.

Stars 163

Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/exploring-codebase

SKILL.md

Codebase Explorer

Explore and understand codebases by locating files, tracing flows, and finding usages.

Quick Reference

Goal	Tool	When
Natural language search	`warpgrep_codebase_search`	Default choice
Semantic/conceptual search	`finder`	Fallback if warpgrep unclear
Exact string/pattern	`Grep`	Last resort, precise matches

Complexity Guide

Query	Approach
Simple (≤3 searches)	Call tools directly
Complex (>3 searches)	Spawn Task subagent

Examples

Simple: Find a function

User: "where is the auth middleware?"
→ warpgrep_codebase_search(search_string='where is auth middleware defined')
→ Return: file paths with line numbers

Moderate: Trace a flow

User: "how does the search API work?"
→ warpgrep_codebase_search(search_string='search API endpoint handler')
→ Read relevant files
→ warpgrep_codebase_search(search_string='search service calls database')
→ Return: summary with file paths

Complex: Debug investigation

User: "why is the background job failing?"
→ Task(
    description: "Investigate background job failure",
    prompt: "Find all code related to background job execution.
    Use warpgrep_codebase_search for: job scheduler, job handler, error handling.
    Read relevant files and trace the flow.
    Return: summary of job lifecycle with file paths and potential failure points."
  )

Fallback Chain

Issue	Action
No results	Broaden query, remove specific terms
Too many results	Add file path filter, use Grep for exact match
Wrong results	Rephrase with different terminology
Warpgrep unavailable	Use finder, then Grep

Output Format

Always include file paths with line numbers
Group findings by file
End with concise summary for complex investigations