From ultimate-seo-geo
Audits websites for SEO and GEO covering technical health, E-E-A-T scoring, domain authority, structured data, rich results, Core Web Vitals, crawlability, robots.txt, sitemaps. Use for audits, traffic drops, schema JSON-LD generation, migrations.
npx claudepluginhub mykpono/ultimate-seo-geo --plugin ultimate-seo-geoThis skill uses the workspace's default tool permissions.
| Attribute | Details |
evals/evals.jsonevals/fixtures/eval10_pass.txtevals/fixtures/eval11_pass.txtevals/fixtures/eval12_pass.txtevals/fixtures/eval1_pass.txtevals/fixtures/eval2_pass.txtevals/fixtures/eval3_pass.txtevals/fixtures/eval4_pass.txtevals/fixtures/eval5_pass.txtevals/fixtures/eval6_pass.txtevals/fixtures/eval7_pass.txtevals/fixtures/eval8_pass.txtevals/fixtures/eval9_pass.txtreferences/ai-search-geo.mdreferences/analytics-reporting.mdreferences/audit-output-example.mdreferences/audit-script-matrix.mdreferences/cite-domain-rating.mdreferences/content-eeat.mdreferences/core-eeat-framework.mdAudits websites for SEO: full site scans, single-page analysis, technical checks (Core Web Vitals, crawlability, indexability), schema markup, E-E-A-T content quality, image optimization, sitemaps, backlinks, and AI GEO.
Provides SEO, AEO, and GEO strategies for search engines and AI visibility. Covers audits, technical SEO, crawlability, indexation, Core Web Vitals, schema markup, and site architecture.
Runs SEO and GEO audits on URLs covering technical SEO, content quality, E-E-A-T signals, and AI citation readiness. Use when evaluating search performance or diagnosing ranking issues.
Share bugs, ideas, or general feedback.
| Attribute | Details |
|---|---|
| Version | 1.5.6 |
| Updated | 2026-03-27 |
| License | MIT |
| Author | Myk Pono |
| Lab | lab.mykpono.com |
| Homepage | mykpono.com |
| Profile |
The definitive SEO and Generative Engine Optimization skill. Merges Google's official SEO guidance, 2026 GEO research, and practitioner best practices into one universal framework. Every finding comes with a clear fix directive — not just diagnosis.
| Goal | Start here |
|---|---|
| Full scored audit | § 2, § 21, references/audit-script-matrix.md |
| AI citations / GEO | § 3, llms_txt_checker.py, entity_checker.py |
| Schema only | § 5, validate_schema.py |
| Local | § 12, local_signals_checker.py |
| Crawl / index / performance | § 4, matrix scripts (robots_checker, sitemap_checker, pagespeed.py if API works) |
| Migration | § 20, redirect_checker.py |
| Keywords / roadmap (no URL yet) | § 7, § 16 — do not invent a live-site /100 score |
When a section points to a reference file, read only what you need for the current task.
Progressive Disclosure rule: Load at most 3 reference files per response — unless running a Mode 1 full audit with generate_report.py, which implicitly covers all dimensions. For single-topic Mode 2 or Mode 3 tasks (e.g., "fix my schema", "write an llms.txt"), the routing table below identifies exactly 1–2 files to load. Loading all 22 reference files for a narrow task wastes context and adds latency with no quality gain. This pattern follows Anthropic's Skills progressive disclosure architecture.
| Task | Read | Run |
|---|---|---|
| Full audit (any type) | references/audit-script-matrix.md | generate_report.py |
| GEO / AI citations | references/ai-search-geo.md, references/entity-optimization.md | robots_checker.py, entity_checker.py, llms_txt_checker.py |
| Schema markup | references/schema-types.md | validate_schema.py |
| Technical / CWV | references/technical-checklist.md | pagespeed.py, robots_checker.py, security_headers.py |
| Content / E-E-A-T | references/eeat-framework.md, references/core-eeat-framework.md | readability.py, article_seo.py |
| CITE domain audit | references/cite-domain-rating.md | link_profile.py |
| Keywords / clusters | references/keyword-strategy.md | — |
| Links | references/link-building.md | internal_links.py, broken_links.py, link_profile.py |
| Local SEO | references/local-seo.md | local_signals_checker.py |
| Images | references/image-seo.md | image_checker.py |
| International / hreflang | references/international-seo.md | hreflang_checker.py |
| Programmatic SEO | references/programmatic-seo.md | — |
| Migration | references/site-migration.md | redirect_checker.py |
| Analytics / myths | references/analytics-reporting.md | — |
| Crawl / indexation | references/crawl-indexation.md | sitemap_checker.py, duplicate_content.py |
| User signal | Action |
|---|---|
| Google Ads / PPC as the primary ask | Paid-media scope — no organic SEO Health Score or crawl Finding wall unless organic SEO is also requested. |
| Employer branding only, pure press/PR distribution, email-only marketing | Narrow guidance; no implied full technical + content audit. |
| GA4/GTM setup only (no organic SEO question) | § 10 measurement checklist — no fabricated domain-wide numeric score. |
| Social community management only | Out of scope unless tied to organic discovery (e.g. sameAs, entity signals). |
| Explicitly scoped task (e.g. “only robots.txt + sitemap”) | Stay in that scope — no domain-wide E-E-A-T essay or /100 score unless the user asks. |
Before routing, determine which audit context applies. This controls what outputs are valid.
| Signal | Context | What's Allowed |
|---|---|---|
| User says "my site", "our site", "I own", provides GSC/GA4 access, or confirms backend access | Internal Mode | Full scored audit, all 27 scripts eligible, Execute mode available, /100 Health Score valid |
| External URL the user does not own (competitor, prospect, reference site) | Competitive Mode | Surface crawl only (homepage + up to 20 pages), no /100 Health Score, Execute mode disabled, all output labeled "External Observation Only" |
When in doubt, ask: "Is this your site, or are you analyzing a competitor?"
This skill operates in three modes. Identify which mode applies before touching anything else.
Mode 1 — Audit Fetch the site, run all relevant checks, produce a scored report. Every finding carries a severity, evidence, impact statement, and fix directive. Output: SEO Health Score + prioritised findings in the standard format (§ 2).
Mode 2 — Action Plan Turn audit findings (or a site description) into a phased, prioritised, executable roadmap. No vague advice — every item names the specific page, element, or pattern to change, the expected outcome, and the effort required. Output: Implementation Phases table (§ 16) + Quick Wins.
Mode 3 — Execute Do the work. Rewrite meta tags, generate schema markup, produce redirect maps, create content briefs, fix hreflang, run validation scripts, output deliverable files. Every execution task ends with a verification step.
Most requests involve all three in sequence: Audit → Plan → Execute. Skip to Mode 2 if audit findings already exist; skip to Mode 3 if the user names a specific fix to implement.
Three questions only — skip any already answered in the user's message.
| # | Question | Why It Matters |
|---|---|---|
| 1 | What is the URL? | Required for all three modes |
| 2 | What is the primary goal? (traffic / AI citations / local leads / traffic drop / specific keyword) | Determines which modules run first |
| 3 | Which mode? Audit / Audit + Plan / Audit + Plan + Execute | Scopes the work — default to all three if unclear |
Everything else (analytics access, CMS, business type) is discovered during the audit.
User request + URL
│
├─ "audit", "analyze", "full check", "what's wrong"
│ └─ Mode 1 → § 2
│
├─ "give me a plan", "roadmap", "what to fix first"
│ └─ Mode 2 → § 16 (run § 2 first if no audit exists)
│
├─ "fix this", "generate schema", "rewrite my titles", "run the scripts"
│ └─ Mode 3 → § 21 for scripts; relevant section for task
│
├─ Traffic drop / rankings lost
│ └─ Mode 1 focused → § 10 first, then § 6 / § 4
│
├─ AI citations / GEO question
│ └─ Mode 1 focused → § 3 first
│
├─ Domain / CMS migration
│ └─ Mode 1 focused → § 20
│
└─ No mode stated + URL / "audit + fix everything"
└─ Mode 1 → 2 → 3 (§ 2, then § 16, then execute top findings)
Audit complete when: SEO Health Score delivered, all Critical and High findings documented in Finding/Evidence/Impact/Fix/Confidence format, no section skipped without reason stated.
Plan complete when: findings grouped into four implementation phases (Foundation / Expansion / Scale / Authority), each item has an owner action, expected outcome, and effort estimate.
Execute complete when: every fix implemented AND verified — run the relevant validation script, review the output, confirm it resolves the original finding.
If the request matches § 0 “When not to run Mode 1”, route to a narrow answer or decline the SEO-audit template — even if generic “marketing” vocabulary appears.
Disambiguation: When multiple rows match, prefer the most specific. If equally specific, use the first match. If nothing matches, fall back to § 0 Intake Checklist.
This table routes by topic. For mode selection (Audit vs. Plan vs. Execute), see § 0 Mode Routing.
| Request Type | Trigger Keywords | Go To |
|---|---|---|
| Full Audit | “audit”, “analyze my site”, “full check”, “site review” | § 2 Full Audit |
| Traffic Drop / Rankings Lost | “traffic dropped”, “lost rankings”, “rankings fell”, “why did traffic drop”, “core update”, “algorithm update”, “rankings dropped” | § 10 Analytics first, then § 4 Technical / § 6 Content |
| GEO / AI Search | “AI Overviews”, “ChatGPT”, “Perplexity”, “AI citations”, “GEO”, “AI Mode”, “SearchGPT”, “Gemini”, “llms.txt”, “AI search” | § 3 GEO |
| Technical SEO | “crawl”, “robots.txt”, “Core Web Vitals”, “speed”, “indexing”, “JS rendering”, “mobile”, “mobile-friendly”, “HTTPS”, “security headers”, “redirect chain” | § 4 Technical |
| Schema / Structured Data | “schema”, “JSON-LD”, “rich results”, “structured data” | § 5 Schema |
| Content / E-E-A-T | “content quality”, “E-E-A-T”, “thin content”, “helpful content”, “CORE-EEAT” | § 6 Content |
| Content Scoring | “CORE-EEAT audit”, “content score”, “CITE audit”, “domain authority score”, “GEO score” | § 6 Content |
| Entity Optimization | “entity”, “knowledge graph”, “knowledge panel”, “Wikidata”, “brand entity” | § 3 GEO |
| Content Pruning / Refresh | “old content”, “content decay”, “delete pages”, “refresh”, “consolidate” | § 6b Pruning |
| Keyword Research | “keywords”, “ranking opportunities”, “content gaps”, “what should I write” | § 7 Keywords |
| Topic Clusters | “topic cluster”, “content strategy”, “pillar page” | § 7b Clusters |
| AEO / Featured Snippets | “featured snippet”, “PAA”, “voice search”, “knowledge panel”, “speakable” | § 7c AEO |
| Competitor Analysis | “competitors”, “benchmark”, “compare to”, “X vs Y page”, “alternatives page” | § 8 Competitors |
| Link Building | “backlinks”, “internal links”, “anchor text”, “referring domains” | § 9 Links |
| Analytics / Reporting | “GA4”, “Search Console”, “CTR”, “rank tracking”, “penalty”, “manual action” | § 10 Analytics |
| Crawl & Indexation | “crawl budget”, “sitemap”, “canonical”, “index bloat”, “noindex”, “duplicate content”, “content cannibalization” | § 11 Crawl |
| Local SEO | “local”, “Google Business Profile”, “GBP”, “map pack”, “NAP” | § 12 Local |
| Image SEO | “images”, “alt text”, “WebP”, “image size” | § 13 Images |
| International SEO | “hreflang”, “multi-language”, “international”, “geo-targeting” | § 14 International |
| Programmatic SEO | “programmatic”, “at scale”, “templates”, “city pages”, “glossary pages” | § 15 Programmatic |
| Strategy / Roadmap | “SEO plan”, “roadmap”, “strategy”, “what should I focus on” | § 16 Strategy |
| Monthly Maintenance | “what should I check”, “monthly SEO”, “ongoing”, “monitor” | § 17 Maintenance |
| Site Migration | “moving domains”, “new URL structure”, “CMS migration”, “redirect map” | § 20 Migration |
| Myths / Misconceptions | “does X help SEO?”, “is X a ranking factor?” | § 18 Myths |
| Script Toolbox | “run a check”, “generate a report”, “validate schema”, “automated audit” | § 21 Scripts |
| No clear match | Query doesn’t match any row above | § 0 Intake Checklist |
| Paid ads primary | “Google Ads”, “PPC campaign”, “ad spend” without organic SEO ask | § 0 — paid scope, not Mode 1 |
| Scoped technical only | “only robots.txt”, “just the sitemap”, “don’t audit content” | § 0 + § 4 / § 11 — stay in scope |
In a bash-capable environment: Run python scripts/generate_report.py https://example.com --output report.html first — it runs the bundled analysis pipeline in generate_report.py (robots, security, social, redirects, llms.txt, links, PageSpeed, entities, hreflang, duplicates, sitemap discovery, local signals, IndexNow probe, on-page parse, readability, article SEO, JSON-LD validation, image alt coverage, etc.). Then use finding_verifier.py to deduplicate at the end. For any single dimension, run the matching script from references/audit-script-matrix.md or §21.
Evidence Integrity — do not state the following unless the corresponding data source ran or was provided:
| Claim | Only state if |
|---|---|
| LCP / INP / CLS / performance score | pagespeed.py ran successfully, or user pasted PageSpeed Insights / CrUX output |
| Backlink count or referring domains | link_profile.py ran and returned data |
| Organic traffic or impression numbers | GSC / GA4 access confirmed and data retrieved |
| Health Score /100 | Internal Mode + minimum 5 scripts ran with data |
| Thin content finding | readability.py + duplicate_content.py both ran |
| Schema errors or validation status | validate_schema.py ran against the page |
| Schema "not found" on a CMS site | Confirmed via Rich Results Test or browser JS console — web_fetch/curl/raw HTML cannot detect JS-injected schema (Yoast, RankMath, AIOSEO inject via client-side JS) |
When data is absent: replace the claim with [metric] not measured — run [script] for actual data or ask the user to provide it. If pagespeed.py failed, lacks an API key, or the environment blocks googleapis.com, say performance data unavailable and give checklist-level guidance (§ 4, references/technical-checklist.md) or ask the user to run PSI / WebPageTest manually.
references/industry-templates.md for business-type-specific architecture and schema priorities.Industry preset (what to prioritize first)
| Detected type | Emphasize | Run early (when shell + network available) |
|---|---|---|
| SaaS / B2B | § 7 keywords, § 5 SoftwareApplication / Product, § 4 tech | generate_report.py, validate_schema.py, meta_lengths_checker.py |
| E-commerce | § 11 indexation, § 5 Product + BreadcrumbList, § 9 internal links | generate_report.py, duplicate_content.py, sitemap_checker.py |
| Local service | § 12, § 5 LocalBusiness, NAP | local_signals_checker.py, robots_checker.py |
| Publisher / blog | § 6 E-E-A-T, § 13 images, Article / NewsArticle | readability.py, article_seo.py, duplicate_content.py |
| Agency / portfolio | § 8 competitors, § 9 authority | link_profile.py + full report |
| Category | Weight |
|---|---|
| Content Quality / E-E-A-T | 22% |
| Technical SEO | 18% |
| On-Page SEO (titles, meta, URLs) | 15% |
| Link Authority | 12% |
| Schema / Structured Data | 10% |
| Core Web Vitals | 8% |
| AI Search Readiness (GEO) | 8% |
| Images | 4% |
| Local SEO (if applicable) | 3% |
For the on-page element checklist (title tags, meta descriptions, H1, URLs, canonicals), see references/technical-checklist.md.
First check for any new site: site:yourdomain.com in Google. Zero results = indexation problem → go to § 4 immediately.
Every audit finding must use this structure:
Finding: [what the issue is]
Evidence: [what was observed / what data shows this]
Impact: [how this hurts rankings, traffic, or citations]
Fix: [specific, actionable step]
Confidence: Confirmed / Likely / Hypothesis
Confidence labels:
Scoring formula: base_score = (positive_signals / (positive_signals + deficit_signals)) × 100. Deduct: Critical −15 pts, Warning −5 pts.
Use this exact template:
# SEO Audit Report — [site.com]
Date: [date] | Business Type: [type] | Audited Pages: [N] | Confidence: High/Medium/Low
## SEO Health Score: XX/100
[chain-of-thought: positive_signals=N, deficit_signals=N, base=XX, Critical −15×N, Warning −5×N = final]
| Category | Score | Status |
|---|---|---|
| Content Quality / E-E-A-T | XX/100 | ✅/⚠️/❌ |
...
## Executive Summary
[2–3 sentences: biggest strength, biggest gap, single highest-impact action]
## 🔴 Critical Issues (fix immediately)
## 🟠 High Priority (fix this week)
## 🟡 Medium Priority (fix this month)
## ⚡ Quick Wins (under 2 hours each)
## 💡 Opportunity Signals
## Full Findings [per-category, each in Finding/Evidence/Impact/Fix/Confidence format]
For a 3-finding excerpt showing the output format, see references/audit-output-example.md.
When converting audit findings into a roadmap (§ 16), use this format per item:
| Fix schema on all product pages | Dev | 2 hr | Star ratings in SERPs (+15–30% CTR) | Phase 1 |
Columns: Action | Owner | Effort | Expected Outcome | Phase
Before producing any Execute output, classify the change:
| Classification | Change Types | Action |
|---|---|---|
| Safe | Meta descriptions, title tags, alt text, FAQ/Article/Organization schema, content rewrites, llms.txt, internal links | Output directly |
| High-Risk | robots.txt, canonical tags, redirect maps, noindex directives, hreflang tags, bulk CMS template changes | State the proposed change and ask for explicit confirmation before outputting — one bad change here can deindex the site |
When implementing a specific fix:
1. Classify: Safe or High-Risk?
2. If High-Risk: state the change and confirm with the user before proceeding
3. State the finding being addressed
4. Produce the fix artifact (code, rewrite, JSON-LD, redirect map)
5. Verify: run scripts/validate_schema.py [file] OR review output directly
6. Confirm: "Fix resolves [Finding] — [evidence of resolution]"
Example:
Addressing: Missing FAQPage schema on /guides/psilocybin-therapy
Fix: [generated JSON-LD below]
Verify: python scripts/validate_schema.py therapy_page.html → 0 errors
Confirmed: FAQPage with 4 Q&A pairs valid; eligible for AI Overview extraction.
GEO = getting content cited by AI engines: Google AI Overviews, AI Mode, ChatGPT Search, Perplexity.
| # | Question | If No → Action |
|---|---|---|
| 1 | Are AI crawlers (OAI-SearchBot, PerplexityBot) allowed in robots.txt? | Remove Disallow rules immediately |
| 2 | Does the page answer its target query in the first 60 words? | Move key answer to opening paragraph |
| 3 | Is page content present in raw HTML (not JS-rendered only)? | Implement SSR or pre-rendering |
| 4 | Does the page have a named author with credentials and a publication date? | Add author bio + date to every key page |
| 5 | Is the brand mentioned on YouTube or Reddit? | Start a presence on the missing platform |
Any "No" = fix before deeper analysis. All "Yes" → proceed to full GEO Score.
For 2026 platform reach and traffic signal data, see references/ai-search-geo.md.
/robots.txt. Confirm OAI-SearchBot, PerplexityBot, ClaudeBot are not Disallowed./llms.txt. Missing → generate from template below. Low-cost hygiene step.references/ai-search-geo.md for correlation data and Wikipedia/Wikidata setup.| Dimension | Weight | Key Checks |
|---|---|---|
| Citability | 25% | Answer in first 40–60 words; 134–167 word self-contained blocks; specific stats |
| Structural Readability | 20% | H1→H2→H3 hierarchy; question-based headings; tables |
| Authority & Brand Signals | 20% | Author bio + credentials; publication date; Wikipedia/Reddit/YouTube presence |
| Technical Accessibility | 20% | AI crawlers allowed; SSR; llms.txt present |
| Multi-Modal Content | 15% | Text + images + video = 78% of cited sources |
Key insight: 44.2% of AI citations come from the first 30% of content. Restructuring alone can 2× citation rate.
For the Quora, Reddit, influencer, and newsletter outreach playbooks, see references/ai-search-geo.md → Tactical Playbooks per Channel.
For Google AI Mode–specific optimization (zero blue links, follow-up queries, Related Questions sections), see references/ai-search-geo.md → Platform-Specific Optimization.
For the AI crawler allow/block table (OAI-SearchBot, PerplexityBot, ClaudeBot, GPTBot, Google-Extended) and the llms.txt quick template, see references/ai-search-geo.md.
Finding: Key answer buried below fold — target query not answered in first 30% of content
Evidence: "How does [product] work" answered in paragraph 6, ~800 words in.
44.2% of AI citations come from first 30% of content — this page fails.
Impact: Low AI Overview and Perplexity citation rate for the site's core query.
Fix: Move the direct answer to the opening paragraph. Keep detail further down.
Confidence: Confirmed | Severity: 🟠 High
When auditing a page's citation potential, always produce a before/after citation demonstration — not just a score. Show the user what an AI-quotable passage from their content would look like:
CURRENT (not citable — 340 words, no direct answer in first 30%)
"Psilocybin has been the subject of considerable scientific investigation in recent
years, with researchers from leading institutions exploring its..."
REWRITTEN (citable — 148 words, direct answer in first sentence, source attributed)
"Psilocybin produces psychedelic effects by binding to serotonin 5-HT2A receptors
in the brain, temporarily altering perception and cognition (Johns Hopkins Center
for Psychedelic Research, 2024). Effects last 4–6 hours at typical doses of
10–30 mg. A 2023 JAMA Psychiatry meta-analysis of 11 RCTs found response rates
of 57–80% for treatment-resistant depression."
WHY IT'S CITABLE: Self-contained (148 words, within 134–167 target), direct answer
first, specific numeric stat, dated institutional source — exactly what AI systems
prefer for citation inclusion.
This concrete demonstration is more actionable than a score alone. Adapted from Anthropic's Citations cookbook pattern of showing source attribution in structured output.
→ See references/ai-search-geo.md (full platform data, brand correlation, Wikipedia/Wikidata setup, Passage Indexing, Princeton GEO research techniques, content type citation share, AI monitoring tools, platform source selection factors) | See references/entity-optimization.md (47-signal entity checklist, AI Entity Resolution Test, Knowledge Graph guide) | Run scripts/robots_checker.py Run scripts/entity_checker.py Run scripts/llms_txt_checker.py Run scripts/social_meta.py
| Metric | Good | Needs Improvement | Poor |
|---|---|---|---|
| LCP | < 2.5s | 2.5–4.0s | > 4.0s |
| INP | < 200ms | 200–500ms | > 500ms |
| CLS | < 0.1 | 0.1–0.25 | > 0.25 |
Measured at 75th percentile (CrUX/PageSpeed Insights). Speed is also a GEO factor: FCP < 0.4s pages average 6.7 AI citations vs. 2.1 for slower pages.
references/technical-checklist.md.<link rel="canonical" href="[absolute-url]">.og:title, og:description, og:image, twitter:card on all shareable pages.Strict-Transport-Security: max-age=31536000; includeSubDomains. ❌ Fail: header absent or max-age=0.For the full Critical Technical Issues + Fix Directives table (9 issues with detection methods and fixes), JavaScript SEO December 2025 clarifications (canonical conflicts, noindex behavior, JS-rendered structured data), and the mobile-first indexing note, see references/technical-checklist.md.
Key rule: Serve all critical SEO elements (canonical, meta robots, structured data, title, meta description, hreflang) in the initial server-rendered HTML — not JS-only.
Finding: Redirect Chain Detected
Severity: 🟠 High | Confidence: Confirmed
Issue: /old-page → /temp-redirect → /final-destination (2-hop chain)
Every extra hop adds latency and dilutes link equity.
Fix: Update all internal links and any external links you control to point directly to
/final-destination. The redirect map remains as a safety net.
Expected impact: Faster crawl, full link equity preservation.
→ See references/technical-checklist.md (detailed CWV fix steps, LCP subparts, IndexNow setup) | Run scripts/pagespeed.py Run scripts/robots_checker.py Run scripts/redirect_checker.py Run scripts/security_headers.py Run scripts/indexnow_checker.py
Script note:
pagespeed.pycalls googleapis.com. In proxy-restricted environments it will fail — fallback: ask user to run pagespeed.web.dev and share results, or use the manual CWV checklist inreferences/technical-checklist.md.
Always use JSON-LD (<script type="application/ld+json">). Schema improves AI citation likelihood ~2.5× (Google/Microsoft, March 2025).
application/ld+json. Caveat: web_fetch, curl, and raw HTML cannot reliably detect schema on CMS sites — many plugins (Yoast, RankMath, AIOSEO) inject JSON-LD via client-side JavaScript that won't appear in static source. If raw HTML shows no schema on a CMS site, verify with Rich Results Test (renders JS) or browser console (document.querySelectorAll('script[type="application/ld+json"]')) before reporting "no schema found."references/schema-types.md.| Site Type | Essential Schema |
|---|---|
| Publisher / Blog | Article/BlogPosting, Person, ProfilePage (author pages), Organization, WebSite, BreadcrumbList |
| Forum / Community | DiscussionForumPosting, Person, Organization |
| SaaS | WebApplication/SoftwareApplication, Organization, WebSite, FAQPage |
| E-commerce | Product + Offer, AggregateRating, Organization, BreadcrumbList, ProductGroup (variants), OfferShippingDetails |
| Local Business | LocalBusiness (most specific subtype), Organization, AggregateRating |
| Personal Site | Person, ProfilePage, WebSite, Article |
@context = "https://schema.org" (https, not http)@type is valid and not deprecated (§ 19)YYYY-MM-DD)For e-commerce schema additions (ProductGroup, Certification, OfferShippingDetails), recent schema types (2024–2026), and AEO schema (Sitelinks Searchbox, Speakable, Knowledge Panel sameAs), see references/schema-types.md.
→ See references/schema-types.md | Run scripts/validate_schema.py
| Update | Date | Impact |
|---|---|---|
| E-E-A-T universal | December 2025 | Applies to ALL competitive queries — not just YMYL |
| AI content quality | September 2025 QRG | AI content acceptable if genuine E-E-A-T; penalized without unique value |
| Helpful Content System merged | March 2024 | Merged into core algorithm — helpfulness weighted continuously |
references/eeat-framework.md for the full scoring framework and factor weights.Key insight: AI can mimic expertise but not fabricate genuine Experience. First-hand signals are the #1 E-E-A-T differentiator post-Dec 2025.
Don't: Recommend increasing word count as a standalone fix. Padding is a negative signal.
For the E-E-A-T scoring framework with factor weights, content quality minimums table, readability grade targets, and 2025 spam categories (expired domain abuse, site reputation abuse, scaled content abuse), see references/eeat-framework.md and references/content-eeat.md.
For the full 80-item CORE-EEAT content audit (8 dimensions, Pass/Partial/Fail scoring, content-type weight tables, 3 veto items, GEO Score vs. SEO Score), see references/core-eeat-framework.md. Use this for deep content quality assessments.
For the 40-item CITE domain authority audit (Citation/Identity/Trust/Eminence, domain-type weights, veto items that cap score at 39, Diagnosis Matrix for CITE × CORE-EEAT strategy), see references/cite-domain-rating.md. Use this for domain-level authority assessments.
→ See references/eeat-framework.md references/content-eeat.md references/core-eeat-framework.md references/cite-domain-rating.md | Run scripts/article_seo.py Run scripts/readability.py Run scripts/duplicate_content.py
For sites older than 2 years, content decay is often higher leverage than creating new content.
| Bucket | Criteria | Action |
|---|---|---|
| Refresh | Had impressions 12–16 months ago, traffic declined, topic still relevant | Update content, improve E-E-A-T, add question headings, update lastModified |
| Prune | < 10 impressions in 12 months, no backlinks, outdated | 301 redirect to most relevant page, then delete |
| Consolidate | Multiple pages covering the same topic | Merge into one strong page; redirect all others |
| Keep | Stable or growing traffic, strong E-E-A-T | Monitor monthly |
Don't: Prune pages with external backlinks without redirecting. Losing backlink equity from an unredirected prune is worse than keeping mediocre content.
For freshness thresholds by content type, see references/content-eeat.md.
→ See references/content-eeat.md
(Volume × Intent Value) / Difficulty — see references/keyword-strategy.md for the full formula with intent-weighted values and priority scoring matrix.| ✅ Good Target | ❌ Poor Target | Why |
|---|---|---|
| "project management software for remote teams" | "project management" | Too broad — DA 80+ players dominate |
| "best CRM for small business 2026" | "CRM software" | Specific + high commercial intent |
| "Salesforce alternatives for nonprofits" | "Salesforce" | Navigational — won't convert |
| "email marketing open rate benchmarks" | "email marketing" | Data opportunity vs. unreachable head term |
| Intent | Pattern | Content Format |
|---|---|---|
| Informational (TOFU) | "what is X", "how to X" | Pillar guide, how-to — create definitional anchor if missing |
| Commercial (MOFU/BOFU) | "best X", "X vs Y", "X alternatives" | Comparison, roundup — high commercial intent, often faster to rank |
| Transactional (BOFU) | "buy X", "X pricing", "free trial" | Landing page, pricing |
→ See references/keyword-strategy.md
Pillar: "Project Management Software" (3,500 words)
| Check | Status |
|---|---|
| Pillar receives most internal links from cluster? | ✅ Required |
| All cluster posts indexed? | ✅ Required |
| No two posts targeting the same primary keyword? | ✅ Required (cannibalization) |
AEO covers zero-click SERP features: Featured Snippets, PAA, Knowledge Panel, voice/speakable. Winning these directly feeds AI Overview and AI Mode citations.
## What is [Topic]?
[Topic] is [definition in 1 sentence]. It works by [mechanism in 1 sentence].
[1–2 sentences context. Total: 40–60 words.]
## How does [Topic] work?
[Direct answer in 40–60 words starting with the subject.]
For Knowledge Panel (sameAs schema), Sitelinks Searchbox (SearchAction code), Speakable schema, and voice search platform breakdown (Siri/Alexa use Bing, not Google), see references/schema-types.md → "AEO Schema" section.
[competitor-url]/robots.txt and [competitor-url]/llms.txt for GEO stance assessment. For topic coverage: run sitemap_checker.py [competitor-url] to confirm sitemap URL and reachability, then fetch the raw sitemap XML directly and read <loc> URL path patterns — folder-level segments absent from the audited site are direct content gap candidates.| Dimension | Opportunity Signal |
|---|---|
| Content depth gaps | Create the definitive resource on under-covered topics |
| Missing topic clusters | Map cluster and execute content plan |
| Schema advantages | Add missing schema immediately; reinforce where you have it |
| AI citation presence | If they're cited and you're not → audit GEO signals (§ 3) |
| E-E-A-T gaps | Leverage credentials where competitors use anonymous bylines |
| AI crawler configuration | If competitor blocks OAI-SearchBot or PerplexityBot in robots.txt → immediate GEO first-mover advantage. Run robots_checker.py [competitor-url]. Output labeled "External Observation Only." |
| llms.txt presence | If competitor lacks llms.txt → your llms.txt gives AI systems clearer indexing signal. Run llms_txt_checker.py [competitor-url]. Output labeled "External Observation Only." |
| Topic coverage gap (sitemap) | Fetch competitor's raw sitemap XML; <loc> URL path patterns absent from your site → direct content calendar input. Confirm sitemap reachability via sitemap_checker.py [competitor-url], then read raw <loc> entries. Output labeled "External Observation Only." |
## Competitive Landscape
| Dimension | [Your Site] | [Competitor 1] | [Competitor 2] |
## Top 3 Gaps to Close
## Top 3 Advantages to Exploit
## AI Citation Gap (if applicable)
## Recommended Comparison Pages to Create
For "X vs Y" and "Alternatives to X" page content requirements, the 4-type comparison page playbook (title formulas, fairness guidelines, CTA placement rules), feature matrix structure, and nominative fair use guidance, see references/link-building.md → "Comparison & Alternatives Page Playbook" section.
Internal linking first — highest leverage, zero cost. Always audit before recommending external acquisition.
| Rule | Standard |
|---|---|
| Orphan pages | Zero allowed — every indexed page needs 1+ internal link |
| Anchor text distribution | 40–50% branded, 15–20% naked URL, 5–10% exact match. >20% exact match = over-optimization |
| Internal nofollow | Remove — nofollow on internal links blocks PageRank flow |
| Link density | 3–5 contextual internal links per 1,000 words |
Don't: Recommend paid link schemes — violates Google's spam policy.
→ See references/link-building.md (CommonCrawl backlink API, comparison page requirements) | Run scripts/internal_links.py Run scripts/broken_links.py Run scripts/link_profile.py
gtag.js in page source. Missing → install and configure organic reporting.| Tool | Purpose |
|---|---|
| Google Search Console | Indexation, Performance, Core Web Vitals (field data) |
| GA4 | Organic sessions, engagement, conversions |
| PageSpeed Insights | Core Web Vitals field + lab data |
| Rank tracker | Weekly position tracking |
| Position | Expected CTR | Action |
|---|---|---|
| 1 | 27–39% | Rewrite title; test question format |
| 3 | 10–14% | Improve meta description; add rich result schema |
| 5 | 5–7% | Rewrite title + meta; optimize for featured snippet |
| 10 | 2–3% | Major content upgrade to push to top 5 |
AI traffic: Perplexity = perplexity.ai referral in GA4. ChatGPT = no referrer, appears as Direct.
→ See references/analytics-reporting.md
Rule of thumb: Crawl budget rarely matters for sites under 500 pages. Focus on content quality first.
site:domain.com in Google. Large discrepancy = investigation needed.noindex and a canonical tag.| Scenario | Fix |
|---|---|
| www vs. non-www | 301 redirect one to the other + canonical |
| HTTP vs. HTTPS | 301 redirect HTTP → HTTPS |
| URL parameters | Canonical → master page |
| noindex + canonical conflict | Use one or the other — never both |
Sitemap health: submitted/indexed ratio >90% = healthy; <70% = investigate content quality or canonicalization.
→ See references/crawl-indexation.md
Apply whenever the site is a local business, service area business, or has physical locations.
For review benchmarks (≥ 4.3 stars, ≥ 50 reviews, ≤ 30 days recency) and citation priority order, see references/local-seo.md.
| Threshold | Action |
|---|---|
| 30+ location pages | ⚠️ WARNING — each needs: local address, team, reviews, locally relevant content |
| 50+ location pages | 🛑 HARD STOP — city-name-only swap targeted by March 2024 Core Update |
Don't: Recommend fake reviews — GBP suspension risk.
→ See references/local-seo.md
<img> — alt text? Declared width/height? WebP format?fetchpriority="high" and NOT lazy-loaded.srcset and sizes on content images.| Element | Standard | Fix |
|---|---|---|
| Alt text | Descriptive, 10–125 chars | "[what + context]" e.g. "White ceramic mug on wooden desk" |
| Format | WebP preferred | Convert to WebP; AVIF for cutting-edge |
| File size | Thumbnails <50KB; content <100KB; heroes <200KB | Squoosh/Cloudinary; CDN compression |
| Responsive | srcset and sizes | Add multi-resolution srcset |
| Lazy loading | Below-fold only | Never lazy-load LCP image |
| Dimensions | width and height on all <img> | Prevents CLS |
| LCP image | fetchpriority="high" | <img fetchpriority="high" src="hero.webp"> |
Progressive enhancement:
<picture>
<source srcset="image.avif" type="image/avif">
<source srcset="image.webp" type="image/webp">
<img src="image.jpg" alt="Descriptive alt text" width="800" height="600"
loading="lazy" decoding="async">
</picture>
Don't: Add loading="lazy" to the LCP image.
→ See references/image-seo.md
rel="alternate".en-GB ✅ en-uk ❌ (region uppercase).<link rel="alternate" hreflang="x-default" href="[fallback-url]">.| Rule | Fix |
|---|---|
| Self-reference required | Add hreflang="[lang]" to own page |
| Return tags required | Audit all alternate pages |
x-default required | Add fallback URL tag |
| Chinese requires script qualifier | zh-Hans / zh-Hant ✅ — bare zh ❌ |
| Japanese code | ja ✅ — jp is a country code ❌ |
→ See references/international-seo.md | Run scripts/hreflang_checker.py
| Threshold | Action |
|---|---|
| >100 pages | ⚠️ WARNING — review content differentiation |
| >500 pages OR <30% unique content | 🛑 HARD STOP |
| <40% differentiation | Flag as thin content risk |
Don't: Approve city pages where only the city name changes — March 2024 Core Update target (60–80% traffic declines seen).
→ See references/programmatic-seo.md (12 playbooks taxonomy, data-asset-to-playbook decision matrix, data defensibility hierarchy, Scaled Content Abuse enforcement timeline with dates, uniqueness calculation formula, progressive rollout strategy)
| Phase | Timeframe | Focus |
|---|---|---|
| Foundation | Weeks 1–4 | Technical fixes, canonical strategy, analytics, essential schema |
| Expansion | Weeks 5–12 | Content creation (TOFU/MOFU/BOFU gaps), internal linking, Local SEO |
| Scale | Weeks 13–24 | Content clusters, link building, GEO optimization, image SEO |
| Authority | Months 7–12 | Thought leadership, digital PR, original research, Wikipedia entity |
Run through the full monthly maintenance checklist (5 categories: Technical Health, Content & Rankings, GEO/AI Search, Local SEO, Analytics Integrity) in references/analytics-reporting.md → "Monthly Maintenance Checklist" section. Key trigger: any page losing impressions for 3+ months → flag for content refresh (§ 6b).
→ See references/analytics-reporting.md
14 common SEO myths with Google's official positions are documented in references/analytics-reporting.md → "Myths & Misconceptions" section. Load when a user asks "does X help SEO?" or "is X a ranking factor?" Key myths to know without loading: meta keywords tag is ignored, word count has no minimum/maximum, Core Web Vitals are a tiebreaker not primary factor, E-E-A-T describes quality but is not a direct ranking factor.
→ See references/analytics-reporting.md
Global rules — apply across all sections.
After generating any Mode 1 audit output — before delivering it — run this internal evaluation pass. The purpose is to catch quality failures before the user sees them. If any criterion fails, revise before responding.
| # | Criterion | Pass Signal | Fail Action |
|---|---|---|---|
| 1 | Every Critical and High finding has an Evidence field from actual script output or verifiable page observation | Evidence: present on each | Add evidence or downgrade severity to Medium |
| 2 | No fabricated metrics | PSI/CrUX/LCP/CLS/INP numbers only appear if pagespeed.py returned JSON | Strip invented numbers; replace with "could not retrieve — verify at pagespeed.web.dev" |
| 3 | Health Score is supported by findings distribution | Critical = −15, High = −8, Medium = −3, Low = −1 applied | Recalculate or note discrepancy |
| 4 | Structured format used on every finding | Finding / Evidence / Impact / Fix / Confidence all present | Add missing fields |
| 5 | No duplicate findings | Run finding_verifier.py if available; manually check if not | Merge duplicates before scoring |
| 6 | Scope respected | Full audit only if user confirmed they own the site; Competitive Mode labeled "External Observation Only" | Re-label or scope down |
| 7 | Fix directives are actionable | Each fix names the specific element, file, or page to change | Rewrite vague fixes ("improve content") with exact instructions |
This pattern is adapted from Anthropic's Evaluator-Optimizer workflow — one pass generates, a second pass evaluates before output reaches the user.
Deprecated schema — Google removed rich result support for these types, so recommending them wastes implementation effort and confuses validation: HowTo (Sept 2023), SpecialAnnouncement (July 2025), ClaimReview (June 2025), Dataset (late 2025), VehicleListing (June 2025), Practice Problem (late 2025), EstimatedSalary (June 2025), LearningVideo (June 2025), EnergyConsumptionDetails (replaced by Certification, April 2025), CourseInfo (June 2025).
INP not FID — FID removed September 9, 2024. Referencing FID confuses users and dates the audit.
Mobile-first is complete — Mobile Googlebot for ALL sites since July 5, 2024.
E-E-A-T is universal — All competitive queries, December 2025.
AI citation ≠ ranking — 85% of pages ChatGPT retrieves are never cited. Being retrieved is necessary but not sufficient.
Mentions > Backlinks for AI — 0.664 vs. 0.218 correlation. Brand mentions on third-party platforms matter more than link building for AI citation.
Paid links risk manual action — violates Google's spam policy. Recommend earning links through content quality instead.
Fake reviews risk GBP suspension — Google actively detects fake review patterns. A suspended profile loses all local visibility.
Programmatic guardrails — Warn at 100+ pages; hard stop at 500+ or <30% unique content. Google's March 2024 Core Update specifically targets thin scaled content.
Blocking AI crawlers harms GEO — Blocking OAI-SearchBot/PerplexityBot removes the site from AI search results entirely.
GPTBot ≠ training only — Blocking it also limits ChatGPT Search citation. Users who block GPTBot expecting only training-opt-out lose live search visibility.
Site migration = any change to URL structure, domain, protocol, or CMS. High-risk — poor migrations cause 30–90% traffic loss.
| Migration Type | Risk Level |
|---|---|
| HTTP → HTTPS | Low |
| Subdomain → subdirectory | Medium |
| URL restructure (same domain) | Medium-High |
| Domain change | High |
| CMS platform change | High |
| Domain + URL structure change | Very High — never do both at once |
Pre-migration: Crawl current site (all URLs + canonicals); export 16 months of GSC data; create complete old URL → new URL redirect map; update all internal links; prepare new sitemap; add + verify new GSC property.
Migration day: Deploy all redirects as 301 (not 302); spot-check 20–30 URLs; submit new sitemap immediately; run GSC URL Inspection on key pages.
Post-migration: Monitor GSC Coverage for 404 spikes (Day 1–3); check impressions (Day 3–7); check key rankings (Week 2); benchmark at Day 30.
For the complete step-by-step checklists, common mistakes, and post-migration monitoring schedule, see references/site-migration.md.
→ See references/site-migration.md | Run scripts/redirect_checker.py
Run scripts as black boxes. Always try python scripts/<name>.py --help first to see usage and options. Do not read the script source code unless --help is insufficient and you need to customize behavior — script files are large and reading them wastes context tokens. They are designed to be invoked directly, not ingested.
There are 24 Python diagnostic scripts for URL/HTML checks, plus requirements-check.py (dependency preflight) and score_eval_transcript.py (regression scoring for evals/evals.json). check-plugin-sync.py is maintainers/CI only and is not copied into the plugin bundle. Every major audit step maps to a script — see references/audit-script-matrix.md. Merge duplicate findings with finding_verifier.py using references/finding-verifier-example.json as the JSON shape reference (optional references/finding-verifier-context-example.json for context).
They are not invoked via subagents in this skill file: the default path is one shell process — either generate_report.py (bundled pipeline, runs the URL + HTML checks below) or targeted python scripts/... --json calls. Optional: In clients that expose a Task/subagent tool, you may delegate independent script runs in parallel only when you are not already running generate_report.py for the same URL (avoid duplicate work). Merge subagent outputs in the main thread before scoring.
Run all individual URL checks in sequence (bash): bash scripts/run_individual_checks.sh https://example.com (prints JSON from each tool; for a single HTML dashboard use generate_report.py instead).
Full-site audits across many pages can fill the context window. When this happens:
[Section] Finding | Severity | Fix — one line per finding. This preserves all actionable information in minimal tokens.This is adapted from Anthropic's session memory compaction pattern, which uses background compaction + prompt caching to manage long-running agent conversations.
When the client exposes a Task/subagent tool (e.g., Cursor agents, Claude Code with parallel tool calls), scripts can be delegated as independent workers. The orchestrator (this skill) delegates, waits for all workers to complete, then synthesizes:
Orchestrator (this skill)
├── Worker A: python scripts/robots_checker.py → JSON findings
├── Worker B: python scripts/sitemap_checker.py → JSON findings
├── Worker C: python scripts/security_headers.py → JSON findings
└── Synthesize: merge all JSON → run finding_verifier.py → score
Hard constraints: Never delegate generate_report.py and individual script workers for the same URL simultaneously — they overlap and produce duplicate findings. Use one or the other. This pattern follows Anthropic's Orchestrator-Workers pattern.
Scripts require outbound network access. In sandboxed or proxy-restricted environments:
pagespeed.pywill fail (calls googleapis.com) → fallback: pagespeed.web.dev manually- All other scripts only access the target site directly and should work normally
- If any script fails with
ProxyError, use the manual checklist in the corresponding reference file
Evidence integrity: If pagespeed.py did not return JSON scores, do not invent PSI/CrUX/LCP/CLS/INP numbers in the narrative (same rule as § 2).
pip install -r requirements.txt
python scripts/generate_report.py https://example.com --output seo-report.html
Runs the bundled analysis pipeline (see §2): URL-based scripts, homepage HTML for validate_schema + image_checker, plus dashboard sections for schema, images, sitemaps, local signals, and IndexNow probe. Use at the start of any Mode 1 full audit.
For the complete script-to-section mapping (all 24 scripts with purpose and audit section), see references/audit-script-matrix.md.
# Validate schema after generating it
python scripts/validate_schema.py page.html --json
# Check AI crawler access
python scripts/robots_checker.py https://example.com
# Check llms.txt
python scripts/llms_txt_checker.py https://example.com
# Regression: score a transcript against eval fixtures
python scripts/score_eval_transcript.py --all-fixtures
Frameworks and sources this skill builds on:
| Source | Credit |
|---|---|
| Agentic-SEO-Skill (github.com/Bhanunamikaze) | Bhanunamikaze — SEO toolkit architecture, specialist agents, technical SEO audit framework |
| claude-seo (github.com/AgriciDaniel) | AgriciDaniel — GEO / DataForSEO patterns, AI crawler tables, subagent delegation |
| core-eeat-content-benchmark (github.com/aaron-he-zhu) | aaron-he-zhu — CORE-EEAT 80-item framework, weights, GEO-first mapping |
| cite-domain-rating (github.com/aaron-he-zhu) | aaron-he-zhu — CITE 40-item domain authority, weights, diagnosis matrix |
| Entity Optimizer (github.com/aaron-he-zhu) | aaron-he-zhu — entity checklist, AI entity resolution, Knowledge Graph guide |
| AI SEO / GEO Content Optimizer (github.com/aaron-he-zhu) | aaron-he-zhu — Princeton GEO data, engine preference mapping, citation-share data |
| Anthropic claude-cookbooks (github.com/anthropics/claude-cookbooks) | Anthropic — Evaluator-Optimizer pattern (§19 self-review), Progressive Disclosure architecture (§0), Orchestrator-Workers for parallel scripts (§21), Session Memory Compaction (§21), Citations pattern for GEO demonstration (§3) |