The composite view: measures a repository against the professional-OSS bar and says what to fix first and which skill fixes it. The failure this skill fixes: ad-hoc audits that check whatever comes to mind, miss whole categories (metadata, protections), and produce unprioritized nag-lists that ignore project stage.
When NOT to use
- The user names the fix ("write a README", "add topics", "protect main") → route straight to the focused skill; don't audit first.
- Code-level bug hunting or PR security review → code-review work, not repo setup.
- CI pipeline debugging → out of scope (CI presence is in scope).
Workflow
- Collect evidence mechanically — no vibes:
Gathers: repo metadata (python3 "${CLAUDE_SKILL_DIR}/scripts/collect_evidence.py" [owner/repo] > /tmp/repo-evidence.jsongh repo view --json), community-profile health percentage, file presence (README/LICENSE/health files/templates/workflows), protections and security settings, releases, archive status, latest CI run. Every value is tri-state —nullmeans not determinable (permissions, plan limits), and the JSON'snot_collectedlist names checks that are manual or agent-judged by design. - Score with
references/audit-checklist.md: six categories, each with weighted checks — README quality, discoverability, community health files, contribution intake, protections, vital signs. Compute per-category scores and the overall grade (A ≥90 … D). Checks answered by evidence fields score mechanically; checks innot_collectedare scored by you reading the repo (say so in the report) or marked "manual review required" — never inferred from silence, andnullevidence is always reported as unknown, not failing. - Right-size before reporting. Apply the checklist's stage rules: a solo hobby repo is not graded down for missing GOVERNANCE or elaborate templates — mark those "deferred by stage", not failing. Non-negotiables at every stage: LICENSE, README basics, no leaked secrets.
- Report (template in the checklist): per-category score table, overall grade,
then the top-5 prioritized fixes, each with impact, effort, and the owning
skill (
readme-author,repo-discoverability,community-health,issue-pr-templates,repo-protections; documentation-set or docs-site gaps →docs-author/docs-site). - Going-public pre-flight (when asked "before I make it public"): add the flip-specific blockers — license present (evidence-backed), PVR to enable right after the flip, social preview ready, plus two MANUAL blockers the evidence never covers: a secret scan of the full git history (gitleaks/trufflehog) and a personal/private-file review. List those two as unchecked boxes the maintainer must do — never present them as passed. Split blockers from nice-to-haves.
- Fix nothing unasked. Offer to run the owning skill for the top items.
Output spec
A report containing: evidence-backed per-category scores, an overall grade, a top-5 fix list with owner-skill routing, stage-deferred items clearly marked, and zero modifications to the repository.
Gotchas
- Some evidence needs permissions: traffic stats need push access; protections and security flags can 403 on private/free plans — the script degrades to "unknown"; report unknowns as unknowns, never as failures.
- The community-profile health percentage only counts public-repo files — on private repos rely on the file-presence checks instead.
- Don't chase 100/100: the checklist encodes diminishing returns; say when a repo is already past the bar its stage needs.
- One audit per repo per conversation — re-run only after fixes land.
Files
references/audit-checklist.md— the six-category weighted checklist, scoring rubric, stage rules, report template.scripts/collect_evidence.py— mechanical evidence collector (gh + filesystem), JSON to stdout; exits non-zero only when the target repo can't be read.