Codebase Navigation
What This Skill Enables
An agent that can quickly orient itself in any codebase - finding the right files, understanding the architecture, and identifying conventions - before writing a single line of code. Agents without this skill guess at file locations, miss existing utilities, and create duplicates.
Core Competencies
1. Project Reconnaissance
Before touching code, build a mental map:
- Read
README.md, CONTRIBUTING.md, and any project-level config files
- Identify the package manager and build system (
package.json, pyproject.toml, Cargo.toml, go.mod)
- Map the directory structure - where does source live? Tests? Config? Docs?
- Identify the entry point(s) of the application
2. Convention Detection
Infer the project's conventions from existing code:
- Naming: camelCase vs snake_case vs kebab-case - match what exists
- File organization: feature-based vs layer-based vs hybrid
- Import style: relative vs absolute, barrel files, path aliases
- Testing conventions: co-located tests vs separate
__tests__ directory, naming patterns
- Error handling: custom error classes, result types, try/catch patterns
3. Dependency Mapping
Trace how components connect:
- Follow imports from the entry point to understand the call graph
- Identify shared utilities and where they live
- Locate configuration and environment variable usage
- Map database models/schemas to their consumers
- Identify external API integrations and their client modules
4. Search Strategies
Use the right tool for each search type:
| Goal |
Strategy |
| Find a file by name |
Glob patterns: **/UserService.*, **/*.config.* |
| Find where a function is defined |
Grep for function name( or def name or class Name |
| Find where a function is called |
Grep for the function name, exclude the definition file |
| Understand data flow |
Start at the API endpoint, follow the handler chain inward |
| Find related tests |
Look for files matching *.test.*, *.spec.*, or test_* near the source |
5. Architecture Recognition
Identify common architectural patterns:
- MVC/MVVM: Models, views/templates, controllers/viewmodels in separate directories
- Clean Architecture: Domain/entities at the core, use cases, adapters, infrastructure at edges
- Microservices: Multiple
services/ or separate packages with their own entry points
- Monorepo:
packages/ or apps/ directory with shared libraries
- Serverless: Function handlers in
functions/ or lambdas/, infrastructure as code nearby
Behavioral Rules
- Read before writing - Never create a file without first searching for an existing one that does the same thing
- Match conventions - New code should be indistinguishable from existing code in style
- Minimize exploration scope - Start narrow (the specific module), widen only when needed
- Document what you find - If the architecture isn't documented, note your findings for context
- Respect boundaries - If the project separates concerns into layers, don't bypass them
Failure Modes
| Failure |
Symptom |
Correction |
| Skipping reconnaissance |
Creating files in wrong locations |
Always map the project before writing |
| Ignoring conventions |
Code looks foreign in the PR diff |
Read 3-5 existing files in the same area first |
| Shallow search |
Missing existing utilities, creating duplicates |
Search by concept, not just by exact name |
| Assuming structure |
"I expect a utils/ folder" when the project uses lib/shared/ |
Let the project tell you its structure |
1---2name: codebase-navigation3description: Efficiently explore, map, and understand unfamiliar codebases before making changes.4---56# Codebase Navigation78## What This Skill Enables9An agent that can quickly orient itself in any codebase - finding the right files, understanding the architecture, and identifying conventions - before writing a single line of code. Agents without this skill guess at file locations, miss existing utilities, and create duplicates.1011## Core Competencies1213### 1. Project Reconnaissance14Before touching code, build a mental map:15- Read `README.md`, `CONTRIBUTING.md`, and any project-level config files16- Identify the package manager and build system (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`)17- Map the directory structure - where does source live? Tests? Config? Docs?18- Identify the entry point(s) of the application1920### 2. Convention Detection21Infer the project's conventions from existing code:22- **Naming**: camelCase vs snake_case vs kebab-case - match what exists23- **File organization**: feature-based vs layer-based vs hybrid24- **Import style**: relative vs absolute, barrel files, path aliases25- **Testing conventions**: co-located tests vs separate `__tests__` directory, naming patterns26- **Error handling**: custom error classes, result types, try/catch patterns2728### 3. Dependency Mapping29Trace how components connect:30- Follow imports from the entry point to understand the call graph31- Identify shared utilities and where they live32- Locate configuration and environment variable usage33- Map database models/schemas to their consumers34- Identify external API integrations and their client modules3536### 4. Search Strategies37Use the right tool for each search type:3839| Goal | Strategy |40|------|----------|41| Find a file by name | Glob patterns: `**/UserService.*`, `**/*.config.*` |42| Find where a function is defined | Grep for `function name(` or `def name` or `class Name` |43| Find where a function is called | Grep for the function name, exclude the definition file |44| Understand data flow | Start at the API endpoint, follow the handler chain inward |45| Find related tests | Look for files matching `*.test.*`, `*.spec.*`, or `test_*` near the source |4647### 5. Architecture Recognition48Identify common architectural patterns:49- **MVC/MVVM**: Models, views/templates, controllers/viewmodels in separate directories50- **Clean Architecture**: Domain/entities at the core, use cases, adapters, infrastructure at edges51- **Microservices**: Multiple `services/` or separate packages with their own entry points52- **Monorepo**: `packages/` or `apps/` directory with shared libraries53- **Serverless**: Function handlers in `functions/` or `lambdas/`, infrastructure as code nearby5455## Behavioral Rules56571. **Read before writing** - Never create a file without first searching for an existing one that does the same thing582. **Match conventions** - New code should be indistinguishable from existing code in style593. **Minimize exploration scope** - Start narrow (the specific module), widen only when needed604. **Document what you find** - If the architecture isn't documented, note your findings for context615. **Respect boundaries** - If the project separates concerns into layers, don't bypass them6263## Failure Modes6465| Failure | Symptom | Correction |66|---------|---------|------------|67| Skipping reconnaissance | Creating files in wrong locations | Always map the project before writing |68| Ignoring conventions | Code looks foreign in the PR diff | Read 3-5 existing files in the same area first |69| Shallow search | Missing existing utilities, creating duplicates | Search by concept, not just by exact name |70| Assuming structure | "I expect a `utils/` folder" when the project uses `lib/shared/` | Let the project tell you its structure |
varunk130