A profile README is a special repository named exactly like your GitHub username (for example octocat/octocat). Its README.md appears at the top of your profile page, above your pinned repositories. It is the first thing recruiters, collaborators and curious visitors see, so it is worth a few minutes of effort.
To create one, make a new public repository with the same name as your username and tick "Add a README file". Then edit the README like any markdown file.
What to include
1. A one-line introduction
Say who you are and what you work on, in plain words. Skip the waving-hand GIF and get to the point:
# Hi, I'm Priya
Backend engineer building payment systems in Go. Currently learning Rust.2. What you are working on now
A short "Currently" list tells visitors what you care about and gives them something to click. Link to the actual repositories.
**Currently**
- Building [ledgerkit](https://github.com/you/ledgerkit), a double-entry accounting library
- Contributing to [Temporal](https://github.com/temporalio/temporal)3. Your tech stack, briefly
List the technologies you actually use, grouped if the list is long. Plain text is easier to read (and to search) than a wall of 40 logo badges.
4. Your best work, with context
Pinned repositories show names and descriptions; your README can explain why each project matters: the problem, the result, the numbers. "Cut CI time from 14 to 4 minutes for 200 engineers" says more than a repository name.
5. Writing and talks
If you blog, speak or make videos, link the two or three best pieces. It shows you can explain your work, which matters as much as writing it.
6. How to reach you
Add one or two links: your website, LinkedIn, Mastodon or email. If you are open to work or to collaboration, say so explicitly.
7. A stats or score badge
Badges that update automatically keep your README current without effort. For example, your GitScore badge shows your score and grade and links to the full breakdown. Look up your profile on GitScore and use "Copy markdown" in the README section, which gives you something like:
[](https://gitscore.live/your-username)8. Something personal (optional)
One line about a hobby or side interest makes the profile feel human and is a common conversation starter. Keep it to one line.
9. Contribution guidelines for your projects
If you maintain open-source projects, point people to where help is most needed: issues labelled good first issue, a discussions board, or a roadmap.
10. A short, scannable layout
Use headings, short lists and blank lines. Most visitors skim. A README that fits on one screen is read; one that needs five screens is scrolled past.
What to skip
- Huge walls of badges and logos. They are slow to load and hard to read on mobile.
- Visitor counters and auto-generated snake animations. Fun once, noise afterwards.
- Long autobiographies. Link to your website instead.
- Out-of-date content. "Currently learning Angular 2" tells visitors the profile is abandoned. Update it every few months, or use auto-updating badges.
A complete example
# Hi, I'm Priya 👋
Backend engineer building payment systems in Go. Open to staff-level roles.
**Currently**
- Building [ledgerkit](https://github.com/you/ledgerkit): double-entry accounting for Go
- Contributing to [Temporal](https://github.com/temporalio/temporal)
**Stack:** Go · PostgreSQL · Kafka · Kubernetes · TypeScript
**Writing:** [How we made idempotency keys boring](https://example.com/idempotency)
[](https://gitscore.live/you)
📫 [priya.dev](https://priya.dev) · [LinkedIn](https://linkedin.com/in/you)Want to see how your profile measures up? Compare it with a friend's or browse popular developer scores for inspiration.