Project Analysis Skill

Perform comprehensive analysis of a project codebase to understand its structure, architecture, key files, and dependencies.

When to Use

Activate when:

• User asks "analyze this project" or "what does this codebase look like?"
• Starting work on an unfamiliar codebase
• Reviewing project architecture before making changes
• Generating documentation about project structure
• Understanding dependency landscape

Analysis Workflow

Step 1: Initial Scan

Scan the codebase to get a high-level overview:

• Total files and lines of code
• Languages detected and their distribution
• File type breakdown
• Directory structure overview

If a recent scan exists, retrieve cached scan results instead of rescanning.

Step 2: Understand Project Type

Based on scan results, identify the project type:

Step 3: Read Key Files

Examine critical files:

Always check:

• README.md - Project purpose and documentation
• package.json / Cargo.toml / pyproject.toml - Dependencies and metadata

Check if they exist:

• tsconfig.json / vite.config.ts / webpack.config.js - Build configuration
• Dockerfile / docker-compose.yml - Container setup
• .env.example - Environment variables
• CONTRIBUTING.md - Development workflow

Step 4: Explore Architecture

Explore the directory layout:

1. List the root directory to see top-level structure
2. List key directories (src/, lib/, app/, etc.) to understand component organization
3. Identify architectural patterns:

Step 5: Analyze Dependencies

Read the dependency file to understand:

• Runtime dependencies: Core libraries the project relies on
• Dev dependencies: Build tools, test frameworks, linters
• Package manager: npm, yarn, pnpm, cargo, pip, etc.
• Dependency count: Overall complexity indicator

Output Format

Present analysis in this structure:

## Project Analysis: [Name]

### Overview
- **Type**: [Web app / API / CLI / Library / etc.]
- **Primary Language**: [language] (X%)
- **Secondary Languages**: [languages]
- **Total Files**: X
- **Total Lines**: X

### Architecture
- **Pattern**: [MVC / Layered / Feature-based / etc.]
- **Key Directories**:
  - `src/commands/` - CLI command implementations
  - `src/services/` - Business logic layer
  - `src/tools/` - AI tool definitions
  - `src/utils/` - Shared utilities

### Key Files
| File | Purpose |
|------|---------|
| `index.ts` | Application entry point |
| `package.json` | Dependencies and scripts |
| `tsconfig.json` | TypeScript configuration |

### Dependencies
- **Package Manager**: [npm/yarn/pnpm]
- **Runtime** (X packages): [key ones listed]
- **Development** (Y packages): [key ones listed]

### Observations
- [Notable patterns or concerns]
- [Suggested improvements]

Analysis Depth Levels

Quick Overview

1. Retrieve cached scan results, or perform a fresh scan
2. Present file count, languages, and structure summary

Standard Analysis

1. Scan project
2. Read README and dependency file
3. List key directories
4. Present full analysis

Deep Dive

1. Scan project
2. Read all key configuration files
3. Explore all major directories
4. Read entry points and core modules
5. Present comprehensive analysis with architecture diagram suggestions

Best Practices

1. Start with cached data: Check for cached scan results first; only perform a fresh scan if no cache exists
2. Read before concluding: Don't guess architecture from file names alone; read key files
3. Be specific: Name actual files and directories, don't generalize
4. Suggest next steps: After analysis, recommend architecture diagramming or dependency mapping
5. Note concerns: Flag large files, missing docs, or unusual patterns