SKILL.md
repo-eval
Score a GitHub repo 0-100 on momentum (popularity trajectory) and maintenance (how well it is run), then drop it on a quadrant. Two axes decouple: a repo can be popular-but-abandoned or niche-but-impeccable. Read them together, never alone.
- Momentum comes from the OSS Insight API (no auth):
stargazers history, issue/PR-creator history, org breakdown.
- Maintenance comes from
gh(your existing auth): time-to-first-response, time-to-merge,
PR acceptance rate, issue half-life, open-PR backlog age, release cadence, self-merge rate, contributor concentration, CI. These are computed month-by-month over a ≥12-month window (--months, default 18) and fitted to a slope, so trends — not just current levels — drive the verdict (e.g. response time creeping up = dying, flat = mature).
The script always prints the raw metrics beside the scores — the verdict is auditable, not a black box. See [REFERENCE.md](REFERENCE.md) for every metric definition, the scoring thresholds, and the gotchas (squash-merge, bot noise, mature-vs-dying).
Quick start
# Full evaluation (needs network for OSS Insight + an authenticated gh)
python3 scripts/repo_eval.py vercel/next.js
# One axis at a time
python3 scripts/repo_eval.py vercel/next.js --momentum-only
python3 scripts/repo_eval.py vercel/next.js --maintenance-only
# Machine-readable (includes the per-month trend series under maintenance.monthly)
python3 scripts/repo_eval.py vercel/next.js --json
# Widen the maintenance trend window, or use weekly star granularity for young repos
python3 scripts/repo_eval.py vercel/next.js --months 24
python3 scripts/repo_eval.py vercel/next.js --period week
# Verify the metric math offline (no network)
python3 scripts/repo_eval.py --selftest
Steps
- Confirm
gh auth statusis logged in (the maintenance axis needs it). OSS Insight needs
no auth but must be reachable (some sandboxes block api.ossinsight.io).
- Run
repo_eval.py OWNER/REPO. If one axis is unreachable it degrades gracefully and the
verdict says "Incomplete" — rerun with --maintenance-only / --momentum-only as needed.
- Read the verdict (the quadrant) first, then sanity-check it against the raw metrics.
The score is a transparent weighted average; trust the metrics over the number.
- When interpreting, apply the REFERENCE.md rules: low momentum + steady maintenance + flat
backlog = mature, not dying; green CI + recent commits that are all bot bumps = neglected, not healthy.
Notes
- Zero third-party dependencies — stdlib + the
ghCLI only. - Bot accounts (
*[bot], dependabot, renovate, github-actions, …) are filtered before
computing contributor, response-time, and merge stats.
- Star/contributor totals are ratchets that only climb; this skill works in **rates and
trends**, not totals, so a rolled-over project still reads as declining.
- On hyper-active repos the issue/PR page cap can make the actual trend window shorter than
--months; the report prints *spanmonths and a ! note when that happens, and the affected trends return null rather than a misleadingly short slope.
- For SaaS-OSS, high contributor concentration is expected (the company is the maintainer) —
it is reported as risk, not penalized heavily. The license axis is out of scope; check it separately (OSI vs BSL/SSPL/source-available, and whether it changed).