Repo README Quality

What this skill does

Reads a repository's README.md end-to-end and produces a punch-list of concrete fixes ordered by impact on first-time-reader comprehension. The output is a markdown report with line-number citations and one-sentence rewrite suggestions per finding.

Inputs

• repo_dir: absolute path to a repo checkout. Must contain a top-level README.md.
• audience (optional): one of developer, end-user, contributor. Defaults to developer.
• Optional package.json / pyproject.toml for cross-checking the project name and install command.

Steps

1. Run wc -l README.md to capture total length; abort with a "missing readme" finding if the file is absent.
2. Read the first 80 lines and check for: H1 title, one-paragraph elevator pitch, badges row, install command in a fenced block.
3. Use rg -n '^#{1,3} ' README.md to extract the heading outline. Verify the order matches the canonical sequence: Title, About, Install, Usage, Configuration, Contributing, License.
4. For every fenced code block, confirm a language hint follows the opening backticks (e.g., ```bash). Flag bare fences.
5. Run rg -n 'TODO|FIXME|XXX|TBD' README.md and surface each hit as a blocker.
6. Cross-reference the install command against package.json#scripts or pyproject.toml — flag drift.
7. Check for a license link near the bottom; resolve it relative to repo root with ls.
8. Count images and verify each ![alt](path) resolves on disk (test -f).
9. Group findings into blocker, warning, suggestion and sort within each by line number.
10. Write the report to stdout in the schema described under Output.

Output

A markdown report with three sections (## Blockers, ## Warnings, ## Suggestions). Each finding line is - L<line>: <fix>. The header includes a verdict (pass | warn | block) and counts. Exit code 1 if any blockers exist, else 0.

Verification

After writing the report, re-read README.md and re-extract the heading outline; the section list in the report must match. Re-run test -f on every image path quoted in the report to confirm no false positives. If the readme has fewer than 30 lines, downgrade all "missing section" findings to suggestions — short readmes are valid for tools.

Edge cases

• Empty or stub README.md (under 10 lines): emit a single blocker "stub readme" and skip structural checks.
• README written in a non-English language: skip prose-quality heuristics, keep structural and link checks.
• Network-fetched badges (shields.io): do not validate over the network; trust the URL shape.
• Symlinked README.md (e.g., to docs/index.md): resolve via readlink -f before reading.