SEO and LLM Rankings

---

name: seo-and-llm-rankings description: >- Audits websites for traditional SEO health and AI search visibility (GEO). Generates 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. Use when auditing SEO, LLM visibility, generative engine optimization, AI Overviews, or AI search optimization. metadata: version: 1.1.0

---

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. 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 | WebFetch tool (bypasses WAFs/firewalls) | Python script (scripts/seo_audit.py) | curl 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

curl: command not found (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. 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:

python3 scripts/seo_audit.py "https://example.com"
python3 scripts/seo_audit.py "https://example.com" --full   # detailed output

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.

WebFetch("https://example.com")              -- main page HTML
WebFetch("https://example.com/robots.txt")   -- robots.txt
WebFetch("https://example.com/sitemap.xml")  -- sitemap
WebFetch("https://example.com/llms.txt")     -- llms.txt (AI discovery)

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

python3 scripts/seo_audit.py "https://example.com"
python3 scripts/seo_audit.py "https://example.com" --full

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.

UA="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
curl -sL -A "$UA" --retry 2 --max-time 30 "https://example.com/robots.txt"
curl -sL -A "$UA" --retry 2 --max-time 30 "https://example.com/sitemap.xml"
curl -sL -A "$UA" --retry 2 --max-time 30 "https://example.com/llms.txt"
curl -sL -A "$UA" --retry 2 --max-time 30 "https://example.com"
curl -sIL -A "$UA" --retry 2 --max-time 30 "https://example.com"

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):

curl "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=https://example.com&strategy=mobile"

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

Glob: **/*.{html,jsx,tsx,astro,vue,svelte,php}
Glob: **/layout.{tsx,jsx,js,ts}
Glob: **/app/layout.{tsx,jsx}
Glob: **/_app.{tsx,jsx}
Glob: **/index.{html,tsx,jsx}
Glob: **/head.{tsx,jsx}
Glob: **/_document.{tsx,jsx}

Step 2: Check meta tags in layout/page files

For Next.js (App Router):

Grep: "metadata|generateMetadata|title|description" in app/layout.tsx, app/page.tsx
Grep: "openGraph|twitter|metadataBase" in app/layout.tsx

For Next.js (Pages Router):

Grep: "|