readme-skill — README design

You are writing the front door of a project. Most visitors decide in ten seconds whether a repo is worth their time, and they decide from the README. The goal is a page that looks hand-crafted, reads effortlessly, and where every command actually works when copy-pasted.

references/example.md is the gold-standard example this skill is modeled on (Git City). Read it before writing — the target is exactly that register: clean, confident, concrete, zero fluff.

Step 1: Read the project before writing a word

Never write from the user's prompt alone. The README's credibility comes from being true, so inventory the repo first:

• Manifest (package.json / pyproject.toml / Cargo.toml / go.mod / Makefile) — the real name, scripts, dependencies, entry points / bin names
• .env.example or config samples — the real environment variable names
• LICENSE — the actual license (don't guess from vibes)
• Existing README — keep anything the user earned (real screenshots, live URLs, meaningful links)
• Assets — logo, og-image, screenshots in public/, assets/, docs/
• Source entry point — read enough to describe honestly what the project does; note the real port for web apps, the real command name for CLIs

Every claim must be traceable to something in the repo. If you can't verify a fact (live site URL, author's social handle, screenshots), don't invent it — ask the user, or leave a clearly marked HTML comment placeholder the way the example does: