GitHub Semantic Repo Finder
Empower developers to find the best GitHub repositories, reference architectures, starter templates, and peer projects using natural semantic search.
GitHub's native search uses strict token intersection matching, which often returns zero results for natural language developer queries (e.g. "lightweight desktop chat app with local LLMs in Rust"). This skill bridges that gap by decomposing developer intent into multi-angle search vectors, ranking repositories by relevance and health, and surfacing actionable insights.
Capabilities
- Semantic Search: Natural language intent search for boilerplates, libraries, architecture patterns, and full-stack reference apps.
- Similarity & Peer Discovery: Given an existing repo or technology (e.g.,
shadcn/ui, pocketbase), find peer repositories, direct alternatives, or cross-framework ports (e.g., Svelte/Vue equivalents).
- Architecture & Health Inspection: Deeply inspect repository structure, language breakdown, recent commit activity, maintenance status, license, and README features.
Workflow Guide
Step 1: Deconstruct Developer Intent
When a developer asks for a repository or reference implementation:
- Identify the core application domain: e.g.,
kanban, auth, video-streaming, vector-search, chat.
- Identify the target tech stack: e.g.,
Next.js, Svelte, Rust, FastAPI, Flutter, Tauri.
- Determine the target repository type:
- Template / Boilerplate: Starting a new app from scratch (
--template).
- Library / Component: Looking for a package to integrate.
- Full-Stack Reference: Looking for an existing production-grade project to study design patterns and folder structures.
Step 2: Execute the Search Engine
Use the helper script find_repo.py:
Semantic Search
python3 .agents/skills/find-repo/scripts/find_repo.py search "<natural_language_prompt>" [options]
Common options:
-l, --language <Lang>: Restrict to a specific language (e.g. Rust, TypeScript, Python, Svelte).--min-stars <N>: Filter out repositories below a community trust threshold (e.g. --min-stars 20).-n, --limit <N>: Return top $N$ ranked candidates (default 10).--template: Filter for official GitHub template repositories.--sort <best-match|stars|updated>: Sorting strategy.--json: Output raw JSON for programmatic handling.
Example:
python3 .agents/skills/find-repo/scripts/find_repo.py search "real-time whiteboard collaboration with webrtc" -l TypeScript -n 5
Finding Similar Repositories & Alternatives
python3 .agents/skills/find-repo/scripts/find_repo.py similar "<owner/repo>" [options]
Example:
# Find Svelte alternatives/equivalents to shadcn-ui
python3 .agents/skills/find-repo/scripts/find_repo.py similar "shadcn-ui/ui" -l Svelte -n 5
Inspecting Repository Architecture & Health
python3 .agents/skills/find-repo/scripts/find_repo.py inspect "<owner/repo>"
Fetches commit recency, health status, licensing, language breakdown, top-level directory structure, and README summary.
Step 3: Evaluate and Synthesize Results
Before presenting repositories to the developer, evaluate them against the Repository Evaluation Criteria:
- Maintenance Health: Is the repository actively maintained (
Active), stale (> 1 year), or dormant (> 2 years)?
- License Permissiveness: Is it safe for the developer's project (
MIT, Apache-2.0) or copyleft (GPL)?
- Architectural Fit: Does the folder structure and setup match the developer's project setup?
Step 4: Present Actionable Recommendations
Format your response clearly:
- Summary Table: Name, Stars, Language, License, Last Updated, and One-line Description.
- Top Recommendations with Context:
- Why this repository matches their specific problem.
- Key architectural features (e.g., uses WebSockets + IndexedDB, Clean Architecture, Tailwind v4).
- How to use it (as a starter template vs code reference vs library).
- Quick Commands: Direct
git clone or inspection command to get started immediately.
Reference Guides
1---2name: find-repo3description: Find GitHub repositories through natural semantic search, discover reference implementations, starter templates, and peer projects, or compare similar repositories to help developers build applications. Use whenever a developer asks to find GitHub repos, boilerplates, libraries, open-source alternatives, or architectural references for their tech stack.4---56# GitHub Semantic Repo Finder78Empower developers to find the best GitHub repositories, reference architectures, starter templates, and peer projects using natural semantic search.910GitHub's native search uses strict token intersection matching, which often returns zero results for natural language developer queries (e.g. *"lightweight desktop chat app with local LLMs in Rust"*). This skill bridges that gap by decomposing developer intent into multi-angle search vectors, ranking repositories by relevance and health, and surfacing actionable insights.1112---1314## Capabilities15161. **Semantic Search**: Natural language intent search for boilerplates, libraries, architecture patterns, and full-stack reference apps.172. **Similarity & Peer Discovery**: Given an existing repo or technology (e.g., `shadcn/ui`, `pocketbase`), find peer repositories, direct alternatives, or cross-framework ports (e.g., Svelte/Vue equivalents).183. **Architecture & Health Inspection**: Deeply inspect repository structure, language breakdown, recent commit activity, maintenance status, license, and README features.1920---2122## Workflow Guide2324### Step 1: Deconstruct Developer Intent2526When a developer asks for a repository or reference implementation:271. **Identify the core application domain**: e.g., `kanban`, `auth`, `video-streaming`, `vector-search`, `chat`.282. **Identify the target tech stack**: e.g., `Next.js`, `Svelte`, `Rust`, `FastAPI`, `Flutter`, `Tauri`.293. **Determine the target repository type**:30 - **Template / Boilerplate**: Starting a new app from scratch (`--template`).31 - **Library / Component**: Looking for a package to integrate.32 - **Full-Stack Reference**: Looking for an existing production-grade project to study design patterns and folder structures.3334### Step 2: Execute the Search Engine3536Use the helper script [find_repo.py](./scripts/find_repo.py):3738#### Semantic Search39```bash40python3 .agents/skills/find-repo/scripts/find_repo.py search "<natural_language_prompt>" [options]41```42Common options:43- `-l, --language <Lang>`: Restrict to a specific language (e.g. `Rust`, `TypeScript`, `Python`, `Svelte`).44- `--min-stars <N>`: Filter out repositories below a community trust threshold (e.g. `--min-stars 20`).45- `-n, --limit <N>`: Return top $N$ ranked candidates (default 10).46- `--template`: Filter for official GitHub template repositories.47- `--sort <best-match|stars|updated>`: Sorting strategy.48- `--json`: Output raw JSON for programmatic handling.4950*Example:*51```bash52python3 .agents/skills/find-repo/scripts/find_repo.py search "real-time whiteboard collaboration with webrtc" -l TypeScript -n 553```5455#### Finding Similar Repositories & Alternatives56```bash57python3 .agents/skills/find-repo/scripts/find_repo.py similar "<owner/repo>" [options]58```59*Example:*60```bash61# Find Svelte alternatives/equivalents to shadcn-ui62python3 .agents/skills/find-repo/scripts/find_repo.py similar "shadcn-ui/ui" -l Svelte -n 563```6465#### Inspecting Repository Architecture & Health66```bash67python3 .agents/skills/find-repo/scripts/find_repo.py inspect "<owner/repo>"68```69Fetches commit recency, health status, licensing, language breakdown, top-level directory structure, and README summary.7071---7273### Step 3: Evaluate and Synthesize Results7475Before presenting repositories to the developer, evaluate them against the [Repository Evaluation Criteria](./references/evaluation_criteria.md):76- **Maintenance Health**: Is the repository actively maintained (`Active`), stale (`> 1 year`), or dormant (`> 2 years`)?77- **License Permissiveness**: Is it safe for the developer's project (`MIT`, `Apache-2.0`) or copyleft (`GPL`)?78- **Architectural Fit**: Does the folder structure and setup match the developer's project setup?7980### Step 4: Present Actionable Recommendations8182Format your response clearly:831. **Summary Table**: Name, Stars, Language, License, Last Updated, and One-line Description.842. **Top Recommendations with Context**:85 - Why this repository matches their specific problem.86 - Key architectural features (e.g., uses WebSockets + IndexedDB, Clean Architecture, Tailwind v4).87 - How to use it (as a starter template vs code reference vs library).883. **Quick Commands**: Direct `git clone` or inspection command to get started immediately.8990---9192## Reference Guides9394- [GitHub Advanced Search Syntax Guide](./references/search_syntax_guide.md): Reference qualifiers (`topic:`, `in:readme`, `stars:`, `is:template`).95- [Repository Evaluation Criteria](./references/evaluation_criteria.md): Checklist for evaluating open-source projects for production apps.
will702