[geo-optimizer] GEO Audit Report — 2026-05-21

[github-actions[bot]]

GEO Audit Report — github/gh-aw

Audit Date: 2026-05-21 17:17 UTC
Run: §26241557044
Audited Targets: Documentation site + README + 20 sitemap pages

---

📊 Overall Scores

Target	Score	Band	Status
Documentation Site (github.github.com/gh-aw/)	42/100	Foundation	🟡 Needs Improvement
GitHub README (github.com/github/gh-aw)	55/100	Foundation	🟡 Needs Improvement
Sitemap Average (20 pages)	33-42/100	Critical-Foundation	🔴 Poor Visibility

Summary: Both primary targets score in the "Foundation" band (40-59), indicating basic AI discoverability but significant optimization opportunities. The project is currently missing critical AI-specific signals that would improve citation rates across major AI engines (ChatGPT, Claude, Perplexity, Gemini).

---

✅ Top Strengths

Documentation Site

• ✅ Meta tags complete (14/14) — Title, description, canonical, OpenGraph fully configured
• ✅ JSON-LD schema present (12/16) — WebSite, Organization, SoftwareApplication, FAQPage schemas implemented
• ✅ RSS feed configured — Blog feed at /blog/rss.xml for content freshness signals
• ✅ Content freshness maintained — Last update: 2026-05-09
• ✅ Strong content foundation — 990 words, proper heading hierarchy, 11 external links

GitHub README

• ✅ Excellent robots.txt (15/18) — All major AI bots explicitly allowed (GPTBot, ClaudeBot, PerplexityBot, etc.)
• ✅ llms.txt implemented (14/18) — 2,905 words, 12 sections, 117 links with proper structure
• ✅ Rich content (12/12) — 3,131 words, 43 headings, 494 numbers, lists/tables, front-loaded key info
• ✅ Complete meta tags (11/14) — Good title, description, OpenGraph coverage

---

🚨 Critical Gaps (High Impact)

1. Missing AI Discovery Endpoints (0/6 for both targets)

Neither the docs site nor README have the modern AI discovery infrastructure:

• ❌ No /.well-known/ai.txt — AI crawler permission manifest
• ❌ No /ai/summary.json — Structured site summary for AI engines
• ❌ No /ai/faq.json — FAQ data in AI-consumable format
• ❌ No /ai/service.json — Service capability descriptions

Impact: AI engines lack structured metadata to properly index and cite the project.

2. Documentation Site: Missing robots.txt (0/18)

The docs site has no robots.txt file, missing explicit Allow directives for citation bots.

Impact: AI crawlers may default to conservative crawling or skip the site entirely.

3. Documentation Site: No llms.txt (0/18)

While the README has an excellent llms.txt, the docs site lacks this organizational signal.

Impact: AI systems can't efficiently discover key documentation pages or understand site structure.

4. README: Missing JSON-LD Schema (0/16)

The GitHub README lacks structured data markup (Organization, WebSite, FAQPage schemas).

Impact: Reduced Knowledge Graph integration and entity disambiguation.

5. Hidden Text Detected (Both Targets)

Both sites have display:none or visibility:hidden content that AI crawlers can read.

Impact: Potential cloaking penalties from AI engines, reduced trust signals.

6. Weak Knowledge Graph Signals

• Docs site: Only 2/4 KG pillars (LinkedIn, Wikidata) — missing Wikipedia, Crunchbase
• README: 0/4 KG pillars — no sameAs links in Organization schema

Impact: Poor entity disambiguation, lower authority signals for AI citation.

7. Keyword Density Issues

• Docs site: github at 2.6% density (keyword stuffing)
• README: issue at 22.9% density (severe keyword stuffing)

Impact: AI engines may penalize over-optimization, reduce ranking.

---

🔧 Recommended Fixes (Prioritized by Impact)

Phase 1: Quick Wins (High Impact, Low Effort)

1. Create robots.txt for docs site — Add explicit Allow rules:

   User-agent: GPTBot
   Allow: /
   
   User-agent: ClaudeBot
   Allow: /
   
   User-agent: PerplexityBot
   Allow: /
   

   Estimated impact: +10-15 points

2. Fix hidden text cloaking — Remove or make visible:

   • Review all display:none and visibility:hidden elements
   • Convert screen-reader-only text to proper sr-only patterns
     Estimated impact: +5-8 points (trust signal)

3. Add canonical link to README — Include:

   <link rel="canonical" href="https://github.com/github/gh-aw">

   Estimated impact: +3 points

4. Diversify keyword usage:

   • Docs site: Replace some "github" instances with synonyms ("platform", "service", "repository host")
   • README: Reduce "issue" repetition (use "problem", "bug report", "ticket")
     Estimated impact: +4-6 points

Phase 2: AI Discovery Infrastructure (Medium Effort, High Impact)

5. Create /.well-known/ai.txt for both targets:

   # AI Crawler Permissions
   allow: /
   

   Estimated impact: +2 points per target

6. Create /ai/summary.json for docs site:

   {
     "name": "GitHub Agentic Workflows",
     "description": "Write repository automation workflows in natural language using markdown files and run them as GitHub Actions.",
     "url": "https://github.github.com/gh-aw/",
     "category": "Developer Tools"
   }

   Estimated impact: +2 points

7. Create /ai/faq.json — Extract existing FAQ content into structured format
   Estimated impact: +2 points

