GitHub Repo Skill: The Next Evolution of Repository Discovery

This is the next-generation version of the GitHub Repo Finder. While the original tool focused on discovering useful repositories, this evolved skill is a Repository Composition Engine. It is designed to help you build complex projects faster by discovering, evaluating, and generating blueprints to combine existing open-source tools with minimal custom code.

🚀 Quick Start Guide

This skill consists of two primary scripts located in the scripts/ directory.

1. Find and Score Repositories

Use repo_finder.py to discover the best tools for any task. It automatically expands your request into multiple search queries and scores results out of 100.

# Basic search for a task
python scripts/repo_finder.py --task "AI chatbot with Next.js" --max-results 5
# Search for a specific language with a quality threshold
python scripts/repo_finder.py --task "PDF processing" --language python --min-stars 500

2. Compare Specific Repositories

When you have a few candidates and need to make a data-driven choice, use the compare mode.

python scripts/repo_finder.py --mode compare --repos "owner/repo1,owner/repo2"

3. Generate a Combination Recipe

The most powerful feature: generate a complete architectural plan to wire multiple repositories together.

# Find repos and pipe them directly into the recipe builder
python scripts/repo_finder.py --task "video processing with OCR" --json | python scripts/recipe_builder.py --task "video processing with OCR"

4. ⚡ Vibe Mode (AI-Agent Optimized)

For ultra-fast "Vibe Coding," use the --vibe flag. This generates code-first, copy-paste ready blueprints specifically optimized for AI agents.

# Generate a copy-paste ready vibe recipe
python scripts/repo_finder.py --task "real-time analytics" --json | python scripts/recipe_builder.py --task "real-time analytics" --vibe

---

🛠 Features & Evolution

This version introduces several major advancements over the original repo finder:

📊 Advanced Scoring Engine

We no longer just look at stars. Every repo is evaluated across five dimensions:

• Popularity (25%): Stars and forks (log-scaled).
• Maintenance (30%): Recency of updates and commit frequency.
• Community (20%): Number of contributors and issue velocity.
• Documentation (15%): Quality of README and presence of examples.
• License (10%): Preference for permissive licenses (MIT, Apache, BSD).

🏗 Automated Recipe Builder

The recipe_builder.py script creates a "Combination Recipe" which includes:

• Architecture Patterns: Automatically detects if you need Microservices, API Composition, or Library integration.
• Glue Code Estimates: Tells you exactly how much code you'll need to write (typically 300-750 lines).
• Integration Steps: A step-by-step 8-stage guide from setup to deployment.
• File Structure: A recommended directory layout for your new project.

⚡ Vibe Mode: Code-First Composition

The new Vibe Mode (--vibe) is the ultimate toolkit for AI agents:

• One-Line Vibe Checks: Instant emoji-based readiness assessment (e.g., ✅ Drop-in, 🐳 Docker-ready).
• Copy-Paste Infrastructure: Generates a full docker-compose.yml for all services.
• Main Orchestration Skeleton: Creates a main.py with pre-configured adapters and TODO markers.
• Environment Templates: Auto-generates a .env file with all required API key placeholders.

---

📋 Comparison: Original vs. Next Version

Feature	Original "Github Repo Finder"	New "Github-Repo-Skill"
Primary Goal	Finding a single useful repo.	Building a full system by combining repos.
Search Intelligence	Keyword-based.	Task-to-Capability mapping.
Scoring	Star count.	Multi-dimensional health scoring.
Output	List of links.	Architectural blueprints (Recipes).
Vibe Coding	No.	Yes (--vibe flag).
Comparison	Manual.	Automated side-by-side analysis.
Bug Status	Unknown.	✅ Production Ready — 82/82 unit tests + 7/7 live integration tests.

---

⚠️ Rate Limits & Known Limitations

Read this before running heavy workloads — GitHub enforces two independent rate limits and a PAT only helps with one of them.

Two rate limits, two different rules

