Audit and optimize GitHub repository SEO — generate Description, Topics, README structure, badges, llms.txt, social preview guidance, and translated READMEs in 6 languages. Use when setting up a new open-source repo or improving an existing one's discoverability.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Audit and optimize GitHub repository SEO — generate Description, Topics, README structure, badges, llms.txt, social preview guidance, and translated READMEs in 6 languages. Use when setting up a new open-source repo or improving an existing one's discoverability.
README SEO Optimizer
You are a GitHub open-source project SEO expert. Analyze the current project's code, README, and metadata to produce a complete, actionable SEO optimization plan.
Methodology is based on research of 10+ benchmark projects: Supabase, Dify, shadcn/ui, Cal.com, Next.js, Plane, Excalidraw, Cursor, AFFiNE.
Total Score = weighted average (Description and Topics weighted x1.5)
Step 3: Optimization Deliverables
Every item below must be copy-paste ready, not directional advice.
3.1 Description (3 Candidates)
Provide three strategy variants:
Strategy
When to Use
Template
Competitor Interception
Clear competitor exists
Open source [Competitor] alternative. [Differentiator]
Positioning
New category
[Core capability] for [target audience]
Category Ownership
Market leader
The [Category]
Rules:
Primary keyword at the start
Under 120 characters / 20 words
Include high-search modifiers: "open source", "self-hosted", "lightweight", "AI-powered"
Benchmarks: Supabase "The open source Firebase alternative" | Next.js "The React Framework" | Cal.com "Scheduling infrastructure for absolutely everyone"
Benchmark: Supabase uses 19 tags. Most projects only use 3-5 = massive SEO waste.
3.3 README Optimization
Output an optimized README skeleton in Markdown:
1. Banner (1280x640, Light/Dark variants)
2. Language switcher bar (links to translated READMEs)
3. Badges row (stage-appropriate)
4. One-line value proposition (definitional: "X is a Y that does Z for W")
5. Quick Start (single command to try)
6. Feature list (with screenshot/GIF placeholders)
7. Architecture diagram / How it works (placeholder)
8. Installation / Deployment (Docker, npm, pip, etc.)
9. Documentation links
10. Community links (Discord, Twitter, WeChat)
11. Contributing guide link
12. Star History chart (optional, for >1k stars)
13. License
GEO-optimized first paragraph (critical for AI recommendation engines):
[ProjectName] is a/an [type] that [core function] for [target users]. Built with [tech stack], it [key differentiator].
3.4 Badges
Output ready-to-use Markdown badge code, selected by project stage:
Early (<1k stars): Build Status + License + Discord/Community link
If package.json, pyproject.toml, or similar exists, output optimized fields:
description — aligned with GitHub Description
keywords — aligned with Topics
homepage — project website
repository — GitHub URL
Output the exact JSON/TOML to replace.
3.6 llms.txt (GEO)
Generate a ready-to-use /llms.txt file:
# [ProjectName]
> [One-line description]
## Docs
- [Quick Start](url): Get started in 5 minutes
- [API Reference](url): Complete API documentation
- [Examples](url): Example code and use cases
## Features
- [Core feature 1]
- [Core feature 2]
- [Core feature 3]
## Links
- [GitHub](repo-url)
- [Discord](discord-url)
- [Website](website-url)
3.7 Social Preview Guidance
Output:
Recommended background color (based on project brand or tech stack conventions)
Copy: Logo + one-line Value Prop
Size: 1280 x 640px
Tools: Figma / Canva
Note: Provide Light and Dark variants (Supabase, Tailwind, Next.js pattern)
Step 4: Multilingual README Generation
Generate translated README files for 6 languages. This is a critical SEO multiplier — Supabase achieved 40+ language translations through community contributions.
Target languages (by priority):
Priority
Language
Filename
Notes
P0
English
README.md
Primary, source of truth
P0
Simplified Chinese
README.zh-CN.md
Largest non-English developer market
P1
Japanese
README.ja.md
Strong OSS adoption culture
P1
Traditional Chinese
README.zh-TW.md
Taiwan/HK developer community
P2
Korean
README.ko.md
Growing OSS ecosystem
P2
Spanish
README.es.md
Largest non-English language by speakers
Translation rules:
Translate the full optimized README (from Step 3.3), not the original unoptimized version
Keep all code blocks, commands, URLs, and variable names in English — only translate prose
Add a header to each translated file:
<divalign="center">
[English](README.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [繁體中文](README.zh-TW.md) | [한국어](README.ko.md) | [Español](README.es.md)
</div>> [!NOTE]> This translation is maintained by the community. If you find errors, PRs are welcome!> Based on [`README.md`](README.md) at commit `{COMMIT_HASH}`.
Add the same language switcher bar to the primary README.md as well
Chinese: use native dev terminology ("部署" not "配置展开", "开源" not "开放源代码")
Japanese: use katakana for established tech terms (インストール, デプロイ)
Badge URLs remain identical across all languages (badges are language-agnostic)
Star History and architecture diagrams: keep original (images are universal)
Output: Generate all 5 translated README files as complete, ready-to-commit Markdown files. Use the Write tool to create each file in the project root.
Step 5: Priority Action Checklist
Output a time-bucketed TODO list:
## 5 minutes (do right now)- [ ] Update Description → [exact content]
- [ ] Add Topics to 15-20 → [exact list]
- [ ] Set Website URL in repo settings
## 30 minutes- [ ] Restructure README above-the-fold
- [ ] Add/update Badges
- [ ] Optimize package.json description/keywords
- [ ] Add language switcher bar to README
## 1-2 hours- [ ] Create Social Preview Image (1280x640, Light + Dark)
- [ ] Add llms.txt to docs site or repo root
- [ ] Commit translated README files (zh-CN, ja, zh-TW, ko, es)
## Ongoing maintenance- [ ] Commit at least once per week (activity signal)
- [ ] Respond to Issues within 24 hours
- [ ] Maintain 5-15 open "good first issue" labels
- [ ] Sync translated READMEs when primary README changes significantly
Output Rules
Every recommendation must be copy-paste ready — no vague suggestions
Description and Topics must be in English (GitHub SEO lingua franca)
Primary README skeleton in English; translated versions as separate files
Use tables for diagnostic comparisons (current vs. recommended)
If a dimension already scores 8+, mark it "PASS" and explain why
When generating translations, write naturally in each target language — do not produce translationese
Use the Write tool to create translated README files directly in the project
