/github-research

name: github-research
description: Explore and analyze GitHub repositories related to a research topic. Reads deep-research output, discovers repos from multiple sources, deeply analyzes code, and produces integration blueprints.
argument-hint: [deep-research-output-dir]

GitHub Research Skill

Trigger

Activate this skill when the user wants to:

• "Find repos for [topic]", "GitHub research on [topic]"
• "Analyze open-source code for [topic]"
• "Find implementations of [paper/technique]"
• "Which repos implement [algorithm]?"
• Uses `/github-research <deep-research-output-dir>` slash command

Overview

This skill systematically discovers, evaluates, and deeply analyzes GitHub repositories related to a research topic. It reads **deep-research** output (paper database, phase reports, code references) and produces an actionable integration blueprint for reusing open-source code.

**Installation**: `~/.claude/skills/github-research/` — scripts, references, and this skill definition. **Output**: `./github-research-output/{slug}/` relative to the current working directory. **Input**: A deep-research output directory (containing `paper_db.jsonl`, phase reports, `code_repos.md`, etc.)

6-Phase Pipeline

Phase 1: Intake     → Extract refs, URLs, keywords from deep-research output
Phase 2: Discovery  → Multi-source broad GitHub search (50-200 repos)
Phase 3: Filtering  → Score & rank → select top 15-30 repos
Phase 4: Deep Dive  → Clone & deeply analyze top 8-15 repos (code reading)
Phase 5: Analysis   → Per-repo reports + cross-repo comparison
Phase 6: Blueprint  → Integration/reuse plan for research topic

Output Directory Structure

github-research-output/{slug}/
├── repo_db.jsonl                     # Master repo database
├── phase1_intake/
│   ├── extracted_refs.jsonl          # URLs, keywords, paper-repo links
│   └── intake_summary.md
├── phase2_discovery/
│   ├── search_results/               # Raw JSONL from each search
│   └── discovery_log.md
├── phase3_filtering/
│   ├── ranked_repos.jsonl            # Scored & ranked subset
│   └── filtering_report.md
├── phase4_deep_dive/
│   ├── repos/                        # Cloned repos (shallow)
│   ├── analyses/                     # Per-repo analysis .md files
│   └── deep_dive_summary.md
├── phase5_analysis/
│   ├── comparison_matrix.md          # Cross-repo comparison
│   ├── technique_map.md              # Paper concept → code mapping
│   └── analysis_report.md
└── phase6_blueprint/
    ├── integration_plan.md           # How to combine repos
    ├── reuse_catalog.md              # Reusable components catalog
    ├── final_report.md               # Complete compiled report
    └── blueprint_summary.md

Scripts Reference

All scripts are Python 3, stdlib-only, located in `~/.claude/skills/github-research/scripts/`.

| Script | Purpose | Key Flags | |--------|---------|-----------| | `extract_research_refs.py` | Parse deep-research output for GitHub URLs, paper refs, keywords | `--research-dir`, `--output` | | `search_github.py` | Search GitHub repos via `gh api` | `--query`, `--language`, `--min-stars`, `--sort`, `--max-results`, `--topic`, `--output` | | `search_github_code.py` | Search GitHub code for implementations | `--query`, `--language`, `--filename`, `--max-results`, `--output` | | `search_paperswithcode.py` | Search Papers With Code for paper→repo mappings | `--paper-title`, `--arxiv-id`, `--query`, `--output` | | `repo_db.py` | JSONL repo database management | subcommands: `merge`, `filter`, `score`, `search`, `tag`, `stats`, `export`, `rank` | | `repo_metadata.py` | Fetch detailed metadata via `gh api` | `--repos`, `--input`, `--output`, `--delay` | | `clone_repo.py` | Shallow-clone repos for analysis | `--repo`, `--output-dir`, `--depth`, `--branch` | | `analyze_repo_structure.py` | Map file tree, key files, LOC stats | `--repo-dir`, `--output` | | `extract_dependencies.py` | Extract and parse dependency files | `--repo-dir`, `--output` | | `find_implementations.py` | Search cloned repo for specific code patterns | `--repo-dir`, `--patterns`, `--output` | | `repo_readme_fetch.py` | Fetch README without cloning | `--repos`, `--input`, `--output`, `--max-chars` | | `compare_repos.py` | Generate comparison matrix across repos | `--input`, `--output` | | `compile_github_report.py` | Assemble final report from all phases | `--topic-dir` |

---

Phase 1: Intake

**Goal**: Extract all relevant references, URLs, and keywords from the deep-research output.

Steps

1. **Create output directory structure**:

   SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-')
   mkdir -p github-research-output/$SLUG/{phase1_intake,phase2_discovery/search_results,phase3_filtering,phase4_deep_dive/{repos,analyses},phase5_analysis,phase6_blueprint}

2. **Extract references from deep-research output**:

   python ~/.claude/skills/github-research/scripts/extract_research_refs.py \
     --research-dir <deep-research-output-dir> \
     --output github-research-output/$SLUG/phase1_intake/extracted_refs.jsonl

3. **Review extracted refs**: Read the generated JSONL. Note:

• GitHub URLs found directly in reports
• Paper titles and arxiv IDs (for Papers With Code lookup)
• Research keywords and themes (for GitHub search queries)

4. **Write intake summary**: Create `phase1_intake/intake_summary.md` with:

• Number of direct GitHub URLs found
• Number of papers with potential code links
• Key research themes extracted
• Planned search queries for Phase 2

Checkpoint

• `extracted_refs.jsonl` exists with entries
• `intake_summary.md` written
• Search strategy documented

---

Phase 2: Discovery

**Goal**: Cast a wide net to find 50-200 candidate repos from multiple sources.

Steps

1. **Search by direct URLs**: Any GitHub URLs from Phase 1 → fetch metadata:

   python ~/.claude/skills/github-research/scripts/repo_meta