Readme Keeper

READMEs rot faster than code. A script gets renamed, a dependency version bumps, or a quickstart step is forgotten, leaving new developers stuck in configuration hell. This skill stops README drift by treating documentation as testable code, ensuring every claim made to a user is backed by the actual state of the repository.

What it does

• Claim extraction identifies every command, file path, version requirement, and link within your documentation.
• Automated verification cross-references extracted claims against the local filesystem, manifest files, and environment paths.
• Drift reporting generates a detailed table of evidence showing exactly where a README lies compared to the repo.
• Structure enforcement provides an optimized "newcomer-first" outline based on the specific features detected in your project.
• CI integration enables an exit-code-based check to prevent merging PRs with broken documentation links or invalid setup commands.

How it works

1. Run claims to inventory every testable statement, from bash snippets to version strings.
2. Execute check to validate those claims against package.json, go.mod, file structures, and PATH.
3. Use the generated report to identify specific sentences that require correction based on the evidence.
4. Apply the outline command when starting new docs to ensure mandatory sections like "What this does not do" are included.

Frameworks & tools

The skill utilizes a standalone Python utility (readmecheck.py) compatible with any repository structure including Node.js, Python, Go, and Rust. It integrates with standard CI/CD pipelines via shell commands.

Why this beats prompting it yourself

Generic LLMs hallucinate setup steps based on common patterns rather than your specific files. This skill tethers the agent to a local verification script that proves a command exists before suggesting it, eliminating the "it works on my machine" documentation trap.

Use cases

• Auditing a legacy repository where the setup steps no longer work on a fresh clone.
• Verifying all internal anchors and file references before a major version release.
• Generating a technically accurate README for a new project that reflects the actual file structure.
• Preventing documentation regression by adding a verification step to a GitHub Action.

Known limitations

Does not execute commands to verify their output; it only verifies the command is invokable. External URLs are not pinged. Does not verify claims that lack a corresponding file-based manifest.