codebase-search skill
Enables agents to search and navigate large codebases using semantic search, grep patterns, and AST analysis to find functions, bugs, and architecture.
- GitHub stars
- 113
- Files
- 1
- Last commit
- Nov 1, 2026
- License
- MIT
- Allowed tools
- 4
What does the codebase-search skill do?
codebase-search enables agents to search and navigate large codebases using semantic search, grep patterns, and AST analysis to find functions, bugs, and architecture.
Summary generated from the skill's SKILL.md.
About the codebase-search skill
Navigating and exploring large codebases is what this skill enables for developers using AI clients like Claude, ChatGPT, or Gemini. It provides a structured way to locate specific functions, trace dependencies, and understand complex software architecture through multiple search methodologies. An agent should load this skill when it needs to perform code archaeology, conduct impact analysis before making changes, or debug an issue by tracing data flow.
The skill utilizes a combination of semantic search for conceptual queries, grep for precise pattern matching, and globbing for file discovery. It also relies on tools such as Read, Grep, Glob, and Bash to interact with the file system. By combining these methods, an agent can move from broad conceptual questions to specific line-by-line analysis, allowing it to identify everything from configuration settings to error handling patterns across various programming languages.
What an agent can do with it
- 1Trace function dependenciesAn agent can find all locations where a specific function is called to understand its impact.
- 2Locate specific bugsDevelopers can use exact error messages to find the source of a runtime issue.
- 3Explore new codebasesUse semantic search to find application entry points and data models in unfamiliar projects.
- 4Identify configuration filesQuickly discover all configuration files within a project using pattern matching.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the codebase-search skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the codebase-search skill in Claude Code
~/.claude/skills/codebase-search/SKILL.md
$ npx degit tmcfarlane/team-avatar/skills/codebase-search ~/.claude/skills/codebase-searchInstall the codebase-search skill in Claude Code (project)
.claude/skills/codebase-search/SKILL.md
$ npx degit tmcfarlane/team-avatar/skills/codebase-search .claude/skills/codebase-searchInstall the codebase-search skill in Codex
~/.agents/skills/codebase-search/SKILL.md
$ npx degit tmcfarlane/team-avatar/skills/codebase-search ~/.agents/skills/codebase-searchInstall the codebase-search skill in Gemini CLI
~/.gemini/skills/codebase-search/SKILL.md
$ npx degit tmcfarlane/team-avatar/skills/codebase-search ~/.gemini/skills/codebase-searchInstall the codebase-search skill in Claude.ai
npx degit tmcfarlane/team-avatar/skills/codebase-search codebase-search && zip -r codebase-search.zip codebase-search # claude.ai → Customize → Skills → + → Create skill → Upload a skill → codebase-search.zip
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A skill needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabletmcfarlane/team-avatar/skills/codebase-search is public and reachablegithub.com/tmcfarlane/team-avatar/tree/HEAD/skills/codebase- ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-01github.com/tmcfarlane/team-avatar/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/tmcfarlane/team-avatar/blob/HEAD/skills/codebase- ↗Pass
- Pre-approved tools are scopedBash lets the agent run any shell command without askinggithub.com/tmcfarlane/team-avatar/blob/HEAD/skills/codebase- ↗Finding
- SKILL.md follows the Agent Skills formatSKILL.md is 533 lines; the spec suggests under 500github.com/tmcfarlane/team-avatar/blob/HEAD/skills/codebase- ↗Finding
SKILL.md
View on GitHubCodebase Search
When to use this skill
- Finding specific functions or classes
- Tracing function calls and dependencies
- Understanding code structure and architecture
- Finding usage examples
- Identifying code patterns
- Locating bugs or issues
- Code archaeology (understanding legacy code)
- Impact analysis before changes
Instructions
Step 1: Understand what you're looking for
Feature implementation:
- Where is feature X implemented?
- How does feature Y work?
- What files are involved in feature Z?
Bug location:
- Where is this error coming from?
- What code handles this case?
- Where is this data being modified?
API usage:
- How is this API used?
- Where is this function called?
- What are examples of using this?
Configuration:
- Where are settings defined?
- How is this configured?
- What are the config options?
Step 2: Choose search strategy
Semantic search (for conceptual questions):
Use when: You understand what you're looking for conceptually
Examples:
- "How do we handle user authentication?"
- "Where is email validation implemented?"
- "How do we connect to the database?"
Benefits:
- Finds relevant code by meaning
- Works with unfamiliar codebases
- Good for exploratory searches
Grep (for exact text/patterns):
Use when: You know exact text or patterns
Examples:
- Function names: "def authenticate"
- Class names: "class UserManager"
- Error messages: "Invalid credentials"
- Specific strings: "API_KEY"
Benefits:
- Fast and precise
- Works with regex patterns
- Good for known terms
Glob (for file discovery):
Use when: You need to find files by pattern
Examples:
- "**/*.test.js" (all test files)
- "**/config*.yaml" (config files)
- "src/**/*Controller.py" (controllers)
Benefits:
- Quickly find files by type
- Discover file structure
- Locate related files
Step 3: Search workflow
1. Start broad, then narrow:
Step 1: Semantic search "How does authentication work?"
Result: Points to auth/ directory
Step 2: Grep in auth/ for specific function
Pattern: "def verify_token"
Result: Found in auth/jwt.py
Step 3: Read the file
File: auth/jwt.py
Result: Understand implementation
2. Use directory targeting:
# Start without target (search everywhere)
Query: "Where is user login implemented?"
Target: []
# Refine with specific directory
Query: "Where is login validated?"
Target: ["backend/auth/"]
3. Combine searches:
# Find where feature is implemented
Semantic: "user registration flow"
# Find all files involved
Grep: "def register_user"
# Find test files
Glob: "**/*register*test*.py"
# Understand the implementation
Read: registration.py, test_registration.py
Step 4: Common search patterns
Find function definition:
# Python
grep -n "def function_name" --type py
# JavaScript
grep -n "function functionName" --type js
grep -n "const functionName = " --type js
# TypeScript
grep -n "function functionName" --type ts
grep -n "export const functionName" --type ts
# Go
grep -n "func functionName" --type go
# Java
grep -n "public.*functionName" --type java
Find class definition:
# Python
grep -n "class ClassName" --type py
# JavaScript/TypeScript
grep -n "class ClassName" --type js,ts
# Java
grep -n "public class ClassName" --type java
# C++
grep -n "class ClassName" --type cpp
Find class/function usage:
# Python
grep -n "ClassName(" --type py
grep -n "function_name(" --type py
# JavaScript
grep -n "new ClassName" --type js
grep -n "functionName(" --type js
Find imports/requires:
# Python
grep -n "from.*import.*ModuleName" --type py
grep -n "import.*ModuleName" --type py
# JavaScript
grep -n "import.*from.*module-name" --type js
grep -n "require.*module-name" --type js
# Go
grep -n "import.*package-name" --type go
Find configuration:
# Config files
glob "**/*config*.{json,yaml,yml,toml,ini}"
# Environment variables
grep -n "process\\.env\\." --type js
grep -n "os\\.environ" --type py
# Constants
grep -n "^[A-Z_]+\\s*=" --type py
grep -n "const [A-Z_]+" --type js
Find TODO/FIXME:
grep -n "TODO|FIXME|HACK|XXX" -i
Find error handling:
# Python
grep -n "try:|except|raise" --type py
# JavaScript
grep -n "try|catch|throw" --type js
# Go
grep -n "if err != nil" --type go
Step 5: Advanced techniques
Trace data flow:
1. Find where data is created
Semantic: "Where is user object created?"
2. Search for variable usage
Grep: "user\\." with context lines
3. Follow transformations
Read: Files that modify user
4. Find where it's consumed
Grep: "user\\." in relevant files
Find all callsites of a function:
1. Find function definition
Grep: "def process_payment"
Result: payments/processor.py:45
2. Find all imports of that module
Grep: "from payments.processor import"
Result: Multiple files
3. Find all calls to the function
Grep: "process_payment\\("
Result: All callsites
4. Read each callsite for context
Read: Each file with context
Understand a feature end-to-end:
1. Find API endpoint
Semantic: "Where is user registration endpoint?"
Result: routes/auth.py
2. Trace to controller
Read: routes/auth.py
Find: Calls to AuthController.register
3. Trace to service
Read: controllers/auth.py
Find: Calls to UserService.create_user
4. Trace to database
Read: services/user.py
Find: Database operations
5. Find tests
Glob: "**/*auth*test*.py"
Read: Test files for examples
Find related files:
1. Start with known file
Example: models/user.py
2. Find imports of this file
Grep: "from models.user import"
3. Find files this imports
Read: models/user.py
Note: Import statements
4. Build dependency graph
Map: All related files
Impact analysis:
Before changing function X:
1. Find all callsites
Grep: "function_name\\("
2. Find all tests
Grep: "test.*function_name" -i
3. Check related functionality
Semantic: "What depends on X?"
4. Review each usage
Read: Each file using function
5. Plan changes
Document: Impact and required updates
Step 6: Search optimization
Use appropriate context:
# See surrounding context
grep -n "pattern" -C 5 # 5 lines before and after
grep -n "pattern" -B 3 # 3 lines before
grep -n "pattern" -A 3 # 3 lines after
Case sensitivity:
# Case insensitive
grep -n "pattern" -i
# Case sensitive (default)
grep -n "Pattern"
File type filtering:
# Specific type
grep -n "pattern" --type py
# Multiple types
grep -n "pattern" --type py,js,ts
# Exclude types
grep -n "pattern" --glob "!*.test.js"
Regex patterns:
# Any character: .
grep -n "function.*Name"
# Start of line: ^
grep -n "^class"
# End of line: $
grep -n "TODO$"
# Optional: ?
grep -n "function_name_?()"
# One or more: +
grep -n "[A-Z_]+"
# Zero or more: *
grep -n "import.*"
# Alternatives: |
grep -n "TODO|FIXME"
# Groups: ()
grep -n "(get|set)_user"
# Escape special chars: \
grep -n "function\(\)"
Best practices
- Start with semantic search: For unfamiliar code or conceptual questions
- Use grep for precision: When you know exact terms
- Combine multiple searches: Build understanding incrementally
- Read surrounding context: Don't just look at matching lines
- Check file history: Use
git blamefor context - Document findings: Note important discoveries
- Verify assumptions: Read actual code, don't assume
- Use directory targeting: Narrow scope when possible
- Follow the data: Trace data flow through the system
- Check tests: Tests often show usage examples
Common search scenarios
Scenario 1: Understanding a bug
1. Find error message
Grep: "exact error message"
2. Find where it's thrown
Read: File with error
3. Find what triggers it
Semantic: "What causes X error?"
4. Find related code
Grep: Related function names
5. Check tests
Glob: "**/*test*.py"
Look: For related test cases
Scenario 2: Learning a new codebase
1. Find entry point
Semantic: "Where does the application start?"
Common files: main.py, index.js, app.py
2. Find main routes/endpoints
Grep: "route|endpoint|@app\\."
3. Find data models
Semantic: "Where are data models defined?"
Common: models/, entities/
4. Find configuration
Glob: "**/*config*"
5. Read README and docs
Read: README.md, docs/
Scenario 3: Refactoring preparation
1. Find all usages
Grep: "function_to_change"
2. Find tests
Grep: "test.*function_to_change"
3. Find dependencies
Semantic: "What does X depend on?"
4. Check imports
Grep: "from.*import.*X"
5. Document scope
List: All affected files
Scenario 4: Adding a feature
1. Find similar features
Semantic: "How is similar feature implemented?"
2. Find where to add code
Semantic: "Where should new feature go?"
3. Check patterns
Read: Similar implementations
4. Find tests to emulate
Glob: Test files for similar features
5. Check documentation
Grep: "TODO.*new feature" -i
Tools integration
Git integration:
# Who changed this line?
git blame filename
# History of a file
git log -p filename
# Find when function was added
git log -S "function_name" --source --all
# Find commits mentioning X
git log --grep="feature name"
IDE integration:
- Use "Go to Definition" for quick navigation
- Use "Find References" for usage
- Use "Find in Files" for broad search
- Use symbol search for classes/functions
Documentation:
- Check inline comments
- Look for docstrings
- Read README files
- Check architecture docs
Troubleshooting
No results found:
- Check spelling and case sensitivity
- Try semantic search instead of grep
- Broaden search scope (remove directory target)
- Try different search terms
- Check if files are in .gitignore
Too many results:
- Add directory targeting
- Use more specific patterns
- Filter by file type
- Use exact phrases (quotes)
Wrong results:
- Be more specific in query
- Use grep instead of semantic for exact terms
- Add context to semantic queries
- Check file types
References
Examples
Example 1: Basic usage
Example 2: Advanced usage
Files in this skill
1codebase-search skill questions
How do I install the codebase-search skill in Claude Code?
Run npx degit tmcfarlane/team-avatar/skills/codebase-search ~/.claude/skills/codebase-search. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the codebase-search skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
When should I use semantic search versus grep?
Use semantic search for conceptual questions like 'How is authentication handled?' and grep for exact text or patterns like specific function names or error messages.