readme-seo

name	readme-seo
description	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.

Execution Flow

Step 1: Project Intelligence Gathering

Read the following files (skip if absent):

• README.md / README / readme.md
• package.json / pyproject.toml / Cargo.toml / go.mod / pom.xml / setup.py
• LICENSE
• CONTRIBUTING.md
• .github/ISSUE_TEMPLATE/ directory
• .github/profile/README.md (Org Profile)
• Root directory file listing (to infer tech stack)

Run simultaneously:

git remote get-url origin 2>/dev/null
git log --oneline -20 2>/dev/null
git tag --sort=-creatordate | head -5 2>/dev/null
ls -la 2>/dev/null

Step 2: SEO Audit (10 Dimensions, 0-10 each)

Score each dimension and output a diagnostic table:

Dimension	What to Check	Scoring
Repo Name	Contains keywords, searchable, brand-consistent	Category keyword=8+, known brand coinage=7, meaningless abbreviation=3
Description	Exists, char count, core keyword placement	Keyword-first + <120 chars=9, exists but generic=5, missing=0
Topics/Tags	Count, coverage across 6 categories	15-20 covering all 6=10, 5-10=5, <5=2
Social Preview	Custom preview image (infer from banner in README)	High-quality banner=8, basic=4, none=0
README Above-the-fold	Logo → Value prop → Quick Start → Badges	All 4 present=10, -2 per missing element
README Structure	Features, deployment, docs, community, license	Complete=10, -2 per missing core section
i18n	Multilingual README files exist?	3+ languages=10, en+zh=8, en-only=4, zh-only=3
Badges	Count and type match project stage	Stage-appropriate=8, over/under-badged=4
GEO Readiness	Definitional first paragraph, llms.txt, structured data	Definitional opener + clean structure=8, generic=4
Activity Signals	Last commit, release cadence, issue response time	Weekly=9, monthly=6, 3+ months stale=2

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"

3.2 Topics/Tags (15-20)

Output organized by 6 categories:

Brand:      [project-name]
Competitor: [competitor]-alternative, [competitor]
Tech Stack: [language], [framework], [database], [runtime]
Category:   [function-category], [industry-category]
Scenario:   self-hosted, open-source, developer-tools, ai-powered
Ecosystem:  [upstream]-plugin, [platform]-extension, [framework]-component

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
• Growth (1k-10k): + npm Downloads / Docker Pulls / PyPI version
• Mature (10k+): + Stars count + Contributors + Product Hunt badge

3.5 Package Metadata Optimization

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:

<div align="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