Skip to content
Join free
alirezarezvani

Readme Polish skill

Use when an existing README must be upgraded, audited, or made scannable: polish/美化/升级/优化/打磨 README, add badges, mermaid, callouts, or collapsible sections, compare against top repos in the same ecosystem, or fix a plain/ugly first screen. Calibrates to the repo's own category, rewrites the hero and information hierarchy, and enforces a deterministic lint gate.

$npx alyn-cli add readme-polish
View this skill on GitHubalirezarezvani/claude-skills/engineering/readme-polish/SKILL.md
Pack stars
29,947
Pack installs
242k
Alyn Score
83/99
Updated
3 h ago
License
MIT

alirezarezvani

Readme Polish

What is the Readme Polish skill?

Readme Polish is a coding skill by alirezarezvani for Claude Code, Cursor, Codex and other AI coding agents. Use when an existing README must be upgraded, audited, or made scannable: polish/美化/升级/优化/打磨 README, add badges, mermaid, callouts, or collapsible sections, compare against top repos in the same ecosystem, or fix a plain/ugly first screen. Calibrates to the repo's own category, rewrites the hero and information hierarchy, and enforces a deterministic lint gate.

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.

When to use it

Use when an existing README must be upgraded, audited, or made scannable: polish/美化/升级/优化/打磨 README, add badges, mermaid, callouts, or collapsible sections, compare against top repos in the same ecosystem, or fix a plain/ugly first screen.

What the SKILL.md covers

  • Before starting
  • Modes
  • Workflow
  • Example
  • Output
  • Related skills
Author
alirezarezvani
Pack
alirezarezvani/claude-skills (30 skills)
Category
Coding, #193 of 1768
Alyn Score
83 / 99
Files
8, includes scripts, includes references
License
MIT
Last updated
3 h ago
Works with
Claude Code, Claude, Cursor, Codex, Gemini CLI, Copilot

Readme Polish compared to similar skills

SkillAlyn ScoreGitHub starsUpdated
Readme Polish · alirezarezvani8330k3 h ago
Db Repo · Nikolay-Shirokov577932 days ago
Zh Readme · laolaoshiren5191327 h ago
Code Review Gate Zh · kyy-logs525086 min ago

Install Readme Polish

Pick your agent. Every command is ready to paste.

$npx alyn-cli add readme-polish

Detects your agents (Claude Code, Cursor, Codex and 70+ more) and installs to the right folder. Add -g to install globally.

$npx skills add alirezarezvani/claude-skills --skill readme-polish

Or use the open skills CLI directly.

01

Install it

Run the command above, or upload the folder in Claude.

02

Ask naturally

Describe the task. Your agent loads readme-polish when the request matches its description.

03

Name it if needed

If it does not trigger, say “use the readme-polish skill”. In Codex, type $readme-polish.

The skill itself

SKILL.md

FolderGitHub

README 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

  1. 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 gh is unavailable, take the conservative default and write "calibration skipped". Never claim calibration you did not do. Mapping and gh commands: references/archetypes.md.
  2. 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.
  3. 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.
  4. 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.
  5. Run the gate. Fix every error and justify each remaining warning.
  6. 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.

  • 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.

Tips for Readme Polish

  • • Start a fresh session after installing so your agent picks up the new skill.
  • • This skill ships scripts. Read them before the first run, and run it in a project without secrets first.
  • • It bundles reference files. The agent reads them only when needed, so they cost no context until then.
  • • It is part of a pack with 30 skills. Install only the ones you need with --skill to keep triggers precise.
  • • If two skills overlap, mention the one you want by name.

Questions about Readme Polish

What does the Readme Polish skill do?

Use when an existing README must be upgraded, audited, or made scannable: polish/美化/升级/优化/打磨 README, add badges, mermaid, callouts, or collapsible sections, compare against top repos in the same ecosystem, or fix a plain/ugly first screen. Calibrates to the repo's own category, rewrites the hero and information hierarchy, and enforces a deterministic lint gate.

How do I install Readme Polish?

Run "npx alyn-cli add readme-polish" in your project. The Alyn CLI installs it for Claude Code, Cursor, Codex and 70+ other agents. In Claude on the web, upload the skill folder as a ZIP under Customize > Skills.

Does Readme Polish work in Cursor and Codex?

Yes. Readme Polish uses the open SKILL.md format, so it works in Claude Code, Claude, Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot and other agents that support agent skills.

When should I use the Readme Polish skill?

Use when an existing README must be upgraded, audited, or made scannable: polish/美化/升级/优化/打磨 README, add badges, mermaid, callouts, or collapsible sections, compare against top repos in the same ecosystem, or fix a plain/ugly first screen.

What is inside the Readme Polish skill?

The SKILL.md covers Before starting, Modes, Workflow, Example, Output, Related skills, and the skill folder has 8 files including scripts.

What is a good alternative to Readme Polish?

Db Repo by Nikolay-Shirokov is the highest-ranked similar skill from another creator, with an Alyn Score of 57 compared to 83 for Readme Polish.

Is Readme Polish free?

Readme Polish is open source on GitHub under the MIT license. It is free to install; check the license before commercial use.

Who made Readme Polish?

Readme Polish is published by alirezarezvani in the alirezarezvani/claude-skills repository, together with 29 other skills.

Similar skills. From other creators.