# Github Seo > Keyword research and SEO content optimization for GitHub repositories — descriptions, topics, README content, plus GEO/AI citability. - **Type:** Skill - **Install:** `agentstack add skill-avalonreset-legends-github-github-seo` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [avalonreset](https://agentstack.voostack.com/s/avalonreset) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [avalonreset](https://github.com/avalonreset) - **Source:** https://github.com/avalonreset/legends-github/tree/main/skills/github-seo ## Install ```sh agentstack add skill-avalonreset-legends-github-github-seo ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # GitHub SEO -- Keyword Research and Content Optimization This is a **data-producing skill**. Its output is consumed by github-readme (for content optimization) and github-meta (for description and topic selection). It can also run standalone for SEO strategy analysis. ## Headless/API Contract For non-interactive systems, use: ```bash python3 scripts/run_headless.py seo --path /path/to/repo ``` That deterministic runner writes `.github-audit/seo-data.json` plus report artifacts under `.github-audit/output/`. It is intentionally a fallback-grade cache seeding path: no DataForSEO MCP calls, so keyword volume, difficulty, intent, AI visibility, and SERP fields are marked unverified. Interactive `github seo` runs are still the path for live DataForSEO research. ## The GitHub SEO Problem (Why This Isn't Normal SEO) GitHub repos are NOT traditional websites. You cannot: - Build backlinks to a README - Optimize page speed (GitHub controls rendering) - Add meta tags or schema markup (GitHub generates these) - Control URL structure (github.com/{owner}/{repo} is fixed) **What you CAN control:** - README content (H1, headings, paragraphs, keywords) -- this IS the SEO page - Repo description (350 chars, becomes OG description on social shares) - Topics/tags (feed GitHub Explore and internal search) - GitHub Pages site (if applicable -- full SEO control there) **What DataForSEO does here:** It answers the question "what should I write in my README, description, and topics so that people find this repo when they Google?" It does NOT scan the repo as a domain. It discovers keyword opportunities. ## The Keyword Opportunity Framework Not all keywords are worth targeting. A keyword is only valuable for GitHub if: 1. **People actually search for it** (volume > 0) 2. **GitHub repos can rank for it** (GitHub appears in SERP results) 3. **The competition is beatable** (difficulty is manageable) 4. **The intent matches** (informational = good for READMEs) ### Opportunity Categories | Category | Volume | Difficulty | GitHub in SERP? | Action | |----------|--------|------------|----------------|--------| | **Sweet Spot** | 100-5,000/mo | Under 40 | Yes, repos in top 20 | TARGET THESE FIRST -- H1, description, first paragraph | | **Worth It** | 1,000-10,000/mo | 40-60 | Yes, repos in top 20 | Target in H2 headings and body content | | **Long Shot** | 10,000+/mo | 60+ | Sometimes | Use variations; may rank over time with stars | | **Skip** | Any | Any | No GitHub repos rank | Don't waste effort -- Google doesn't serve repos for this | | **Low Value** | Under 50/mo | Any | Any | Usually not enough traffic -- but see Niche Exception below | **Niche Exception:** For ultra-niche repos where the ENTIRE addressable search space is low volume (e.g., "knife design software" at 40/mo for a parametric knife CAD tool), a breadth since you can't measure volume Mark every recommendation as "UNVERIFIED -- no DataForSEO data" in the report. ### 3. Recommend Produce a structured keyword strategy report. This is the data that downstream skills (readme, meta) consume. **With DataForSEO data:** ``` ## Keyword Strategy Report ### Data Sources - DataForSEO MCP (live data, [date]) - Codebase analysis - GitHub competitor search ### Keyword Opportunities (sorted by Opportunity Score) | Keyword | Volume/mo | Difficulty | Intent | GitHub in SERP? | Score | Category | |---------|----------|------------|--------|----------------|-------|----------| | [term] | 2,400 | 32 | Info | **Yes (#4)** VERIFIED | 1,632 | Sweet Spot | | [term] | 1,800 | 45 | Info | **Yes (#8)** VERIFIED | 990 | Worth It | | [term] | 590 | 18 | Info | Unverified (0.5) | 242 | Needs SERP check | | [term] | 8,100 | 72 | Comm | **No** VERIFIED | 0 | Skip | | [term] | 3,200 | 55 | Info | Unverified (0.5) | 880 | Needs SERP check | NOTE: "VERIFIED" = we ran a SERP check and know the answer. "Unverified" = we used 0.5 as a placeholder. Never write "likely" or "probably" -- it's data or it's unknown. ### Primary Keyword: "[term]" - Volume: X/mo | Difficulty: Y | Category: Sweet Spot - Currently in README H1: [yes/no] - Currently in description: [yes/no] - Placement: H1 tagline, first paragraph, repo description ### Secondary Keywords (for H2 headings): 1. "[term]" -- X/mo, difficulty Y → H2: "Installation"→ "[term] Installation" 2. "[term]" -- X/mo, difficulty Y → H2: "Features" 3. "[term]" -- X/mo, difficulty Y → H2: "Usage" ### Recommended Topics (for GitHub): [list of 10-20 topics derived from keyword data, formatted as lowercase-hyphenated] ### Recommended Description: "[keyword-optimized description under 350 chars with primary keyword in first 10 words]" ### AI Visibility Status: - ChatGPT mentions project: [yes/no, context] - Competitors ChatGPT mentions instead: [list] - LLM mention count: [number across platforms] - Recommendation: [what to add to README for better AI citability] ### Competitor Keywords: - [competitor repo]: ranks for [keywords] -- we should target [overlapping terms] ### FAQ Opportunities (from People Also Ask): Google confirms these questions are asked about this topic. Each is a potential README section or FAQ entry: 1. "[exact PAA question]" → Recommend: add to README as H2/H3 or FAQ 2. "[exact PAA question]" → Recommend: address in description or first paragraph [List ALL PAA questions extracted from SERP responses] ### Google-Suggested Related Keywords (from People Also Search): Free keyword ideas direct from Google's own data: - [term 1], [term 2], [term 3], ... [These supplement DataForSEO suggestions -- may reveal keywords we missed] ### Community Signals (from SERP forums/discussions): - Reddit threads ranking: [URLs and subreddits] - Hacker News discussions: [URLs] - Other forums: [URLs] - Recommendation: [whether to engage these communities for visibility] ``` **Without DataForSEO data (degraded mode):** Same structure but prefix report with a prominent warning: "⚠ DEGRADED MODE -- No DataForSEO data. All recommendations are unverified guesses. Install DataForSEO for real keyword data: extensions/dataforseo/install.ps1" Use qualitative assessments ("High relevance based on codebase analysis") but mark every row in the keyword table as "Unverified" with Score = N/A. ### 4. Execute **Write to shared data cache** after producing the keyword strategy report: ```bash mkdir -p .github-audit grep -qxF '.github-audit/' .gitignore 2>/dev/null || echo '.github-audit/' >> .gitignore ``` Write `.github-audit/seo-data.json` with: timestamp, mode (quick/full), primary_keyword (keyword, volume, difficulty, category, intent), secondary_keywords array, skip_keywords array, recommended_description, recommended_topics, paa_questions, ai_visibility, serp_verified flag, github_in_serp flag, github_serp_position. Reference: `github/references/shared-data-cache.md` for exact schema. SEO skill primarily produces recommendations -- execution happens in other skills: - github-readme applies keyword recommendations to README content - github-meta applies topic and description recommendations to GitHub settings - If running standalone, present the strategy report for the user to act on ## GEO Optimization Checklist For AI citability (ChatGPT, Perplexity, Google AI Overviews): - [ ] Clear "X is a Y that does Z" definition statement in README - [ ] Structured comparisons (tables comparing to alternatives) - [ ] Specific statistics and data points - [ ] Answer-first formatting for key questions - [ ] Well-structured heading hierarchy (H1 > H2 > H3) - [ ] SoftwareSourceCode schema on GitHub Pages (if applicable) ## Output Structured keyword strategy report that other skills can consume. Every keyword recommendation cites its data source (DataForSEO volume, GitHub search, codebase analysis, etc.). No keyword is ever recommended without justification. ### DataForSEO Cost Receipt At the END of every report, include a cost receipt showing exactly what was spent. Track each DataForSEO MCP call made during the analysis and calculate the total. ``` --- ### DataForSEO Cost Receipt | Call | Tool | Cost | |------|------|------| | Seed 1: "[seed phrase]" | keyword_suggestions | ~0.05 | | Seed 2: "[seed phrase]" | keyword_suggestions | ~0.05 | | SERP: "[checked keyword]" | serp_organic_live_advanced | ~0.10 | | **Total DataForSEO cost** | | **~0.20** | | Mode | Quick | | --- ``` Cost estimates per call type: - `keyword_suggestions`: ~0.05 per call - `serp_organic_live_advanced`: ~0.10 per call - `ranked_keywords`: ~0.05 per call - `ai_optimization_chat_gpt_scraper`: ~0.15 per call - `ai_opt_llm_ment_search`: ~0.10 per call - `bulk_keyword_difficulty`: ~0.02 per call - `search_intent`: ~0.02 per call Always show the receipt. Users deserve to know what they're spending. ### Next Step After completing SEO keyword research, always end with this handoff: ``` SEO research complete. Keywords are cached in .github-audit/seo-data.json. Next recommended step: github-meta -- optimize description, topics, and settings using your keyword data ``` If running as part of the audit SOP, reference the step number: "Step 4 complete. Next skill: `github-meta`" ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [avalonreset](https://github.com/avalonreset) - **Source:** [avalonreset/legends-github](https://github.com/avalonreset/legends-github) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-avalonreset-legends-github-github-seo - Seller: https://agentstack.voostack.com/s/avalonreset - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.