jawwad-ali GitHub Repository SEO Skill
Why This Matters
With 200+ million repositories on GitHub, the top 1% receives the overwhelming majority of stars, forks, and traffic. The difference between a repo that gets discovered and one that dies in obscurity is NOT code quality — it's optimization. GitHub SEO is the highest-leverage, lowest-effort thing you can do for any project.
The Two Search Engines You're Optimizing For
1. GitHub's Internal Search — Developers searching directly on GitHub. Driven by repository name, About description, and Topics. Stars/forks are secondary signals.
2. Google (External Search) — Google indexes GitHub repos. README content, repo name, and description influence Google ranking. A well-optimized repo can rank on Google's first page.
The 10-Point GitHub SEO System
Complete ALL 10 points for every repository.
1. Repository Name (Highest Impact)
The single most important ranking factor for GitHub search.
Rules:
- Include the primary keyword users would search for
- Use hyphens to separate words (not underscores or camelCase)
- Keep it short: 2-5 words max
- Be specific and descriptive, not clever or generic
- Include the technology if it's a key differentiator
Examples across different project types:
❌ my-project ❌ cool-app ❌ projectX
✅ SaaS / Web Apps:
nextjs-admin-dashboard
react-kanban-board
ai-expense-tracker
stripe-subscription-starter
✅ Developer Tools:
markdown-preview-cli
git-commit-analyzer
api-rate-limiter
docker-dev-environment
✅ AI / ML:
ai-resume-analyzer
llm-chatbot-template
image-classification-api
rag-document-search
✅ Mobile:
react-native-fitness-app
flutter-weather-app
Formula: [technology]-[what-it-does] or [what-it-does]-[platform]
2. About Description (Second Highest Impact)
The "About" section in the repository sidebar (Settings → description).
Rules:
- Start with the main keyword/phrase
- Keep between 5-15 words
- Describe WHAT it does, not HOW it works
- Include the primary technology
- No emojis or filler words
Examples:
❌ "A cool project I made"
❌ "My portfolio project built with stuff"
✅ "Real-time project management dashboard built with Next.js and WebSockets"
✅ "AI-powered resume analyzer with feedback scoring using Claude API"
✅ "Full-stack e-commerce platform with Stripe payments and admin dashboard"
✅ "CLI tool for analyzing Git commit patterns and team productivity"
✅ "React Native fitness tracker with workout logging and progress charts"
Formula: [Primary keyword] [brief what-it-does] built with [key technologies]
3. Topics / Tags (Critical for GitHub Search)
GitHub uses topics as a PRIMARY search filter. You get up to 20 topics — use them all.
Rules:
- Fill ALL 20 topic slots
- First 3-5 should be exact keywords people search for
- Include: language, framework, category, use-case, and industry
- Lowercase, hyphens for multi-word topics
- Mix broad and specific
4-tier topic strategy (adapt per project):
Tier 1 — Primary keywords (what people search):
[main category], [product type], [problem it solves]
Examples: admin-dashboard, project-management, expense-tracker
Tier 2 — Technologies used:
[language], [framework], [database], [key-libraries]
Examples: nextjs, react, typescript, tailwindcss, prisma, postgresql
Tier 3 — Features/capabilities:
[standout features], [patterns used]
Examples: real-time, ai-powered, drag-and-drop, authentication, stripe
Tier 4 — Industry/broader category:
[domain], [audience], [related terms]
Examples: saas, developer-tools, open-source, fullstack, portfolio
4. README.md (The Landing Page)
The README determines whether visitors star, fork, or leave. For Google, README content is indexed.
Structure for any project (in this exact order):
1. Hero section (banner image or logo + title)
2. One-line description with primary keyword
3. Badges row (tech stack + status badges)
4. About section (2-3 sentences)
5. Key Features (5-7 bullets)
6. Tech Stack (table or badge grid)
7. Screenshots (3-5 images/GIFs)
8. Getting Started (prerequisites, install, run)
9. Architecture overview (optional)
10. Live Demo link (CRITICAL for portfolio projects)
11. License
12. Contact / links
Read references/readme-details.md for complete templates, badge code, screenshot guidelines, and examples for different project types.
5. Social Preview Image (Open Graph)
When your repo link is shared on Twitter/X, LinkedIn, Slack, Discord — this image is what people see.
How to set: Repository Settings → Social preview → Upload image
Specs:
- Recommended: 1280 × 640px (2:1 ratio)
- Minimum: 640 × 320px
- Format: PNG, JPG, or GIF (under 1 MB)
- PNG with transparency supported
What to include:
- Project name (large, readable text)
- One-line description
- Screenshot/mockup of the app
- Tech stack icons
- Clean, branded design
Tools: Figma (free), Canva, og-image.vercel.app, bannerbear.com
Why: Posts with images receive 150%+ more engagement on social media.
6. Shields.io Badges
Badges provide instant visual info about your project. They signal professionalism.
Essential badges for any project:
<!-- Status -->
<!-- Tech (pick what applies) -->
<!-- Dynamic (auto-update) -->
Rules:
- Pick ONE style:
flat-square(modern) orfor-the-badge(bold). Never mix. - 8-12 badges max total
- Status badges first, then tech badges
- Get brand colors from simpleicons.org
7. GitHub Profile Optimization
Your profile is seen alongside every repo. Optimize it.
Profile README (create repo: username/username):
- Brief bio + tech stack badges + pinned project links + contact
- Keep it to one screenful — no walls of text
Pinned repos:
- Pin 3-6 best projects (best one first — people scan left to right)
- Every pinned repo needs description + topics set
Profile settings:
- Professional photo
- Bio with role + technologies + what you build
- Location, website link, social links filled in
8. Commit History & Activity
Active repos signal quality to both algorithms and humans.
Rules:
- Commit regularly (not one massive initial commit)
- Use conventional commits:
feat:,fix:,docs:,style:,refactor: - Never commit secrets, .env, node_modules
- A green contribution graph signals active development
9. Repository Hygiene
Must-have files:
README.md — Landing page
LICENSE — MIT recommended for portfolio
.gitignore — Configured for your stack
.env.example — Template listing all required env vars
Nice-to-have:
CONTRIBUTING.md — Collaboration guidelines
CHANGELOG.md — Version history
CODE_OF_CONDUCT.md — Professional practice
Settings to configure:
- Description + topics + website URL filled
- Social preview uploaded
- Disable unused sidebar items (Releases, Packages, Deployments if not used)
10. Promotion & Distribution
Where to share:
- Reddit: r/webdev, r/reactjs, r/nextjs, r/sideproject, r/programming, r/python
- X/Twitter: #buildinpublic, #webdev, #opensource + tag relevant accounts
- Dev.to / Hashnode: "How I Built X" article linking to the repo
- Hacker News: "Show HN" for interesting projects
- LinkedIn: Post with screenshots + live demo link
- Discord: Relevant tech community servers
Post formula:
- Lead with the PROBLEM it solves
- Include screenshot or GIF
- Link to live demo AND GitHub repo
- Ask a question to encourage engagement
Encouraging stars:
- Subtle CTA in README: "If you found this useful, consider giving it a ⭐"
- Star prompt on live demo site (top banner or footer)
Pre-Push Checklist
REPOSITORY SETTINGS
□ Name is keyword-rich and hyphen-separated
□ Description is 5-15 words, starts with primary keyword
□ Topics: all 20 slots filled
□ Website URL points to live demo
□ Social preview image uploaded (1280×640px)
□ Unused sidebar items unchecked
□ License set (MIT recommended)
README.md
□ Hero screenshot/banner at the top
□ One-line description with primary keyword
□ Shields.io badges (consistent style)
□ About section (2-3 sentences)
□ Key Features (5-7 bullets)
□ Tech Stack section
□ Screenshots (3-5 images/GIFs)
□ Getting Started with tested, copy-paste commands
□ Live Demo link prominently placed
□ All links work (no broken links)
□ No empty sections or placeholder text
REPOSITORY HYGIENE
□ .gitignore configured properly
□ .env.example lists all required variables
□ LICENSE file present
□ No secrets in commit history
□ Meaningful commit messages
PROFILE
□ Pinned repositories updated
□ Profile README current
□ Bio includes relevant keywords
README Templates & Badge Code
See references/readme-details.md for:
- Complete README templates for different project types (SaaS, API, CLI, mobile)
- Full badge snippet library (30+ technologies)
- Screenshot formatting and sizing
- Getting Started section that actually works
- Profile README template
- SEO keyword placement strategy