review-readme

Review a README for template conformance, accuracy, completeness, clarity, and usability.

11|1|Updated Jul 25, 2025

Search Tags:#template #documentation #markdown #audit #readme #review #badges

Ready to run

npx skills add https://github.com/tomzx/agents --skill review-readme-tomzx

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: review-readme
Source: https://github.com/tomzx/agents/tree/main/skills/review-readme
Command: npx skills add https://github.com/tomzx/agents --skill review-readme-tomzx

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? READMEs drift out of sync with the projects they describe: stale version badges, broken install commands, missing requirements, and unfilled template placeholders mislead new users. This Skill audits a README against a fixed template and the actual project files, then reports prioritized findings. ## Core Features & Use Cases - Six-category audit: Checks template conformance, accuracy, completeness, clarity, usability, and hygiene, with each finding prioritized as MUST, SHOULD, or MAY fix. - Accuracy verification: Cross-checks license badges against the LICENSE file, version badges against package manifests (go.mod, package.json, Cargo.toml, pyproject.toml), and install commands against actual runnability. - Use Case: Before publishing a repository, run the review to catch a badge claiming Go 1.20 while go.mod requires 1.22, or a Getting Started section that assumes an unstated compiler prerequisite. ## Quick Start Review the README.md in this repository against the create-readme template and report prioritized findings.

Frequently Asked Questions about review-readme

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I review a README for accuracy against my project?▼

Read the README alongside the LICENSE file, package manifest, and source tree, then verify every claimed value: license badge, language version, platform support, and install commands. Flag any mismatch, such as a badge version that differs from go.mod or package.json.

What should a README review checklist include?▼

Cover six categories: template conformance (required sections in order), accuracy (badges and links match reality), completeness (What, Why, Requirements), clarity (specific descriptions, defined jargon), usability (5-minute getting started), and hygiene (no leftover placeholders).

How do I check if README badges are correct?▼

Compare each badge against its source of truth: the license badge against the LICENSE file, language and version badges against the package manifest, and platform badges against actual build targets. Remove badges that do not apply to the project.

Why do README install instructions fail for new users?▼

Install steps often assume unstated prerequisites like a compiler, runtime, or system dependency that the Requirements section never mentions. Verify each command is copy-pasteable and runnable as written on a fresh environment.

When should I use a README review versus a full documentation review?▼

Use the README review when checking the fixed README template, badge correctness, and the getting-started path for a single repository. Use a wider documentation review when auditing an entire docs tree beyond the README.