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:

bash

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

ParameterDefaultExampleEcosystem keyword(s)(required)"AI agent", "LLM tools", "Kubernetes"Target count15top 15 by starsMinimum stars5,000Filter out small reposLanguage filter_(any)Python, TypeScriptAdditional criteria(none)_"must have bug label issues"

Step 2: Search & Collect#

Use multiple search strategies to find candidates:

text

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 PointHow to GetStar countGitHub API / webPrimary languageGitHub APILast commit dateGitHub APIOpen issue countGitHub APIBug-labeled issuesgh issue list --label bug --state open --limit 5``good first issue countGitHub searchCONTRIBUTING.md exists?Check repo rootCI configured?Check .github/workflows/PR template exists?Check .github/PULL_REQUEST_TEMPLATE.mdLicenseGitHub API

Step 3: Score & Rank#

Score each repository on a contribution friendliness scale:

FactorWeightScoringActionable bug issues30%3=many clear bugs, 1=noneActivity (recent commits)20%3=daily, 2=weekly, 1=monthly+Contribution docs15%3=CONTRIBUTING+template, 2=partial, 1=noneCI/CD health15%3=green CI, 2=partial, 1=noneCommunity size (stars)10%3=>50K, 2=>10K, 1=>5KResponse time to PRs10%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:

markdown

# {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.