How do I check that my README's setup steps actually work?

Setup instructions rot. A script gets renamed, a Node version moves on, a config file is added and nobody updates the README. The person who finds out is a newcomer, usually at the worst moment: the first ten minutes with your project.

You can test this without installing anything. Give an assistant the README and the files it points to, and ask it to check each step against the evidence instead of reading the README politely.

What you need

• The README.
• The files its steps depend on: the package manifest (package.json, pyproject.toml or similar), any version file such as .nvmrc, example config or .env.example, the CI workflow, and a file listing of the repository. A tree listing is enough for the last one.
• Nothing is run. You are asking for a read, not a build.

The prompt

Paste this into a new chat, then paste the README and the files under it, each with its file name above it.

You act as a new user following a project's README. Work only from the files I paste below. Never guess a version, command or file. Mark anything you cannot verify as UNVERIFIED and say which file you would need.

1. List every step a newcomer must follow as a numbered list: prerequisites and versions, clone and install, configuration and environment variables, services, run, test, URLs and ports. Quote the README briefly.
2. For each step say OK (evidence matches: cite the file and the line or key), BROKEN (evidence contradicts it), MISSING (a newcomer needs something the README does not say) or UNVERIFIED. Check that scripts named in the README exist in the manifest, that referenced files and links are in the file listing, that versions agree across files, and that the commands are in a workable order.
3. Describe the real first run: what a newcomer who follows the README exactly would hit first, second and so on, and where they would stop.
4. Give the README edits that fix each problem, as concrete replacement lines, ordered by how soon a newcomer meets them.
Do not run anything and do not edit anything.

Here are my files:

[paste the files here, each under its file name]

How to check the result

The useful part is the third step, the description of the real first run. It tells you where a newcomer who follows the README to the letter would stop. Read that first, then go back to the table.

For every BROKEN, open the file the assistant cited and confirm the evidence. A typical one: the README says to run a script the manifest does not have. You can check that in ten seconds.

For every MISSING, ask whether it is really missing or whether the assistant did not get the file that has it. If it is real, add the line the assistant suggested. Edit the wording so it sounds like you.

UNVERIFIED is honest, not a failure. It means the answer needs something that was not pasted, such as whether a package install actually resolves. Run that one yourself in a clean folder, or in a container, and watch what happens.

Limits

• It does not run your project. A step can look right on paper and still fail on a real machine.
• It cannot see files you did not paste. Missing evidence shows up as UNVERIFIED, not as a guess.
• It cannot judge whether a link works. Open the links yourself.
• It checks the README against the repository. It does not test your instructions on Windows, Mac and Linux. If you support all three, try the steps on each.

Browse all skills in the catalog

Want this as a ready-made skill? README First-Run Check (Free) does it in your own assistant.