Github Research

<!-- AUTO-GENERATED by export-skills.py — DO NOT EDIT -->
---
name: github-research
description: Find reputable GitHub repositories with quality filters (stars, recency, license). Use when searching for code samples, reference implementations, libraries, or templates on GitHub. Prioritizes curated Awesome Lists, then searches with star thresholds to ensure code quality. Requires gh CLI (version 2.14+).
---

# GitHub Research

Find reputable GitHub repositories using quality filters. Prioritize curated Awesome Lists, then search with star thresholds.

## When to Use

- "Find GitHub repos for X"
- "Search GitHub for Y examples"
- "Find a good library for Z"
- Discovering quality open-source code, templates, or reference implementations

## Workflow

### Step 1: Check Awesome Lists First

Awesome Lists are community-curated collections of quality resources. Search them first:

```bash
gh search repos "awesome <topic>" --stars=">=5000" --limit=5 \
  --json name,stargazersCount,url,description
```

If a relevant Awesome List exists (e.g., `awesome-python`, `awesome-react`), recommend it as the primary source.

### Step 2: Search with Quality Filters

```bash
gh search repos "<query>" \
  --language=<lang> \
  --stars=">=1000" \
  --archived=false \
  --limit=10 \
  --json name,url,stargazersCount,license,description,pushedAt
```

**Star thresholds by use case:**

| Use Case | Threshold | Flag |
|---|---|---|
| Production code | 1000+ stars | `--stars=">=1000"` |
| Learning/examples | 500+ stars | `--stars=">=500"` |
| Exploration | 100+ stars | `--stars=">=100"` |

### Step 3: Apply Additional Filters

| Filter | Flag | Example |
|---|---|---|
| Topic | `--topic` | `--topic=cli` |
| Recency | `--updated` | `--updated=">2024-01-01"` |
| License | `--license` | `--license=mit` |
| Owner | `--owner` | `--owner=microsoft` |
| Sort | `--sort` | `--sort=stars` |

### Step 4: Validate Top Results

For the top 3-5 candidates, check quality indicators:

```bash
gh api "repos/<owner>/<repo>" --jq '{
  stars: .stargazers_count,
  forks: .forks_count,
  issues: .open_issues_count,
  updated: .pushed_at,
  license: .license.spdx_id
}'
```

**Quality indicators:**
- Recent activity (updated within 6 months)
- Active issues/PRs (maintained)
- Multiple contributors
- Clear license (MIT, Apache-2.0 preferred)

### Step 5: Save Results

Save research to `docs/research/` as Markdown:

```
docs/research/YYYY-MM-DD-<topic>-github-repos.md
```

Include: repo name, stars, license, URL, and brief description.

## Examples

```bash
# FastAPI templates
gh search repos "fastapi template" --language=python --stars=">=500" --archived=false --limit=10

# CLI tools in Go
gh search repos --topic=cli --language=go --stars=">=1000" --limit=10

# React component libraries (recent)
gh search repos "react component library" --language=typescript \
  --stars=">=1000" --updated=">2024-01-01"
```

## Rate Limits

- Search API: 30 requests/minute (authenticated)
- Check remaining: `gh api rate_limit --jq '.resources.search.remaining'`

## Prerequisites

- GitHub CLI version 2.14+ with `gh search repos` command
- Authenticated: `gh auth status`

## Anti-Patterns

| Avoid | Why | Instead |
|---|---|---|
| No star threshold | Returns low-quality repos | Use `--stars=">=500"` minimum |
| Skipping Awesome Lists | Miss curated resources | Always check Awesome Lists first |
| Ignoring recency | Stale repos cause issues | Filter by `--updated` or check `pushedAt` |
| Ignoring license | Legal risk | Filter by `--license` or verify in results |
| Single search query | Misses relevant repos | Try multiple query variations |

## References

- Source: claude-skills/github-research (MIT License)
- Requires: [GitHub CLI](https://cli.github.com/) v2.14+

<!-- Source: .faos/custom/skills/tools/github-research/SKILL.md -->