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:
- GitHub username — for searching and attribution
- GitHub token — run
gh auth loginor setexport 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.