GitHub Repo Teardown

Purpose

Transform any GitHub open-source project into a product + engineering teardown — a single HTML document that explains not just what the code does, but why it's designed that way and what you can learn from it. The core premise: every technical choice reflects a product judgment, and every product design requires an architecture to support it.

When to Trigger

User shares a GitHub repo URL and asks to analyze / explain / teardown
User says "break down this repo", "how is this designed", "analyze this project"
User mentions "teardown", "code walkthrough", "explain this codebase"
User wants to learn from an open-source project's design
User drops a GitHub link with even minimal context ("what is this?")

Configuration

Language

Output defaults to English. If the user's message is in another language (e.g., Chinese, Japanese, Spanish), match that language for the narrative while keeping technical terms, code references, and file paths in their original form.

If the user explicitly requests a language (e.g., "write it in Chinese", "用中文写"), follow that instruction regardless of the default.

Research Phase

Before writing anything, gather comprehensive information. Follow these steps in order, spending 5-15 tool calls depending on repo complexity. Do not skip steps — thin research produces thin teardowns.

Step 1: Repo Overview

web_fetch the GitHub repo main page to get: README content, directory structure, stars/forks/language breakdown, license, last commit date
Pay attention to any Architecture / Design / How It Works sections in the README
Check for ARCHITECTURE.md, DESIGN.md, CONTRIBUTING.md, or AGENTS.md

Step 2: Deep-Dive Sources (pick 2-4 most useful)

web_search "{repo-name} architecture" or "{repo-name} how it works internally"
Try fetching DeepWiki: https://deepwiki.com/{owner}/{repo} — often has good architecture analysis. If unavailable, skip without concern — it's a nice-to-have, not a dependency.
Look for the project's official blog post, launch announcement, or HN/Reddit discussion
If the repo has a /docs directory or documentation site, fetch key pages

Step 3: Source Code Reconnaissance

From README and any architecture docs, identify 3-5 key source files — entry points, core modules, config files, data models
web_fetch these files directly via raw GitHub URLs: https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{path}
You don't need to read every line — focus on understanding the relationships between files, the main abstractions, and any clever patterns
Check package.json, Cargo.toml, pyproject.toml, or equivalent for dependency insights

Step 4: Community & Traction Signals

Scan the Issues tab (sort by most commented or most reacted) to understand:
- What problems users actually hit
- What features are most requested
- Where the project's limitations show
Check Discussions or recent release notes if available
Note contributor count and commit frequency — signals project health

Step 5: Comparable Repos Discovery (CRITICAL — do not skip)

This step directly feeds CH.6 and is one of the highest-value parts of the teardown.

web_search for 2-4 comparable or alternative projects:
- "{repo-name} vs" or "{repo-name} alternatives"
- Search by the problem domain: "{problem-the-repo-solves} open source"
For each comparable repo found, web_fetch its GitHub page to get: stars, language, approach/architecture, key differentiator
Look for projects that solve the same problem differently, not just forks or clones
Note: "comparable" includes both direct competitors AND projects with similar architectural patterns applied to different domains

Step 6: Synthesize Before Writing

Before opening any file, mentally organize:

One-line definition of what this project is (test: would a smart non-technical person get it?)
The main analogy you'll use throughout the document
3 key design decisions that make this project interesting
The "aha" insight — what's the non-obvious thing about this project?

Output Framework

Produce a single HTML file saved to /mnt/user-data/outputs/ and displayed via present_files.

Document Structure (10 chapters — trim as needed)

┌─────────────────────────────────────────────────┐
│  HEADER                                          │
│  - Project name + one-line definition (must fit  │
│    in a single sentence)                         │
│  - Health indicators: Stars / Language / Version  │
│  - Audience tag: who should read this            │
└─────────────────────────────────────────────────┘

CH.1  What Problem Does It Solve?
      - Before vs After (pain → solution)
      - A real-world analogy (non-technical readers should get it)
      - 🔑 Product Insight (why this problem is worth solving)

CH.2  Core Mechanism
      - Explain the core working principle using ONE main analogy
        that runs through the entire document
      - Side-by-side: what the user sees vs what the system does
      - ⚙️ Technical Notes (file names, function names for deep-divers)

CH.3  Architecture & Key Decisions
      - Architecture flow diagram (annotated with the analogy)
      - "Why A not B" decision cards (3-5 key design choices)
      - 🎯 Product-level takeaway for each decision

CH.4  A Single Operation's Full Journey
      - Pick ONE typical user action and trace it through the system
      - Timeline-style: each step shows what happens + what tech is used
      - Technical notes: file paths, function names

CH.5  Product Design Highlights (3-5)
      - Each highlight: Title + Paragraph + Product Insight
      - Tag which ones are "reusable patterns"

CH.6  Comparable Repos & Positioning
      - 2-4 comparable/alternative projects with actual GitHub links
      - For each: what it is, stars, approach, key difference
      - Positioning matrix or comparison table
      - "When to use THIS repo vs THAT repo" decision guide
      - (If insufficient data found in research, say so honestly
        and provide what you have)

CH.7  Risks & Trade-offs
      - 2-3 key limitations or trade-offs
      - "What did it sacrifice to gain its current advantage?"
      - Honest > comprehensive

CH.8  Technical Quick Reference
      - Source tree with annotations
      - Tech stack table
      - Key dependencies explained
      - (Reference section for deep-divers)

CH.9  Where Can This Be Applied? (Application Brainstorm)
      - Three tiers of application (see detailed spec below)
      - Card-based layout, each scenario as an independent block
      - Distinguish "use directly" vs "borrow the pattern"
      - 6-8 cards total (quality over quantity)

