readme
Installation
SKILL.md
Readme
A README answers three questions for someone who has never seen the repository: what is this, can I run it, and where do I go next. Everything else is a distraction from those three.
Read the repository before writing a line
Never describe a project from its name. Every claim in the output must come from a file you read.
| To write | Read |
|---|---|
| Tech stack, versions | package.json, pyproject.toml, Cargo.toml, lockfile |
| Getting started | the task runner (justfile, Makefile, package.json scripts), .env.example |
| Project structure | the actual tree, two levels deep |
| Features | routes, entry points, CI workflow names — not the previous README |
| Deployment | .github/workflows/, compose.yaml, Dockerfile |
Where a fact is unavailable, leave a bracketed placeholder — [Node.js 24+], [Module A] — for the author to complete. An invented version number is worse than a blank.
A placeholder belongs in prose, never inside an attribute that renders. src="[hero image URL]" does not read as a note to the author; it renders as a broken-image icon, as the first thing on the page. When an asset does not exist, drop the element.