How to write a GitHub profile README that is actually worth reading

Create a repository with the same name as your GitHub username, add a README.md, and GitHub renders it at the top of your profile page. That is the entire mechanism. It has been available since 2020 and it is still one of the most underused pieces of real estate in a developer’s public presence.

It is also, more often than not, wasted. The typical profile README is a wall of badges, an animated banner, a trophy case and a visitor counter - and nothing that tells you what the person actually does.

The ten-second test

Assume the person reading your profile is a recruiter, a hiring manager, or a maintainer deciding whether to take your pull request seriously. They will give it roughly ten seconds before scrolling to your repositories.

In that time they want three things:

1. What you do, specifically.
2. What you have built that is worth looking at.
3. How to reach you.

Everything else is decoration. Decoration is fine, but not before those three things are answered. Whether that reviewer actually opens profile links, and at which stage of hiring it tends to happen, is its own question - covered in more detail in do recruiters actually check your GitHub.

Start with one concrete sentence

The opening line does most of the work. Compare a common opener:

👋 Hi, I’m Sam! Passionate developer who loves coding and learning new things!

with:

Backend engineer working on payments infrastructure in Go. Currently building a job queue that runs inside PostgreSQL.

The second tells you the domain, the language, and the current focus. It gives a reader an immediate reason to look at a specific repository. “Passionate about technology” describes essentially every person on the platform and therefore distinguishes no one.

Be specific about the boring details: the language you actually write, the industry you work in, the problem you are currently stuck on.

Point at three or four things, not everything

Your repository list is already on the page, sorted by whatever GitHub decides. The README is your chance to override that with editorial judgement.

Pick three or four projects and write one line each explaining what the thing does and why it exists:

### Things I've built

- **pgqueue** - a durable job queue that runs entirely inside PostgreSQL, so
  small teams do not have to run Redis just for background work.
- **svg-charts** - server-rendered chart primitives with no client-side
  JavaScript. Built after one too many dashboards shipped 300 KB to draw a bar.
- **dotfiles** - my Neovim, zsh and tmux setup, documented well enough that I
  can rebuild a machine in twenty minutes.

Notice what those lines do: each one contains a reason. “A job queue” is a category. “A job queue so small teams do not have to run Redis” is a point of view, and a point of view is what makes someone click.

Pinned repositories do the same job, better

GitHub lets you pin up to six repositories. Use all six, and choose them deliberately rather than letting star counts decide.

A good pinned set usually mixes:

• your most substantial project,
• something small and finished,
• something that demonstrates a language or domain you want to be hired for,
• and, if relevant, a contribution to a well-known project.

Pinned repositories appear above the fold on every profile and require no maintenance. They are the highest-leverage thing on this list.

On badges, stats cards and trophies

There is a large ecosystem of generated images for profile READMEs: language breakdowns, streak counters, trophy cabinets, animated snakes that eat your contribution graph.

A couple of honest observations.

They are fun, and there is nothing wrong with fun. But they are also generated from data that is already visible one scroll down, they add several external image requests to your profile load, and they occasionally break when the service hosting them goes down or hits its rate limit. A profile that is entirely generated widgets reads as though the person had nothing specific to say.

If you use them, use one or two, below your written introduction rather than above it.

What to leave out

• Visitor counters. Nobody has ever been impressed by one.
• Long skill matrices with progress bars. Self-assessed percentages are not information. A reader cannot tell your 80% Python from someone else’s 60%.
• Every technology you have ever opened. A list of forty tools signals indiscriminate collecting. A list of eight signals judgement.
• Contact details you do not check. An email you never read is worse than no email.

Keep it current, or keep it timeless

The main failure mode of a good README is decay. “Currently building X” is excellent in March and embarrassing in December when X shipped a year ago.

Either write it in a way that ages well, or put a date on the current-focus section so a reader can calibrate. A line like “Currently (2026) working on…” costs nothing and prevents the impression that you abandoned the profile.

A workable skeleton

# Sam Rivera

Backend engineer working on payments infrastructure in Go.
Currently building a job queue that runs inside PostgreSQL.

### Things I've built
- **pgqueue** - durable job queue inside PostgreSQL, so small teams skip Redis.
- **svg-charts** - server-rendered charts with zero client JavaScript.
- **dotfiles** - reproducible Neovim, zsh and tmux setup.

### Currently
Reading about write-ahead logs. Slowly learning Rust.

### Elsewhere
[Website](https://example.com) · [LinkedIn](https://linkedin.com/in/example) ·
sam@example.com

That is short enough to read in ten seconds and specific enough to be worth the time.

A good profile README is worth pairing with a deliberate look at which repositories you actually pin and list elsewhere, since a strong README pointing at weak or abandoned projects undercuts itself. See how to choose which GitHub projects belong on your resume for narrowing a full profile down to the ones worth featuring, and the full GitHub profile cleanup pass for everything else worth checking before you apply.

See what your profile currently says

If you want a read on what your public activity actually communicates - which languages dominate, which repositories lead on stars, how consistent your contribution history looks - you can generate a visual CV from your username and see it laid out in one place. It is often a useful corrective: the language you think of as “yours” is not always the one your repositories are written in.