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:

1. Identify project type by reading package.json, tsconfig.json, or framework-specific configs
2. 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/ ``

1. 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:

1. Read package.json:

- Extract dependencies (runtime libraries) - Extract devDependencies (development tools) - Note scripts (available commands) - Check engines (Node.js version requirements)

1. 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

1. 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:

1. 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) ``

1. API/Backend patterns:

`` Use Grep to search for: - API routes: "export.*GET|POST|PUT|DELETE" - Database queries: "prisma\.|mongoose\.|sql" - Authentication: "auth|jwt|session" ``

1. State management patterns:

`` Use Grep to find: - Context API: "createContext|useContext" - Redux: "createSlice|useSelector" - Zustand: "create.*useStore" ``

1. 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:

1. Linting & Formatting:

- Check for: .eslintrc, .prettierrc, biome.json - Run linter if available: npm run lint (via Bash)

1. Testing coverage:

- Find test files: Use Glob for **/*.{test,spec}.{js,ts,jsx,tsx} - Calculate coverage: Run npm run test:coverage if available

1. TypeScript strictness:

- Read tsconfig.json - Check strict: true, strictNullChecks, etc. - Look for @ts-ignore or any usage (Grep)

1. 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:

1. Check for lock files:

- Presence of package-lock.json, yarn.lock, pnpm-lock.yaml

1. Run security audit (if npm/pnpm available):

``bash npm audit --json # or pnpm audit --json ``

1. Check for outdated dependencies:

``bash 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

1. Progressive Detail: Start with high-level overview, dive deeper only when needed
2. Context Window Management: For large codebases, analyze in chunks (by directory/feature)
3. 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)

1. Time Efficiency: Complete analysis in < 60 seconds for typical projects
2. 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 checks
• project-initialization - Compare against templates to identify missing setup
• refactoring-safe - Identify refactoring opportunities
• Framework-specific skills (nextjs-optimization, react-patterns) - Auto-invoke based on detected framework

Error Handling

If analysis cannot complete:

1. Missing dependencies: Suggest running npm install
2. Corrupted files: Report specific files and continue with partial analysis
3. Large codebase: Switch to targeted analysis mode (specific directories only)
4. Permission issues: Request necessary file access permissions

Version History

• 1.0.0 (2025-01-03): Initial skill creation with progressive disclosure support