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

• 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