8. Create /ai/service.json — Describe service capabilities:

   {
     "name": "gh-aw",
     "type": "GitHub CLI Extension",
     "capabilities": ["workflow compilation", "agentic automation", "AI integration"]
   }

   Estimated impact: +2 points

Phase 3: Schema & Entity Enhancements (Medium Effort, Medium Impact)

9. Add JSON-LD schemas to README (via GitHub profile or org page):

   • Organization schema with sameAs links
   • WebSite schema
   • FAQPage schema (if GitHub supports custom schemas)
     Note: GitHub README may have limited schema support
     Estimated impact: +8-12 points

10. Expand Knowledge Graph pillars:

    • Add Wikipedia link to docs site Organization schema
    • Add Crunchbase link if available
    • Add sameAs links to README (via org profile)
      Estimated impact: +4-6 points

11. Add contact info to Organization schema:

    • Include address, telephone, or contactPoint
      Estimated impact: +2-3 points

Phase 4: Content Optimization (Low Effort, Medium Impact)

12. Add numerical data to docs site — Include:

    • Statistics ("50+ workflows", "10x faster automation")
    • Metrics ("95% test coverage", "<100ms compilation")
      Estimated impact: +5 points (+40% AI visibility per recommendation)

13. Front-load key information — Ensure critical details appear in first 30% of content
    Estimated impact: +3-4 points

14. Add visible /about link to docs site navigation
    Estimated impact: +2 points (trust signal)

15. Create llms.txt for docs site:

    geo llms --base-url https://github.github.com/gh-aw

    Estimated impact: +12-16 points

Phase 5: Advanced Enhancements (Optional)

16. Add WebMCP attributes — For Chrome AI agent support:

    <button toolname="compile-workflow" tooldescription="Compile markdown to GitHub Action">

    Estimated impact: Future-proofing (no immediate score impact)

17. Add form accessibility — Descriptive labels for AI agent interaction
    Estimated impact: +2-3 points (accessibility + AI agent support)

---

📋 Full Breakdown by Category

Documentation Site (github.github.com/gh-aw/)

Category	Score	Status	Notes
AI Discovery	0/6	❌ Failed	No .well-known/ai.txt, no /ai/* endpoints
Brand & Entity	6/10	✅ Passed	2/4 KG pillars, no /about link, has contact info
Content	7/12	✅ Passed	No numbers, no front-loading, no lists/tables
llms.txt	0/18	❌ Failed	File not found
Meta Tags	14/14	✅ Passed	All essential tags present
robots.txt	0/18	❌ Failed	File not found
Schema JSON-LD	12/16	✅ Passed	Has WebSite, Org, Software, FAQ schemas
Signals	6/6	✅ Passed	Has RSS, lang=en, freshness signals

Total: 45/100 points across 8 categories (reported as 42/100 in summary)

---

GitHub README (github.com/github/gh-aw)

Category	Score	Status	Notes
AI Discovery	0/6	❌ Failed	No .well-known/ai.txt, no /ai/* endpoints
Brand & Entity	3/10	✅ Passed	0/4 KG pillars, has /about link, no contact info
Content	12/12	✅ Passed	Excellent: numbers, links, tables, front-loading
llms.txt	14/18	✅ Passed	Strong: 2,905 words, 12 sections, 117 links
Meta Tags	11/14	✅ Passed	Missing canonical link
robots.txt	15/18	✅ Passed	All citation bots allowed
Schema JSON-LD	0/16	❌ Failed	No structured data schemas
Signals	3/6	✅ Passed	Has lang, no RSS, no freshness date

Total: 58/100 points across 8 categories (reported as 55/100 in summary)

📄 Sitemap Page Scores (Top 5 of 20)

Rank	URL	Score	Notes
1	github.github.com/gh-aw	42/100	Homepage (same as main audit)
2	.../blog/2026-01-13-meet-the-workflows-continuous-improvement	33/100	Blog post
3	.../blog/6	33/100	Blog page 6
4	.../blog/2	33/100	Blog page 2
5	.../blog	33/100	Blog index

Findings:

• Homepage scores highest (42/100) but still in Foundation band
• Blog pages uniformly score 33/100 (Critical band)
• Likely share same structural issues: missing AI discovery endpoints, no robots.txt
• Lower scores suggest blog posts need individual optimization

Recommendation: Focus on homepage/main docs first, then apply learnings to blog template.

---

🎯 Success Metrics

Target Score After Phase 1-2: 70-75/100 ("Good" band)
Target Score After Phase 3: 80-85/100 ("Excellent" band)
Timeline: 2-4 weeks for Phases 1-3

Key Performance Indicators:

• AI citation rate in ChatGPT/Claude/Perplexity (track manually)
• Crawler activity from GPTBot, ClaudeBot, PerplexityBot (check server logs)
• Knowledge Graph appearance in search results
• Structured data validation in Google Search Console

---

📚 Resources

• GEO Optimizer Tool: geo-optimizer-skill
• llms.txt Spec: [llmstxt.org]((llmstxt.org/redacted)
• AI Discovery Standards: /.well-known/ai.txt, /ai/*.json (emerging standards)
• Schema.org Documentation: [schema.org]((schema.org/redacted)

---

Automated audit powered by geo-optimizer-skill · Run §26241557044

Generated by 🌍 GEO Optimizer Daily Audit · ● 1M · ◷

• expires on May 24, 2026, 5:23 PM UTC

[github-actions[bot]]

This discussion has been marked as outdated by GEO Optimizer Daily Audit.

A newer discussion is available at Discussion #34482.