SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsteardown-github

teardown-github

Frontend & websites

View repository

Updated 10-15 23:42

About this skill

GitHub Repo Teardown — Product × Engineering Deep-Dive Report

Source This Skill is ported from the ClawHub platform's @jjliu6's github-repo-teardown, MIT-0 license (free to use, modify, and redistribute, no attribution required). During migration, the context: fork、disable-model-invocation、allowed-tools frontmatter field was added, and the output path and file naming rules were adjusted; the core content remains consistent with the original Skill.

Break down any GitHub open-source project into abeautifully formatted HTML report, understandable by both product people and engineers.

Step -1: Determine the output filename

  1. Extract the project name from the URL:PROJECT_NAME(e.g. https://github.com/Foo/hermes-agent → hermes-agent）
  2. Get the timestamp:date +"%Y-%m-%d-%H%M"
  3. Determine the output path:{当前工作目录}/{PROJECT_NAME}-teardown-{yyyy-mm-dd-HHmm}.html
  4. Before writing, use Glob to confirm the path does not exist; after confirming, call Write

Phase 1: Research (6 steps, steps 2-5 can be executed in parallel)

Step 1: Repo Overview

  • Get the README, directory structure, star count, primary language breakdown, License, and latest commit date
  • Look for architecture documents such as ARCHITECTURE.md, DESIGN.md, CONTRIBUTING.md, etc.

Step 2: Deep Information Sources (can run in parallel with Steps 3-5)

  • Use WebSearch to search for architecture design discussions and internal implementation analyses of the project
  • Search DeepWiki (if available), official blogs, and author interviews
  • Scrape HackerNews / Reddit launch posts (search site:news.ycombinator.com {项目名}）

Step 3: Source Code Reconnaissance (can run in parallel with Steps 2, 4, 5)

  • Identify the 3-5 most core source files (retrieved via GitHub raw URLs)
  • Focus on relationships between files and core abstractions
  • Check dependency files (package.json, Cargo.toml, go.mod, requirements.txt, etc.)

Step 4: Community Signals (can run in parallel with Steps 2, 3, 5)

  • Scan the Issues tab for highly upvoted issues to identify user pain points and unmet needs
  • Check Discussions and Release Notes (the last 3 versions)
  • Record the number of contributors and commit frequency

Step 5: Competitor Research (can run in parallel with Steps 2, 3, 4)

  • Use WebSearch to search for alternatives and competing projects
  • Scrape the GitHub pages of 2-4 competitors (stars, language, positioning, differentiators)
  • Refer to the "Compared to" / "Why not X" sections in the README

Step 6: Synthesis and Distillation (depends on the results of the first 5 steps)

  • Determine a one-sentence definition (used as the core anchor for the entire report)
  • Choosea core analogy that runs through the main thread(the analogy must serve understanding, not decoration)
  • Identify the 3 most important design decisions

Phase 2: Output (10-chapter HTML report)

CH.1 — Problem Definition

  • Scenario comparison before vs. after solving
  • A real-world analogy that lets non-technical readers understand instantly
  • Product Insight: what this project's existence unlocks that was previously impossible

CH.2 — Core Mechanism

  • Running analogy: explain how the system works in one sentence (introduced in CH.1, extended through CH.2-4)
  • User perspective vs. system internal perspective comparison
  • Key file/function references (with a technical detail layer)

CH.3 — Architecture & Design Decisions

  • Architecture diagram (ASCII or structured description), with analogy mappings annotated
  • 3-5 decision cards of "why choose A over B," each containing product-level rationale

CH.4 — Full-Chain Tracing of a Single Operation

  • Select a typical user operation and trace it completely from trigger to response
  • Timeline format: each step includes technical context
  • Include file paths and function names

CH.5 — Product Design Highlights

  • 3-5 design highlights, each with product-level insight
  • Annotate reusable design patterns

CH.6 — Competitor Comparison & Market Positioning

  • 2-4 alternatives (including GitHub links, stars, language, core differences)
  • "When to use which" decision guide
  • Positioning matrix or comparison table

CH.7 — Risks & Trade-offs

  • 2-3 key limitations
  • What was sacrificed to gain the current advantages

CH.8 — Technical Quick Reference

  • Annotated source directory tree
  • Tech stack table
  • Key dependency notes

CH.9 — Application Scenarios (Three Tiers)

Tier A — Direct Use(2-3 cards) Specific problems this project can solve out of the box: who / under what circumstances / how to use

Tier B — Combined Use(1-2 cards) Combine this project with other tools to produce new capabilities that are unavailable when used alone

Tier C — Borrow the Pattern(1-2 cards) Do not depend on this library; port only its design ideas to other languages/scenarios

CH.10 — Transferable Mental Models

  • 3-5 design principles usable across projects
  • Numbered, each 1-2 sentences
  • Truly takeaway insights, not a project summary

Writing Standards

Throughline Analogy

  • Introduced in CH.1, continuously extended through CH.2-4
  • The analogy serves understanding, not decoration
  • The entire report always uses the same analogy framework

Dual-Layer Narrative

  • Surface layer(PM-readable): business language, 80% of the content understandable without technical depth
  • Deep layer(Engineer-usable): file paths, function names, protocol details
  • The two layers are visually distinguished via code font, gray background, and annotation boxes

Insight Annotation (Color-Coded)

  • 🔵 Blue: product insights / design principles
  • 🟠 Orange: technical design lessons
  • 🟢 Green: reusable patterns
  • 🟣 Purple: growth / business strategy

Tone

Like a senior consultant giving a private briefing—direct, opinionated where annotated, concise.

Quality Checklist (Confirm Each Item Before Writing)

  • One-sentence definition is clear and accurate
  • The analogy remains consistent across CH.1-4
  • No content duplication between chapters
  • Surface narrative is PM-readable
  • Deep narrative is engineer-usable
  • CH.6 includes real GitHub links and a "when to use which" decision guide
  • Each card in CH.9 clarifies who / what to do / how to do it
  • CH.10 is a truly transferable insight (not a restatement of the project summary)
  • All insights in the full text come from the specific characteristics of the project (no generic boilerplate)

HTML Visual Specification

<!-- 字体 -->
Newsreader（serif，标题）/ Inter（sans-serif，正文）/ JetBrains Mono（代码）
通过 Google Fonts CDN 加载

<!-- 布局 -->
背景色：#faf9f6（温暖白）
最大宽度：820px，居中，充裕留白

<!-- 洞察标注样式 -->
.insight-blue   { border-left: 4px solid #3b82f6; background: #eff6ff; }
.insight-orange { border-left: 4px solid #f97316; background: #fff7ed; }
.insight-green  { border-left: 4px solid #22c55e; background: #f0fdf4; }
.insight-purple { border-left: 4px solid #a855f7; background: #faf5ff; }

<!-- 组件类型 -->
- 类比卡片（analogy-card）
- 竞品对比面板（comparison-panel）
- 流程图（flow-diagram，用 CSS flexbox）
- 决策卡片（decision-card，含"问题/结论/原因/代价"四字段）
- 时间线（timeline）
- 场景卡片（scenario-card，含 Tier 标签）
- 技术参考块（tech-reference）

The complete HTML must be a single file (inline CSS), not dependent on external resources (except fonts).