Repo Analyzer

In-depth Git project analysis skills

We provide in-depth analysis of open-source projects and generate professional architecture reports. These reports offer profound technical insights, enabling readers to understand business problems, master architectural design, and develop their own critical thinking.

When to Use

• Analyze the architecture and design of open source projects
• Compare the design differences between two similar projects
• In-depth study of the implementation ideas of a framework or library

When NOT to Use

• Simple code issues or debugging
• Single file analysis or code review
• No code modifications required at the architectural level

Output Language

The default language is Chinese. If the user asks a question in another language, the language used will be the same.

Core Principles

1. Prioritize Business Perspective

Start with "What problem does this project solve?", not "What functions are in this file?"

| Don't | Yes | | ----- | --- |

The handleRequest(ctx) function accepts a Context parameter... After a request comes in, the system will go through three stages: authentication, rate limiting, and route distribution... | interface MessageQueue { push(); pop() } | Modules are decoupled through message queues; producers only need to post messages, and consumers pull messages according to priority.

2. Controlling the level of abstraction: Talking about design, not code.

By default, descriptions are presented at the design pattern and architecture level; raw code is not shown unless absolutely necessary. The focus is on the process, logic, and design principles, expressed using architecture diagrams (Mermaid), flowcharts, and tables, rather than code snippets. Code is only shown when the design is exceptionally ingenious, the project has a unique original concept, or the implementation is a core selling point, and in such cases, it must first be explained in natural language.

3. Global Associations

Every local analysis must be connected to the overall project design philosophy—this is the key difference between "code specifications" and "architectural analysis." See the global connections section in [analysis-guide.md](references/analysis-guide.md) for details.

4. Inspirational Writing

The goal is to learn something and stimulate thinking, not just provide a code manual. It's like a senior engineer explaining something on a whiteboard—with viewpoints, reasoning, and comparisons. See the inspirational writing section of [analysis-guide.md](references/analysis-guide.md) for details.

5. In-depth Insight: Why > What (Mandatory)

Every design decision must be explained in terms of motivation, trade-offs, and the costs of alternatives. Describing "what" is just the starting point; explaining "why" is where the value of the analysis lies. Every core module and the overall architecture must answer: Why design it this way? It's not just about "what pattern was used," but rather "why it's suitable for this scenario." What would happen if we didn't do it this way? The cost of the alternative.

• Gap with industry best practices? Areas of leadership and room for improvement.
• If you were to redesign it? Demonstrate a deeper understanding.
• A systematic design philosophy? A style that runs throughout the project (e.g., "convention over configuration," "zero-cost abstraction")

Example:

> ❌ The routing system uses a middleware pattern and supports chained calls. > > ✅ The routing system opted for an onion model instead of a linear pipeline. While linear pipelines are simpler to implement, the onion model allows each middleware to handle both request and response phases simultaneously—crucial for logging, timing, and error recovery. Express initially chose a linear model but later had to resort to various hacks to handle post-response logic; Koa learned from this experience and switched to the onion model. If I were to redesign it, I would consider adding middleware dependency declarations so the framework can automatically sort them—this is what Fastify does, avoiding hidden bugs caused by order.

Supplementary Requirements

• Code as the Standard — All conclusions are supported by code, clearly marked with file path or file path:line number range. Vague descriptions are prohibited.
• Human Touch — Like a senior engineer giving an onboarding session to a new colleague, incorporate subjective evaluations and suggestions, avoiding AI-sounding clichés.
• Focus on Key Points, Briefly Cover Secondary Aspects — In-depth analysis of core innovations, with general utility functions briefly mentioned.
• Critical Thinking — Compare with industry practices, point out real problems, and do not shy away from shortcomings. See [analysis-guide.md](references/analysis-guide.md)
• Fluent and Easy-to-Understand Writing — The overall writing style should be fluent and natural, allowing even novice engineers to understand and learn from it. Avoid overly academic language or piling up jargon.
• Avoid a rambling, disjointed account — Each module should demonstrate in-depth detail, avoiding brief mentions or superficial discussions. If appropriate, each module should be accompanied by a corresponding Mermaid architecture diagram, ensuring readers are inspired and grasp the essence of the design.

