geo-audit

Category: Data & AI | Uploader: ArtSabintsev | Downloads: 0 | Version: v1.0（Latest）
GEO audit and autofix tool. Audits any website for AI search engine optimization (ChatGPT, Claude, Perplexity, Gemini, Google AI Overviews) and traditional SEO. Generates fix files automatically and recommends code-level changes for approval. Use when user says "geo", "seo", "audit", "AI search", "AI visibility", "citability", or provides a URL for analysis.
Changelog: Source: GitHub https://github.com/ArtSabintsev/geo-audit-skill
Directory Structure

Current level: Root
📁 scripts/
- 📄 brand_presence.py 13.2 KB
- 📄 citability.py 28.0 KB
- 📄 content_freshness.py 17.0 KB
- 📄 eeat.py 12.6 KB
- 📄 fetch_page.py 15.3 KB
- 📄 internal_links.py 15.9 KB
- 📄 llms_txt.py 10.5 KB
- 📄 platform_readiness.py 8.9 KB
- 📄 schema_check.py 8.7 KB
- 📄 search_intent.py 16.6 KB
- 📄 technical_seo.py 18.1 KB
📁 templates/
- 📁 schema/
  - 📄 article.json 603 B
  - 📄 local-business.json 716 B
  - 📄 organization.json 411 B
  - 📄 product.json 540 B
  - 📄 software.json 473 B
- 📄 llms.txt.j2 218 B
📄 .gitignore 40 B
📄 LICENSE 1.0 KB
📄 README.md 8.9 KB
📄 SKILL.md 21.2 KB
SKILL.md

---
name: geo-audit
description: >
  GEO audit and autofix tool. Audits any website for AI search engine optimization
  (ChatGPT, Claude, Perplexity, Gemini, Google AI Overviews) and traditional SEO.
  Generates fix files automatically and recommends code-level changes for approval.
  Use when user says "geo", "seo", "audit", "AI search", "AI visibility",
  "citability", or provides a URL for analysis.
user-invocable: true
argument-hint: <url> or quick <url>
allowed-tools: Read, Grep, Glob, Bash, WebFetch, Write, Edit, Agent
---

# GEO Audit + Autofix — Claude Code Skill

> Audit any website for AI search visibility, then fix the problems.

---

## Commands

| Command | What It Does |
|---------|-------------|
| `/geo-audit <url>` | Full audit + autofix |
| `/geo-audit quick <url>` | Findings only, no fixes |

---

## Audit Flow

### Phase 1: Discovery (Sequential)

1. **Fetch the homepage** using the `fetch_page.py` script:
   ```bash
   python3 ${CLAUDE_SKILL_DIR}/scripts/fetch_page.py <url> full
   ```
   This returns JSON with page data (including language, viewport, OG tags, meta robots, X-Robots-Tag, response time, detected platform), robots.txt, llms.txt status, and sitemap pages.

   The script auto-detects 15 platforms: WordPress, WordPress.com, Squarespace, Wix, Shopify, Webflow, Ghost, Framer, HubSpot, Carrd, Weebly, Drupal, Next.js, Vercel, Netlify. The `detected_platform` field will be `{"name": "Squarespace", "slug": "squarespace"}` or `null`.

   **When a platform is detected**, tailor all fix recommendations to that platform. For example:
   - WordPress: "Install Yoast SEO plugin, go to Yoast SEO > Tools > File Editor"
   - Squarespace: "Go to Settings > Website > SEO > robots.txt"
   - Wix: "Go to Dashboard > Marketing & SEO > SEO Tools > robots.txt Editor"
   - Shopify: "Go to Online Store > Themes > Edit Code > robots.txt.liquid"

2. **Detect business type** from the fetched data:
   - **SaaS** — pricing page, "sign up", "free trial", API docs, /app, /dashboard
   - **E-commerce** — product pages, cart, "add to cart", price elements
   - **Local Service** — phone number, address, "near me", Google Maps embed
   - **Publisher** — blog, articles, bylines, publication dates
   - **Agency** — portfolio, case studies, "our services", client logos
   - **Other** — default, apply general GEO best practices

