codebase-search_skill

Overview

This skill helps you search and navigate large codebases efficiently to find functions, trace call paths, and understand architecture. It supports semantic search, exact-text grep, glob-based file discovery, and AST-aware inspections. Use it to locate bugs, analyze impact before changes, or explore unfamiliar legacy code. The goal is fast, repeatable discovery and clear next steps for reading or modifying code.

How this skill works

The skill combines three search strategies: semantic queries to locate concepts across the codebase, grep/regex for precise text matches, and glob patterns for file discovery. It guides a layered workflow: start broad with semantic search, narrow with targeted grep inside relevant directories, then read files and follow imports or call sites. Advanced steps include tracing data flow, finding all callsites and tests, and using git blame or logs for historical context.

When to use it

• Finding where a feature, function, or class is implemented
• Tracing callchains and data flow end-to-end
• Locating the source of an error or unexpected behavior
• Performing impact analysis before refactoring or deleting code
• Discovering configuration, environment variables, or constants

Best practices

• Start broad (semantic) then narrow (grep + directory targeting)
• Read surrounding context, not just matching lines
• Use file-type filters and globs to reduce noise
• Check git history (git blame, git log) for why code exists
• Document findings and verify assumptions against tests
• Use IDE Go to Definition/Find References for faster local navigation

Example use cases

• Find where user authentication is implemented: semantic search for authentication -> grep in auth/ for verify_token -> read jwt.py
• Locate bug source: grep the exact error message -> read file -> semantic query for what triggers it -> check related tests
• Prepare a refactor: grep all callsites of function_to_change -> glob for tests -> run semantic queries to find dependent subsystems
• Add a feature: semantic search for similar feature implementations -> identify controllers/services -> read tests for patterns to follow
• Code archaeology: semantic search for legacy term -> follow imports and build a dependency map