github-reader
Use when reading a GitHub repository (especially a research code release with an accompanying paper) and producing a faithful digest that covers the implementation logic, the main insight, and the key reported results. Research-first with graceful fallback for non-paper repos. Handles arXiv link detection and delegates paper reading to arxiv-latex-reader / pdf-reader. Triggers: "read repo", "read this github", "analyze github", "digest repo", "github reader", "extract from github", "summarize this codebase", "read this code", "https://github.com/"
Best use case
github-reader is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Use when reading a GitHub repository (especially a research code release with an accompanying paper) and producing a faithful digest that covers the implementation logic, the main insight, and the key reported results. Research-first with graceful fallback for non-paper repos. Handles arXiv link detection and delegates paper reading to arxiv-latex-reader / pdf-reader. Triggers: "read repo", "read this github", "analyze github", "digest repo", "github reader", "extract from github", "summarize this codebase", "read this code", "https://github.com/"
Teams using github-reader should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/github-reader/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How github-reader Compares
| Feature / Agent | github-reader | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Use when reading a GitHub repository (especially a research code release with an accompanying paper) and producing a faithful digest that covers the implementation logic, the main insight, and the key reported results. Research-first with graceful fallback for non-paper repos. Handles arXiv link detection and delegates paper reading to arxiv-latex-reader / pdf-reader. Triggers: "read repo", "read this github", "analyze github", "digest repo", "github reader", "extract from github", "summarize this codebase", "read this code", "https://github.com/"
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# GitHub Reader
## When to Use
- Reading a GitHub research-code release (e.g. a paper implementation on CompVis, HuggingFace, or a lab org) and wanting the core idea + architecture + results in one pass
- Onboarding to an unfamiliar library or CLI tool and wanting a guided walkthrough rather than a file-by-file listing
- Following up an `academic-deep-research` or `arxiv-latex-reader` pass by reading the referenced code
- Any prompt that pastes a `https://github.com/<owner>/<repo>` URL with "read" / "summarize" / "explain" intent
Not for: PR or issue digests, commit-history analysis, private-repo auth flows, or blog-style write-ups (use `blog-reader` for those).
## Output
A single markdown file at `docs/github/YYYY-MM-DD-<owner>-<repo>.md` with **seven fixed sections**:
1. **Overview** — 1 paragraph, venue if paper.
2. **Main Insight** — 2–4 sentences from the paper abstract (if fetched) or README motivation.
3. **Architecture** — tree listing of 5–10 core files with one-line annotations.
4. **Implementation Walkthrough** — 300–500 words tracing **one canonical flow** (training step / sampling call / quickstart) with 10–30-line snippets pinned to `file:line`.
5. **Key Results** — metrics from paper tables when fetched, else README benchmarks.
6. **Reproducibility** — deps, hardware, exact run command.
7. **See Also** — paper link + related skills.
## Workflow
1. **Parse input** — extract `owner/repo` from URL; strip `/tree/<branch>`, query strings, trailing slash.
2. **Fetch metadata** via `gh api repos/<owner>/<repo>` (see `github-cli` skill): stars, description, topics, default branch, `size` (KB), language.
3. **Size gate** — if `size > 500000` (500 MB), ask the user before cloning. Opt-in via `--allow-large`.
4. **Shallow clone**:
```bash
git clone --depth 1 --filter=blob:none \
https://github.com/<owner>/<repo> /tmp/github-reader/<owner>-<repo>
```
5. **Paper detection** — grep `README*`, `CITATION*`, `paper.bib` for `arxiv.org/abs/`, `arxiv.org/pdf/`, or `.pdf` URLs.
6. **Paper digest (if link found)** — delegate:
- arXiv → `arxiv-latex-reader` (index + abstract + Method + main results table)
- PDF → `pdf-reader`
Save to `<workspace>/paper_digest.md`. Pull abstract + top result table into the digest's Main Insight and Key Results sections.
7. **File selection** — `git ls-tree -r --name-only HEAD`, skip the list below, then rank:
1. README-mentioned `.py` / `.ipynb` paths
2. Entry points at root: `train*.py`, `main*.py`, `sample*.py`, `inference*.py`, `demo*.py`
3. Largest `.py` in `model/ models/ nn/ network/ networks/ src/ lib/`
4. One `configs/*.yaml` or `.json`
**Skip:** `tests/`, `test_*.py`, `setup.py`, `docs/`, `examples/`, vendored deps, weight files (`.pt`, `.safetensors`, `.bin`), `__init__.py` unless >50 lines.
8. **Read core files** — full file for ≤500 lines; otherwise section-chunk by top-level `class` / `def` and read only the functions referenced by the canonical flow.
9. **Emit digest** — fill the 7-section template.
10. **Verify** — every section non-empty; ≥3 `file:line` pins in the walkthrough; `Key Results` non-empty when a paper was fetched.
## Picking the Canonical Flow
| Repo type | Canonical flow |
|---|---|
| Training code | `python train.py` → dataset → model init → forward → loss → optimizer step |
| Inference / sampling | `python sample.py` → model load → sampling loop → save output |
| Library | README quickstart example → 3 main call sites |
| CLI tool | `main()` entry → one representative command path |
Trace one flow end-to-end with `file:line` pins. Describing files independently turns the walkthrough into a listing and loses control-flow understanding — don't do it.
## Anti-Patterns
- **Cloning a huge repo silently** — always run the size gate; a 2 GB clone burns bandwidth and disk without buying anything.
- **Skipping the paper** — if an arXiv link is in the README, fetch it. Key Results sourced only from README hype is not a faithful digest.
- **File-by-file summary** — describes contents without showing how data flows through them. Use a canonical flow instead.
- **No `file:line` pins** — hand-wavy walkthrough reads authoritative but can't be verified. Always anchor.
- **Reading `tests/` or `__init__.py` and calling it core implementation** — filter those out before the ranking step.
- **Leaving "Key Results" empty** when the repo plainly cites benchmarks — either pull them from the paper or quote the README table.
- **Inventing numbers** — every metric in Key Results must trace to a source in the repo or paper. Cite it.
## Example Invocation
```
Read https://github.com/CompVis/zigma
```
Expected outcome: `docs/github/YYYY-MM-DD-compvis-zigma.md` with all seven sections populated, paper insight sourced from the ECCV 2024 arXiv PDF, walkthrough tracing `train.py` → model class → Mamba block forward pass.
## See Also
- `arxiv-latex-reader` — Invoked for deep-reading the underlying paper when an arXiv link is detected.
- `pdf-reader` — Invoked when the paper link is a direct PDF rather than arXiv.
- `github-cli` — Patterns for `gh api` and authenticated repo metadata.
- `academic-deep-research` — Adjacent skill for surveying a research topic rather than a single repo.
- `blog-reader` — Shares the "fetch-then-digest" pattern but for blog posts rather than code.Related Skills
pdf-reader
Use when reading PDF papers, reports, or long documents where text, figures, and tables must all be captured and chunk-summarized without truncation. Converts PDF to a markdown + paper_content.json workspace, extracts figures and tables as standalone files, then delegates to arxiv-latex-reader's progressive two-layer reading (section index + on-demand deep reads). Triggers: "read pdf", "pdf to markdown", "summarize pdf", "pdf paper", "extract figures from pdf", "extract tables from pdf", "marker pdf", "pymupdf", "docling", "paper digest", "pdf reader"
blog-reader
Use when reading a long technical blog post (ML research, engineering deep-dives, Distill/Lil'Log-style posts) and producing a faithful, figure-aware summary. Handles context-over-limit via section-based chunking, captures important figures via multimodal Read, and runs a coverage test to catch missing information. Triggers: "read this blog", "summarize this post", "read blog", "digest this article", "long blog post", "read this article", "blog summary", "distill post", "summarize url", "chunk and summarize"
arxiv-latex-reader
Use when reading large arxiv papers without context overflow. Progressive two-layer reading: index all sections (~2k tokens), then deep-read on demand. Never truncates. Triggers: "read paper", "paper sections", "section index", "progressive reading", "paper_content.json", "section summary"
github-cli
Use when interacting with GitHub repos, PRs, issues, releases, or API data. Covers gh CLI usage patterns, authentication, and common queries. Triggers: "gh", "github", "pull request", "PR", "issue", "gh api", "gh pr", "gh issue", "github release"
ml-ablation-design
Use when designing ablation studies to compare model components, loss functions, or architectural choices. Covers synthetic data experiments, variant loops, production metrics, and W&B grouping. Triggers: "ablation", "ablation study", "variant comparison", "controlled experiment", "synthetic data experiment"
gpu-training-acceleration
Use when optimizing PyTorch training speed or memory on CUDA GPUs — global flags, torch.compile, fused optimizers, mixed precision, gradient checkpointing, kernel fusion, memory layout, or latent-space training. Applies to any PyTorch training workload. Triggers: "torch.compile", "TF32", "fused optimizer", "mixed precision", "bf16", "fp16", "gradient checkpointing", "Triton kernel", "CUDA flags", "GPU slow", "GPU memory"
genai-evaluation-metrics
Use when evaluating generative models — choosing metrics (FID, IS, KID, sFID, FDD, FVD, PRDC, LPIPS, SSIM, AuthPct, Vendi), setting up online or offline evaluation, feature extractor selection, distributed computation, memory management during sampling. Triggers: "FID", "IS", "KID", "inception score", "frechet", "LPIPS", "SSIM", "evaluation metrics", "generative evaluation", "FVD"
youtube-wiki
Use when reading a YouTube video (especially an AI/ML interview, podcast, or technical talk) and producing a faithful, timestamped wiki entry the user can return to weeks later. Fetches the transcript via yt-dlp, sections by chapters or LLM-detected topics, summarizes per-section with parallel subagents, preserves verbatim quotes with speaker attribution, and runs a coverage test against the raw transcript. Triggers: "youtube wiki", "video wiki", "summarize this youtube", "watch this interview", "read this talk", "digest this video", "https://youtu.be/", "https://www.youtube.com/watch"
insert-wiki
Use when capturing a single URL (X tweet, LinkedIn post, HN thread, short blog, news article, GitHub gist or issue) as a small persistent markdown entry the user can re-read later for motivation or grep across future sessions. Verbatim body + author + tags + a one-line "Why I saved this" hook. Writes to docs/wikis/YYYY-MM-DD-<slug>.md. WebFetch by default; CDP via Playwright MCP for login-walled hosts (x.com, twitter.com, linkedin.com). Redirects YouTube / arXiv / GitHub repo URLs to their specialized skills. Triggers: "insert wiki", "add to wiki", "insert this", "save this tweet", "capture this post", "add this to my wiki", "remember this link", "https://x.com/", "https://twitter.com/", "https://linkedin.com/posts/"
idea-feasibility
Use when evaluating whether a research or product idea is actually feasible — buildable, evaluable, and de-risked by available checkpoints, code, datasets, and GPU budget. Normalizes the idea, gathers primary-source evidence (arXiv, GitHub, project pages, model hosts), scores it against four mandatory hard gates, and emits a verdict + falsifiable MVP. Triggers: "idea feasibility", "is this idea feasible", "feasibility check", "can we do this", "is this practical", "worth pursuing", "评估想法可行性", "可行性分析", "这个 idea 能做吗", "这个想法靠谱吗"
idea-explore
Use when proposing new research ideas grounded in a seed paper or method — surfaces the gaps that the citation cone hasn't filled, the drawbacks the community already complains about in the official repo's GitHub issues, and the adjacent angles the literature suggests. Orchestrates followup-analysis (already-done exclusion), GitHub-issue mining (known drawbacks), and academic-deep-research (adjacent literature) into a ranked candidate-ideas report. Triggers: "idea explore", "idea-explore", "propose ideas", "explore ideas", "new directions", "research gaps", "what's missing", "build on this paper", "探索想法", "提出新想法", "研究空白"
idea-box
Use when promoting an idea from a fleeting thought into a tracked artifact with a lifecycle. Defines a per-idea on-disk directory (./idea_box/<slug>/) and a hard-gated state machine (explored → feasible/blocked → building → built/killed) that the existing reader/evaluator skills (idea-feasibility, ml-ablation-design, academic-deep-research, followup-analysis, arxiv-latex-reader, pdf-reader, github-reader, blog-reader) plug into. Public repo ships only the convention; idea data lives in the user's private idea-box repo. Triggers: "idea box", "idea-box", "new idea", "advance idea", "list ideas", "kill idea", "想法箱", "新想法", "推进想法", "列出想法"