SEO & LLM Rankings

Audit websites for traditional SEO health and AI search visibility (GEO). Generate prioritized reports with actionable fixes and ready-to-use prompts for AI coding agents. Covers Google, Bing, ChatGPT, Perplexity, Claude, Gemini, Copilot, and Google AI Overviews.

Before You Start

Check for product marketing context first:
If .agents/product-marketing-context.md exists, read it before asking questions. Use that context and only ask for information not already covered.

Gather missing context by asking the user:

1. 1. Audit mode -- Live URL scan or local codebase scan?
2. Site URL (if URL mode) -- What URL should be audited?
3. Project path (if codebase mode) -- Where is the project? (default: current workspace)
4. Scope -- Full site audit or specific pages/sections?
5. Site type -- SaaS, e-commerce, blog, local business, portfolio, etc.
6. Primary keywords -- What keywords/topics matter most?
7. Business goal -- Traffic, leads, signups, sales, brand awareness?
8. Known issues -- Any specific concerns or recent traffic drops?
9. Tech stack -- Next.js, WordPress, Shopify, static HTML, etc.

Only ask what you don't already know. If the user gives a URL, use URL mode. If the user says "audit my project" or "scan the codebase," use codebase mode. If ambiguous, ask.

---

Platform Detection & URL Fetching Strategy

URL mode fetches live pages via HTTP. This often fails because of WAFs (Cloudflare, etc.), corporate firewalls, bot-detection, or restricted shell environments. Before running any URL-mode fetch, detect your platform and use the most reliable method available.

How to detect your platform:

• - Cursor -- You have a WebFetch tool and WebSearch tool. You may also have @Web mentions available. If you can call WebFetch, you are in Cursor.
• Claude Code -- You have a WebFetch tool natively. Similar to Cursor but runs in a terminal-based agent.
• Codex (OpenAI) -- You have browser tools or web-fetch MCP tools. Check your available tool list.
• Windsurf -- You have built-in web browsing and URL fetching capability.
• Aider / terminal-only agents -- No built-in web tools. You must rely on shell commands (curl, python3).
• GitHub Copilot Workspace -- Has web access through its own tool surface.

URL fetching priority chain (try in order, fall back on failure):

Platform	Primary Fetch Method	Fallback 1	Fallback 2
Cursor	INLINECODE8 tool (bypasses WAFs/firewalls)	Python script (scripts/seo_audit.py)	INLINECODE10 with browser UA
Claude Code

WebFetch tool | Python script | curl with browser UA |
| Codex | WebFetch / browser tools | Python script | -- |
| Windsurf | Built-in web browsing | Python script | curl with browser UA |
| Aider / terminal | Python script | curl with browser UA | -- |
| Other | Python script | curl with browser UA | -- |

Failure detection: Treat any of these as a fetch failure that should trigger the next fallback:

• - HTTP 403, 404, 5xx status codes
• Connection timeout or connection refused
• Empty response body
• SSL/TLS errors
• INLINECODE17 (Windows without curl)

If all methods fail, do NOT silently skip the check. Inform the user that the URL could not be reached and suggest:

1. 1. Trying from a different network
2. Pasting the page HTML or file content directly for analysis
3. Switching to codebase mode if they have the source locally

---

Audit Mode Selection

This skill supports two audit modes:

Mode	When to Use	How It Works
URL mode	Site is live / deployed	Fetches pages via HTTP, checks robots.txt, sitemap, llms.txt, load time
Codebase mode

Site is local / pre-deployment | Scans project files using Glob, Read, Grep -- checks HTML, layout files, config |

Codebase mode is especially useful for:

• - Catching SEO issues before deployment
• Projects not yet live
• When the user wants to scan source code directly
• Auditing meta tags set in framework layout/page files (Next.js, Astro, etc.)

---

Audit Workflow

Phase 1: Technical SEO Scan

Choose your mode:

URL Mode

Run the audit script and manual checks:

CODEBLOCK0

Manual checks -- use the fetching strategy from "Platform Detection & URL Fetching Strategy" above.

Follow the priority chain for your platform. Examples for each method:

Primary: WebFetch (Cursor, Claude Code, Codex, Windsurf)

Use WebFetch for each resource. This is the most reliable method -- it handles TLS, follows redirects, and bypasses most WAF/bot-detection blocks.

CODEBLOCK1

