GitHub Research Skill

Trigger

• "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

~/.claude/skills/github-research/

./github-research-output/{slug}/

paper_db.jsonl

code_repos.md

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

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

extract_research_refs.py

--research-dir

--output

search_github.py

gh api

--query

--language

--min-stars

--sort

--max-results

--topic

--output

search_github_code.py

--query

--language

--filename

--max-results

--output

search_paperswithcode.py

--paper-title

--arxiv-id

--query

--output

repo_db.py

merge

filter

score

search

tag

stats

export

rank

repo_metadata.py

gh api

--repos

--input

--output

--delay

clone_repo.py

--repo

--output-dir

--depth

--branch

analyze_repo_structure.py

--repo-dir

--output

extract_dependencies.py

--repo-dir

--output

find_implementations.py

--repo-dir

--patterns

--output

repo_readme_fetch.py

--repos

--input

--output

--max-chars

compare_repos.py

--input

--output

compile_github_report.py

--topic-dir

Phase 1: Intake

Steps

1. Create output directory structure:
   bash

   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:
   bash

   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

Steps

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

   python ~/.claude/skills/github-research/scripts/repo_metadata.py \
     --repos owner1/name1 owner2/name2 ... \
     --output github-research-output/$SLUG/phase2_discovery/search_results/direct_urls.jsonl

2. Search Papers With Code: For each paper with an arxiv ID:
   bash

   python ~/.claude/skills/github-research/scripts/search_paperswithcode.py \
     --arxiv-id 2401.12345 \
     --output github-research-output/$SLUG/phase2_discovery/search_results/pwc_2401.12345.jsonl

3. Search GitHub by keywords (3-8 queries based on research themes):
   bash

   python ~/.claude/skills/github-research/scripts/search_github.py \
     --query "multi-agent LLM coordination" \
     --min-stars 10 --sort stars --max-results 50 \
     --output github-research-output/$SLUG/phase2_discovery/search_results/gh_query1.jsonl

4. Search GitHub code (for specific implementations):
   bash

   python ~/.claude/skills/github-research/scripts/search_github_code.py \
     --query "class MultiAgentOrchestrator" \
     --language python --max-results 30 \
     --output github-research-output/$SLUG/phase2_discovery/search_results/code_query1.jsonl

5. Fetch READMEs for repos that lack descriptions:
   bash

   python ~/.claude/skills/github-research/scripts/repo_readme_fetch.py \
     --input <repos.jsonl> \
     --output github-research-output/$SLUG/phase2_discovery/search_results/readmes.jsonl

