GREAT README

A README is a landing page and a short design doc in one. It must answer, in order: what is this, why should I care, how do I try it in 5 minutes, how does it work and why was it built this way. Business story first, then the tech. Delivered as a PR per repo; the default branch is never touched.

Hard rules (never violate)

1. Never describe what the code doesn't do.
2. Never push to the default branch, and never push or open a PR without an explicit yes from the user (unattended runs excepted).
3. Never ship a hero with a broken image or a placeholder, and never present a mockup or generated image as a screenshot of the real product.
4. Never put a Roadmap, status or Sustainability/business-model section in the README.
5. Ask before running anything on the user's computer, except this skill's own scripts and the repo's documented commands (quick start, build, test). Installing packages still needs a yes.

Phase 0 — Audit the repo

Before writing, read the current README, package metadata (package.json, pyproject.toml, Package.swift…), CI workflows, LICENSE, docs/, existing logos (favicon, app icon, public/, assets/), OG image and screenshots, the live URL, and enough source to verify every claim (entry points, workflow/graph definitions, schedules).

Keep what's already good. Preserve accurate prose, design principles, tables and links. Change structure and missing pieces, not the author's voice.

Phase 1 — Ask about gaps

Some gaps are the user's decision, not the README's. After the audit and before writing, ask about every gap you found in one round (the question tool, max 4 questions; group the rest), each with 2-4 concrete options derived from the repo, the recommended one first and marked "(Recommended)". Typical gaps and how to build the options:

If the answer is to add an asset later, leave a one-line HTML comment slot (<!-- Logo slot: add … then uncomment -->) and the commented-out tag; nothing about it appears in the rendered README. No third-party logos, characters or brand marks in a generated logo.

If nobody can answer (unattended run), take the recommended option, say so in the PR description, and keep the rendered README free of any mention of the gap.

Phase 2 — Write the hero

The hero is the first screen, written in the reader's voice (see "Voice" in Phase 3).

Logo on the left, never centered. Preferred layout: logo floated left, with the name, the one-liner and the badges stacked in a column to its right; the link row and the OG image go full width below.

<img src="docs/assets/logo.svg" width="164" align="left" alt="<Name> logo: <what it depicts>">

# <Name>

**<One sentence: what it does, for whom, with one concrete number or differentiator.>**

<badges: max 6, health first, then stack, all on one line>

<br clear="left">

