Write a good README

This skill is built by Evil Martians, 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: