lingzhi227/agent-research-skills/github-research

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/.

Phase 1: Intake

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

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} ``

1. 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 ``

1. 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)

1. 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:

``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 ``

1. 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 ``

1. 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 ``

1. 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 ``

1. 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 ``

1. 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 ``

1. 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

Goal: Score and rank repos, select top 15-30 for deeper analysis.

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 ``

1. 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 ``

1. 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" ``

1. 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 ``

1. 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 ``

1. 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

Goal: Clone and deeply analyze the top 8-15 repos.

Steps

1. Select repos for deep dive: Take top 8-15 from ranked list.

1. 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/ ``

1. 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 ``

1. 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 ``

1. 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 ``