3. **Identify key pages** from sitemap (up to 50 pages). Prioritize:
   - Homepage
   - About/team pages
   - Top content/blog pages
   - Product/service pages
   - Pricing page (if SaaS)

### Phase 2: Parallel Analysis (11 Subagents)

Launch these 11 analyses simultaneously using the Agent tool:

#### Agent 1: AI Citability + Content Quality
- Run citability scorer on up to 10 key pages:
  ```bash
  python3 ${CLAUDE_SKILL_DIR}/scripts/citability.py <url>
  ```
- Score passages for AI citation readiness (answer block quality, self-containment, statistical density, structural readability, uniqueness signals)
- Detects comparison patterns, how-to/instructional content, cause-effect language
- Enhanced self-containment: flags dangling pronouns, context-reference phrases
- Page-level findings: data table detection (>500 word pages), heading structure validation (>50% blocks without headings)
- FAQ/featured snippet detection: Q&A headings, definition patterns ("What is..."), numbered step lists, direct answer quality
- Conversational language scoring: second-person pronouns, questions, contractions, natural connectors
- Entity recognition: named entity density, defined terms, bold/emphasis terms
- Semantic topic coverage: heading diversity, subtopic breadth, repetitive heading detection
- LLM chunk-size scoring: checks if passages match ~500-token retrieval window sizes (optimal 225-415 words), flags oversized blocks (>600 words)
- Keyword density check: extracts primary keyword from title/H1, flags stuffing (>3%) or underuse (<0.5%)

#### Agent 2: AI Crawler Access + llms.txt Quality
- Parse robots.txt results from Phase 1 fetch data
- Check status of these AI crawlers: GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, anthropic-ai, PerplexityBot, CCBot, Bytespider, cohere-ai, cohere-training-data-crawler, Google-Extended, GoogleOther, GoogleOther-Image, GoogleOther-Video, Applebot-Extended, FacebookBot, Amazonbot, Meta-ExternalAgent, Meta-ExternalFetcher, YouBot, AI2Bot, Ai2Bot-Dolma, Diffbot, ImagesiftBot, aiHitBot, DuckAssistBot, img2dataset, MyCentralAIScraperBot, omgili, omgilibot, Quora-Bot, TikTokSpider
- Run llms.txt quality scorer:
  ```bash
  python3 ${CLAUDE_SKILL_DIR}/scripts/llms_txt.py <url>
  ```