If WebFetch returns an error for a specific resource (403, 404, 500, or timeout), note the failure and try the next fallback for that resource. Do NOT skip the check silently.

Fallback 1: Python script

CODEBLOCK2

The script has built-in retry logic and User-Agent rotation. If the script reports a fetch failure, it will print a diagnostic message with the status code and suggested next steps.

Fallback 2: curl with browser User-Agent

Use a realistic browser User-Agent to avoid bot detection. Add --retry 2 and --max-time 30 for resilience.

CODEBLOCK3

If all methods fail for a resource, tell the user which resource could not be fetched, the error received, and suggest they paste the content manually or switch to codebase mode.

PageSpeed check (optional, API-based):

CODEBLOCK4

What to check (both modes):

• - Title tag exists, 50-60 chars, contains primary keyword
• Meta description exists, 150-160 chars, compelling
• Single H1 per page, contains primary keyword
• Heading hierarchy: H1 > H2 > H3 (no skips)
• HTTPS enabled with valid certificate
• robots.txt exists and allows important pages
• XML sitemap exists and is accessible
• Page loads in < 3 seconds (URL mode only)
• Core Web Vitals: LCP < 2.5s, INP < 200ms, CLS < 0.1 (URL mode only)
• Open Graph and Twitter Card tags present
• Images have alt text
• No broken internal links

Codebase Mode

Scan the project files directly using Glob, Read, and Grep. No live server needed.

Step 1: Discover project structure and framework

CODEBLOCK5

Step 2: Check meta tags in layout/page files

For Next.js (App Router):
CODEBLOCK6

For Next.js (Pages Router):
CODEBLOCK7

For static HTML:
CODEBLOCK8

For Astro/Vue/Svelte:
CODEBLOCK9

Step 3: Check for robots.txt and sitemap

CODEBLOCK10

For Next.js dynamic generation:
CODEBLOCK11

Step 4: Check for llms.txt

CODEBLOCK12

Step 5: Check schema markup in source

CODEBLOCK13

Step 6: Check headings structure

CODEBLOCK14

For React/JSX components:
CODEBLOCK15

Step 7: Check images for alt text

CODEBLOCK16

Step 8: Check Open Graph and social tags

CODEBLOCK17

Codebase mode limitations:

• - Cannot check page load time or Core Web Vitals (needs live server)
• Cannot test HTTP redirect chains or SSL
• Cannot detect runtime-only issues (client-side rendering, JS errors)
• Schema injected purely at runtime by plugins won't be visible

Codebase mode advantages:

• - Catches issues before deployment
• Can see the actual source code and suggest exact file/line fixes
• Works offline
• Can scan all pages at once instead of one URL at a time
• Fix prompts can reference exact file paths

Phase 2: GEO / AI Visibility Scan

AI Crawler Access -- check robots.txt for these bots (in URL mode, fetch directly; in codebase mode, read the robots.txt file from public/ or project root):

Bot	Platform	Purpose
GPTBot	OpenAI	ChatGPT training/knowledge
ChatGPT-User

OpenAI | ChatGPT web browsing |
| ClaudeBot | Anthropic | Claude training |
| Claude-Web | Anthropic | Claude web search |
| anthropic-ai | Anthropic | Claude training data |
| PerplexityBot | Perplexity | Real-time search answers |
| Google-Extended | Google | Gemini / AI Overviews |
| Applebot-Extended | Apple | Apple Intelligence |
| Bingbot | Microsoft | Copilot (uses Bing index) |

llms.txt File:
Check if https://example.com/llms.txt exists. This AI discovery file (introduced 2024, widely adopted 2026) provides structured context to LLMs. Sites with llms.txt saw ~35% increase in AI visibility within 60 days. If missing, recommend creating one -- see references/fix-prompt-templates.md for a ready-to-use prompt.

Schema Markup:

INLINECODE23 and curl cannot reliably detect JS-injected schema (Yoast, RankMath, AIOSEO). Use browser tools or Google Rich Results Test for accurate detection.

Check for: FAQPage (+40% AI visibility), Article, Organization, WebPage, BreadcrumbList, SpeakableSpecification. See references/schema-templates.md.

AI Citation Scoring:
Score the page across 5 dimensions (see references/ai-citation-scoring.md):

