Repo READMEs that make a recruiter open the link

Status: Outline — full guide coming soon. Get notified when it ships →

What this covers

• The opening hook formula: 1 line that explains what the project does, in product terms
• Where the screenshot/GIF goes (and why it goes there)
• The 6-section structure: hook, demo, why, how it works, run locally, what's next
• Why your stack badges and shields.io row are hurting conversions

Why this matters for Indian devs going remote

Recruiters and hiring managers don't read code — they read READMEs. A well-structured README turns a repo into a portfolio piece; a default npx create-next-app README turns the same repo into noise. This is one of the highest-leverage edits an Indian dev can make to existing work.

Outline

The 1-line opening hook

TODO — formula: "X is a Y that does Z for W users." Three examples.

Where the screenshot goes

TODO — hero shot or 5-second GIF immediately after the hook line; alt-text rules.

The 6 sections

TODO — hook / demo / why / how it works (architecture) / run locally / what's next. What each section actually contains.

Why stack badges hurt

TODO — they push the actual content below the fold and signal "tutorial follow-along".

Common mistakes to avoid

• Defaulting to the framework's auto-generated README
• Burying the demo screenshot at the bottom
• Writing "this is a project I made for X bootcamp"

Templates / examples

TODO — a copy-paste 6-section template, 3 before/after README rewrites, and a screenshot-capture checklist.

Related guides

• Portfolio projects: building one strong proof-point repo
• Your GitHub profile README: what recruiters actually see

---

Have a question about this? DM me on LinkedIn or drop your email to get the full guide as soon as it's published.