---
name: write-readme-prompt
description: A prompt that writes a clear README.md for a project from its code - what it does, a quick start that actually runs, configuration, usage examples and where to get help - in plain GitHub Markdown without emoji clutter or invented features. Use when a repo has no README, the README is out of date, or before making a project public.
license: MIT
metadata:
  category: coding-prompts
  tags: "docs,github,writing"
  author: johnny-bravo
  version: "1.0"
  updated: "2026-11-02"
  status: published
  aliases: "readme, readme.md, project docs"
  source_url: "https://github.com/github/awesome-copilot/tree/5269f7ea2d6c3a9bfda5ed878b6726cf509121fd/skills/create-readme"
  source_license: MIT
  copyright: "Copyright GitHub, Inc."
  original_author: "GitHub awesome-copilot contributors (create-readme)"
  modified: "Adapted by TheSkillVault: replaced the role-play and external example links with an original README outline and accuracy rules; added steps, adapt notes, secrets check and done-when."
  imported_on: "2026-11-02"
---

# Write a README (prompt)

A README answers three questions fast: what is this, how do I run it, and where do I go next. This prompt writes one from your actual code.

## When to use
- Your repo has no README or a one-line one.
- The setup steps in the README no longer work.
- You are about to share or open-source a project.

## Steps
1. Open the project in your AI tool so it can read the code and config.
2. Paste the prompt below.
3. Run the quick start yourself on a clean checkout and fix anything that fails.
4. Commit the README.

## Prompt
```text
Write a README.md for this project based on its actual code and config files.

Sections, in order:
1. Project name and a one-sentence description of what it does and who it is for.
2. Quick start: the exact commands to install and run it, from a fresh clone. Include required versions (Node, Python and so on).
3. Configuration: every environment variable, with a fake example value. Point to .env.example if it exists.
4. Usage: one or two short, real examples.
5. Project structure: a short tree of the main folders, only if it helps.
6. Scripts: the main commands (test, build, lint) and what each does.
7. Help: where to report issues or ask questions.

Rules:
- Only describe features that exist in the code. If unsure, leave it out or ask.
- Plain GitHub Markdown, short sentences, no emoji decoration.
- Do not add licence, contributing or changelog sections; those have their own files. A one-line licence pointer is fine.
- Never include real keys, tokens or internal URLs.
```

## How to adapt
- Library rather than app? Swap the quick start for an install and import example.
- Internal tool? Add a "Who owns this" line in section 7.

## Gotchas
- Check that every command in the quick start runs. A broken first command loses most readers.
- AI tools invent badges and features. Delete anything you cannot point to in the code.

## Portability
Works with any language, any git host and any chat AI or coding agent. No tool lock-in.

## Done when
- A new person can clone and run the project using only the README.
- Every listed feature and variable exists in the code, and no secrets appear.

## Example prompt
"Write a README for this repo based on the code. Make sure the quick start commands actually work."

---
Adapted from "create-readme" in github/awesome-copilot (MIT, Copyright GitHub, Inc.). See LICENSE.txt.