Analyzing Workflow

Flexibility Principle: All stages and sections below are advisory guidelines, not a checklist that must be strictly followed. The agent should make dynamic decisions based on the characteristics of the project being analyzed—if a stage or step is not relevant to the current project, it can be skipped or simplified. The quality of the final report is paramount.

Phase 1: Project Acquisition and Initialization

1. Parse user input (supports owner/repo, GitHub/GitLab/Gitee URL, local path, project name)
2. Create a workspace: Create a directory repo-analyses/${REPO_NAME}-{YYYYMMDD} in the user's home directory as $WORK_DIR (cross-platform: macOS/Linux use $HOME, Windows use $USERPROFILE or $HOME).
3. If the user provides a local path, skip the clone step; otherwise, clone the repository using git clone --depth=1.
4. Obtain basic metadata (Star, Fork, Contributors, Code Statistics)

Phase 2: Project Scale Assessment and Analysis Model Selection

1. Count the number of valid lines of code (excluding skippable code), and list the distribution by module.

• Code definitions can be skipped: test code, build/deployment configuration (Dockerfile, CI yaml, etc.), automatically generated code (protobuf generation, lock files, etc.), and sample/documentation code.
• Use tools like find + wc -l or cloc to perform statistics, grouping by top-level directory.

1. Report code size to users, using AskUserQuestion to allow users to select analytics modes:

| Pattern | Core Module Coverage | Secondary Module Coverage | Applicable Scenarios | | ------------------------------- | -------------------- | ------------------------- | ---------------------------------------------- | | Quick Analysis | ≥30% | ≥10% | Quickly understand the overall project picture | | Standard Analysis (Recommended) | ≥60% | ≥30% | Conventional Architecture Analysis | | In-depth analysis | ≥90% | ≥60% | Thoroughly examine each design decision |

1. Write the code size statistics and user-selected analysis mode into drafts/03-plan.md, and use this to control the analysis depth in subsequent stages.

Coverage Calculation Rules:

• Coverage = Union of line ranges actually requested by the Read tool / Total number of lines in the file
• For large files (>500 lines), they must be read in segments to ensure that the following critical sections are covered:
• Type definitions and imports in the file header (first 100 lines)
• Core business logic functions (located by directory structure or function name)
• Test code at the end of the file (if any)
• Reading only a small portion of a file ( 5000), incremental writing of drafts must be requested in the subagent prompt:

• After completing the analysis of each subsystem/submodule, immediately write that section into a draft file.

The first subsystem uses Write to create files, and subsequent subsystems use Edit to append.

• Do not wait until the entire file has been read before writing it all at once.
• Coverage details will be added at the end.

Main agent waiting discipline:

• After the subagent starts, the main agent must not read the source code files that the subagent is responsible for.
• During the waiting period, the main agent should focus on: reading project documents (architecture/, docs/), conducting external research, designing the report skeleton, and preparing the integration framework for Phase 8.
• The criterion for determining if a subagent is stuck is: no new lines have been added to the output file for more than 5 minutes. Only after confirming a stuck state can the main agent take over the analysis of that module. \***\Premature merging is strictly prohibited:* The merging process for Phases 7 and 8 must only begin after all subagents have completed. Do not start writing the final report while some subagents are still running.

Phase 7: Cross-validation + Quality Control (Main Agent)

7.1 Coverage Gating:

1. Read the coverage details table at the end of each drafts/06-module-*.md file.
2. Quick check: Does each draft end with a coverage table, and are the totals marked as meeting the standards? (✅/❌)
3. Only modules marked with ❌ or lacking a coverage table require in-depth inspection.
4. Non-compliant modules → The main agent automatically supplements the reading of key documents that were not covered, and adds the supplementary findings to the corresponding draft.
5. If the requirements are still not met after supplementation → Report to the user which modules are not meeting the requirements and the reasons (e.g., files are too large, binary files, etc.).

