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 INLINECODE4

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)

CODEBLOCK0

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

CODEBLOCK1

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:

• - [ ] One-line definition is truly one sentence?
• [ ] Main analogy runs through the entire document (not switching per chapter)?
• [ ] Every chapter adds new information (not rephrasing earlier content)?
• [ ] A PM can understand 80% reading only the surface layer?
• [ ] An engineer can find specific files and functions in the deep layer?
• [ ] CH.6 includes actual GitHub links to comparable repos?
• [ ] CH.6 has a clear "when to use which" decision guide?
• [ ] CH.9 scenarios are specific enough (who / what / how all stated)?
• [ ] CH.9 "Borrow Pattern" tier has genuine cross-domain leaps (not "same domain, new name")?
• [ ] CH.10 takeaways are transferable mental models (not a project summary)?
• [ ] Insights are specific to THIS project (not "AI is changing the world" platitudes)?
• [ ] HTML saved to /mnt/user-data/outputs/ and displayed via present_files?

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.

• - GitHub: github.com/jjliu6
• LinkedIn: linkedin.com/in/junjieliu
• Products: philosophie.ai

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