Project Analysis Skill Skill

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

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

Agent Skills: Project Analysis Skill

Install this agent skill to your local

Skill Files