Tooluck logoTooluck
SKILL.md

readme-polish

Agent skill fromalirezarezvani/claude-skills

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. Not for brand-new READMEs from scratch or hero-image design.

How to install readme-polish

install readme-polish
# install the claude-skills pack with the skills CLI
npx skills add alirezarezvani/claude-skills

# or add only this skill to Claude Code: copy the folder

engineering/readme-polish/

# into

~/.claude/skills/readme-polish/ (all projects)

.claude/skills/readme-polish/ (one project)

engineering/readme-polish/SKILL.md

MITFull file
1# README Polish
2
3Upgrade an **existing** README to the standard of the leading repos in its own ecosystem. Polish is
4information hierarchy that survives a 15-second skim; every component must earn its place. This is
5not a generator: no banner for a single-tool repo, no badge for a service that does not exist, no
6screenshot placeholder.
7
8Do not use it for a README with no content yet, for hero or banner image design, or for API
9reference docs. If the README is already accurate and scannable, say so and propose a smaller change.
10
11## Before starting
12
13Ask only what the repo cannot tell you: the category (single tool, library or framework, collection,
14commercial product), the audience (evaluating developers or installing users), and which claims are
15true today (version, license, test status).
16
17## Modes
18
19- **Upgrade** (default): run the full workflow and rewrite the file.
20- **Audit only**: run steps 1-3 and 5, report findings with line references, do not rewrite.
21- **Calibrate**: run step 1 only and recommend a presentation tier with reasons.
22
23## Workflow
24
251. **Calibrate.** Sample 2-3 leading repos in the same category and classify them as minimal or
26 full-component. Single tools get the middle tier (badges, mermaid, callouts); collections and
27 commercial products may use full components. If the network or `gh` is unavailable, take the
28 conservative default and write "calibration skipped". Never claim calibration you did not do.
29…

Excerpt shown under the repository's MIT license.

More skills in claude-skills

Keep exploring

Similar skill repositories

Tooluck Weekly · every Monday

New AI tools and agent skills, once a week

The tools added to Tooluck that week, the newest skills for Claude Code, Codex and Cursor, and one side-by-side comparison. No spam, unsubscribe anytime.