1. 1. Extractability -- Can AI pull a useful answer?
2. Quotability -- Are there statements worth citing?
3. Authority -- Does it signal expertise?
4. Freshness -- Is content current?
5. Entity Clarity -- Can AI identify the entity?

Veto rule: If AI crawlers are blocked in robots.txt, AI visibility score = 0 regardless of content quality.

Phase 3: Content Quality Assessment

GEO Methods Check (see references/geo-methods.md):

• - Citations with sources present? (+27-40% visibility)
• Statistics with named sources? (+33-37%)
• Expert quotes with attribution? (+30-43%)
• Answer-first format? (40-60 word answer capsule after H2s)
• No keyword stuffing? (causes -9 to -10%)

E-E-A-T Signals:

• - Author bios with credentials visible?
• About page with company information?
• Contact information accessible?
• First-hand experience demonstrated?
• Content dated and recently updated?

Content Structure for AI Extraction:

• - Clear H2/H3 headings that match questions people ask
• Answer in first sentence after each heading
• Tables for comparisons, ordered lists for processes
• Short paragraphs (2-3 sentences)
• FAQ sections with direct answers

AI Writing Detection:
Check content for AI writing patterns that reduce credibility. See references/ai-writing-detection.md.

---

Report Format

Generate this report after completing all three phases:

CODEBLOCK18

---

Fix Prompt Generation

When the audit finds a small number of fixable issues, generate a ready-to-use prompt that the user can paste directly into their AI coding agent (Cursor, Claude Code, Codex, etc.).

When to generate a fix prompt:

• - Fewer than ~10 distinct issues found
• Issues are code-level fixes (meta tags, schema, robots.txt, content structure)
• User asks for a prompt to fix things
• Codebase mode: always generate fix prompts with exact file paths and line numbers

How to build the prompt:

1. 1. Read the fix prompt templates from references/fix-prompt-templates.md
2. Select the relevant template(s) based on audit findings
3. Fill in the specific issues, file paths, and current values from the audit
4. Combine into a single .prompt.md formatted prompt with:

- Clear persona (SEO/GEO expert) - Specific task listing each issue found - Step-by-step fix instructions - Validation criteria

Example output (URL mode):

CODEBLOCK19

Example output (codebase mode):

CODEBLOCK20

---

Content Prompt Generation

When the audit identifies content gaps -- missing pages, thin content that needs rewriting, or opportunities for new pages targeting high-value queries -- generate a ready-to-use prompt that produces SEO + GEO optimized content when pasted into an AI writing/coding agent.

When to generate a content prompt:

• - Audit reveals content gaps (missing pages for queries the site should rank for)
• Programmatic SEO opportunities identified (see table below)
• User explicitly asks for help creating new content or pages
• Thin content flagged (word count < 300) that needs a full rewrite rather than a quick fix
• Competitor analysis shows topics the site doesn't cover but should

How to build the prompt:

1. 1. Read the content prompt templates from references/content-prompt-templates.md
2. Select the template matching the page type:

- Article / Blog Post -- informational content targeting a query - Landing / Product Page -- conversion-focused page - Glossary / Definition Page -- "What is X?" pages (great for pSEO) - Comparison Page -- "X vs Y" structured comparison - FAQ / Resource Page -- Q&A aggregation page - Location / Persona Page -- localized or audience-specific variant

1. 3. Fill placeholders using audit findings, keyword data, and product-marketing-context (if .agents/product-marketing-context.md exists)
2. The template already embeds GEO optimization rules (answer capsules, citation density, quotation slots from references/geo-methods.md), anti-AI-writing constraints (from references/ai-writing-detection.md), and schema markup requirements -- do not remove them
3. Output as a single .prompt.md formatted prompt

Example output (article page):

CODEBLOCK21

Example output (comparison page):

CODEBLOCK22

Combining with programmatic SEO: When the audit suggests scale pages (integrations, locations, personas, glossary terms), use the batch pattern in Template 3 or Template 6 from references/content-prompt-templates.md. Provide the list of items (terms, cities, audiences) inside the prompt so the agent generates one page per item using the same structure.

---

Programmatic SEO Opportunities

For sites that could benefit from pages at scale, suggest opportunities from these playbooks:

If the site has...	Suggest...
Product with integrations	Integration pages (/integrations/[tool]/)
Multi-segment audience

Persona pages (/for/[audience]/) |
| Local presence | Location pages (/[service]/[city]/) |
| Competitor landscape | Comparison pages (/compare/[x]-vs-[y]/) |
| Industry expertise | Glossary pages (/glossary/[term]/) |
| Design/creative product | Template pages (/templates/[type]/) |

Only suggest if there's genuine search demand and the site has (or can create) unique data for each page. Use subfolders, not subdomains.

---

Platform-Specific Optimization

For detailed ranking factors per platform, see references/platform-ranking-factors.md.

Quick reference:

Platform	Primary Index	Key Factor	Unique Requirement
Google	Google	Backlinks + E-E-A-T	Core Web Vitals
Google AI Overviews

Google | E-E-A-T + Schema | Knowledge Graph |
| ChatGPT | Bing-based | Domain Authority | Content-Answer Fit |
| Perplexity | Own + Google | Semantic Relevance | FAQ Schema, freshness |
| Claude | Brave | Factual Density | Brave Search indexing |
| Copilot | Bing | Bing Index | MS Ecosystem presence |

---

Validation Tools

Tool	URL	Purpose
Google Rich Results Test	search.google.com/test/rich-results	Schema validation (renders JS)
Schema.org Validator

validator.schema.org | Schema syntax check |
| PageSpeed Insights | pagespeed.web.dev | Core Web Vitals |
| Google Search Console | search.google.com/search-console | Indexing, errors, performance |
| Bing Webmaster Tools | bing.com/webmasters | Bing indexing |

---

References

• - references/ai-citation-scoring.md -- 5-dimension AI citation scoring framework
• references/platform-ranking-factors.md -- Per-engine ranking factors (2026)
• references/geo-methods.md -- Princeton GEO 9 methods with updated data
• references/schema-templates.md -- JSON-LD structured data templates
• references/seo-checklist.md -- Prioritized P0/P1/P2 audit checklist
• references/ai-writing-detection.md -- AI writing patterns to avoid
• references/fix-prompt-templates.md -- Fix prompt templates for AI coding agents
• references/content-prompt-templates.md -- Content creation prompt templates for new pages (SEO + GEO optimized)

Scripts

• - scripts/seo_audit.py -- Full SEO + GEO audit (no API required). Checks meta tags, headings, robots.txt, sitemap, llms.txt, AI crawlers, schema, performance.

CODEBLOCK23

---

Troubleshooting: URL Fetch Failures

URL fetching can fail for many reasons. Use this table to diagnose and recover.

Symptom	Likely Cause	Fix
403 Forbidden	WAF/bot detection (Cloudflare, etc.)	Use WebFetch (Cursor/Claude Code) or curl with browser UA
404 on known pages

URL path wrong OR CDN blocking non-browser agents | Verify URL in a browser, then try WebFetch |
| 429 Too Many Requests | Rate limiting | Wait and retry, or use WebFetch |
| 500 Server Error | Server issue or aggressive bot blocking | Retry with backoff (script does this automatically), try WebFetch |
| Connection timeout | Firewall blocking outbound requests | Use WebFetch, or ask user to paste content |
| Empty response | Bot trap returning empty body | Use WebFetch, verify the URL loads in a real browser |
| SSL/TLS error | Certificate issue or corporate MITM proxy | Add --insecure to curl (warn user), or use WebFetch |
| curl: command not found | Windows without curl or restricted env | Use Python script (scripts/seo_audit.py) or WebFetch |
| Script exits with code 2 | Connection/timeout error (no HTTP status) | Network issue; try WebFetch or check VPN/firewall |
| Script exits with code 1 | HTTP error (got a status code back) | Check the status code in output; likely bot detection |

Platform-specific notes:

• - Cursor: Always prefer the WebFetch tool. It handles TLS, follows redirects, and bypasses most WAF blocks. If fetching a URL fails with WebFetch, do NOT silently skip the check -- inform the user with the error and suggest they paste the content or switch to codebase mode.
• Claude Code: Same as Cursor -- WebFetch is available and preferred.
• Codex (OpenAI): Use available browser/web tools. Check your tool list for WebFetch or equivalent.
• Windsurf: Use built-in browsing capability. Falls back to shell commands.
• Terminal-only agents (Aider, etc.): Must rely on shell commands. Use the Python script first (it has retry logic and UA rotation), then fall back to curl with a browser User-Agent.
• GitHub Copilot Workspace: Use platform web access tools. Fall back to Python script if unavailable.