7.2 Spot Check Verification:

1. Select 2-3 key conclusions from the draft of each core module.
2. Go back to the source code and verify the accuracy of the conclusion line by line.
3. If deviations are found, revise the corresponding content in the draft.

7.3 Cross-validation:

1. Cross-validation of cross-module conclusions labeled "Pending Main Agent Validation"
2. Provide comprehensive answers to the exploratory questions and identify cross-module design patterns.
3. Verify global coherence: Are the analyses of each module connected to the overall project design philosophy?
4. Write to drafts/07-cross-validation.md

Phase 8: Multi-source fusion and final report (primary agent)

1. Extract architectural insights and a systematic design philosophy
2. Deepen competitor comparison based on Phase 3 research results (supplementary searches only when Phase 3 information is insufficient).
3. Propose improvements "if redesigned".
4. Write to drafts/08-insights.md
5. Multi-Source Fusion: Using the report chapter structure designed in Phase 5 as the framework, content is extracted from various drafts to fill in the gaps. When the same concept appears in multiple drafts, the most detailed version is used, supplemented with information unique to other versions. After fusion, all "See Draft X" or "See Appendix" navigation indicators are removed.

• Narrative Coherence: Organize module chapters according to the narrative line designed in Phase 5. Each module chapter must begin with 1-2 transition sentences connecting to the conclusion or question of the previous module. Avoid abrupt transitions such as "Next, we will analyze module X," and instead use natural transitions (e.g., "The Gateway completes the authentication and routing of requests, but it is only responsible for 'who can come in,' not 'what can be done after coming in.' This responsibility for behavior control is undertaken by the strategy engine.").

1. Segmented Writing: The final report usually exceeds 500 lines. First, write the first few sections (200-300 lines), and then append the rest using Edit. Before each append, use Read to confirm the end position.
2. Coverage Summary: Summarize the coverage data and write it to drafts/08-coverage.md (do not include it in the final report).

• Data is extracted directly from the coverage details table at the end of each subagent's draft, without requiring the main agent to recalculate.
• If the main agent adds additional reads in phase 7, the added lines will be added to the "Read Lines" count of the corresponding module.

Summary table format:

| Module | Type | Number of Files | Valid Lines of Code | Number of Lines Read | Coverage | Meets Standard | | ------ | -------------- | --------------- | ------------------- | -------------------- | -------- | -------------- | | ... | Core/Secondary | ... | ... | ... | ...% | ✅/❌ |

1. Compile and generate the final report (excluding the coverage section).

List of Draft Files

All intermediate processes are saved to $WORK_DIR/drafts/:

| Stage | Document | | ----- | ------------------------------------------- | | 3 | 03-research.md, 03-plan.md | | 5 | 05-modules-plan.md | | 6 | 06-module-{name}.md (subagent generation) | | 7 | 07-cross-validation.md | | 8 | 08-insights.md, 08-coverage.md |

Files are written in blocks, with each block not exceeding 300 lines or 15KB.

Special Scenarios

• Very large projects (>50,000 lines): Prioritize analysis of core modules, using agents for parallel analysis.
• Comparative Analysis Mode: Two projects complete phases 1-4 respectively, and then in phase 5, design a comparative report structure, adding "Design Decision Comparison" and "Selection Recommendations" to the skeleton constraints.

Output Requirements

1. The final report is a single Markdown file: $WORK_DIR/ANALYSIS_REPORT.md
2. Extensive use of Mermaid charts to display architecture, processes, and data flows.
3. For developers who need to understand the business architecture.
4. A framework for evaluating strengths and weaknesses [analysis-guide.md](references/analysis-guide.md)
5. Analytical Philosophy and Depth Standards Reference [analysis-guide.md](references/analysis-guide.md)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ntk148v
• Source: ntk148v/skills
• License: MIT

Install and usage instructions live in the source repository linked above.