Resource	Limit	Reset window	Does a PAT raise it?
Core REST (/repos/*, /user, etc.)	5000 req/hour (60 without PAT)	hourly	✅ yes — this is why we recommend GITHUB_TOKEN
Search (/search/repositories)	30 req/min	per-minute	❌ no — the search cap is the same for everyone

Each --task invocation expands to ~5 search queries, so the practical ceiling is ~6 task searches per minute, regardless of PAT tier. If you get a 429 while a token is set, it's almost always the secondary search cap kicking in, not the core limit.

Other known limitations (from the v1.1.0 stress-test pass)

• recent_commits capped at 100 per repo. The --details flag fetches the most recent 100 commits for maintenance scoring. Very busy repos will plateau at that ceiling; the maintenance sub-score is still directionally correct.
• Role detection with bare --repos. When recipe_builder.py is invoked with --repos (no API metadata fetched), role assignment falls back to name-based heuristics and can misclassify e.g. tailwindlabs/tailwindcss as ai/ml. Use repo_finder.py --json | recipe_builder.py --task "…" for accurate roles.
• vibe_check keyword coverage is not exhaustive. Stripe, OpenAI, and similar SDKs may be classified as "Drop-in" if their description doesn't contain api key / token / auth. Inspect the generated .env template before assuming it's safe to skip.
• 429 warning text is generic. When the search secondary limit hits, the script prints "Set GITHUB_TOKEN for higher limits" — this is misleading because the search cap is independent of your token.

These are tracked as future work; no crash bugs were found.

---

🔧 Installation & Setup

1. Clone the repo:

   git clone https://github.com/Ehsas317/github-repo-skill.git
   cd github-repo-skill

2. (Optional) Set GitHub Token: To avoid rate limits, set your GitHub Personal Access Token:

   export GITHUB_TOKEN=your_token_here

3. Run: The scripts use the Python Standard Library, so no extra pip install is required!

---

🧪 Tests

The skill ships with an 82-test stress-test suite that covers the scoring engine, query generation, network resilience (mocked 403/404/422/429/5xx), recipe generation, vibe mode, and CLI flows.

python3 -m unittest tests.test_stress

See CHANGELOG.md for the full list of bug fixes applied during the stress-test pass.

---

✅ Verified Status — v1.1.0 (Hardened)

This release passed a full stress-test pass on 2026-07-08 in an Ubuntu 24.04 / Python 3.11 sandbox. The skill is Production Ready.

Unit Tests (82/82 PASSED)

Category	Tests	Status	Coverage
Date Parsing	5	PASSED	ISO Zulu, offsets, and garbage strings
Scoring Logic	12	PASSED	Weighted popularity / maintenance / docs
Topic Extraction	5	PASSED	Case-insensitive, deduped keyword mapping
Recipe Generation	25	PASSED	Docker Compose, env templates, glue code
CLI Interface	35	PASSED	Correct exit codes and JSON output

Live Integration Tests (7/7 PASSED, against real GitHub API)

Scenario	Result	Observation
Basic Search (websocket chat)	PASSED	Fast response, accurate ranking
Complex Task (--details deep-dive)	PASSED	100+ API calls, stable in 322s
Compare Mode (mixed valid/invalid)	PASSED	Gracefully skipped malformed / 404 specs
Recipe Mode (end-to-end)	PASSED	Correct JSON + architecture patterns
Vibe Mode (piped builder)	PASSED	Generated Docker + adapter skeletons
Error Handling (missing args)	PASSED	Exit code 1 + helpful message
Large Results (--max-results 50)	PASSED	API-capped to 30, no pagination crash

Concurrency / Rate Limiting (10/10 PASSED)

• 5 parallel threads × 10 independent search tasks → 100% success
• Internal retry logic and exponential backoff handled the burst without race conditions.

Key Improvements (vs. previous version)

1. Query Sanitization — no more language:None leaks in search queries.
2. Resilience — github_api_get handles 404, 403, 429, 5xx without crashing.
3. Consistency — Docker Compose service names sanitized; ports guaranteed unique.
4. Efficiency — Vibe mode uses an anti-hang mechanism for stdin reading.

🔐 No PAT is shipped with this repo. The skill reads GITHUB_TOKEN / GH_TOKEN only from the user's local environment (via Authorization: Bearer … header) and never embeds it in URLs, logs, or output.

---