| name | github-repo-seo |
| description | Optimizes GitHub repositories for maximum discoverability, professional presentation, and portfolio impact. Use this skill EVERY TIME you create a new repository, write a README, set up a GitHub project, prepare a portfolio project for deployment, or when the user mentions 'README', 'GitHub repo', 'push to GitHub', 'make it public', 'portfolio', 'open source', 'repo setup', 'GitHub profile', or 'publish project'. This skill covers repository naming, description optimization, topic tags, README structure, social preview images, badges, profile SEO, Google indexing, and promotion strategies. Trigger even when the user just says 'push this to GitHub' or 'set up the repo' — those are the moments where SEO matters most and is most often forgotten. |
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) or for-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
