---
name: readme-writer
description: Writes or fixes a README from the actual code - what the project is, a quick start whose commands are verified, a configuration table, common tasks and troubleshooting - without inventing features. Use when a repo has no README, an outdated one, or the user asks for project docs.
---

# README Writer

A README is correct only if a new person can follow it and succeed. Derive every statement from the code, and run the commands you document.

## Workflow

1. Read before writing. If a README exists, read it fully and note what is stale. Then read the manifests (`package.json`, `pyproject.toml`, `go.mod`, ...), entry points, `Makefile` or scripts, `Dockerfile`, CI config, `.env.example`, and the code that reads environment variables.
2. Build the facts list: what the project does (from code, not from the name), required runtime versions, install, run, test and build commands, ports, config variables, external services it needs.
3. Verify the quick start. In a clean checkout or temporary directory when possible, run the install and start commands exactly as you will write them, and confirm the result (a URL responds, a test passes, a CLI prints help). Use dummy values for configuration; never use real secrets. Ask before running anything that touches real external services or data.
4. Write the README using the structure below, keeping only sections that apply.
5. Re-read it as a newcomer: every command copy-pasteable, every path real, every variable listed.

## Structure

```
# Project name
One or two sentences: what it does and for whom.

(Optional) Screenshot, diagram or short demo output.

## Requirements
Runtime versions and tools, with the versions that were tested.

## Quick start
Numbered commands, from clone to seeing it work.

## Configuration
| Variable | Required | Default | Description |

## Usage
The 3 to 5 most common tasks, each with a command and expected result.

## Development
Run tests, lint, build; project layout in a few lines.

## Troubleshooting
Symptom -> cause -> fix, for problems that really occur.

## License
```

Add Deployment, API or Contributing sections only if the repo has material for them. Link to longer docs instead of duplicating them.

## Rules

- No invented features, endpoints, flags or badges. If you cannot find it in the code, it is not in the README.
- Mark anything you could not verify, for example "not tested on Windows".
- The configuration table covers every environment variable the code reads. Find them with a search such as `grep -rnE "process\.env|os\.environ|getenv" .` and adapt to the language. Show example values that are obviously fake, such as `your-api-key-here`. Never copy real values from a `.env` file.
- Commands go in fenced code blocks with the language tag. Use `$`-free lines so they can be pasted.
- Prefer short sentences and concrete nouns. Skip marketing words and long feature lists that restate the code.
- When fixing an existing README, preserve useful content and the author's structure, change only what is wrong or missing, and say what you changed.

## Pitfalls

- Copying the quick start from the old README without running it.
- Documenting the ideal setup rather than the one that works (missing system packages, a needed database, a code generation step).
- Leaving template leftovers: "TODO", placeholder project names, dead links.
- Listing environment variables that no longer exist or omitting the required ones.
- Putting real hostnames, tokens, personal emails or internal URLs in examples.

## Report back

The files written or changed, the commands you verified and their results, anything you could not verify, and questions where the code did not answer (for example the intended license).

Source: [AnyModel skills catalog](https://anymodel.org/en/skills) · License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
