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
When NOT to use: For questions about a single file or feature, just read the relevant file directly — a full analysis is overkill.
Analysis Workflow
Step 1: Survey the Codebase
Build a high-level overview using standard filesystem operations:
- List the directory tree with
ls or Glob to see top-level structure
- Read manifest files to identify the stack:
package.json, go.mod, pyproject.toml, Cargo.toml, Gemfile, pom.xml, etc.
- If useful, count files by extension to gauge language distribution, e.g.
find . -name '*.ts' -not -path '*/node_modules/*' | wc -l
Step 2: Understand Project Type
Based on what the survey found, identify the project type:
| Indicator |
Project Type |
| package.json + React/Next.js |
Web application |
| package.json + Express/Fastify |
API server |
| Cargo.toml |
Rust project |
| pyproject.toml / setup.py |
Python project |
| go.mod |
Go project |
| Dockerfile + docker-compose |
Containerized service |
| index.ts + bin/ |
CLI tool |
Step 3: Read Key Files
Examine critical files:
Always check:
README.md - Project purpose and documentationpackage.json / Cargo.toml / pyproject.toml - Dependencies and metadata
Check if they exist:
tsconfig.json / vite.config.ts / webpack.config.js - Build configurationDockerfile / docker-compose.yml - Container setup.env.example - Environment variablesCONTRIBUTING.md - Development workflow
Step 4: Explore Architecture
List key directories (src/, lib/, app/, etc.) to understand component organization, then identify architectural patterns:
| Pattern |
Indicators |
| MVC |
controllers/, models/, views/ directories |
| Layered |
services/, repositories/, handlers/ |
| Feature-based |
Feature directories with co-located files |
| Monorepo |
packages/ or apps/ directories |
| Microservices |
Multiple service directories with own configs |
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
Analysis Depth
Scale depth to the request — quick = structure + project type only; deep = all steps plus reading entry points and core modules.
Output Format
Present analysis in this structure:
## Project Analysis: [Name]
### Overview
- **Type**: [Web app / API / CLI / Library / etc.]
- **Primary Language**: [language] (X%)
- **Total Files**: X
### Architecture
- **Pattern**: [MVC / Layered / Feature-based / etc.]
- **Key Directories**:
- `src/commands/` - CLI command implementations
- `src/services/` - Business logic layer
### Key Files
| File | Purpose |
|------|---------|
| `index.ts` | Application entry point |
| `package.json` | Dependencies and scripts |
### 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]
Best Practices
- Be specific: Name actual files and directories, don't generalize
- Note concerns: Flag large files, missing docs, or unusual patterns
Common Mistakes
- Don't guess architecture from file names alone — read key files before concluding
- Don't include vendored/generated directories (node_modules, dist, target) in counts or structure
1---2name: project-analysis3description: Use when starting work on an unfamiliar codebase or asked to 'analyze this project' - maps structure, project type, architecture pattern, key files, and dependencies into a standard report4---56# Project Analysis Skill78Perform comprehensive analysis of a project codebase to understand its structure, architecture, key files, and dependencies.910## When to Use1112Activate when:13- User asks "analyze this project" or "what does this codebase look like?"14- Starting work on an unfamiliar codebase15- Reviewing project architecture before making changes16- Generating documentation about project structure17- Understanding dependency landscape1819**When NOT to use**: For questions about a single file or feature, just read the relevant file directly — a full analysis is overkill.2021## Analysis Workflow2223### Step 1: Survey the Codebase2425Build a high-level overview using standard filesystem operations:26271. List the directory tree with `ls` or Glob to see top-level structure282. Read manifest files to identify the stack: `package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml`, `Gemfile`, `pom.xml`, etc.293. If useful, count files by extension to gauge language distribution, e.g. `find . -name '*.ts' -not -path '*/node_modules/*' | wc -l`3031### Step 2: Understand Project Type3233Based on what the survey found, identify the project type:3435| Indicator | Project Type |36|-----------|-------------|37| package.json + React/Next.js | Web application |38| package.json + Express/Fastify | API server |39| Cargo.toml | Rust project |40| pyproject.toml / setup.py | Python project |41| go.mod | Go project |42| Dockerfile + docker-compose | Containerized service |43| index.ts + bin/ | CLI tool |4445### Step 3: Read Key Files4647Examine critical files:4849**Always check:**50- `README.md` - Project purpose and documentation51- `package.json` / `Cargo.toml` / `pyproject.toml` - Dependencies and metadata5253**Check if they exist:**54- `tsconfig.json` / `vite.config.ts` / `webpack.config.js` - Build configuration55- `Dockerfile` / `docker-compose.yml` - Container setup56- `.env.example` - Environment variables57- `CONTRIBUTING.md` - Development workflow5859### Step 4: Explore Architecture6061List key directories (src/, lib/, app/, etc.) to understand component organization, then identify architectural patterns:6263| Pattern | Indicators |64|---------|-----------|65| MVC | controllers/, models/, views/ directories |66| Layered | services/, repositories/, handlers/ |67| Feature-based | Feature directories with co-located files |68| Monorepo | packages/ or apps/ directories |69| Microservices | Multiple service directories with own configs |7071### Step 5: Analyze Dependencies7273Read the dependency file to understand:74- **Runtime dependencies**: Core libraries the project relies on75- **Dev dependencies**: Build tools, test frameworks, linters76- **Package manager**: npm, yarn, pnpm, cargo, pip, etc.77- **Dependency count**: Overall complexity indicator7879## Analysis Depth8081Scale depth to the request — quick = structure + project type only; deep = all steps plus reading entry points and core modules.8283## Output Format8485Present analysis in this structure:8687```markdown88## Project Analysis: [Name]8990### Overview91- **Type**: [Web app / API / CLI / Library / etc.]92- **Primary Language**: [language] (X%)93- **Total Files**: X9495### Architecture96- **Pattern**: [MVC / Layered / Feature-based / etc.]97- **Key Directories**:98 - `src/commands/` - CLI command implementations99 - `src/services/` - Business logic layer100101### Key Files102| File | Purpose |103|------|---------|104| `index.ts` | Application entry point |105| `package.json` | Dependencies and scripts |106107### Dependencies108- **Package Manager**: [npm/yarn/pnpm]109- **Runtime** (X packages): [key ones listed]110- **Development** (Y packages): [key ones listed]111112### Observations113- [Notable patterns or concerns]114- [Suggested improvements]115```116117## Best Practices1181191. **Be specific**: Name actual files and directories, don't generalize1202. **Note concerns**: Flag large files, missing docs, or unusual patterns121122## Common Mistakes123124- **Don't guess architecture from file names alone** — read key files before concluding125- **Don't include vendored/generated directories** (node_modules, dist, target) in counts or structure
britt