6. Merge all results into master database:
   bash

   python ~/.claude/skills/github-research/scripts/repo_db.py merge \
     --inputs github-research-output/$SLUG/phase2_discovery/search_results/*.jsonl \
     --output github-research-output/$SLUG/repo_db.jsonl

7. Write discovery log: Create

   phase2_discovery/discovery_log.md

   with search queries used, results per source, total unique repos found.

Rate Limits

• GitHub search API: 30 requests/minute (authenticated)
• Papers With Code API: No strict limit but be respectful (1 req/sec)
• Add

  --delay 1.0

  to batch operations when needed

Checkpoint

• repo_db.jsonl

  populated with 50-200 repos

• discovery_log.md

  with search details

Phase 3: Filtering

Steps

1. Enrich metadata for all repos:
   bash

   python ~/.claude/skills/github-research/scripts/repo_metadata.py \
     --input github-research-output/$SLUG/repo_db.jsonl \
     --output github-research-output/$SLUG/repo_db.jsonl \
     --delay 0.5

2. Score repos (quality + activity scores):
   bash

   python ~/.claude/skills/github-research/scripts/repo_db.py score \
     --input github-research-output/$SLUG/repo_db.jsonl \
     --output github-research-output/$SLUG/repo_db.jsonl

3. LLM relevance scoring: Read through the top ~50 repos (by quality_score) and assign

   relevance_score

   (0.0-1.0) based on:
   • Direct relevance to research topic
   • Implementation completeness
   • Code quality signals (from README, description)
   • Update the relevance scores:
   bash

   python ~/.claude/skills/github-research/scripts/repo_db.py tag \
     --input github-research-output/$SLUG/repo_db.jsonl \
     --ids owner/name --tags "relevance:0.85"

4. Compute composite scores and rank:
   bash

   python ~/.claude/skills/github-research/scripts/repo_db.py score \
     --input github-research-output/$SLUG/repo_db.jsonl \
     --output github-research-output/$SLUG/repo_db.jsonl
   python ~/.claude/skills/github-research/scripts/repo_db.py rank \
     --input github-research-output/$SLUG/repo_db.jsonl \
     --output github-research-output/$SLUG/phase3_filtering/ranked_repos.jsonl \
     --by composite_score

5. Select top repos: Filter to top 15-30:
   bash

   python ~/.claude/skills/github-research/scripts/repo_db.py filter \
     --input github-research-output/$SLUG/phase3_filtering/ranked_repos.jsonl \
     --output github-research-output/$SLUG/phase3_filtering/ranked_repos.jsonl \
     --max-repos 30 --not-archived

6. Write filtering report: Create

   phase3_filtering/filtering_report.md

   :
   • Stats before/after filtering
   • Score distributions
   • Top 30 repos with scores and rationale

Scoring Formula

activity_score = sigmoid((days_since_push < 90) * 0.4 + has_recent_commits * 0.3 + open_issues_ratio * 0.3)
quality_score  = normalize(log(stars+1) * 0.3 + log(forks+1) * 0.2 + has_license * 0.15 + has_readme * 0.15 + not_archived * 0.2)
composite_score = relevance * 0.4 + quality * 0.35 + activity * 0.25

Checkpoint

• ranked_repos.jsonl

  with 15-30 repos

• filtering_report.md

  with scoring details

Phase 4: Deep Dive

Steps

1. Select repos for deep dive: Take top 8-15 from ranked list.
2. Clone each repo (shallow):
   bash

   python ~/.claude/skills/github-research/scripts/clone_repo.py \
     --repo owner/name \
     --output-dir github-research-output/$SLUG/phase4_deep_dive/repos/

3. Analyze structure for each cloned repo:
   bash

   python ~/.claude/skills/github-research/scripts/analyze_repo_structure.py \
     --repo-dir github-research-output/$SLUG/phase4_deep_dive/repos/name/ \
     --output github-research-output/$SLUG/phase4_deep_dive/analyses/name_structure.json

4. Extract dependencies:
   bash

   python ~/.claude/skills/github-research/scripts/extract_dependencies.py \
     --repo-dir github-research-output/$SLUG/phase4_deep_dive/repos/name/ \
     --output github-research-output/$SLUG/phase4_deep_dive/analyses/name_deps.json

5. Find implementations: Search for key algorithms/concepts from research:
   bash

   python ~/.claude/skills/github-research/scripts/find_implementations.py \
     --repo-dir github-research-output/$SLUG/phase4_deep_dive/repos/name/ \
     --patterns "class Transformer" "def forward" "attention" \
     --output github-research-output/$SLUG/phase4_deep_dive/analyses/name_impls.jsonl

6. Deep code reading: For each repo, READ the key source files identified by structure analysis. Write a per-repo analysis in

   phase4_deep_dive/analyses/{name}_analysis.md

   :
   • Architecture overview
   • Key algorithms implemented
   • Code quality assessment
   • API / interface design
   • Dependencies and requirements
   • Strengths and limitations
   • Reusability assessment (how easy to extract components)
7. Write deep dive summary:

   phase4_deep_dive/deep_dive_summary.md

IMPORTANT: Actually Read Code

• Read the main source files (entry points, core modules)
• Understand the actual implementation approach
• Identify specific functions/classes that implement research concepts
• Note code patterns, design decisions, and trade-offs

Checkpoint

• Repos cloned in

  repos/

• Per-repo analysis files in

  analyses/

• deep_dive_summary.md

  written

Phase 5: Analysis

Steps

1. Generate comparison matrix:
   bash

   python ~/.claude/skills/github-research/scripts/compare_repos.py \
     --input github-research-output/$SLUG/phase4_deep_dive/analyses/ \
     --output github-research-output/$SLUG/phase5_analysis/comparison.json

2. Write comparison matrix: Create

   phase5_analysis/comparison_matrix.md

   :
   • Table comparing repos across dimensions (language, LOC, stars, framework, license, tests)
   • Dependency overlap analysis
   • Strengths/weaknesses per repo
3. Write technique map: Create

   phase5_analysis/technique_map.md

   :
   • Map each paper concept / research technique → specific repo + file + function
   • Identify gaps (techniques with no implementation found)
   • Note alternative implementations of the same concept
4. Write analysis report:

   phase5_analysis/analysis_report.md

   :
   • Executive summary of findings
   • Key insights from code analysis
   • Recommendations for which repos to use for which purposes

Checkpoint

• comparison_matrix.md

  with repo comparison table

• technique_map.md

  mapping concepts to code

• analysis_report.md

  with findings

Phase 6: Blueprint

Steps

1. Write integration plan:

   phase6_blueprint/integration_plan.md

   :
   • Recommended architecture for combining repos
   • Step-by-step integration approach
   • Dependency resolution strategy
   • Potential conflicts and how to resolve them
2. Write reuse catalog:

   phase6_blueprint/reuse_catalog.md

   :
   • For each reusable component: source repo, file path, function/class, what it does, how to extract it
   • License compatibility matrix
   • Effort estimates (easy/medium/hard to integrate)
3. Compile final report:
   bash

   python ~/.claude/skills/github-research/scripts/compile_github_report.py \
     --topic-dir github-research-output/$SLUG/

4. Write blueprint summary:

   phase6_blueprint/blueprint_summary.md

   :
   • One-page executive summary
   • Top 5 repos and why
   • Recommended next steps

Checkpoint

• integration_plan.md

  complete

• reuse_catalog.md

  with component catalog

• final_report.md

  compiled

• blueprint_summary.md

  as executive summary

Quality Conventions

1. Repos are ranked by composite score:

   relevance × 0.4 + quality × 0.35 + activity × 0.25

2. Deep dive requires reading actual code, not just READMEs
3. Integration blueprint must map paper concepts → specific code files/functions
4. Incremental saves: Each phase writes to disk immediately
5. Checkpoint recovery: Can resume from any phase by checking what outputs exist
6. All scripts are stdlib-only Python — no pip installs needed

7. gh

   CLI is required for GitHub API access (must be authenticated)
8. Deduplication by

   repo_id

   (owner/name) across all searches
9. Rate limit awareness: Respect GitHub search API limits (30 req/min)

Error Handling

• If

  gh

  is not installed: warn user and provide installation instructions
• If a repo is archived/deleted: skip gracefully, note in log
• If clone fails: skip, note in log, continue with remaining repos
• If Papers With Code API is down: skip, rely on GitHub search only
• Always write partial progress to disk so work is not lost

References

• See

  references/phase-guide.md

  for detailed phase execution guidance
• Deep-research skill:

  ~/.claude/skills/deep-research/SKILL.md

• Paper database pattern:

  ~/.claude/skills/deep-research/scripts/paper_db.py