# Repo Audit

> Audit a repository against the 10 "repo to product" tips (Mateusz Pusz) — discoverable naming, green CI matrix, issue triage, prose documentation, zero-install demos, dev containers, consumption paths, release announcements, contributor recognition, community building. Use when the user asks to audit, score, review, or health-check a repo's project hygiene, onboarding experience, docs structure, packaging, or open-source readiness; or says "repo audit", "audit this repo", "is my repo professional", "repo to product", "score my README". Read-only — pair with repo-upgrade to apply the fixes.

- Skill: `breed/repo-audit` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add breed/repo-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/breed/repo-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: breed (https://skillmd.com/u/breed)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/breed/repo-audit

---


# Repo Audit

Score a repository against the ten tips that separate a *technically good repo* from a *product people can actually use and contribute to*.

Core premise: **technical excellence ≠ project excellence.** This audit measures the second one only. It says nothing about whether the code is good.

## Workflow

1. **Establish the target.** Default to the cwd. If the user names another path or a GitHub URL, use that. Confirm you are at the repo root (look for `.git/`).
2. **Detect the ecosystem.** Read `references/ecosystems.md` and identify the language/build stack. Every check below has an ecosystem-specific form — apply the right one. Multi-language repos: audit the primary published artifact.
3. **Run the rubric.** Read `references/rubric.md` and work through all ten tips. Each has explicit detection commands and 0/1/2 scoring criteria.
4. **Report.** Use the output format below.

Prefer batching the cheap filesystem checks into a few parallel Bash calls rather than one call per check. `gh` is often available for the GitHub-side checks (labels, discussions, releases, Actions); if `gh auth status` fails, mark those checks `UNKNOWN` rather than guessing.

## Scoring

Each tip scores **0–2**:

| Score | Meaning |
|---|---|
| **0** | Absent — the practice is simply not there |
| **1** | Partial — something exists but misses the point (e.g. a `CHANGELOG.md` of raw commit subjects, or a README with no code sample above the fold) |
| **2** | Good — meets the bar described in the rubric |

Total is out of 20. `UNKNOWN` checks are excluded from both numerator and denominator — report the adjusted denominator rather than silently scoring an unverifiable item as 0.

Grade bands: **17–20** product · **12–16** solid repo, gaps at the edges · **7–11** works for the author, hostile to newcomers · **0–6** fortress.

## Output format

Report in the conversation by default. Write `REPO-AUDIT.md` into the target repo **only** if the user asks or passes `--write` — dropping files into someone's repo uninvited is intrusive.

Lead with the scorecard:

```
Repo: <name>   Ecosystem: <stack>   Score: 13/20

  1 Discovery        ██░  2   unique name, README pitch is generic
  2 Green CI         █░░  1   CI exists, single config, no badge
  3 Triage           ░░░  0   no issue templates, Discussions off
  ...
```

Then, per tip that scored below 2: **what's missing**, **why it costs you** (in the talk's terms — lost users, lost contributors, lost trust), and **the smallest concrete fix**. Cite real paths (`​.github/workflows/ci.yml:14`).

Close with **"Start here"** — the three highest-leverage fixes, ordered by (impact ÷ effort). The talk's own advice is explicit: *don't implement all ten at once; do one this week and the next one a month later.* Respect that. Do not hand back a 10-item work plan.

## Rules

- **Read-only.** Never modify the audited repo. The single exception is `REPO-AUDIT.md` on explicit request.
- **Verify, don't assume.** "Has a CONTRIBUTING.md" is not a pass — open it and check it explains how to build and run tests. An empty template scores 1, not 2.
- **No score inflation.** The rubric bar is deliberately high. Most healthy repos land 10–14. Saying so plainly is more useful than a generous grade.
- **Judge intent, not checklist compliance.** A repo with no `CONTRIBUTORS.md` but a maintainer who thanks people in every release thread is doing tip 9 correctly. Score the outcome.
- **Small/private repos:** tips 1, 5, 8, 10 (discovery, public demos, release marketing, evangelism) may be genuinely irrelevant for an internal tool with three known users. Ask, or mark `N/A` and adjust the denominator — do not penalize a repo for not marketing itself to a public that doesn't exist.

## Reference

Source notes: `TIPS.md` in the repo-to-product repo (talk: https://www.youtube.com/watch?v=DWXlyOd_z88).