Readme Validator

The Problem

Your README has a badge linking to a Travis CI that shut down two years ago, a screenshot from 2023 that no longer matches the UI, and no Installation section — so new contributors can't figure out how to get started. You didn't notice because you wrote it once and never revisited. Now it's the first thing the world sees.

What You Get

• Broken link detection — every Markdown link, HTML anchor, and fragment reference is validated against actual file existence and URL resolution
• Section completeness audit — checks for Project Title, Description, Installation, Usage, Configuration, Contributing, License, Changelog, and Acknowledgments based on project type
• Badge validation — verifies badge images load from trusted CDNs, checks syntax correctness, and flags expired or 404'd badge URLs
• Image quality scan — flags screenshots older than 12 months on active projects, empty alt text, and external image hosts prone to link rot
• Formatting consistency check — heading hierarchy, code block language tags, table alignment, and mixed bullet styles across the entire document
• Severity-scored report — produces a 0-100 quality score with Critical/Warning/Info findings in a structured table format

Why This Beats Prompting It Yourself

You can ask "check my README" once, but you won't ask it before every push. This skill applies a systematic checklist that catches the 12+ categories of README rot that accumulate invisibly over months. A human reviewer reads for meaning; this validator reads for structural integrity — the things that make the difference between a project that looks maintained and one that looks abandoned.

Example Session

You: "Validate the README for my open-source CLI tool"

Agent: "README Validation Report — Score: 72/100

Critical Issues (2):

• Line 45: http://example.com/docs returns 404 — Installation docs are unreachable
• Line 1: No License section found — legal risk for reuse

Warnings (3):

• Line 78: Travis CI badge uses deprecated .org domain
• Line 5: No Contributing section for an open-source project
• Line 92: Screenshot from March 2023 — project has had 4 major releases since

Info (4):

• Line 23: Code block missing language tag
• Line 12: Mixed bullet styles (- and *)
• Line 105: No table of contents for a 280-line README
• Line 67: Inconsistent heading capitalization

Total links checked: 24 | Broken: 2 | Sections present: 6 of 9"

Use Cases

• Pre-publish audit before pushing a new repo or open-source project
• Documentation sprint cleanup across an organization's repositories
• CI/CD integration to catch README rot before it reaches the main branch
• Onboarding a new project by establishing a documentation quality baseline
• Preparing repos for submission to awesome-lists or curated directories

Known Limitations

This skill is read-only and does not modify files. Link liveness (HTTP status codes) requires external network verification beyond the structural checks. Handles Markdown (.md) files up to 500KB; ReStructuredText and AsciiDoc are out of scope.