- Scores existence, content length, markdown structure (# title, > description, ## sections), key pages section, about section, markdown link format, llms-full.txt bonus
- If llms.txt is missing, draft one based on site structure

#### Agent 3: Schema / Structured Data
- Run schema checker on homepage and key pages:
  ```bash
  python3 ${CLAUDE_SKILL_DIR}/scripts/schema_check.py <url>
  ```
- Detect existing JSON-LD, microdata, RDFa
- Validate against schema.org specs including @context validation (missing or non-standard @context)
- Identify missing schema types based on business type
- Generate correct JSON-LD for missing schemas using templates in `templates/schema/`

#### Agent 4: Technical SEO (13 checks)
- Run the technical SEO analyzer:
  ```bash
  python3 ${CLAUDE_SKILL_DIR}/scripts/technical_seo.py <url>
  ```
  Or pipe Phase 1 data:
  ```bash
  python3 ${CLAUDE_SKILL_DIR}/scripts/fetch_page.py <url> full | python3 ${CLAUDE_SKILL_DIR}/scripts/technical_seo.py
  ```
- 13 weighted checks: HTTPS, redirect chain, canonical tag, H1 count, meta description length, word count (300+), security headers, SSR detection, viewport meta, language attribute, Open Graph tags, response time (<3s), image alt text coverage (80%+)
- Optionally check Core Web Vitals via PageSpeed Insights:
  ```
  https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=<url>&strategy=mobile
  ```

#### Agent 5: E-E-A-T Analysis (9 signals)
- Run the E-E-A-T analyzer:
  ```bash
  python3 ${CLAUDE_SKILL_DIR}/scripts/eeat.py <url>
  ```
  Or pipe Phase 1 data:
  ```bash
  python3 ${CLAUDE_SKILL_DIR}/scripts/fetch_page.py <url> full | python3 ${CLAUDE_SKILL_DIR}/scripts/eeat.py
  ```
- 9 weighted signals: author bylines, publication dates, citation language, credentials, contact information, about page link, trust indicators, first-party expertise, schema.org authorship
- Each signal has a weight; score = (earned weight / total weight) * 100

#### Agent 6: Brand Presence
- Run the brand presence analyzer:
  ```bash
  python3 ${CLAUDE_SKILL_DIR}/scripts/brand_presence.py <url>
  ```
  Or pipe Phase 1 data:
  ```bash
  python3 ${CLAUDE_SKILL_DIR}/scripts/fetch_page.py <url> full | python3 ${CLAUDE_SKILL_DIR}/scripts/brand_presence.py
  ```
- Social media links (10 platforms: Twitter/X, LinkedIn, GitHub, YouTube, Wikipedia, Instagram, Facebook, TikTok, Reddit, Crunchbase)
- Review site links (5 platforms: G2, Capterra, Trustpilot, Product Hunt, Yelp)
- Brand pages (/about, /press, /media, /newsroom, /news)
- Schema.org sameAs links in structured data

#### Agent 7: Platform Readiness (composite)
- Run after all other dimension scores are available:
  ```bash
  echo '{"schema":72,"eeat":65,"citability":80,"llms_txt":45,"technical_seo":90,"brand_presence":55}' \
    | python3 ${CLAUDE_SKILL_DIR}/scripts/platform_readiness.py
  ```
- Computes per-platform readiness:
  - **Google AI Overviews**: schema 50% + eeat 50%
  - **ChatGPT**: citability 50% + llms_txt 50%
  - **Claude**: citability 40% + llms_txt 30% + eeat 30%
  - **Perplexity**: technical_seo 50% + citability 50%
  - **Gemini**: schema 40% + brand_presence 30% + eeat 30%
- Overall score = average of all 5 platform scores

#### Agent 8: Brand Mentions (Web Search)
- Search for the brand/site name across:
  - Reddit (site:reddit.com "<brand>")
  - YouTube (site:youtube.com "<brand>")
  - Wikipedia mentions
  - LinkedIn presence
  - GitHub presence (if relevant)
  - Industry directories

#### Agent 9: Search Intent Classification
- Run the search intent classifier:
  ```bash
  python3 ${CLAUDE_SKILL_DIR}/scripts/search_intent.py <url>
  ```
  Or pipe Phase 1 data:
  ```bash
  python3 ${CLAUDE_SKILL_DIR}/scripts/fetch_page.py <url> full | python3 ${CLAUDE_SKILL_DIR}/scripts/search_intent.py
  ```
- Classifies page into intent categories: informational, commercial, transactional, navigational
- Detects page type: article, product, pricing, comparison, service, homepage, about, support, general
- Checks intent-page type alignment — mismatches hurt AI citation
- Intent-specific recommendations (e.g., question headings for informational, comparison tables for commercial)
- Signals detected: URL structure, heading patterns, content patterns, CTA language, price elements

#### Agent 10: Content Freshness
- Run the content freshness scorer:
  ```bash
  python3 ${CLAUDE_SKILL_DIR}/scripts/content_freshness.py <url>
  ```
  Or pipe Phase 1 data:
  ```bash
  python3 ${CLAUDE_SKILL_DIR}/scripts/fetch_page.py <url> full | python3 ${CLAUDE_SKILL_DIR}/scripts/content_freshness.py
  ```
- Parses dates from 5 sources: meta tags (article:published_time, article:modified_time), JSON-LD (datePublished, dateModified), `<time>` elements, visible text ("Published on...", "Updated..."), HTTP Last-Modified header
- Calculates content age in days from the most recent date
- Scoring: <30 days = 100, <90 days = 85, <180 days = 70, <365 days = 55, <2 years = 35, older = 15
- Flags: no dates found, stale content (>1 year), published date without modified date, no visible date on page

#### Agent 11: Internal Link Structure
- Run the internal link analyzer:
  ```bash
  python3 ${CLAUDE_SKILL_DIR}/scripts/internal_links.py <url>
  ```
  Or pipe Phase 1 data (includes sitemap for coverage check):
  ```bash
  python3 ${CLAUDE_SKILL_DIR}/scripts/fetch_page.py <url> full | python3 ${CLAUDE_SKILL_DIR}/scripts/internal_links.py
  ```
- Link density: internal links per 1000 words (target: 5-15)
- Anchor text quality: flags generic anchors ("click here", "read more", empty text)
- Link diversity: ratio of unique destinations to total links
- Hub pattern detection: checks if page links to related content in the same section (hub-and-spoke topology)
- Sitemap coverage: how many sitemap pages are reachable via internal links from this page

### Phase 3: Report

Present findings grouped by category. For each category:
- Current state (what exists now)
- Issues found (with severity: Critical / High / Medium / Low)
- Confidence label for each finding:
  - **Confirmed** — directly verified (e.g., missing HTTPS, no H1 tag, absent robots.txt entry)
  - **Likely** — based on heuristic analysis (e.g., SSR detection, regex-based E-E-A-T signals, composite platform scores)
  - **Hypothesis** — suggested improvement, may not apply to every site (e.g., missing data tables, FAQ content suggestions)
- Specific findings with evidence

**Do NOT compute a weighted composite score.** Report each category independently. Let the user interpret priorities.

Categories to report:
1. AI Citability
2. AI Crawler Access
3. llms.txt Status
4. Structured Data / Schema
5. Technical SEO
6. Content Quality & E-E-A-T
7. Brand Presence
8. Platform Readiness
9. Search Intent
10. Content Freshness
11. Internal Link Structure

### Phase 4: Autofix

**Auto-generate** (write immediately to `geo-fixes/` in current working directory):
- `geo-fixes/llms.txt` — ready-to-deploy llms.txt file
- `geo-fixes/llms-full.txt` — detailed version
- `geo-fixes/schema/` — JSON-LD files for each missing schema type
- `geo-fixes/robots-txt-additions.txt` — recommended robots.txt additions for AI crawlers
- `geo-fixes/meta-tags.html` — optimized meta tag snippets
- `geo-fixes/FINDINGS.md` — full audit report in markdown

**Recommend for approval** (present to user, do NOT implement until approved):
- Heading structure changes (H1/H2/H3 hierarchy fixes)
- Meta description rewrites
- Content restructuring for citability (passage length, answer blocks)
- Alt text additions for images
- Internal linking improvements
- Any changes to existing source code files

### AI-Powered Suggestions

Use your intelligence as an LLM to generate contextual, site-specific suggestions beyond what the scripts can detect. These go in the report and fix files.

#### 1. Meta Description Rewrites
For every page with a missing, too-short, or too-long meta description (from technical_seo.py findings):
- Read the page title, H1, and first 200 words of body content
- Write an optimized meta description (120-160 characters) that:
  - Includes the primary topic/keyword naturally
  - Uses active voice and a clear value proposition
  - Is compelling enough to earn a click from both search results and AI citations
- Write the result to `geo-fixes/meta-tags.html` as a ready-to-paste `<meta name="description">` tag with a comment noting which page it's for

#### 2. Alt Text Generation
For every image flagged as missing alt text (from technical_seo.py):
- Examine the image `src` filename, surrounding text context, and page topic
- Write descriptive, specific alt text (10-20 words) that:
  - Describes what the image shows, not just the topic
  - Includes relevant keywords naturally (no keyword stuffing)
  - Avoids starting with "Image of" or "Photo of"
- Present as a table: | Image src | Suggested alt text |

#### 3. Heading Restructure
If the page has no H1, multiple H1s, or poor heading structure (from technical_seo.py and citability.py):
- Analyze the page content and propose a complete heading hierarchy:
  - One H1 that captures the primary topic
  - H2s for each major subtopic (aim for 4-8 on content-heavy pages)
  - H3s for sub-sections where appropriate
- Frame at least 1-2 headings as questions (for FAQ/snippet eligibility)
- Present as: Current heading structure → Proposed heading structure

#### 4. FAQ Section Drafting
If the page has no FAQ/featured-snippet-ready content (from citability.py `citability-no-faq-content`):
- Identify 3-5 questions that the page content implicitly answers
- Write each as a Q&A pair:
  - **Question**: Natural language question a user would ask
  - **Answer**: 2-3 sentence direct answer, starting with a declarative statement
- Generate matching FAQPage JSON-LD schema and write to `geo-fixes/schema/faq-page.json`
- The FAQ content itself goes in the report as a recommendation (not auto-applied)

#### 5. Content Gap Analysis
Based on the page topic, business type, and existing content:
- Identify 3-5 subtopics or questions the page does NOT cover but should
- For each gap:
  - **Missing topic**: What's not covered
  - **Why it matters**: How this gap affects AI citability (e.g., "ChatGPT frequently gets asked about X but your page doesn't address it")
  - **Suggested addition**: A 1-2 sentence description of what to add
- Consider the business type (SaaS, e-commerce, local, publisher, agency) when identifying gaps — e.g., a SaaS page missing pricing comparisons, or a local business missing service area information

#### 6. Robots.txt Crawler Explainer
For every blocked AI crawler found in the robots.txt analysis:
- Explain what the crawler does and who operates it
- Explain the tradeoff of allowing vs. blocking it:
  - **If allowed**: What happens (e.g., "Your content may appear in ChatGPT responses with citation links back to your site")
  - **If blocked**: What you lose (e.g., "Your content won't be indexed by OpenAI's search product")
- Flag any crawlers that are blocked but probably shouldn't be (e.g., blocking GPTBot but wanting ChatGPT visibility)
- Flag any crawlers that are allowed but the user might want to block (e.g., training-only crawlers like `cohere-training-data-crawler` or `img2dataset`)

Present this as a table:
| Crawler | Operator | Status | What it does | Recommendation |

**Content rewrite suggestions** — For the 3-5 weakest citability passages (lowest scores from citability.py), generate a rewritten version that:
- Starts with a clear declarative sentence (5-30 words) that directly answers the implied question
- Stays within the optimal 134-167 word passage length
- Replaces dangling pronouns with proper nouns
- Adds statistical density where appropriate (numbers, percentages, named sources)
- Structures as Q&A, definition, or how-to format when the topic allows

Present each rewrite as:
- **Original** (first 50 words + score)
- **Suggested rewrite** (full passage)
- **Why** (which citability factors improve)

Present code-level recommendations as a numbered list with:
- File path (if in a repo context)
- Current state
- Recommended change
- Why it helps AI visibility

Wait for user to approve specific items before making any code edits.

---

## Script Reference

### fetch_page.py
```
python3 ${CLAUDE_SKILL_DIR}/scripts/fetch_page.py <url> [mode]
```
Modes: `page`, `robots`, `llms`, `sitemap`, `full`

Returns JSON to stdout. Page mode includes: language attribute, viewport meta, Open Graph tags, meta robots, X-Robots-Tag header, response time (ms), and checks 32 AI crawlers.

### citability.py
```
python3 ${CLAUDE_SKILL_DIR}/scripts/citability.py <url>
```
Returns JSON with per-passage citability scores, page-level summary, and structural findings (data table detection, heading structure validation, FAQ/snippet detection, conversational language, entity density, semantic topic coverage, LLM chunk-size scoring, keyword density).

### schema_check.py
```
python3 ${CLAUDE_SKILL_DIR}/scripts/schema_check.py <url>
```
Returns JSON with detected schemas, validation results (including @context validation), and missing schema recommendations.

### eeat.py
```
python3 ${CLAUDE_SKILL_DIR}/scripts/eeat.py <url>
```
Or pipe from fetch_page.py:
```
python3 ${CLAUDE_SKILL_DIR}/scripts/fetch_page.py <url> full | python3 ${CLAUDE_SKILL_DIR}/scripts/eeat.py
```
Returns JSON with 9 E-E-A-T signals, per-signal weights, overall score, grade, and findings.

### brand_presence.py
```
python3 ${CLAUDE_SKILL_DIR}/scripts/brand_presence.py <url>
```
Or pipe from fetch_page.py:
```
python3 ${CLAUDE_SKILL_DIR}/scripts/fetch_page.py <url> full | python3 ${CLAUDE_SKILL_DIR}/scripts/brand_presence.py
```
Returns JSON with social platform presence (10), review platforms (5), brand pages, sameAs detection, score, and findings.

### technical_seo.py
```
python3 ${CLAUDE_SKILL_DIR}/scripts/technical_seo.py <url>
```
Or pipe from fetch_page.py:
```
python3 ${CLAUDE_SKILL_DIR}/scripts/fetch_page.py <url> full | python3 ${CLAUDE_SKILL_DIR}/scripts/technical_seo.py
```
Returns JSON with 13 weighted technical checks, per-check pass/fail, overall score, grade, and findings.

### llms_txt.py
```
python3 ${CLAUDE_SKILL_DIR}/scripts/llms_txt.py <url>
```
Or pipe from fetch_page.py:
```
python3 ${CLAUDE_SKILL_DIR}/scripts/fetch_page.py <url> full | python3 ${CLAUDE_SKILL_DIR}/scripts/llms_txt.py
```
Returns JSON with llms.txt quality score, spec compliance checks, and findings.

### platform_readiness.py
```
python3 ${CLAUDE_SKILL_DIR}/scripts/platform_readiness.py <schema> <eeat> <citability> <llms_txt> <tech_seo> <brand>
```
Or pipe dimension scores as JSON:
```
echo '{"schema":72,"eeat":65,"citability":80,"llms_txt":45,"technical_seo":90,"brand_presence":55}' \
  | python3 ${CLAUDE_SKILL_DIR}/scripts/platform_readiness.py
```
Returns JSON with per-platform readiness scores (Google AI Overviews, ChatGPT, Claude, Perplexity, Gemini), recommendations, and overall score.

### search_intent.py
```
python3 ${CLAUDE_SKILL_DIR}/scripts/search_intent.py <url>
```
Or pipe from fetch_page.py:
```
python3 ${CLAUDE_SKILL_DIR}/scripts/fetch_page.py <url> full | python3 ${CLAUDE_SKILL_DIR}/scripts/search_intent.py
```
Returns JSON with primary/secondary intent classification (informational, commercial, transactional, navigational), confidence level, detected page type, intent-page alignment check, and intent-specific findings.

### content_freshness.py
```
python3 ${CLAUDE_SKILL_DIR}/scripts/content_freshness.py <url>
```
Or pipe from fetch_page.py:
```
python3 ${CLAUDE_SKILL_DIR}/scripts/fetch_page.py <url> full | python3 ${CLAUDE_SKILL_DIR}/scripts/content_freshness.py
```
Returns JSON with dates found (from meta tags, JSON-LD, `<time>` elements, visible text, HTTP headers), content age, freshness score, grade, and findings.

### internal_links.py
```
python3 ${CLAUDE_SKILL_DIR}/scripts/internal_links.py <url>
```
Or pipe from fetch_page.py:
```
python3 ${CLAUDE_SKILL_DIR}/scripts/fetch_page.py <url> full | python3 ${CLAUDE_SKILL_DIR}/scripts/internal_links.py
```
Returns JSON with link density, anchor text quality, link diversity, hub pattern detection, sitemap coverage, score, grade, and findings.

---

## Business Type Adaptations

Adjust recommendations based on detected type:

| Type | Key Schema | Key Recommendations |
|------|-----------|-------------------|
| SaaS | SoftwareApplication, Organization | Comparison pages, feature definitions, pricing structured data |
| E-commerce | Product, Offer, AggregateRating | Product descriptions as answer blocks, review aggregation |
| Local | LocalBusiness, GeoCoordinates | Google Business Profile, local citations, service area pages |
| Publisher | Article, Person, Organization | Author pages, E-E-A-T signals, topic clusters |
| Agency | Organization, Service | Case studies as citable content, portfolio schema |

---

## Quality Gates

- Max 50 pages crawled per audit
- 30-second timeout per page fetch
- 1-second delay between requests
- Always respect robots.txt
- Skip pages with >80% content similarity
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
geo-audit

Directory Structure

SKILL.md

Report

Notice
