Do you know how to add a README.md to your GitHub Profile?
Loading last updated info...
Your repos should have an awesome README, but what about you?
Your GitHub profile is often the first thing a recruiter, a client, or a potential collaborator sees. By default it's a wall of repository names and a contribution graph, which says nothing about who you are or what you're good at.
GitHub has a hidden feature that fixes this: a profile README, which is a README.md that renders at the top of your profile page.
How it works
The magic is a special repository named exactly the same as your GitHub username. When GitHub finds a public repo with that name containing a README.md, it renders it on your profile.
E.g. If your username is johnsmith, create a repo called johnsmith containing a README.md.
Steps to create your profile README
- Go to github.com/new
- Set the Repository name to your GitHub username (GitHub will show a message confirming you've found the secret ✨)
- Set the visibility to Public, as it won't render if it's private
- Tick Add a README file
- Click Create repository
- Edit
README.mdand commit - Visit
github.com/<your-username>to see it live
✅ Figure: Good example - Name the repo after your username and GitHub confirms you've found the ✨special✨ repository
The repo name must match your username exactly. A repo called About-Me, or one with a stray trailing character, will not render on your profile. It just sits there as an ordinary repository.
If your README isn't showing up, check the repo name first, then check it's public.
GitHub also supports an organization profile README. Create a public repo called .github in your org, and add profile/README.md to it.
What to include
Keep it short and scannable. This is a landing page, not a resume.
- Who you are: Your role, company, and the tech you work with
- What you're working on: Current projects or areas of focus
- What you're learning: Shows curiosity and invites conversation
- How to reach you: LinkedIn, blog, X, email
- Links to your best repos: Point people at your strongest work
- (Optional) Stats and badges: E.g. github-readme-stats for language and contribution cards
What not to include
- Walls of technology icons: A grid of 30 logos with no context tells a reader nothing about your actual skill level
- Empty "coming soon" placeholders: A half-finished README looks worse than none at all
- Joke content a client wouldn't appreciate: Remember that clients and recruiters read this page
- Your full employment history: Link to LinkedIn instead, and keep the profile short
❌ Figure: Bad example - The page opens straight into pinned repos. There's even an 'About Me' repo pinned, but because its name doesn't exactly match the username, GitHub never renders it on the profile
✅ Figure: Good example - Brady Stroud's profile README shows who he is, what he works on, his tech stack, and a link to his portfolio, all above the fold
Sample profile README
# Hi, I'm John Smith 👋I'm a Software Engineer at [SSW](https://www.ssw.com.au), building enterprise apps with **.NET**, **Azure**, and **Angular**.## 🔭 What I'm working on- [SSW.CleanArchitecture](https://github.com/SSWConsulting/SSW.CleanArchitecture), a .NET template for Clean Architecture- Speaking at user groups about AI-assisted development## 🌱 What I'm learning- Semantic Kernel and building agents on top of LLMs## 📫 Get in touch- [LinkedIn](https://www.linkedin.com/in/johnsmith)- [My blog](https://johnsmith.dev)
✅ Figure: Good example - Short, specific, and gives a visitor a reason to reach out
Keep it current
A profile README that says "currently learning Angular 12" is worse than no README at all, because it tells people you stopped caring.
Add a recurring reminder to review your profile README every 6 months, or automate the dynamic parts (latest blog posts, recent activity) with a GitHub Action so it updates itself.