Home / Developers and data / Check a README works for a first-time user

Check a README works for a first-time user

Who it is for
Developers who want newcomers to get started on the first try.
What you give it
The repository, or the README and files pasted.
What you get back
Each step marked OK, broken or missing, with the README edits that fix it.

It is a text file you add to an AI assistant, or paste into a chat.

Free. MIT licence: use it, change it, share it.

Before and after

The README of a small public React tutorial app says to run yarn && yarn start.

After (real output, excerpt):
Short answer: no. The one command the README gives, yarn && yarn start, stops at the second half, because the project has no start script.
4 | yarn start | BROKEN | package.json scripts are only dev, build, lint and preview. There is no start.
1 | Install Node.js | MISSING version | .nvmrc says v24. The README gives no version.
Run command: yarn / yarn dev

See it run

Animated demo of Check a README works for a first-time user on a real example: the input goes in and the finished result appears. The still shows the final result.

What it does

Point it at a repository. It follows the README like a new user would and checks every step against the repo: versions, scripts, files, environment variables, ports and links. You get each step marked OK, BROKEN, MISSING or UNVERIFIED with evidence, the first-run path a newcomer would actually take, and the README edits that fix it.

The evidence

1 real-data run on a public MDN tutorial repository (Claude). The missing start script, the .nvmrc version and the stale Create React App text were all real.

Limits

  • Read-only by default, so some steps stay UNVERIFIED.
  • It cannot see what is not in the repo.
  • It proposes README edits; it does not make them.

Questions

Questions or a problem?

Use the contact page.

Contact page

Which assistants does it work with?

Works in ChatGPT or any chatbot: you paste in your details and it writes the result. A repo to read, or the README and manifests pasted.

For technical users

Using it with an AI assistant

  1. Run npx skills add proskillpacks/skills in your project and pick this skill. Or copy the readme-first-run-check folder from GitHub (https://github.com/proskillpacks/skills/tree/main/skills/developers/readme-first-run-check).
  2. Put the readme-first-run-check folder where your assistant looks for skills. The generic path is .agents/skills/ (or npx skills add from a folder). Tool-specific paths:
    • Claude Code: ~/.claude/skills/ (or .claude/skills/ inside one project)
    • OpenAI Codex, Gemini CLI, Cursor and others: .agents/skills/ or the skills folder their docs name
    • claude.ai: zip the skill folder yourself, then Customize, Skills, the plus button, Create skill, Upload a skill (code execution must be on in Settings, Capabilities)
    • ChatGPT or any chatbot: open the skill's prompt.md, paste it into the chat, then paste your own text or link
    • Steps for each tool, with links to its official docs: how to install skills
  3. Ask for the job in plain words, for example: "Check the getting started steps in the README. Don't install anything.". The skill loads by itself.
Get the files from GitHub (for developers)

Jobs that go with this