
readme-polish
Deterministic README quality gate that polishes existing READMEs to leading-repo standards.
- version
- 2.14.12
- GitHub stars
- 30.3K
What it does
- Adds
check_readme.py, a stdlib-only gate that flags dead links, placeholder badges, broken anchors, and oversized diagrams - Covers a full upgrade flow: category calibration, a 15-second scannability test, a fact audit, and a rewrite
- Enforces a missing first-screen install command as a failure, with exit codes 0 clean, 1 warnings, 2 errors
- Designed for maintainers who want a repeatable README check in CI, with static checks only and manual render review
Upgrade an existing README to the visual and structural standard of the leading repos in its own ecosystem: archetype calibration, component selection, restraint boundaries, honesty rules, and a deterministic lint gate. Ships scripts/check_readme.py, a stdlib-only README gate for dead links, placeholder badges, broken anchors, oversized diagrams and a missing first-screen install command.
Add marketplace
/plugin marketplace add alirezarezvani/claude-skillsRun it inside Claude Code once, then install the plugin below.
Install
/plugin install readme-polish@claude-code-skillsRun it inside Claude Code after adding the marketplace.
Files
Discovered from sourceREADME Polish
Upgrade an existing README to the standard of the leading repos in its own ecosystem. Polish is information hierarchy that survives a 15-second skim; every component must earn its place. This is not a generator: no banner for a single-tool repo, no badge for a service that does not exist, no screenshot placeholder.
Do not use it for a README with no content yet, for hero or banner image design, or for API reference docs. If the README is already accurate and scannable, say so and propose a smaller change.
Before starting
Ask only what the repo cannot tell you: the category (single tool, library or framework, collection, commercial product), the audience (evaluating developers or installing users), and which claims are true today (version, license, test status).
Modes
- Upgrade (default): run the full workflow and rewrite the file.
- Audit only: run steps 1-3 and 5, report findings with line references, do not rewrite.
- Calibrate: run step 1 only and recommend a presentation tier with reasons.
Workflow
- Calibrate. Sample 2-3 leading repos in the same category and classify them as minimal or
full-component. Single tools get the middle tier (badges, mermaid, callouts); collections and
commercial products may use full components. If the network or
ghis unavailable, take the conservative default and write "calibration skipped". Never claim calibration you did not do. Mapping andghcommands: references/archetypes.md. - Run the 15-second test. The first screen states the value in one sentence, a copy-pasteable install command sits in the first 40 lines, and the hero plus three sections answer what, why and how to install. Each failure is a work item.
- Build the fact list. Mark every version, license, test claim, benchmark, link, badge and screenshot as true, stale or invented. Keep true ones, update stale ones from the repo, delete invented ones. A dead badge is worse than no badge.
- Rewrite in this order: hero (title, one-sentence value, badge row, nav links), quickstart,
why it exists (a comparison table beats adjectives), how it works (mermaid of seven nodes or
fewer), proof with real numbers from this repo, reference material in
<details>, and limits. Put explicit anchors (<a id="install"></a>) before non-ASCII or emoji headings. Component choice, anti-patterns and syntax: references/components.md. - Run the gate. Fix every error and justify each remaining warning.
- Ask for a render check. Static checks cannot see rendering: the user confirms on the target platform that mermaid, badges, callouts, anchors and tables render, then rerun step 2.
Example
python3 scripts/check_readme.py README.md
python3 scripts/check_readme.py --strict --json README.md
python3 scripts/check_readme.py --sample
The stdlib-only gate (no network) flags dead local links, broken or placeholder badges, non-ASCII
and broken anchors, mermaid diagrams over the node limit, tables wider than five columns, more than
six badges, and a first screen with no install command. Exit codes: 0 clean, 1 warnings, 2
errors (or warnings under --strict), 3 a missing or unreadable file. Heading-slug
matching follows GitHub (repeated headings get -1, -2); the mermaid node count is approximate.
Output
A rewritten README.md (or a findings report in audit mode), the calibration note, the fact list,
the gate output, and the items still awaiting a human render check. Acceptance checklist and
proactive triggers: references/checklist.md.
Related skills
write-a-skill: authoring a new skill, not polishing docs.code-tour: a guided walkthrough of code, not install docs.commit-craft: turning the change into a clean commit or PR.
Readme
readme-polish
Upgrade an existing README to the visual and structural standard of the leading repos in its own ecosystem: archetype calibration, component selection, restraint boundaries, honesty rules, and a deterministic lint gate.
Quickstart
git clone https://github.com/alirezarezvani/claude-skills.git
cd claude-skills
python3 engineering/readme-polish/scripts/check_readme.py README.md
What it does
- Classifies the repository's category (single tool, framework, collection, commercial) by sampling leading repos in the same topic, then picks a presentation tier with reasons.
- Runs a 15-second scannability test on the current README and records each failure as a work item.
- Builds a fact list (true / stale / invented) so the rewrite cannot keep dead badges, old versions, or invented metrics.
- Rewrites the hero, quickstart, proof, reference, and limits sections with only components that carry information.
- Ships
scripts/check_readme.py, a stdlib-only gate for dead links, broken or placeholder badges, non-ASCII anchors, oversized mermaid diagrams, wide tables, badge overload, and install-command placement.
Usage
python3 scripts/check_readme.py README.md
python3 scripts/check_readme.py --strict --json README.md
python3 scripts/check_readme.py --help
Exit codes: 0 clean, 1 warnings, 2 errors.
Modes
- Upgrade — full audit and rewrite.
- Audit only — findings report with line references, no edits.
- Calibrate — sample the ecosystem and recommend a tier.
Limits
Static checks cannot see rendering and cannot judge whether a component is warranted. The human render check and the fact audit remain manual by design.
License
MIT.
Details
- Marketplace
- alirezarezvani/claude-skills
- Source
- engineering/readme-polish
- Author
- zhengqiuyang
- Category
- Development
- Keywords
- readme, documentation, markdown, badges, mermaid, docs-quality, lint
More from alirezarezvani/claude-skills
All 130- reflect-skillv2.14.5
- research-ops-skillsv2.14.6
- research-orchestratorv2.14.7
- research-summarizerv2.14.5
- roastv2.14.6
- scrum-masterv2.2.0
- security-guidancev2.14.5
- self-improving-agentv2.14.11
- skill-doctorv2.14.1
- skill-retrov2.14.6
- skill-security-auditorv2.2.0
- skillopt-sleepv2.14.5
- slo-architectv2.14.5
- snowflake-developmentv2.14.5
- spinning-up-deep-rlv2.14.6
- statistical-analystv2.14.12
- support-opsv2.14.14
- swedish-mentorv2.14.5
- syllabusv2.14.6
- terraform-patternsv2.14.6
- universal-scraping-architectv2.14.9
- video-content-strategistv2.14.5
- video-studiov2.14.14
- vpe-advisorv2.14.5
Similar to readme-polish
More Documentation & Learning
academy-guideanthropics/skills196.9K starsRecommends relevant Claude Academy courses, tutorials, and use cases when users ask how to use Claude
explanatory-output-styleanthropics/claude-code156.1K starsAdds educational insights about implementation choices and codebase patterns (mimics the deprecated Explanatory output style)
ruflo-docsruvnet/ruflo82.2K starsDocumentation generation, drift detection, and API docs automation
context7upstash/context765K starsUp-to-date documentation lookup. Pull version-specific documentation and code examples directly from source repositories into your coding agent's context.
googledocs-automationComposioHQ/awesome-claude-skills51.5K starsAutomate Google Docs tasks via Rube MCP (Composio): create, edit, search, export, copy, and update documents. Always search tools first for current schemas.
amazon-location-serviceanthropics/claude-plugins-official47.9K starsGuide developers through adding maps, places search, geocoding, routing, and other geospatial features with Amazon Location Service, including authentication se