Most READMEs fail at install. The reader hits a missing peer dependency on line 3 and bounces before seeing the part that matters. The fix is unglamorous: a working install path up top, real quickstart code in the first screen, and an “if install fails” block before any marketing. These 12 prompts force that order. For ongoing maintenance, pair them with code review prompts and changelog prompts.
TL;DR
- A good README answers three questions in the first screen: what is this, how do I install it, how do I run it once.
- Order matters more than length. Install and a runnable quickstart come before features, badges, and the project story.
- Prompts 1–3 are the spine (skeleton, quickstart, install troubleshooting). Run those first; the rest are situational.
- Feed a code-aware agent the real entry point and public exports so it writes against your actual API, not a guess.
Which AI tool to run these in (June 2026)
Paste these into whatever model you already use, but for anything that should reflect real code, prefer an agent that can read the repo rather than a single pasted file:
- Claude Code runs Anthropic models only (Sonnet 4.6 for everyday drafts, Opus 4.7 when it needs to reason across many files). Both ship with a 1M-token context window as of June 2026, so it can hold a mid-size repo at once. Bundled with a Claude Pro plan at $20/month.
- Cursor (Hobby free, Pro $20/month) indexes the whole project locally and lets you @-mention files, so a prompt like “write the quickstart from
src/index.ts” pulls the right code without manual copy-paste. - ChatGPT (Free, Plus $20/month, GPT-5.5) and Gemini 3.1 Pro (Google AI Pro $19.99/month) work fine for the template-only prompts below, where you paste the snippet yourself.
For prompts that say paste, an agent that already has repo access skips the paste step entirely. Always read the generated quickstart against the live code before committing it.
Best for
- OSS libraries and frameworks
- Internal tools at a company
- Indie products and side projects
- Templates, starters, and boilerplates
- CLI tools published to npm, pip, or cargo
1. Minimal README skeleton
Project: [name]. What it does in 1 sentence: [x]. Target audience: [who].
Generate a README with ONLY these sections in this order:
1. Tagline (1 sentence, max 80 chars)
2. Install (max 3 shell commands)
3. Quickstart (max 30 LOC code block showing the most common use case)
4. What's next (3 bullet links: deeper docs, examples, contributing)
No "About", no "Features" list, no badges section yet.2. Quickstart that fits on one screen
Below is the project's entry point + key public API surface.
Write a quickstart code block of 30 lines or fewer that demonstrates the most
common use case END-TO-END (import, init, call, print result).
The reader should be able to copy-paste it and see output without reading
anything else. After the code block, add 3 lines explaining what just happened.
Entry point + APIs: [paste]3. Install troubleshooting block
Project install steps: [list]. Languages / runtimes required: [list versions].
Add an "If install fails" section with the 5 most likely failure modes for this stack:
- Peer-dependency conflict
- Version mismatch (Node / Python / runtime)
- Missing system dependency (build tools, libssl, etc.)
- Permission / sudo issue
- Network / proxy / corporate firewall
For each: how to recognize it (error message snippet), how to fix it (1-2 commands).4. Examples gallery
For project [name], generate 5 short worked examples covering distinct use cases
(not 5 variations of the same one).
For each: (a) 1-paragraph context — who would do this and why,
(b) full runnable code block, (c) 1 line describing expected output.
Order from simplest to most advanced. Link each to a longer doc if relevant.5. API reference quick table
Below is the module's public exports. Generate a single-table API reference with columns:
Name | Type (function / class / constant) | 1-line description | Link to deeper doc
Sort by: most-used first, not alphabetical.
Mark deprecated APIs with a strikethrough and a "use X instead" note.
Module exports: [paste]6. Comparison-with-alternatives section
Project [name] competes with [A], [B], [C]. Be honest, not boastful.
Write a comparison section with:
- 1 paragraph framing: "pick [name] if X, pick [A] if Y"
- A 4-row table on dimensions: speed, ergonomics, scope, ecosystem maturity
- Mark with a check / cross / partial where each tool wins
- Include at least one row where an alternative beats us
End with a 1-line link to the alternatives' homepages.7. Contributing section
Generate a CONTRIBUTING section of 200 words or fewer covering:
- Dev setup (clone, install dev deps, run watcher)
- Running tests (full suite + single test)
- Code style (linter / formatter command, not the rules)
- PR checklist (tests added, CHANGELOG updated, conventional commit)
- How to find a "good first issue"
Link to longer CONTRIBUTING.md for the rest.8. Audit an existing README
Audit this README against a checklist:
- Is the install path discoverable in the first screen?
- Is there a working quickstart that the reader can copy-paste?
- Are common install failures addressed?
- Is the API surface scannable in under 30 seconds?
- Does the comparison section punch our weight, not exaggerate?
For each fail, give specific line refs and a 1-line rewrite.
README: [paste]9. Badges and shields strategy
For [name] ([language, package manager]), recommend which badges belong at the
top of the README and which are noise.
Output: badge | what it signals to a reader | include? (yes / no / only-if-X) | reason.
Cap the final list at 5 badges. Prioritize signals that affect install decisions
(CI status, package version, license) over vanity (downloads, stars).10. README for a library wrapping an LLM
Project: a [language] wrapper around [LLM API].
Generate a README that handles the LLM-specific concerns most wrappers ignore:
- API key setup (env var, .env, secret manager) with a security warning
- Cost expectations (per-call ballpark, when caching kicks in)
- Rate-limit and retry behavior
- Streaming vs blocking modes
- A "When NOT to use this" section
Keep quickstart at 30 LOC or fewer. Show one streaming and one blocking example.This is where READMEs drift fastest, because model names and prices move. As a reference point for the numbers your wrapper might quote: the Claude Opus 4.7 API runs $5 / $25 per million input / output tokens, Sonnet 4.6 $3 / $15, GPT-5.5 $5 / $30, and Gemini 3.1 Pro $2 / $12 (June 2026). Tell the model to label any such figure “as of [date]” so readers know it is a snapshot, not a contract.
11. README for a CLI tool
Project: a CLI named [name] that [does what].
Generate a CLI-shaped README:
- Install (homebrew / npm / pip / curl one-liner, depending on distribution)
- 30-second usage: 3 example invocations, each with expected stdout
- Flags table: flag | type | default | what it does
- Config file (if any): path, format, example
- Exit codes
- One troubleshooting example showing a real error and its fix12. README rewrite from a stale version
Below is the current README, last updated 18 months ago. The project has since [what changed].
Rewrite to reflect today's reality without bloating the file:
- Remove dead links and deprecated APIs
- Replace outdated install instructions
- Trim sections that no longer apply
- Add the 2-3 most important new features in their natural place
Output: rewritten README + a short changelog of what you removed and why.
Current README: [paste]
Recent changes: [paste]How to read the generated draft
A model will happily invent an import path or a flag that does not exist. Before you commit:
- Run the quickstart yourself in a clean checkout. If it errors, the README is already broken.
- Grep the generated code for symbols that are not in your public exports.
- Confirm every install command on a second OS if you ship cross-platform (the Windows or corporate-network path is where READMEs quietly lose readers).
- Check that any version or price number carries an “as of” date.
Common mistakes
- Long marketing intro before the install command, so impatient readers bounce.
- Quickstart that does not actually run, because it references a removed API or skips imports.
- No “if install fails” section, so the 20% of readers on Windows or corporate networks give up silently.
- Alphabetical API reference instead of usage-frequency order, so the reader scrolls past the part they need.
- Comparison section that pretends competitors never win, which makes the whole README read like an ad.
FAQ
How long should a README be? Long enough that a stranger can install and run it once, no longer. If your project has deep docs, the README is a landing page that points to them, not a replacement for them. The first screen is the only part most readers see.
Should I let AI write the whole README unsupervised? No. Use it for structure, the install-failure section, and the API table, where it saves real time. But run the quickstart in a clean checkout before committing. The single most common failure is a copy-paste quickstart that references an API the project removed.
Which model should I use for these prompts? For template-only prompts (badges, comparison, contributing), any current model works: GPT-5.5, Claude Sonnet 4.6, or Gemini 3.1 Pro. For prompts that need real code (quickstart, API table, stale-rewrite), use a repo-aware agent like Claude Code or Cursor so it writes against your actual exports instead of guessing.
How do I keep a README from going stale? Treat it like code. Add a CI step that runs the quickstart on every release, and use prompt 12 whenever a major version ships. Pair it with changelog prompts so the README and the changelog move together.
What is the single highest-leverage section? The “if install fails” block. It costs a few lines and rescues the readers who would otherwise bounce in silence, which are exactly the ones you never hear from.
Related
Tags: #Prompt #AI coding #README