The prompt
Score 10 of 10, Excellent
Use it when Your repository has no README, or an out-of-date one, and you want one a newcomer can install and run the project from.
- {{audience}}
- {{project_notes}}
- {{repo_files}}
- {{existing_docs}}
- {{license}}
- {{contributing}}
Full prompt and why it works
Prompt
Write a README.md for the repository described below, for {{audience}}, so that someone who has never seen the project can tell in a minute what it does and can install and run it from the README alone. What the project is and why it exists, in my words: {{project_notes}} Files from the repository (package manifest, scripts, Makefile, example configuration such as .env.example, CLI help output): """ {{repo_files}} """ Existing docs or notes to draw on: {{existing_docs}} License file name and contents, if any: {{license}} How we take contributions: {{contributing}} Use these sections, in this order, with Markdown headings: 1. Project name and a one-sentence description. 2. What it does: up to 5 bullets, from my notes and the code. 3. Requirements: runtime versions and system dependencies, from the manifest. 4. Install: numbered steps with the commands in code blocks. 5. Usage: the smallest working example, then the most common task or two. 6. Configuration: a table with the columns Setting, Required, Default, What it does, from the example configuration. 7. Development: how to run the tests, the linter and a local build. 8. Contributing: from what I wrote, or a link to CONTRIBUTING.md if it exists. 9. License: named only from the license file. Keep it under 700 words, not counting code blocks. Write in plain, direct sentences. A good README answers what the project is and how to run it before anything else. Every command must come from the files above: a script in the manifest, a Makefile target, a documented CLI flag. Do not invent commands, flags, environment variables, URLs, badges, version numbers, benchmarks or features. If a step needs a command I have not given, write it where it belongs and add an HTML comment after it: <!-- CHECK: not found in the repository files -->. Leave out marketing language such as "blazing fast" or "powerful". If there is no license file, write "License: [CHECK: no license file found]" and do not choose one. If my notes and the code disagree, for example on the supported runtime version, follow the code and list the difference after the README under "Notes for the maintainer".
Variables
- {{audience}}
- Who reads it, for example "developers adding this library to their app" or "engineers on our team running the service".
- {{project_notes}}
- What the project does and why, in a few sentences of your own.
- {{repo_files}}
- The package manifest (package.json, pyproject.toml or similar), Makefile or scripts, the example configuration file and any CLI --help output.
- {{existing_docs}}
- Docs or notes worth drawing on, pasted or listed, or "none".
- {{license}}
- The license file's name and first lines, or "none".
- {{contributing}}
- How you take contributions, for example "pull requests welcome, run the tests first", or "internal only".
Why it works
- What to avoid. Every command must come from the repository files, and anything else is marked with a CHECK comment, so the README never tells a newcomer to run a script that does not exist.
- Format. Fixed sections in the order a newcomer needs them, with configuration as a table built from the example settings file.
- If unsure. A missing license is flagged rather than chosen, and conflicts between your notes and the code go to a note for the maintainer.