| name | explore |
| description | Explores codebase structure, stack, and architecture. Triggers: explore codebase, project structure, stack overview, architecture map. |
| user-invocable | true |
| effort | medium |
| argument-hint | [path or question] |
| allowed-tools | Read, Grep, Glob |
Codebase Exploration
$ARGUMENTS
Explore and understand a codebase structure.
Project context
- Config files: !
find . -maxdepth 2 -type f -name "*.json" -o -name "*.toml" -o -name "*.yaml" -o -name "*.yml" 2>/dev/null | head -20
Usage
/explore [path]
What This Command Does
- Maps project structure
- Identifies technology stack
- Finds key files and patterns
- Reports architecture overview
Output Format
## Codebase Analysis Report
### Project Type
- **Language**: [TypeScript/Python/PHP/etc.]
- **Framework**: [Next.js/FastAPI/Laravel/etc.]
- **Package Manager**: [npm/pnpm/pip/composer]
### Directory Structure
project/
āāā src/ # Source code
āāā tests/ # Test files
āāā config/ # Configuration
āāā ...
### Key Files
| File | Purpose |
|------|---------|
| `src/index.ts` | Entry point |
| `src/api/` | API routes |
### Dependencies
- **Runtime**: [list]
- **Dev**: [list]
### Patterns Detected
- [Pattern 1]
- [Pattern 2]
### Entry Points
- [Entry 1]
- [Entry 2]
Technology Detection
| Marker | Technology |
|---|
package.json | Node.js |
tsconfig.json | TypeScript |
next.config.* | Next.js |
nuxt.config.* | Nuxt |
pyproject.toml | Python |
composer.json | PHP |
pubspec.yaml | Flutter/Dart |
Cargo.toml | Rust |
go.mod | Go |
When to Use
- Starting work on unfamiliar codebase
- Before planning major changes
- Understanding dependencies
- Finding specific code patterns
READ-ONLY
This skill ONLY reads and analyzes.
It does NOT write or modify any files.
Visual Output
For an interactive HTML tree visualization of the codebase:
python ${CLAUDE_SKILL_DIR}/scripts/visualize.py .
This generates codebase-map.html with collapsible directories, file sizes, and type-colored indicators.
KB Integration
smart_query("codebase analysis: {technology}")
hybrid_search_kb("project structure {framework}")
Rules
- MUST use
Glob and Grep before Read ā scan for shape before opening files
- MUST deliver a map of the codebase (entry points, layers, module boundaries), not a file listing ā a tree without interpretation is noise
- NEVER read every file sequentially; target reads via grep patterns and filename globs
- NEVER modify any file ā this is a read-only skill
- CRITICAL: when the repo contains generated code (
node_modules, vendor/, dist/, build/), exclude it from scans or the signal drowns in generated noise
- MANDATORY: summarize the stack once at the top (language, framework, package manager, test runner) before diving into structure
Gotchas
find . and ls -R ignore .gitignore by default and include node_modules, vendor/, .venv/, target/. Use git ls-files or fd / rg for a git-aware listing, or explicitly prune.
package.json says "type": "module" ā ESM; absence ā CommonJS. Mixing them without noticing produces "Cannot use import statement outside a module" errors later; call out the setting in the report.
- Frameworks with file-based routing (Next.js, Nuxt, SvelteKit) treat the
app/ or pages/ tree as the router. A directory listing alone does not reveal routes ā the framework convention does. Name the framework first, then the routes.
pyproject.toml can declare multiple project layouts (src/, flat, namespace packages). "Where is the main code" is not obvious without reading [tool.setuptools.packages] or [tool.poetry.packages].
- Large monorepos use workspaces (
pnpm-workspace.yaml, nx.json, turbo.json) with apps and packages. Treating the root as the project conceals the actual component boundaries ā surface the workspace topology first.
When NOT to Use
- To explain a specific module's design ā use
/explain
- To find a specific identifier or symbol ā use
Grep directly or /research-mastery
- To audit architecture for deepening candidates ā use
/architecture-audit
- To scaffold a new project ā use
/app-builder
- When the user already knows the codebase ā skip the overview and jump to the concrete task