Markdown

markdown

A README earns its place if a stranger can read it and know, in under a minute, what the project does and how to run it. Skip a step only when it genuinely doesn't apply, not because it's easier to skip.

Step 1: Ground truth is the code, not old docs

Before writing anything, read the manifest (package.json, pyproject.toml, requirements.txt, go.mod, Cargo.toml, etc.) for real dependencies, scripts, and entry points; skim the main source files and folder structure; check .env.example for real env var names; check docker-compose.yml/Makefile/CI config for real ports and build commands.

If a README already exists, treat it as a hint, not a source. Old READMEs drift: a changed port, a setup step nobody updated, a cut feature. Verify every concrete claim (commands, ports, env vars, prerequisites) against the code before reusing it. If a claim can't be verified, say so to the user instead of carrying it forward silently.

If the project is genuinely opaque from static reading, ask the user one or two direct questions rather than guess.

Step 2: Sections adapt to the project, not the other way around

Don't force the same sections on every project. A CLI doesn't need a dev-server walkthrough; a library needs an API reference more than Usage screenshots; a hosted-only tool may need no local install steps at all.

A default shape to start from, then adjust:

<a id="readme-top"></a>

# Project name

One or two sentences: what it does, for whom, grounded in a real capability (not "a powerful
tool for X").

- Live demo / deployed link, if one exists
- The 1-3 things worth knowing up front

[optional: screenshot of the main screen]

<details><summary>Table of contents</summary>
... links to the sections that actually exist below ...
</details>

## Built with
Grouped by layer (frontend / backend / AI services / infra), only the layers that exist.

## Getting started
### Prerequisites
### Installation
Numbered, copy-pasteable, in the order a fresh clone actually needs them.

## Usage
Numbered walkthrough of real flows, each with a screenshot if a live/local demo was available.

[Add/replace: API Reference, Configuration, Architecture, Deployment, Contributing, License:
whatever a reader of *this* project actually needs.]

Keep the back-to-top links and details/summary table of contents for anything past 3-4 sections; drop both for a short single-screen README.

Step 3: Screenshots only when there's something to point a browser at

This skill runs across harnesses (Claude Code, Cowork, Codex CLI, Cursor, others), and each one exposes browser capability under a different tool name, if at all. Don't assume one; check what's actually available.

• URL/local instance available, and a browser tool exists: use it for 3-6 real, meaningful flows (not just the landing page). Save to images/ at the project root with descriptive filenames (01-home.jpg, 02-submit-flow.jpg), reference with relative markdown paths. Read references/screenshot-capture.md for how to find the right tool per harness and the exact wording for the next case.
• URL/instance available, but no browser tool exists here: different from no URL at all: the user gave you something to look at and you can't. Say so plainly in your final response (not buried in a transcript), finish without screenshots. Exact wording in references/screenshot-capture.md.
• Nothing available at all: skip the section. No placeholder image, no ASCII mockup, no invented description of what a screenshot would show. Normal and fine for a CLI, library, or backend-only service.
• Ambiguous (could run locally but isn't running): ask, don't assume.

Step 4: Write it

Read references/writing-style.md before drafting, not just skim it. It covers the exact filler patterns to avoid and what to write instead. This matters more here than in most docs: a README that reads like marketing copy makes a reader assume the project itself is thin.

Use actual runnable commands, filenames, and port numbers from Step 1. If you're not sure a command works, don't present it as if you ran it.

Step 5: Save it where the project lives

Write README.md (and images/ if applicable) directly into the project's repo root, next to the manifest from Step 1, not to a staging or output folder, so it's immediately visible and ready to commit.

If the folder isn't writable, isn't clearly identified, or there are multiple candidates, ask before writing rather than guessing a location.

Step 6: Self-check before calling it done

Reread as a stranger who's never seen the project:

• Does the opening say what it does in one read, without hype words?
• Would every "Installation" command actually work copy-pasted in order?
• Do all image paths point to files that actually exist in images/?
• Did you carry forward any unverified claim from an old README?
• Literally text-search the draft for the em dash character (—) and replace every instance with a period, comma, colon, or parentheses. A general reread does not reliably catch a single punctuation mark; this is the single most common thing that slips through otherwise careful drafts, so it gets its own explicit pass.

Fix anything that fails before calling it done.