Nobody reads your code. They read your README.

Nobody reads your code. They read your README.

Your README is not documentation. It's a landing page.

It's the page that decides whether someone stars the repo, installs the package, or closes the tab. And most of us write it in five minutes at the end of a build, when we're already tired and want to ship.

I found something that fixed this for me. Free, open source, and it took a minute.

Shieldcn

It's at shieldcn.dev. It builds READMEs - cover image, badges, layout - following the conventions you'd otherwise have to carry in your head.

I rebuilt the README for shadscan with it. Before, it was a title and one line of description:

# shadscan

The deterministic UI audit for shadcn apps

After, it had a proper header image and a badge row - npm version, weekly downloads, the lot - above the description and quick start.

That took one minute.

The studio

shieldcn.dev/studio is the visual builder. Set the title and subtitle, pick your badges - npm version, GitHub stars, custom ones - and reorder them so the number you care about comes first.

The defaults are the whole point. You don't have to already know what a good README looks like. It does.

But I don't use the studio

This is the part worth your attention.

Shieldcn ships an agent skill. Install it once and your coding agent knows how to build the badges and the README itself - Claude Code, Cursor, Codex and others.

npx skills add jal-co/shieldcn -a claude-code
npx skills add jal-co/shieldcn -a cursor

Then you just ask for what you want:

Add npm and GitHub badges. Size xs, ghost variant, working in light and dark mode.

Migrate the Shields.io badges in this README to shieldcn.

Set up a badge row with stars, license, and version.

For shadscan I said:

I want a perfect README, go to the Shieldcn studio and make one for this project.

The agent already had the context - it produced the cover image, the badges, the description, all of it. I didn't think about it once.

The detail nobody else got right

The badges work in light and dark mode on GitHub.

That sounds small. Go open your own README in dark mode and count how many badges are sitting in a little white box.

One thing to actually do this week

Open the repo you link to most. Look at the README the way a stranger would, for five seconds.

Does it say what the project does? Does it show what it looks like? Does it tell you how to install it?

If it misses any of those, fix it this week. It's an hour of work that changes how many people ever try the thing you built.

And go star it

Shieldcn is sitting at just over 800 stars. For what it does, that's too low. It's free, it's open source, and someone maintains it so you don't have to.