Overview
Project Reader is a project structure analysis skill that can automatically detect the tech stack of a frontend/full-stack project, analyze the directory structure, parse module dependencies, and generate a highly readable analysis report. Through a layered reading workflow, it helps developers quickly understand the architecture design of an unfamiliar project.
When to Use
This skill should be used in the following scenarios:
- Taking over a new project: Need to quickly understand the project's tech stack and code structure
- Technical research: Evaluate a project's technical solution or code quality
- Code review: Analyze the project's dependency relationships and module organization
- Refactoring preparation: Understand the existing project's architecture in order to carry out reasonable refactoring
- Learning examples: Learn best practices by analyzing open-source projects
Quick Start
Basic usage
# 进入技能目录
cd /home/luckxp/.agents/skills/project-reader
# 生成完整的项目分析报告
python scripts/generate_report.py /path/to/project
# 指定输出文件
python scripts/generate_report.py /path/to/project -o report.md
Layered analysis
For finer control, you can run the analysis scripts layer by layer:
# 第 1 层:框架检测
python scripts/detect_framework.py /path/to/project
# 第 2 层:目录结构分析
python scripts/analyze_structure.py /path/to/project
# 第 3 层:依赖关系分析
python scripts/analyze_dependencies.py /path/to/project
Layered Reading Workflow
Project Reader uses a layered reading workflow, gradually deepening understanding of the project from macro to micro.
Layer 1: Framework detection
Run detect_framework.py to obtain the project's basic technical information:
- Framework type:React、Vue、Angular、Next.js、Nuxt、Svelte、SvelteKit、Gatsby、Remix
- UI library:Material UI、Ant Design、Radix UI、Chakra UI、Element Plus、Vuetify、Tailwind CSS、Styled Components
- Build tool:Vite、Webpack、Turbopack、Rollup、Parcel、esbuild
- Package manager:npm、yarn、pnpm、bun
- Entry file: Identify the application's startup entry
- Project metadata: Name, version, description, available scripts
Layer 2: Directory structure analysis
Run analyze_structure.py to understand how the project is organized:
- Directory tree: Recursively generate the project's directory structure (maximum depth 5 levels)
- File type distribution: Count the number of files of each type (JavaScript, TypeScript, Vue, Python, etc.)
- Key directories: Identify important directories in the project (src, components, hooks, utils, services, etc.)
- Configuration files: List project configuration files (tsconfig.json, vite.config.js, .eslintrc, etc.)
Layer 3: Dependency relationship analysis
Run analyze_dependencies.py to deeply understand the connections between modules:
- Module dependency graph: Extract import/require statements from all files
- Core modules: Sort by reference count to identify the most frequently used modules
- Circular dependencies: Detect circular dependency issues existing in the project
- Module list: List all module paths in the project
Layer 4: Module content reading
After completing the first three layers of analysis, based on the generated report:
- Identify core modules and key files
- Start reading from the entry file to understand the application startup process
- Review the organization of key directories
- Analyze the implementation logic of core modules
Scripts
detect_framework.py
Framework detection script, used to identify the project's basic tech stack.
python scripts/detect_framework.py /path/to/project
Example output:
{
"framework": "Next.js",
"ui_library": "Tailwind CSS",
"build_tool": "Vite",
"package_manager": "pnpm",
"dependencies": ["next", "react", "react-dom", "tailwindcss", ...],
"entry_points": ["src/app/layout.tsx", "src/app/page.tsx"],
"project_name": "my-next-app",
"project_version": "1.0.0",
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start"
}
}
Detection scope:
- 9 mainstream frontend frameworks
- 8 UI libraries/styling solutions
- 6 build tools
- 4 package managers
analyze_structure.py
Directory structure analysis script that generates the project's directory tree and file statistics.
python scripts/analyze_structure.py /path/to/project
Output includes:
- Complete directory tree structure (JSON format)
- File type distribution statistics
- Key directory identification results
- Configuration file list
analyze_dependencies.py
Dependency analysis script that extracts and analyzes reference relationships between modules.
python scripts/analyze_dependencies.py /path/to/project
Output includes:
- Dependency list for each file
- Core modules sorted by usage frequency
- Detected circular dependencies
- Complete list of all modules
Supported file types:
- JavaScript (.js, .jsx)
- TypeScript (.ts, .tsx)
- Vue (.vue)
- Python (.py)
generate_report.py
Report generation script that integrates the output of the above three scripts to generate an analysis report in Markdown format.
# 输出到标准输出
python scripts/generate_report.py /path/to/project
# 输出到文件
python scripts/generate_report.py /path/to/project -o report.md
Report contents include:
- Project overview (name, path, version, description)
- Framework information (framework, UI library, build tool, package manager)
- Directory structure (directory tree, file type distribution, key directories)
- Dependency analysis (module statistics, core modules, circular dependencies)
Resources
references/common_patterns.md
Reference documentation for common project structure patterns, including:
- Standard structure for React projects
- Next.js project structure (App Router and Pages Router)
- Standard structure for Vue projects
- Comparison of common directory patterns
- Key configuration file descriptions
Directory structure
project-reader/
├── SKILL.md # 技能文档
├── scripts/ # 分析脚本
│ ├── detect_framework.py # 框架检测
│ ├── analyze_structure.py # 目录结构分析
│ ├── analyze_dependencies.py # 依赖关系分析
│ └── generate_report.py # 报告生成
├── references/ # 参考资料
│ └── common_patterns.md # 项目结构模式
└── assets/ # 静态资源(预留)
When using the Project Reader skill, it is recommended to start with Quick Start and gradually go deeper into each level of the layered reading workflow as needed.