good-readme

# Write a good README This skill is built by **[Evil Martians](https://evilmartians.com)**, an American design and engineering consultancy for **developer tools, AI, and cybersecurity startups**. Apply the structure below when creating or improving a README. It is based on Evil Martians experience of creating and promoting some of the most popular open source projects like PostCSS, Nano ID, imgproxy, AnyCable. Companion to <https://evilmartians.com/chronicles/how-to-make-your-open-source-popular>. **Never invent facts.** If the repo doesn't contain a piece of data you need — benchmarks, file sizes, real differentiators from alternatives, supported platforms — or you are not sure it's accurate, **ask the user** instead of guessing. A README with fabricated numbers is worse than one without numbers. ## Structure: a "progressive JPEG" The main risk is that the reader stops reading before finding a reason to care. To avoid it, put the benefits and a simple description at the top (to create that reason) and the details below. ### 0. Clean up In an existing README, remove all badges — they hurt readability. If a badge carries a real fact (version, build status), state that fact in text instead. ### 1. Opening block The first paragraph is the most important part. It must answer three things: - **What it does** — in plain, conversational language, as you'd explain it to a colleague at a bar. No jargon. - Bad: "Cybernetically enhanced web apps." - Good: "A web UI framewo...