CH.10 Portable Takeaways
      - 3-5 transferable insights from this project
      - Numbered, 1-2 sentences each
      - Not a summary — distill into reusable mental models

CH.6 Comparable Repos — Detailed Spec

This chapter is one of the most valuable parts of the teardown. Users want to understand not just what THIS project does, but how it fits in the landscape.

Required elements:

Each comparable repo gets: Name (linked), Stars count, Language, One-line description, Architectural approach, Key differentiator from the subject repo
A clear "when to use which" decision framework
Honest assessment — don't artificially favor the subject repo

Comparison formats (pick the most appropriate):

Table: Best for 3+ repos with clear feature dimensions
Decision tree: Best when the choice depends on context ("If you need X, use A; if Y, use B")
Positioning map: Best when repos differ on 2 clear axes

If research yielded thin results:

State clearly: "Limited comparable projects found in this specific niche"
Still provide whatever alternatives exist, even if they're partial overlaps
Suggest search terms the reader can use to find more

CH.9 Application Scenarios — Detailed Spec

The most practically valuable chapter. Goal: give readers specific, actionable directions, not vague possibilities.

Three Tiers

Tier A: Use Directly — "What can I do with it tomorrow?"

What real problem can this repo solve as-is?
2-3 specific scenarios: Who uses it / For what / Expected outcome
Format: "A [role] can use this to [specific action], eliminating [specific pain point]"

Tier B: Combine — "What creates a chemical reaction?"

What tools/platforms/products does this pair well with for 1+1>2 effects?
2-3 combination proposals, each explaining what NEW capability emerges
Focus on non-obvious combinations — obvious ones are already in the README

Tier C: Borrow the Pattern — "What new products could this inspire?"

Extract the core design pattern (not the code) and apply it elsewhere
Use the format: "If you apply [this pattern] to [another domain], you get..."
2-3 cross-domain applications, each specific enough to be a product spec
This is the most creative tier — encourage bold leaps, but each must land on a concrete product form

Card Design

Each scenario is an independent card with:

Type tag: 🔧 Use Directly / 🧪 Combine / 💡 Borrow Pattern
Scenario title
One-line summary: who + what for
2-3 sentences on how to execute

Total: 6-8 cards. Every card must contain genuine insight.

Chapter Usage Rules

Must write: CH.1, CH.2, CH.3, CH.4, CH.9, CH.10 (core skeleton)
Strongly recommended: CH.5, CH.6, CH.8 (applicable to most repos)
Write if warranted: CH.7 (when there are clear trade-offs)
Overall principle: every paragraph must add information — no padding
If a chapter would be thin, skip it entirely rather than write filler

Writing Style Guide

The Throughline Analogy

Choose 1 main analogy per project (e.g., browser-use = "a remote-controlled restaurant order")
Introduce it in CH.1, extend it through CH.2-CH.4
The analogy must serve understanding, not decoration
Avoid: switching to a new unrelated analogy every chapter

Dual-Layer Narrative

Surface layer: Product logic, business value, user perspective (a PM can read just this layer and understand 80%)
Deep layer: File paths, function names, protocol details (engineers dig into this layer for implementation specifics)
Visually separate them: technical details use code font, gray backgrounds, or "Technical Note" callout boxes

Insight Callouts

Use colored callout boxes to mark insights:

🔵 Blue: Product insight / Design principle
🟠 Orange: Technical design lesson
🟢 Green: Reusable pattern
🟣 Purple: Growth / Business strategy

Voice & Tone

Like a senior product advisor giving you a private briefing
Not a textbook, not a blog post — it's "help you understand fast and form judgment"
Opinions are welcome but labeled: distinguish analysis from fact
Concise and direct — every sentence earns its place

Language Conventions

Narrative in the configured output language (default: English)
Technical terms stay in English regardless (Daemon, IPC, CDP, Schema, etc.)
Code snippets and file paths always in original form
Project-specific terminology in original language with brief explanation on first use

Visual Design Guide

Overall Aesthetic

Light background (#faf9f6 warm white), high readability
Serif font for headings (Newsreader) — gravitas
Sans-serif for body (Inter) — modern readability
Monospace for technical content (JetBrains Mono)
Max width 820px, centered layout
Generous whitespace, clear visual hierarchy

Google Fonts

<link href="https://fonts.googleapis.com/css2?family=Newsreader:ital,wght@0,400;0,600;0,700;1,400&family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;600&display=swap" rel="stylesheet">

Key Components

Analogy cards: White rounded cards, 💡 emoji marker
Comparison panels: Two-column layout (Before vs After, Traditional vs New)
Flow diagrams: Horizontal emoji flow with arrow connectors
Decision cards: 2×2 grid, Q&A format
Insight callouts: Left color bar + tinted background
Timeline: Circle dots + vertical line + content cards
Tech reference: Monospace file tree + tables
Scenario cards: Independent rounded cards, type tag top-left (🔧/🧪/💡)
Comparable repo cards: GitHub-style cards with stars badge, language dot, link

Responsive Design

Cards stack vertically on narrow screens
Side-by-side comparisons collapse to stacked on mobile
Font sizes adjust for readability

Quality Checklist

Before delivering, verify:

What This Skill is NOT

❌ Not a code review (doesn't read every line)
❌ Not a README translation (doesn't repeat existing docs)
❌ Not an academic paper (doesn't aim for completeness)
❌ Not an SEO article (no filler content)
✅ It's a product teardown that helps you rapidly understand a project's design wisdom and walk away with actionable insights

Credits

Built by Junjie Liu at Philosophie AI — where AI proves its value through real, practical use.

If this skill helped you understand a project better, consider starring it on ClawHub.