repo_health_audit v1.0.0

name: "repo_health_audit" description: "Run a periodic health audit across public repos: standard files present and current, branch protection and security settings, documentation quality, stale issues and releases, and a fix order per repo. Triggers when auditing one repo or a whole account, before announcing a repo, after a fix wave, or on a quarterly maintenance cadence."

Repo Health Audit

Purpose

Public repos drift. A licence never got added, branch protection was set up for the old default branch, the changelog stopped three releases ago, and forty open issues have not been touched in a year. None of that shows up in the code. This skill runs one repeatable audit across one repo or a whole account, scores every repo on the same sheet, and hands back a fix order that puts the dangerous gaps first.

The audit covers five areas: community files, documentation quality, security settings, branch protection and review, and hygiene (stale issues and PRs, releases, activity). Full check definitions are in references/checklist.md, weights and grade bands in references/scoring-sheet.md, and a real three repo pass in references/worked-example.md.

Workflow

1. Pick the mode. Local mode audits clones on disk and needs no network: python3 bin/repo_audit.py ./repo-a ./repo-b. Remote mode reads GitHub through the gh CLI and covers the checks a clone cannot show: python3 bin/repo_audit.py --remote owner/repo-a --remote owner/repo-b. Account mode audits every public, unarchived repo of a user or org: python3 bin/repo_audit.py --owner someorg --limit 30. Add --md report.md --csv scores.csv --json report.json to save all three outputs. Run gh auth status first in remote mode, and use a token with admin read on the repos when branch protection results matter.
2. Verify one repo by hand before trusting the sweep. On the first remote run for an account, pick one repo you administer and compare the script output against the ground truth: Settings, Branches for protection, Settings, Code security and analysis for Dependabot alerts, secret scanning, push protection, and code scanning, and Insights, Community Standards for the community profile. The community profile API is also available directly at GET /repos/{owner}/{repo}/community/profile, which returns a health percentage and the file list. If the script and the settings pages disagree, fix your understanding of the script output before running the account pass.
3. Read the documentation, do not just count files. The script scores README shape: substantial length, install or getting started steps, a usage section with a code block, onward links, and a changelog with a version or Unreleased entry in Keep a Changelog form (Added, Changed, Deprecated, Removed, Fixed, Security). Then open the two or three worst READMEs yourself. A README can pass every shape check and still fail to say what the project does. Note that as a manual finding in the report.
4. Check security against GitHub's own minimum. For a public repo that minimum is Dependabot alerts, secret scanning, push protection, and code scanning enabled, a SECURITY.md with a private reporting route, and a Dependabot config covering each ecosystem in the repo. If you want a second signal, run OpenSSF Scorecard (scorecard --repo=github.com/OWNER/REPO) on the highest value repos and compare its branch protection, code review, pinned dependencies, and maintained checks against yours. Treat disagreements as a prompt to look, not as an error in either tool.
5. Assess stale load and releases. Count open issues and PRs untouched for more than 90 days and report the count and the share. Check that releases or tags exist, that they follow one version format (semantic versioning is the default recommendation), and that the changelog names the latest tag or a recent date. Recommend stale automation only with guardrails: warn first, exempt pinned and security labels and milestones, and never auto-close an item where the next action belongs to a maintainer.
6. Score, grade, and order the fixes. Use the sheet in references/scoring-sheet.md. Unknown checks leave the denominator and lower coverage instead of scoring zero, and no repo gets a grade below 70 percent coverage. Within a repo, fix committed secret files first, then missing branch protection and secret scanning, then missing LICENSE and SECURITY, then missing update and scanning automation, then README gaps, then the rest. Across an account, work F grades before D before C after the urgent items are cleared.
7. Rerun after fixes and diff the CSV. The audit only counts if the second run moves. Compare category subtotals, not just headline scores, and keep both CSVs so the next quarterly pass starts from evidence.

Output Contract

A finished audit delivers:

• Scoring sheet (CSV): one row per repo with score, coverage, grade, the five category subtotals, and the top three fixes. This is the account view.
• Per repo report (Markdown and JSON): every check marked pass, fail, or unknown with the evidence the script saw, the fix order for that repo, and a separate list of what could not be determined and why.
• Manual findings section: anything you found by reading that the script cannot see, such as a README that passes shape checks but never explains the project, a CODEOWNERS file pointing at people who left, or an org level .github default covering a file the repo lacks.
• Fix plan: the account level order from step 6, grouped as fix now (secret files, unprotected public repos with real traffic), fix this cycle (licences, security policies, automation), and routine (templates, changelog currency, stale backlog).
• Limits line: which repos were audited in local mode only, which checks stayed unknown, and any plan limits (for example a private repo feature that needs GitHub Advanced Security) recorded as limits rather than failures.

Operating Rules

1. Unknown is not fail. A protection endpoint that returns 404 to a token without admin read means not visible, not unprotected. Say which one you know, and verify in Settings before reporting a repo as unprotected.
2. Presence is not quality, and a score is not a verdict. The sheet ranks work, it does not rank maintainers. Report bands and failed checks, and never publish a league table of repos by score to shame anyone.
3. Secrets outrank scores. A committed .env, key, or credential file in the lowest scoring or the highest scoring repo is the first fix either way. Removing the file is step one, rotating the credential if it was real is step two, and both come before any points work.
4. Respect plan and scope limits. Some security features cost money on private repos, and org default files in a .github repo can cover a gap that looks local. Record the real reason a check fails before assigning the fix.
5. Do not auto-close people into silence. Stale automation that closes contributor work because a maintainer was busy does lasting damage. If a repo has no stale policy at all, that is a neutral finding, not a failing one. The failing pattern is a large stale backlog nobody has triaged.
6. Fix in small verified batches. Add the missing standard files from GitHub's own templates where they exist (licence chooser, Contributor Covenant, the community profile Add buttons), rerun the audit after each batch, and stop when the remaining findings are deliberate choices. Record deliberate choices, such as a solo repo waiving the review requirement, in the report so the next audit does not flag them again.
7. Keep the cadence. Quarterly for a full account, in the first week for a new public repo, and after every fix wave. An audit that runs once is a snapshot. The value is in the diff between runs.