readme-polish
Audit a GitHub README and rewrite it using modern 2025-2026 patterns — centered header, badges, hero image, GitHub alert callouts, emoji-prefixed features, expandable details, Mermaid diagrams, tables over dense prose. Produces a scannable README that works for a 10-second skim and a deep dive.
yzhao062 · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add yzhao062/anywhere-agents --skill readme-polishAbout this skill
name: readme-polish description: Audit a GitHub README and rewrite it using modern 2025-2026 patterns — centered header, badges, hero image, GitHub alert callouts, emoji-prefixed features, expandable details, Mermaid diagrams, tables over dense prose. Produces a scannable README that works for a 10-second skim and a deep dive.
Readme Polish
Overview
Modern GitHub READMEs are scannable first, readable second. A skimmer should understand what the project does, who it is for, and how to install it in 10 seconds. Motivated readers get more detail from collapsibles, tables, and follow-up sections.
This skill takes an existing README (or a blank slate) and rewrites it using the visual and layout patterns that well-regarded 2025-2026 open-source projects have converged on. It does not invent the content; content comes from the project itself. It shapes how that content is presented.
When to Use
- A README is a text wall with no visual anchors and no one can tell what the project does from a first glance.
- An OSS release is about to ship and the README has not been pass-edited for discoverability.
- The README mixes reference material with quickstart, so the install path is buried.
- Publishing badges, adding a hero image, or restructuring sections would measurably help adoption.
- A practitioner with social credibility wants the README to convey both "this is legit" and "here is how to use it" without competing for attention.
When NOT to Use
- The README already follows the patterns below and the content is fine. Do not thrash for style.
- The project is internal / private / never published. No audience to optimize for.
- The project needs documentation at site-level scale (tutorials, API reference, cookbook). README polish only covers the repo root; use Sphinx / MkDocs / Docusaurus for real docs sites.
Phase 1: Audit the current README
Before editing, classify what is there against the modern-README checklist. The goal is to identify which patterns are missing, which are misapplied, and which content should be moved, collapsed, or deleted.
Use references/checklist.md as the audit grid. For each row, mark present / absent / broken.
Key audit questions:
- First-paint (above-the-fold): is the project name, one-line tagline, badges, and install command visible before the reader has to scroll? If not, content above those is displacing them.
- Credentials placement: is there a 100+ word maintainer bio blocking the first section? Move it into a
> [!NOTE]callout or footnote. - Why-section shape: if the README has a "Why you'd use this" or scenario block, are the items narrative (cause / effect, before / after) or feature-shaped? Narrative content reads warmer as bold-lead paragraphs; feature claims read cleaner as emoji-prefixed bullets. Pick one pattern per section.
- Install path clarity: can the reader find a single working install command in under 5 seconds? If not, there is probably too much pre-install framing.
- Reference material above-the-fold: are limitations, related projects, detailed repo layout, maintenance policy visible before install? They should be collapsed.
- Visual anchors: does the first screen have badges, a hero image, or a diagram? Without at least one, the README feels like documentation instead of a product page.
- Examples block (What This Looks Like): does the README show what the project LOOKS LIKE in practice (screenshot, file tree, themed diagram, before / after, mock)? If yes, do 3+ examples each use a different visual format, or are three monospace blocks stacked in a row? The latter reads as a text wall regardless of content quality.
- Themed Mermaid: if Mermaid diagrams exist, do they use
%%{init: ...}%%to match brand palette, or do they render with the default red/orange/blue and clash with the rest of the page? - Heading case: is Title Case applied consistently across all H2 and H3? Sentence-case headings mixed with Title Case headings read as AI-generated or unedited (agent-style RULE-G).
- Version-boundary honesty: if a release ships primitives that are not yet wired, does the README name the boundary explicitly (what works today, what is queued), or does it present roadmap claims as shipped behavior?
- Anchor hygiene: do dot-nav links resolve to real sections (GitHub's auto-generated anchor rules: lowercase, hyphens for spaces, strip punctuation)?
Phase 2: Apply modern patterns
See references/patterns.md for the full catalog with copyable snippets. Summary of the highest-impact patterns:
Hero / first-paint
- Centered header via
<div align="center">. Title, one-line tagline, badge row, dot-separated nav, one-liner elevator pitch. - Shield.io badges for package version (PyPI, npm), license, CI status, GitHub stars. Keep to 4-5; more than that becomes noise.
- Dot-separated nav links (
[Install](#install) · [Workflow](#workflow) · [Features](#features)) below badges. Helps skimmers jump. - Hero image — a PNG or SVG that makes a skimmer stop scrolling. Two paths:
- HTML mockup rendered via headless Chrome → PNG (good for feature grids, dashboards). See
ci-mockup-figureskill for capture workflow. <picture>tag with light/dark variants for logos. Required only when the project has a logo/wordmark.
- HTML mockup rendered via headless Chrome → PNG (good for feature grids, dashboards). See
- Maintainer credibility in a
> [!NOTE]callout, not a prose paragraph. Ideal length: 2–3 sentences with verifiable signals (package stars, citations, institutional affiliation).
Content body
- GitHub alert callouts for emphasis:
> [!NOTE],> [!TIP],> [!WARNING],> [!CAUTION],> [!IMPORTANT]. Each renders as a colored box with an icon. Do not overuse — one per major section at most. - Emoji-prefixed one-liner bullets for "What you get" / "Features" when items are feature claims. Each bullet = 1 emoji + bolded feature name + one-line takeaway. 5