Codebase Analysis Skill
Objective
Perform comprehensive, systematic analysis of project codebases to understand:
- Project structure and organization
- Technology stack and dependencies
- Architectural patterns and conventions
- Code complexity and quality metrics
- Key components and their relationships
When to Use This Skill
Auto-invoke when:
- Starting work on a new project
- User asks to "analyze", "review", "audit", or "understand" the codebase
- Before making architectural decisions
- Planning refactoring or major changes
- Onboarding new developers
Analysis Methodology
Phase 1: Discovery (Project Structure)
Goal: Map the high-level project organization
Tools: Glob, LS, Read
Process:
- Identify project type by reading
package.json,tsconfig.json, or framework-specific configs - Map directory structure using LS at root level:
Key directories to identify: - Source code: src/, app/, pages/, components/ - Tests: __tests__/, tests/, *.test.*, *.spec.* - Config: config/,.config/ - Documentation: docs/, README.md - Build output: dist/, build/,.next/ - Scan for important files:
- Build configs: vite.config.*, webpack.config.*, next.config.* - TypeScript: tsconfig.json, tsconfig.*.json - Package management: package.json, package-lock.json, yarn.lock, pnpm-lock.yaml - Environment: .env*, .env.example - Git: .gitignore, .git/
Phase 2: Technology Stack Analysis
Goal: Identify frameworks, libraries, and versions
Tools: Read, Grep
Process:
- Read package.json:
- Extract dependencies (runtime libraries) - Extract devDependencies (development tools) - Note scripts (available commands) - Check engines (Node.js version requirements)
- Identify framework:
- Next.js: Check for next in dependencies, next.config.*, app/ or pages/ directory - React: Check for react and react-dom - Vue: Check for vue, *.vue files - Svelte: Check for svelte, *.svelte files - Angular: Check for @angular/core, angular.json
- Identify key libraries:
- State management: Redux, Zustand, MobX, Pinia - Routing: react-router, vue-router, next/navigation - UI libraries: MUI, Ant Design, shadcn/ui, Chakra UI - Styling: Tailwind CSS, styled-components, emotion, CSS modules - Testing: Vitest, Jest, Playwright, Cypress - Build tools: Vite, Webpack, esbuild, Turbopack
Phase 3: Architecture Pattern Analysis
Goal: Understand code organization and patterns
Tools: Grep, Glob, Read
Process:
- Component patterns (for React/Vue/Svelte):
Use Glob to find: **/*.{jsx,tsx,vue,svelte} Analyze: - Component naming conventions - File structure (co-located styles, tests) - Component size (lines of code) - API/Backend patterns:
Use Grep to search for: - API routes: "export.*GET|POST|PUT|DELETE" - Database queries: "prisma\.|mongoose\.|sql" - Authentication: "auth|jwt|session" - State management patterns:
Use Grep to find: - Context API: "createContext|useContext" - Redux: "createSlice|useSelector" - Zustand: "create.*useStore" - File organization patterns:
- Monorepo: Check for packages/, apps/, turbo.json, nx.json - Feature-based: Check for directories like features/, modules/ - Layer-based: Check for components/, services/, utils/, hooks/
Phase 4: Code Quality & Complexity Assessment
Goal: Identify potential issues and technical debt
Tools: Grep, Bash, Read
Process:
- Linting & Formatting:
- Check for: .eslintrc*, .prettierrc*, biome.json - Run linter if available: npm run lint (via Bash)
- Testing coverage:
- Find test files: Use Glob for **/*.{test,spec}.{js,ts,jsx,tsx} - Calculate coverage: Run npm run test:coverage if available
- TypeScript strictness:
- Read tsconfig.json - Check strict: true, strictNullChecks, etc. - Look for @ts-ignore or any usage (Grep)
- Code complexity indicators:
Use Grep to flag potential issues: - Large files: Find files > 500 lines - Deep nesting: Search for excessive indentation - TODO/FIXME comments: Grep for "TODO|FIXME|HACK" - Console logs: Grep for "console\.(log|debug|warn)"
Phase 5: Dependency & Security Analysis
Goal: Identify outdated or vulnerable dependencies
Tools: Bash, Read
Process:
- Check for lock files:
- Presence of package-lock.json, yarn.lock, pnpm-lock.yaml
- Run security audit (if npm/pnpm available):
npm audit --json # or pnpm audit --json - Check for outdated dependencies:
npm outdated
Output Format
Provide a structured analysis report:
# Codebase Analysis Report
## Project Overview
- **Name**: [project name from package.json]
- **Type**: [framework/library]
- **Version**: [version]
- **Node.js**: [required version]
## Technology Stack
### Core Framework
- [Framework name & version]
### Key Dependencies
- UI: [library]
- State: [library]
- Routing: [library]
- Styling: [library]
- Testing: [library]
### Build Tools
- [Vite/Webpack/etc]
## Architecture
### Directory Structure[tree-like representation of key directories]
### Patterns Identified
- [Component patterns]
- [State management approach]
- [API structure]
- [File organization]
## Code Quality Metrics
- **TypeScript**: [strict/loose/none]
- **Linting**: [ESLint/Biome/none]
- **Testing**: [X test files found, coverage: Y%]
- **Code Issues**: [TODOs: X, Console logs: Y]
## Recommendations
1. [Priority recommendation]
2. [Next priority]
3. ...
## Risk Areas
- [Potential issues or technical debt]
## Next Steps
- [Suggested actions based on analysis]Best Practices
- Progressive Detail: Start with high-level overview, dive deeper only when needed
- Context Window Management: For large codebases, analyze in chunks (by directory/feature)
- Tool Selection:
- Use Glob for file discovery (faster than find) - Use Grep for pattern search (faster than reading all files) - Use Read only for critical files (package.json, configs)
- Time Efficiency: Complete analysis in < 60 seconds for typical projects
- Actionable Insights: Always provide specific, actionable recommendations
Integration with Other Skills
This skill works well with:
quality-gates- Use analysis results to run appropriate quality checksproject-initialization- Compare against templates to identify missing setuprefactoring-safe- Identify refactoring opportunities- Framework-specific skills (
nextjs-optimization,react-patterns) - Auto-invoke based on detected framework
Error Handling
If analysis cannot complete:
- Missing dependencies: Suggest running
npm install - Corrupted files: Report specific files and continue with partial analysis
- Large codebase: Switch to targeted analysis mode (specific directories only)
- Permission issues: Request necessary file access permissions
Version History
- 1.0.0 (2025-01-03): Initial skill creation with progressive disclosure support