Chapter 2 of 7 · 4 checks · 3 min

Profile README

A profile README is the free-form section at the top of your profile. Make sure it actually appears, then keep it short and specific.

Show

Create a public repository named exactly like your username with a README.mdMust
Why it matters and how to check
GitHub shows a profile README only when the repository name matches your username, the repository is public, it has a README.md in its root, and that file has content. If you created the repository before July 2020, GitHub's docs say it is not shown automatically: use Share to profile in the repository.
The README disappears if you empty or delete the file, make the repository private, or rename either the repository or your account so they no longer match.
Check it: open your profile while signed out and confirm the README renders at the top.
Do
Name the repository exactly as your username
Keep it public
Avoid
Putting the README in a subfolder, where it will not show
Say who you are, what you work on and where to see your best workShould
Why it matters and how to check
A good profile README answers three questions in a few lines: what you do, what you are working on or learning now, and which projects best show your skills. Add how to reach you and, if relevant, what kind of work or collaboration you are open to.
Link to two or three projects with one line each on the problem they solve. Visitors skim, so short sections with clear headings beat long paragraphs.
Check it: a visitor can find your best project from the README in one click, and the whole README fits on about one screen.
Do
Link your strongest two or three projects with one line each
Say what you are working on now
Avoid
A long autobiography
Copying a template without changing it
Keep badges, widgets and animations to a minimumNice to have
Why it matters and how to check
Profile READMEs often fill up with generated stats cards, streak counters, dozens of technology badges and animated banners. They slow the page down, break when third-party services go offline, and push your actual projects below the fold.
A short list of technologies in plain text says the same thing as forty logos. Stats cards mostly repeat what your contribution graph already shows.
Check it: every image in your README loads, and removing any one of them would lose real information.
Do
List your stack in plain text
Test that every image and widget still loads
Avoid
Rows of logos for tools you used once
Widgets that depend on a service you do not control
Update the profile README when your focus or projects changeShould
Why it matters and how to check
A README that says you are learning a language you dropped two years ago, or features projects you have since archived, makes the whole profile feel abandoned.
Put a reminder in your calendar every few months, or whenever you finish a significant project, to reread it and update the current focus and featured projects.
Check it: every statement in the README is still true today, and every linked project is still public.
Do
Review it whenever you finish a major project
Avoid
"Currently learning" lines that are years out of date