Github Seo

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:

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:

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), primarykeyword (keyword, volume, difficulty, category, intent), secondarykeywords array, skipkeywords array, recommendeddescription, recommendedtopics, paaquestions, aivisibility, serpverified flag, githubinserp flag, githubserpposition. 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
• Source: avalonreset/legends-github
• License: MIT

Install and usage instructions live in the source repository linked above.