Most READMEs fail at install. The reader hit a missing peer dep on line 3 and bounced before seeing the cool part. The fix is brutal: working install path up top, real quickstart code in the first screen, and an “if install fails” block before the marketing. These 12 prompts force that order. For ongoing maintenance, pair with code review prompts.
Best for
- OSS libraries and frameworks
- Internal tools at a company
- Indie products and side projects
- Templates / starters / boilerplates
- CLI tools published to npm / pip / 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, ≤80 chars)
2. Install (max 3 shell commands)
3. Quickstart (≤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 ≤30 lines 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 ✓ / ✗ / 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 ≤200 words 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 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 <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 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. Show one streaming and one blocking example.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}Common mistakes
- Long marketing intro before the install command, so impatient readers bounce
- Quickstart that doesn’t actually run (references a removed API or skips imports)
- No “if install fails” section, so the 20% of readers on Windows / corporate networks give up silently
- Alphabetical API reference instead of usage-frequency order — the reader scrolls past the part they need
- Comparison section that pretends competitors don’t win at anything, which makes the whole README feel like marketing
Related
Tags: #Prompt #AI coding #README