Reads a project's README the way a new user would and checks, against the repository itself, every step they are told to take - the prerequisites and versions, the install and setup commands, the files, scripts, environment variables and ports the README mentions, and the run and test commands. It reports each step as OK, BROKEN, MISSING or UNVERIFIED with file evidence, then gives the first-run path a newcomer would actually experience and the README edits that fix it.
npx mdskills install proskillpacks/readme-first-run-checkRelated
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.
Any assistant that reads the open SKILL.md format works.
readme-first-run-check folder into .agents/skills/ in your project (or ~/.agents/skills/ for everywhere). Create the folder if it is not there. Or use your tool's own skills folder (for example .claude/skills/ for Claude Code).No install: open prompt.md, copy it, paste it into ChatGPT or any chatbot, and add your material where marked.
Needs: nothing beyond what the skill says about git or file access. Without a shell, it asks you to paste what it needs.
Works with any AI assistant that reads SKILL.md (Claude, OpenAI Codex, Gemini CLI, Cursor, GitHub Copilot and others). We run our release tests on Claude Sonnet and Opus. Use your assistant's strongest model: in our tests, a small, fast model added facts that were not in the source data.
The README of a small public React tutorial app says to run yarn && yarn start.
After (skill output, excerpt): Short answer: no. The one command the README gives,
yarn && yarn start, stops at the second half, because the project has nostartscript. 4 |yarn start| BROKEN |package.jsonscripts are onlydev,build,lintandpreview. There is nostart. 1 | Install Node.js | MISSING version |.nvmrcsaysv24. The README gives no version. Run command: yarn / yarn dev
1 real-data run on a public MDN tutorial repository (Claude Sonnet). We checked each finding against the repo: the missing start script, the .nvmrc version and the stale Create React App text are all real. Not yet run on other models.
Made by Pro Skill Packs. Free under the MIT licence.
Install via CLI
npx mdskills install proskillpacks/readme-first-run-checkReadme First Run Check is a free, open-source AI agent skill. Reads a project's README the way a new user would and checks, against the repository itself, every step they are told to take - the prerequisites and versions, the install and setup commands, the files, scripts, environment variables and ports the README mentions, and the run and test commands. It reports each step as OK, BROKEN, MISSING or UNVERIFIED with file evidence, then gives the first-run path a newcomer would actually experience and the README edits that fix it.
Install Readme First Run Check with a single command:
npx mdskills install proskillpacks/readme-first-run-checkThis downloads the skill files into your project and your AI agent picks them up automatically.
Readme First Run Check works with Claude Code, Claude Desktop, Cursor, Vscode Copilot, Windsurf, Continue Dev, Codex, Gemini Cli, Amp, Roo Code, Goose, Opencode, Trae, Qodo, Command Code, Chatgpt. Skills use the open SKILL.md format which is compatible with any AI coding agent that reads markdown instructions.