What if there is no README or marker files?

Use fallback indicators like package.json, go.mod, Dockerfile, and project scripts; note needs clarification if evidence is insufficient.

How is the tech stack identified?

From explicit markers and dependency/config files; cross-check frameworks and infrastructure artifacts to confirm the stack.

What happens if the analysis can't verify every item?

Mark items as 'needs clarification' in the report and document missing evidence to avoid incorrect assumptions.

analyzing-projects

Scanned

npx machina-cli add skill Putra213/claude-workflow-v2/analyzing-projects --openclaw

Files (1)

SKILL.md

3.5 KB

Analyzing Projects

Project Analysis Workflow

Copy this checklist and track progress:

Project Analysis Progress:
- [ ] Step 1: Quick overview (README, root files)
- [ ] Step 2: Detect tech stack
- [ ] Step 3: Map project structure
- [ ] Step 4: Identify key patterns
- [ ] Step 5: Find development workflow
- [ ] Step 6: Generate summary report

Step 1: Quick Overview

# Check for common project markers
ls -la
cat README.md 2>/dev/null | head -50

Step 2: Tech Stack Detection

Package Managers & Dependencies

package.json → Node.js/JavaScript/TypeScript
requirements.txt / pyproject.toml / setup.py → Python
go.mod → Go
Cargo.toml → Rust
pom.xml / build.gradle → Java
Gemfile → Ruby

Frameworks (from dependencies)

React, Vue, Angular, Next.js, Nuxt
Express, FastAPI, Django, Flask, Rails
Spring Boot, Gin, Echo

Infrastructure

Dockerfile, docker-compose.yml → Containerized
kubernetes/, k8s/ → Kubernetes
terraform/, .tf files → IaC
serverless.yml → Serverless Framework
.github/workflows/ → GitHub Actions

Step 3: Project Structure Analysis

Present as a tree with annotations:

project/
├── src/              # Source code
│   ├── components/   # UI components (React/Vue)
│   ├── services/     # Business logic
│   ├── models/       # Data models
│   └── utils/        # Shared utilities
├── tests/            # Test files
├── docs/             # Documentation
└── config/           # Configuration

Step 4: Key Patterns Identification

Look for and report:

Architecture: Monolith, Microservices, Serverless, Monorepo
API Style: REST, GraphQL, gRPC, tRPC
State Management: Redux, Zustand, MobX, Context
Database: SQL, NoSQL, ORM used
Authentication: JWT, OAuth, Sessions
Testing: Jest, Pytest, Go test, etc.

Step 5: Development Workflow

Check for:

.eslintrc, .prettierrc → Linting/Formatting
.husky/ → Git hooks
Makefile → Build commands
scripts/ in package.json → NPM scripts

Step 6: Output Format

Generate a summary using this template:

# Project: [Name]

## Overview
[1-2 sentence description]

## Tech Stack
| Category | Technology |
|----------|------------|
| Language | TypeScript |
| Framework | Next.js 14 |
| Database | PostgreSQL |
| ...      | ...        |

## Architecture
[Description with simple ASCII diagram if helpful]

## Key Directories
- `src/` - [purpose]
- `lib/` - [purpose]

## Entry Points
- Main: `src/index.ts`
- API: `src/api/`
- Tests: `npm test`

## Conventions
- [Naming conventions]
- [File organization patterns]
- [Code style preferences]

## Quick Commands
| Action | Command |
|--------|---------|
| Install | `npm install` |
| Dev | `npm run dev` |
| Test | `npm test` |
| Build | `npm run build` |

Analysis Validation

After completing analysis, verify:

Analysis Validation:
- [ ] All major directories explained
- [ ] Tech stack accurately identified
- [ ] Entry points documented
- [ ] Development commands verified working
- [ ] No assumptions made without evidence

If any items cannot be verified, note them as "needs clarification" in the report.

Source

git clone https://github.com/Putra213/claude-workflow-v2/blob/main/skills/analyzing-projects/SKILL.mdView on GitHub

Overview

Analyzes codebases to understand structure, tech stack, patterns, and conventions. This skill guides onboarding and exploration by answering how a system works and what its architecture looks like.

How This Skill Works

It follows the Project Analysis Workflow: Step 1 quick overview, Step 2 tech stack detection, Step 3 project structure analysis, Step 4 key patterns identification, Step 5 development workflow checks, and Step 6 a structured summary output. It detects tech stack from common files (package managers, requirements, go.mod, etc.), maps the repository as an annotated tree, identifies architecture and API style, and then produces a report plus a validation checklist.

When to Use It

Onboarding to a new project and establishing its context
Exploring unfamiliar code to locate entry points and module relationships
Answering questions like 'how does this work?' or 'what's the architecture?'
Planning upgrades or migrations by assessing dependencies and tech choices
Documenting a clear, shareable project overview for teammates

Quick Start

Step 1: Run the Project Analysis Progress checklist and review root README
Step 2: Detect tech stack from common markers (package.json, requirements.txt, Dockerfile, etc.) and map the structure
Step 3: Generate a summary report using the Output Format and perform Analysis Validation

Best Practices

Start with the Quick Overview (README and root files) to seed understanding
Detect tech stack using standard markers (package.json, pyproject.toml, Dockerfiles, etc.)
Present results as a tree with annotations for clarity
Use the Output Format template to produce a consistent summary
Note uncertainties as 'needs clarification' when evidence is missing

Example Use Cases

Onboard a Node/React project and map its src structure and dependencies
Audit a Python Django monolith to identify services, APIs, and data models
Analyze a Go microservice repository with Docker and Kubernetes configs
Review a Java Spring Boot monorepo with multiple modules and CI workflows
Evaluate a multi-repo workspace to extract an architecture overview

Frequently Asked Questions

Add this skill to your agents