Engineering

README Prompt Template

Overview, Installation, Usage, Examples, Configuration — the README skeleton with required, runnable code examples.

Open in Markdown Output Builder

Overview

READMEs die in two ways: missing sections (no install steps, no examples) and decorative code blocks that don't run. This setup generates READMEs against the five-section skeleton every reader expects, with README-specific rules — one-paragraph project description up top, most common use case first — and Require Code Examples: every behavior-describing section carries a fenced, language-tagged block that is usable as written, no pseudo-code, no "..." placeholders.

How to use this resource

Generate and describe your project below it

The prompt carries the structure; your project details go in the input under it.
Check the code rule

"Usable as written" bans the placeholder snippets that make READMEs look done without being useful.
Keep common-case-first

The README rule that matters most: the reader installing for the first time outranks the power user.

Why This Works

The five-section skeleton matches what every README reader scans for
Required code examples close the decorative-snippet gap
Newcomer-first ordering is encoded as a rule, not a hope

Best for

Open-source maintainers shipping many small projects
Teams standardizing internal repo documentation
READMEs whose examples must actually run

Not for

Deep-dive system documentation — that's the Technical Documentation setup
Summarizing an existing README — that's the Structured Summary Prompt

Use cases

Writing READMEs for new projects in one consistent shape
Backfilling READMEs across a repo collection
Forcing real install commands instead of "install the package"

FAQ

Which README sections must carry a runnable code block, and what counts as a failing snippet?

The CODE RULES require a fenced, language-tagged block in every section that describes behavior or usage, so Installation, Usage, and Examples each need one while a prose-only Overview may not. A block fails the rule 'usable as written' if it leans on pseudo-code or '...' placeholders, so 'pip install ...' or 'your-config-here' must become real commands before you ship the file.

Where does content go that doesn't fit Overview, Installation, Usage, Examples, or Configuration?

It lands inside the closest existing section, never as a new top-level heading. The CONSISTENCY RULES say 'Do not add new top-level sections' and fix those five '## ' headings in order, so a Troubleshooting note folds under Configuration or Usage and API notes fold into Examples. Every generated README keeps the same five-section shape instead of sprouting one-off headings.

Why does the generated README come back wrapped in a code fence, and how do I stop it?

That happens when the assistant treats the whole document as one block. The OUTPUT RULES already state 'Do not wrap the document in code fences' and 'Start directly with the # title line', returning only the markdown with no preamble. If a stray outer fence still appears, resend the prompt unchanged in ChatGPT, Claude, or Gemini — a fresh generation usually drops it, since the rule is baked in.

Customize This Resource

Opens this setup in Markdown Output Builder. Generate to get the full markdown prompt — then adjust the sections, table rules, and consistency level.

Open in Markdown Output Builder

Prompt Template

Copy it as-is, or use Open in Markdown Output Builder to load it pre-filled and customize it with your own context.

TASK
Generate a complete README for a new open-source project.
Produce a new markdown document — there is no source text to summarize.

DOCUMENT
The document is a project README — the first thing a new user reads.
- Open with a one-paragraph project description before the first section.
- The most common use case comes first; edge cases come last.

DOCUMENT STRUCTURE
Start with one "# " title line, then use exactly these sections, in this order:
## Overview
What the project does and why it exists.
## Installation
Step-by-step install commands.
## Usage
How to use it, most common case first.
## Examples
Working examples a reader can copy.
## Configuration
Options, defaults, and environment variables.

MARKDOWN RULES
- One "# " title at the top; every section below it is a "## " heading.
- Use markdown lists for enumerations — no walls of prose.
- No HTML tags — pure markdown.

TABLE RULES
- Use a markdown table when content is naturally tabular — comparisons, option matrices, parameter lists; otherwise prefer prose.
- Every table needs a header row and a separator row.

CODE RULES
- Every section that describes behavior or usage must include a fenced code example with a language tag.
- Code examples must be usable as written — no pseudo-code, no "..." placeholders.

CONSISTENCY RULES
- Use every section defined above, in the order given.
- Do not add new top-level sections — put extra material inside the closest existing section.

OUTPUT RULES
- Return only the markdown document — no preamble, no closing commentary.
- Start directly with the "# " title line.
- Do not wrap the document in code fences.

More resources from Markdown Output Builder

Resource

Markdown Output Prompt — Lock the Document Structure

The contract that stops AI documents from restructuring themselves: a pinned section skeleton, forced tables, and strict consistency rules.

Prompt Engineering

Resource

API Documentation Prompt

Overview, Authentication, Endpoints, Error Handling, Rate Limits — endpoint docs in an identical structure, with parameter tables and runnable examples forced.

Engineering

Resource

Changelog Prompt — User-Readable Change Logs

Added, Changed, Fixed, Removed, Security — changelog entries written as user-visible changes, not commit messages.

Engineering

Resources that pair well

Resource

Executive Summary Prompt

Summary, Why It Matters, What Happens Next — the executive summary contract for readers who will never open the source.

Operations

Resource

Force JSON Output from AI

Stop getting 'Sure, here is the JSON…' — the output-contract pattern that forces models to return only parseable JSON: schema, example, and a strict rule block.

Prompt Engineering

Resource

Fix Invalid JSON from AI

The JSON won't parse and you can't see why. Deterministic cause-sniffing — trailing commas, single quotes, unclosed brackets — and the repair prompt that fixes it.

Engineering

Related tools

Tool

Markdown Output Builder

Build prompts that produce documents in a fixed structure — headings, sections, and tables.

Structured Output

Workflows that use this resource

Workflow

AI Code Documentation Workflow

Generate documentation that matches the code instead of drifting from it — have AI explain what the code really does, write it up as structured docs, then validate the format holds.

3 steps 25–45 minutes

Guides for this resource

Guide

How to Write a README With AI From Your Project Facts

Your README works perfectly on the one machine where the tool was already installed. Everyone else hits a missing prerequisite in the first ninety seconds. Here's how to build a README from your real setup facts — and the clean-machine run that decides whether any of it is true.

Software Development with AI

Guide

How to Generate a Changelog With AI From Your Merged Changes

The changelog gets written last, from a list of PR titles someone else wrote for a reviewer who has moved on. Here is how to generate a changelog with AI that records what shipped for the people upgrading — and parks what nobody can stand behind yet.

Software Development with AI

Tip: Save time by exploring related resources and tools that integrate with this resource.