Repo Scout — Repository Discovery & Ranking

Overview

Systematically discover and rank GitHub repositories in a given ecosystem. Produces a structured, actionable ranking document.

Use cases: Open-source contribution targeting, technology landscape surveys, competitive analysis, ecosystem exploration.

Prerequisites

Before starting, the user must have GitHub CLI authenticated:

gh auth status   # Must show "Logged in"

If not configured, ask the user to provide:

1. GitHub username — for searching and attribution
2. GitHub token — run gh auth login or set export GH_TOKEN=<token>

Without auth, gh API calls will hit rate limits quickly and private repo data won't be accessible.

Workflow

Step 1: Define Scope

Ask the user for (with sensible defaults):

| Parameter | Default | Example | |-----------|---------|---------| | Ecosystem keyword(s) | (required) | "AI agent", "LLM tools", "Kubernetes" | | Target count | 15 | top 15 by stars | | Minimum stars | 5,000 | Filter out small repos | | Language filter | (any) | Python, TypeScript | | Additional criteria | (none) | "must have bug label issues" |

Step 2: Search & Collect

Use multiple search strategies to find candidates:

Search strategies:
1. GitHub search: "{keyword}" sorted by stars
2. "awesome-{keyword}" curated lists
3. GitHub trending in the domain
4. Web search for "{keyword} top open-source projects {year}"

For each candidate repository, collect:

| Data Point | How to Get | |------------|-----------| | Star count | GitHub API / web | | Primary language | GitHub API | | Last commit date | GitHub API | | Open issue count | GitHub API | | Bug-labeled issues | gh issue list --label bug --state open --limit 5 | | good first issue count | GitHub search | | CONTRIBUTING.md exists? | Check repo root | | CI configured? | Check .github/workflows/ | | PR template exists? | Check .github/PULL_REQUEST_TEMPLATE.md | | License | GitHub API |

Step 3: Score & Rank

Score each repository on a contribution friendliness scale:

| Factor | Weight | Scoring | |--------|--------|---------| | Actionable bug issues | 30% | 3=many clear bugs, 1=none | | Activity (recent commits) | 20% | 3=daily, 2=weekly, 1=monthly+ | | Contribution docs | 15% | 3=CONTRIBUTING+template, 2=partial, 1=none | | CI/CD health | 15% | 3=green CI, 2=partial, 1=none | | Community size (stars) | 10% | 3=>50K, 2=>10K, 1=>5K | | Response time to PRs | 10% | 3=<3d, 2=<7d, 1=>7d |

Step 4: Filter Out

Mark repositories to skip if:

• Non-code repo (awesome-lists, documentation-only, resource collections)
• Desktop/mobile UI bugs requiring hardware access
• No actionable bug issues (only feature requests or stale issues)
• Archived or unmaintained (no commits in 6+ months)
• Hostile contribution environment (PRs routinely ignored)

Step 5: Produce Ranking Document

Write {workspace}/ecosystem-top{N}.md:

# {Ecosystem} — Top {N} Repositories

> Generated: {date}
> Keywords: {keywords}
> Minimum stars: {min_stars}

## Rankings

| Rank | Repository | Stars | Language | Open Bugs | Score | Notes |
|------|-----------|-------|----------|-----------|-------|-------|
| 1 | owner/repo | 45.2K | Python | 12 | 8.5/10 | Active, good docs |
| 2 | ... | ... | ... | ... | ... | ... |

## Skipped Repositories

| Repository | Reason |
|-----------|--------|
| owner/repo | Non-code (awesome-list) |

## Detailed Profiles

### 1. owner/repo (45.2K ⭐)
- **Language**: Python
- **Last commit**: 2 days ago
- **Open issues**: 234 (12 labeled `bug`)
- **CONTRIBUTING.md**: ✅
- **CI**: ✅ GitHub Actions
- **Score breakdown**: Activity 3/3, Bugs 3/3, Docs 2/3, CI 3/3, Community 2/3, Response 2/3
- **Notes**: Very active, welcoming community

Output

• {workspace}/ecosystem-top{N}.md — Structured ranking document ready for downstream use

Tips

• When used as part of a contribution campaign, the output feeds directly into the issue-hunter skill for issue analysis.
• For technology evaluation, the ranking + detailed profiles are the final deliverable.
• Re-run periodically to catch ecosystem changes.