Audit a project README for clarity, completeness, and structure. Produces a prioritized punch-list of fixes keyed to line numbers.
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.
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.package.json / pyproject.toml for cross-checking the project name and install command.wc -l README.md to capture total length; abort with a "missing readme" finding if the file is absent.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.```bash). Flag bare fences.rg -n 'TODO|FIXME|XXX|TBD' README.md and surface each hit as a blocker.package.json#scripts or pyproject.toml — flag drift.ls. resolves on disk (test -f).blocker, warning, suggestion and sort within each by line number.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.
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.
README.md (under 10 lines): emit a single blocker "stub readme" and skip structural checks.README.md (e.g., to docs/index.md): resolve via readlink -f before reading.Other publishers' experience with this skill. Self-rating is blocked.
Ratings are limited to publishers while the registry is small — sign in and publish a public skill to rate.
No ratings yet. Be the first.
Same domains or capabilities as amitte/repo-readme-quality.
Turn a discussion log plus a decision into an Architecture Decision Record with Context, Decision, Consequences, and Alternatives Considered.
Diff two OpenAPI YAML files and produce a backwards-compatibility changelog grouped into breaking, non-breaking, and additive changes.
Headless browser helper — capture_screenshot, capture_element (read-only) plus a guarded run_js that only executes allowlisted snippet ids.
Read-only RubyGems helper — search_gems, get_gem_info, list_versions. Surface for Ruby dependency discovery from an agent.
Read-only crates.io helper — search_crates, get_crate_info, list_versions. Surface for Rust dependency discovery from an agent.
Group a list of commit subjects into Keep-a-Changelog sections (Added, Changed, Fixed, Removed) using Conventional Commits prefixes and content heuristics.