[**Live site**](<url>) · [How it works](#how-it-works) · [Architecture](#architecture) · [Quick start](#quick-start)

<img src="<path to the OG image>" alt="<the OG image's text, written out>" width="860">

• The column only works if it is no taller than the logo: one-liner ≤ 2 lines at GitHub width (~120 characters), badges on one line. Size the logo (140-180px) so the column fits beside it; never let the one-liner wrap under the logo.
• <br clear="left"> is required, or the link row floats beside the logo.
• Fallback when the logo is wide, not square, or the column can't fit: logo inline in the title, then the rest stacked, all left-aligned: # <img src="docs/assets/logo.svg" width="44" align="top" alt="…"> <Name>
• Dark mode: use a logo that works on both backgrounds (an app-icon tile is ideal); if it can't, wrap it in <picture> with a prefers-color-scheme: dark source.
• Check the hero in the GitHub preview (light and dark) before committing.

Rules:

• One-liner leads with the outcome, not the implementation. If the repo serves a bigger initiative (a live-coding series, a product family), the one-liner is still about this repo; context goes in the next paragraph.
• Badges, same shields.io style, max 6. Order: health (CI, coverage, version or latest release, license) → stack (built with, LLM, runtime/platform). Health badges must link somewhere real. Stack badges are part of the tech showcase.
• Link row works as a table of contents: live/website/download · docs or Storybook · how it works · architecture · quick start · deploy/releases.
• Visual = the project's OG image (the social preview its site already uses): find it through the og:image meta tag in the site code (og/*.png, public/landing/*/og.png, docs/assets/og-image.png…) and reference that file directly, so the README and the link preview stay in sync. Its logo and name repeating the header is fine. Write the image's text out in the alt text. Don't add separate screenshots or banners next to it.
• No OG image (libraries, UI kits, CLIs): use a real product visual instead (a rendered component grid, the app in use), and ask whether to design an OG image (see Phase 1).
• Nothing critical lives only inside an image: the tagline is also in text (one-liner or alt text).

Phase 3 — Write the sections

Write the sections in the fixed order below.

Voice

The README is written for a person who wants to learn about the project, not as notes from an agent to the developer.

• The README never talks about itself or its own files. No "this section explains…", "diagram sources live in…", "images are kept in X so they aren't published", "this README covers…". Where files live belongs in Project layout only if a reader needs it.
• No excuses or absence notices. Don't announce what doesn't exist ("there is no CI yet", "no license file has been added", "no screenshot available"). Omit it, or ask and add it (see Phase 1).
• Name the owner. Copyright and credits use the person's name: "© <year> <owner name>. All rights reserved.", not "default copyright applies".
• State decisions as facts about the project, not as instructions or justifications ("Timepass talks only to macOS", not "this diagram shows who uses it…"). Contributing may address contributors directly ("run make build"), but never with internal to-dos.
• Findings that need the user's action (a failing test, an undeclared dependency, an old name in config) go in the PR description, never in the README.
• No em or en dashes as punctuation (—, –, or - between clauses). Use a period, comma, colon or parentheses instead. This applies to all README text, alt text, tables and docs/ files you write. Hyphens inside words (light-dark) and numeric ranges (2-4, written with a hyphen) are fine.

Sections (fixed order)

1. Hero (Phase 2)
2. Why: the problem from the user's pain (2-4 sentences), who it's for and not for, what it does differently, traction if real. Optional Design principles table (principle → in practice) when the project has opinions worth showing.
3. Quick start: prerequisites stated, copy-paste commands that succeed on a clean machine, the smallest working example. Long variants go in <details>.
4. How it works: the mechanism in markdown prose and small tables.
5. Architecture: the C1 system context diagram, always, followed by 2-3 short markdown paragraphs and a link to docs/ARCHITECTURE.md when deeper diagrams exist. Then a one-line Tech stack grouped by layer.
6. Usage / configuration: the 80% cases inline; everything else linked to docs/. Include a short Project layout tree when the repo has more than a handful of top-level folders.
7. Documentation: a two-column table (Doc | What's in it) of the docs that exist (see "Docs to reference"). Mark docs written in another language, e.g. "(Spanish)".
8. Contributing: how to add the common thing (a country, a component, a timezone), which command validates it, what CI runs. Link CONTRIBUTING.md if it exists.
9. License: license plus data/asset attributions.

Roadmap, status and Sustainability/business-model sections go stale, and the real roadmap lives in the user's own tooling. If the README already has one, remove it (also from the link row and any TOC) and list the removal in the PR description. Don't move it to another doc or replace it with a link.

Keep the README under ~400 lines. Prose is short and scannable markdown; tables for comparisons and step-by-step mechanics; bold sparingly.

Docs to reference

Link only docs that exist and say something; never link an empty template. Create a missing one only when the repo clearly needs it, and say so in the PR.

Where they appear: the important ones in the hero link row (Docs/Storybook, Deploy); contextually inside sections (Architecture → ARCHITECTURE.md, Quick start → SETUP.md); all of them in the Documentation table.

Phase 4 — Draw the diagrams

4.1 Decide what to draw

Answer this prompt against the code you actually read, before drawing anything:

If you had to describe this in modules, a conceptual architecture, or a process map with data flows, how would you represent the current state and requirements of this?

From the answer pick diagrams by C4 level, each with one job:

• C1 system context (required, goes in the README). The system as one box in the center; people above it (pill-shaped); external systems below it (third-party APIs, data sources, LLMs, app stores). Each edge has a ≤4-word verb label ("fetches prices daily", "accepts findings in PRs"). No internals.
• C2 containers (what runs where) → docs/ARCHITECTURE.md: runtimes/hosts as containers, deployable units inside, people and external systems outside.
• Process map per important flow → docs/ARCHITECTURE.md: the real step names from the code, in order, with the data stores they hand off through.
• Modules (C3) → docs/ARCHITECTURE.md, only when the internal layering is the story (atoms → molecules → organisms, core → adapters).

Small projects (a menu bar app, a UI kit) usually need C1 only, and no ARCHITECTURE.md. Don't invent a pipeline to fill space.

Diagrams carry labels, never prose. Inside an SVG: box titles, ≤5-word subtitles, ≤4-word edge labels, container names. Legends, notes, captions and explanations are markdown around the image, never text in the SVG.

4.2 Draw one themeable SVG per diagram

Write docs/diagrams/src/<name>.svg by hand in Claude's diagram style, no Mermaid. Read references/svg-diagram-spec.md before drawing: it holds the allowed classes, edge and color rules, and the layout rules where diagrams break.

4.3 Bake and check

Run from the target repo's root:

python3 <skill-directory>/scripts/theme_svg.py docs/diagrams/src/*.svg --out docs/diagrams --png

It writes <name>-light.svg / <name>-dark.svg with colors and system fonts baked in (GitHub renders README SVGs as <img>: no CSS variables, no web fonts) and, with --png, previews loaded as <img> exactly like GitHub. Look at every PNG and fix overlaps, clipped text, or arrows through boxes before moving on. Delete the PNGs before committing.

--png needs Playwright and Chromium: pip install playwright, then playwright install chromium.

4.4 Embed

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/diagrams/<name>-dark.svg">
  <img src="docs/diagrams/<name>-light.svg" alt="<the whole flow in one sentence>" width="880">
</picture>

The text around each diagram is plain markdown: what it answers before it, the non-obvious rule it shows after it. Paths in docs/ARCHITECTURE.md are relative to docs/ (diagrams/<name>-dark.svg, ../src/...). Don't mention where diagram sources live. Name sources after what they show: context.svg (C1), containers.svg (C2), <flow>.svg for process maps. If docs/ is a published site (GitHub Pages, docs/CNAME), put diagrams and README images in .github/readme/ instead, without explaining why.

Phase 5 — Verify

Run this checklist, fix whatever fails, and rerun it until every item passes. An item that can't pass goes in the PR description, never in the README.

• No Roadmap, status or Sustainability section anywhere in the README.
• Voice: nothing in the rendered README talks about the README, its files or its diagrams; no "yet"/"no X" absence notices; copyright names the owner.
• No em or en dashes used as punctuation anywhere in the README or the docs you wrote (grep -n '[—–]' README.md docs/*.md returns nothing you added).
• Every gap was asked about (or the recommended default was taken and listed in the PR).
• Logo on the left; the column beside it doesn't wrap under the logo (or the inline-title fallback is used).
• Hero has a real logo and the project's OG image (or a real product visual when there is no OG image), or the user was asked how to fill the gap (no broken images, no placeholders presented as final).
• Every number, schedule, command and file path in the README exists in the repo.
• Quick start commands run (execute them when the toolchain is available).
• All relative links and image paths resolve; badge URLs point at real workflows.
• Diagram step names match the code; no prose inside any SVG; light and dark previews checked; C1 is in the README.
• Render the README and docs/ARCHITECTURE.md (when it exists) like GitHub and show the screenshots to the user before opening the PR. Run from the target repo's root:

  python3 <skill-directory>/scripts/render_readme.py README.md docs/ARCHITECTURE.md --out "$TMPDIR/readme-preview"

  It writes <name>-light.png / -dark.png, draws stand-in badges if shields.io is unreachable, and exits 1 listing images that failed to load. Needs npm, plus pip install markdown playwright and playwright install chromium. Lists nested by 2 spaces look flat here (Python-Markdown, not GitHub's parser) but nest on GitHub: leave them.

Phase 6 — Deliver

When the checklist passes, wait for the user's explicit yes on the screenshots before pushing or opening the PR; on an unattended run, skip the wait. Deliver on a branch (docs/great-readme) with a PR per repo. Never push to the default branch. One commit for diagrams, one for the README.

Report

Print this in the chat response. The PR description carries the same gaps, removals and findings.

## GREAT README: <repo>

PR: <url>

### Changes made
- <sections rewritten or kept, diagrams added>
- Removed: <Roadmap, status or Sustainability sections, if any>

### Gaps
- <gap>: <option taken, and whether it was asked or the recommended default>

### Still needs human attention
- <failing test, undeclared dependency, old name in config, checklist item that can't pass>