Most READMEs fail in the same boring ways. No install section. A code block with no command in it. A "TODO" left in from the first commit. A license nobody mentioned. You notice these only when a stranger opens an issue asking how to run the thing.
I wanted a check I could run before pushing, and that an AI agent could use as evidence instead of a gut feeling. So I wrote readme-auditor, a Hermes skill with one standard-library Python script.
You point it at a README:
python3 scripts/readme_audit.py README.md It returns a 0-100 score and findings sorted by severity: missing title, missing intro, missing Install or Usage section, unclosed code fences, placeholder text, empty link targets, images without alt text, and so on. With --check-links it also sends HEAD requests and flags 404s. With --fail-under 80 it exits with code 1, so it can gate CI.
A tiny README gets output like this:
README score: 49/100 [HIGH ] No Install / Getting started section [MEDIUM] No license mention [MEDIUM] 1 empty link target(s) The skill then tells the agent to turn each finding into actual text to insert, without making up facts about the project, and to re-run the script to show before and after.
It is a heuristic. Section detection looks for English heading words, and the score measures structure, not whether the content is true. But as a first pass it catches the embarrassing stuff in a second.
The skill is MIT licensed in the hermes-skills library.
Skill (MIT): https://github.com/RobinBeraud/hermes-skills/tree/main/software-development/readme-auditor
All skills: https://github.com/RobinBeraud/hermes-skills
This post was written with AI assistance and reviewed through automated checks.
