SuperAPI AI Directory

project-reader

General & other

View repository

Updated 10-16 10:22

About this skill

Project Reader

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:

  1. Identify core modules and key files
  2. Start reading from the entry file to understand the application startup process
  3. Review the organization of key directories
  4. 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.