How to Write a README with AI

An open-source CLI tool can be genuinely useful and still get skipped, because the README answers the wrong questions. New users want three things fast: what it does, how to install it, and the one command that proves it works. Everything else — flags, edge cases, contributing rules — is depth, and depth should come after the first success.

The example is a small command-line tool that converts a CSV file into a SQLite database. It is the kind of utility that lives or dies on a good README, because the entire value is a single command. Here is a workflow that turns the tool’s real behaviour into documentation a stranger can follow in sixty seconds.

The README You Are Aiming For

A first screen that states what the tool does and who it is for, a copy-paste install block, a quickstart with one working command, a flags table, real usage examples, and the license and contributing notes. The goal is a reader who has never seen the project running the tool within a minute.

Step 1: Gather the Facts Before Writing

Do not let the model invent install steps or flags. Feed it the real interface and the real constraints first.

I am writing a README for a command-line tool.
Name: csv2sqlite
Purpose: converts a CSV file into a SQLite database table in one command.
Install: from source with pip install -e . and a release on PyPI as csv2sqlite.
Commands: convert, inspect, and version.
Constraints: Python 3.10 or newer, no external database server, memory-safe for files up to 2 GB.
List what is present here, and separately list the gaps I must fill before writing (for example the exact flags and the license).

You get an inventory plus a gaps list — usually the precise flag names, exit codes, and license. Filling those gaps before drafting is what keeps the README from promising features the tool does not have.

Step 2: Write the One-Line Pitch and First Screen

The first screen decides whether anyone reads the rest. Keep it terse and concrete.

Write the top of the README:
1. A one-line description under 15 words that names the input and the output.
2. A two-sentence paragraph stating who it is for and the problem it removes.
3. A short "Why this tool" list of 3 bullets, each a single benefit, no marketing adjectives.
Then suggest 3 badge slots (build status, version, license) with placeholder text.

You get a first screen where the value is obvious before the user scrolls. “Convert a CSV file into a SQLite database with one command” beats a paragraph about the author’s motivation.

Step 3: Write Install and Quickstart

Install must be copy-paste ready. Quickstart must end in a visible result, not a success message the user has to trust.

Write an Installation section with two options: install from PyPI and install from source.
Write a Quickstart with a single working example that converts a CSV into a database and then inspects it.
Every command must be in a copy-paste block. End the quickstart by showing the expected output, including the row count and the database file name.
Assume the reader is on macOS or Linux but note the Windows equivalent for one command.

You get a quickstart where the newcomer sees a real result, such as a printed table count, and knows the tool works before reading a single flag.

Step 4: Document the Flags in a Table

Flags are where a README earns its keep. A scannable table beats a wall of prose.

Write the CLI reference as a table with columns: Flag, Default, Description.
Cover these flags: --db, --table, --delimiter, --header, --types, --batch-size.
For each, state the default value and describe the effect in one line. Note which flags are required.
Add one short example command under the table showing a non-default delimiter and an explicit table name.

You get a reference users can scan without leaving the README. Because the table lives next to the quickstart, a reader can go from first success to a customised command in one scroll.

Step 5: Add Examples, Contributing, and License

Depth sections should be short and link out where a longer explanation would bloat the file.

Add three sections:
1. Examples: three realistic use cases (loading a sales export, importing a log dump, and a typed import with --types).
2. Contributing: a four-line note covering how to run the tests and how to open a pull request.
3. License: a placeholder line naming the license and asking the maintainer to confirm it.
Keep each section tight and avoid repeating anything already in the quickstart.

You get a README with depth that does not repeat itself. The contributing note points to running the tests, which is the first thing a new contributor actually needs.

Step 6: Run the Sixty-Second Read Test

Finally, check the README the way a stranger would, from the top.

Review the README as a first-time user who has 60 seconds.
Report: (1) can they tell what the tool does from the first screen, (2) can they install and run one command without scrolling past the quickstart, (3) any jargon or missing step that would block them.
List every fix as a concrete edit, in order of importance.

You get a short list of blocking issues, usually a missing prerequisite or an unexplained flag. Fixing those is the difference between a starred repo and a closed tab.

Final Deliverable Checklist

• A one-line description naming input and output.
• A copy-paste install block for at least two paths.
• A quickstart that ends in visible output.
• A flags table with defaults and required notes.
• Three realistic usage examples.
• Contributing and license sections, with placeholders resolved.
• A passed sixty-second read test.

Reference: Flags Table Shape

Common Pitfalls

Pitfall 1 — documenting flags that do not exist. Models happily invent plausible options. Every flag in the README must be copied from the real command help, not the model’s memory.

Pitfall 2 — a quickstart that prints nothing. End it with expected output. A user who sees a row count knows the tool worked.

Pitfall 3 — burying install under a wall of features. Install belongs near the top. Features can wait.

Pitfall 4 — leaving placeholders like the license unresolved. A README that says “license TBD” reads as abandoned. Confirm and state it.

To explain the code behind the tool, see our explain a codebase prompt and the roundup of coding prompt examples. For a companion utility, browse our SQL query generator prompt.

Worked Example: The Quickstart Block

Here is the quickstart as it should appear, with escaped angle brackets shown so you can see the placeholder convention.

pip install csv2sqlite

csv2sqlite convert sales.csv --db sales.db --table orders

Expected output:
Created table "orders" with 12,480 rows in sales.db

Two commands, one visible result. Everything else in the README is optional depth for the reader who already trusts the tool.

Quick FAQ

How long should a CLI README be? Short enough that a stranger runs your tool in a minute, long enough to document every flag. For a small utility that is often three or four screens.

Should I write the README before or after the code? After the interface is stable. Writing it against a shifting CLI means constant rewrites; generate a first draft once the flags settle.

Can AI generate the whole README from the source? It can seed it, but you must verify every command, default, and install step against the running tool. Documentation that drifts from behaviour is worse than none.

What if my project has no tests yet? Say so in the contributing section and point readers to a manual check. Honesty about status is better than a broken test command.

Sources & Notes

The documentation-first, quickstart-driven README structure is a widely used open-source convention; the prompts and examples here are our own, reviewed on 2026-10-09. Verify all install instructions and flags against your actual release before publishing, and resolve any license placeholder before you make the repository public.