When to use this
- A new project or package has no README yet.
- An existing README has drifted from what the code actually does (wrong commands, missing a new required env var).
- Not for generating API reference docs -- use api-doc-generator for that; a README is an entry point, not exhaustive reference.
The skill file
Copy this verbatim. It's written in the SKILL.md format (YAML frontmatter + markdown instructions) that Claude Code, and increasingly other agent tools, read directly.
--- name: readme-generator description: Write or update a README by reading the actual codebase (entry points, scripts, dependencies, config) rather than filling a generic template. Use for a new project's first README or to fix one that's drifted from reality. --- # README Generator Every claim in the README must be verifiable against the actual repo. Don't write "run `npm start`" without checking `package.json` actually defines that script. ## What to gather before writing 1. What does this project actually do -- read the entry point, main module, or primary route/handler set, not just the name. 2. Real install steps: check the actual package manager/lockfile, language version requirements (from a version file or CI config), and any non-obvious setup (database, env vars -- check `.env.example` if one exists). 3. Real run/build/test commands: pull them directly from `package.json`/`Makefile`/`pyproject.toml`/CI config, don't guess generic ones. 4. Actual project structure, if it's non-obvious, from the directory layout. ## Structure 1. One-paragraph description: what it is and who it's for. 2. Quickstart: install -> run, the minimum to see it working. 3. Configuration: required env vars/config, with what each does. 4. Development: how to run tests, lint, build. 5. Project structure, only if it's non-obvious from browsing. 6. License/contributing, if applicable and not already covered elsewhere. ## What to avoid - Copying a generic README template's section headers if they don't apply (e.g. a "Deployment" section for a library with no deployment story). - Commands that aren't verified against the actual scripts/config. - Badges/links to CI, license, etc. that don't actually exist for this repo.
Installing it elsewhere
The frontmatter/body split above is Claude Code's convention. Here's how to carry the same instructions into other tools:
Save the file below verbatim (frontmatter included) at that path, project-local or in ~/.claude/skills/ for a user-level skill. Claude Code loads the name/description pair to decide when to pull it in, or you invoke it directly as /readme-generator.
Convert the YAML frontmatter to Cursor's rule format (description, globs, alwaysApply: false) and keep the markdown body as the rule content. Cursor surfaces it by description match, same idea as Claude Code's auto-load.
Codex CLI (and increasingly other agentic CLIs) read AGENTS.md at the repo root as always-on instructions. Paste the markdown body under a heading like ## {title}; for GitHub Copilot's coding agent, the equivalent file is .github/copilot-instructions.md.
Append the markdown body to .windsurfrules at the repo root. Windsurf treats the whole file as always-on context, so keep only the instructions you want applied on every request.
- Writing install/run commands from convention ("probably npm start") instead of checking what's actually defined.
- Leaving stale instructions when only part of the README was updated.
- Including boilerplate sections (elaborate contributing guide, code of conduct) that don't match the project's actual size/maturity.