Aeo SEO Site Audit

AEO & Content Analysis Skill (Ahrefs Complement)

This skill analyzes content quality, JSON-LD schema validation, and AEO (Answer Engine Optimization) for pages you specify. It complements Ahrefs Site Audit (which handles technical SEO) by focusing on aspects that require content analysis and AI-readiness assessment.

Use this skill when Ahrefs Site Audit cannot:

• Validate JSON-LD schema completeness and correctness
• Assess content quality and depth
• Evaluate how well pages answer user questions directly
• Identify authority/expertise signals
• Recommend AI-friendly content restructuring
• Assess natural language optimization
• Flag citability gaps

When to Use This Skill

Trigger this skill when the user:

• Has run an Ahrefs Site Audit and wants to go deeper on content
• Asks "why isn't my content ranking for [query]?"
• Wants to "optimize for AI search" or "ChatGPT search"
• Asks "how do I get cited by AI" or "appear in AI overviews"
• Wants to "improve schema markup for content types"
• Asks "how can I make my content more AI-friendly?"
• Wants "content quality analysis" beyond technical SEO

Core Workflow

Steps 1-2. [Coordinator] Gather Input — get URLs, Ahrefs project ID (optional), business context Steps 3–8. [Haiku Agents] Fetch Ahrefs data (if provided) + extract entity/structure signals + crawl pages + content gap analysis Steps 9–16. [Sonnet Agent] Validate schema, assess entity/cluster authority, analyze content quality, prioritize gaps, generate report

Agent Architecture

Coordinator (main Claude)

Handles Steps 1–2: gathers user input and orchestrates the two agents. Passes URLs + Ahrefs project ID to the Haiku agent(s), then passes all Haiku output payloads to the Sonnet agent.

Haiku Research Agents

• One agent per URL, launched in parallel
• One additional agent for the Ahrefs API call (if project ID provided)
• Job: mechanical data extraction only — no analysis or judgment
• Output: structured JSON payload per URL (see Haiku Output Contract section below)

Sonnet Synthesis Agent

• Single agent, runs after all Haiku agents complete
• Receives all Haiku JSON payloads + Ahrefs data
• Job: schema validation, content analysis, gap prioritization, report writing
• Output: final report

Environment Detection

Before starting the audit, check which tools are available and adjust accordingly:

Note: JSON-LD extraction is NOT optional. Audits claiming "no schema found" without explicit JSON-LD extraction attempts are incomplete and inaccurate. Always verify schema presence before reporting it as missing.

Critical: Distinguish "Crawlable" from "Indexable"

⚠️ Modern Googlebot executes JavaScript. A site with empty static HTML (SPA, client-side rendering) may still be indexed by Google. The presence of a <div id="root"></div> does NOT mean the site is "not indexed."

Crawlable = Static HTML contains content (good for all crawlers, fastest for Googlebot) Indexable = Google can find and index the content (true even if JS-rendered; Googlebot waits for JS execution) Optimal for AI crawlers = Static HTML with schema markup (most AI answer engines have limited JS execution)

Do not conclude a site is "not indexed" based solely on static HTML analysis. Always verify actual indexing status first (see Step 1 below).

COORDINATOR

Step 1: Gather Input & Verify Indexing Status

Ask the user for:

Required:

• Target URLs or Local Files: The pages or codebase files to analyze.
  • If user provides live URLs: Proceed with the multi-agent web crawling in Steps 2-8.
  • If user asks you to audit a local codebase (e.g., within Claude Code): Skip Steps 2 through 8. Use your file reading tools to inspect the source files directly, extract schema/structure, and begin your evaluation directly at Step 9.

⚠️ Before proceeding, verify actual Google indexing status:

If user reports the site is "not indexed":

1. Ask: "Have you checked Google Search Console coverage report?" or "Have you tried site:yourdomain.com in Google search?"
2. If uncertain, recommend they verify using:
   • Google Search Console (Coverage > Indexed pages)
   • site:yourdomain.com search operator
   • Google's URL Inspection tool (one specific URL)
3. Do not assume a site is unindexed based on static HTML analysis alone. Modern Googlebot executes JavaScript and can index SPAs.
4. If the site is actually indexed, note this in the report's findings — the audit focus shifts to crawlability, AI-friendliness, and schema optimization (not indexing recovery).

Optional:

• Ahrefs Project ID (recommended): If you have Ahrefs Site Audit set up, provide the project ID
  • Skill will automatically fetch technical audit findings (titles, H1s, broken links, crawl issues, etc.)
  • Report combines Ahrefs technical findings + this skill's content/AEO analysis
  • No need to manually export/attach CSV—we pull directly from Ahrefs API
• Business context: What does the site do? What keywords/topics matter most?
• Content goals: Are you targeting AI search engines (ChatGPT, Perplexity, AI Overviews)?
• Current pain points: "Content not ranking well" / "Low AI citations" / "Thin content" etc.

Note: This skill complements Ahrefs Site Audit (which checks titles, meta descriptions, H1 tags, broken links, etc.). Focus here is content depth, schema, and AEO.

Step 2: Orchestrate Agents

After gathering input, launch Haiku agents in parallel using the Task tool — one per URL, plus one for the Ahrefs API call if a project ID was provided, plus one site-level agent for entity signals (Step 4), site structure (Step 5), and content gap analysis (Step 6). Do not wait for one to finish before launching the next.

For each URL in target_urls:
  Task(
    subagent_type: "general-purpose",
    model: "haiku",
    prompt: <full HAIKU AGENT — Per-URL instructions, Steps 6 + 7 + 8> + "\n\nURL to process: {url}"
  )

# Site-level agent (runs once, not per URL)
Task(
  subagent_type: "general-purpose",
  model: "haiku",
  prompt: <HAIKU AGENT — Site-Level instructions, Steps 4 + 5> + "\n\nBrand name: {brand_name}\nHomepage: {homepage_url}"
)

If ahrefs_project_id provided:
  Task(
    subagent_type: "general-purpose",
    model: "haiku",
    prompt: <HAIKU AGENT — Ahrefs instructions, Step 3> + "\n\nProject ID: {ahrefs_project_id}"
  )

Collect all Task results. Once every Haiku agent has returned its JSON payload, proceed to the SONNET AGENT section.

HAIKU AGENT — Ahrefs (optional, one agent per audit)

Step 3: Fetch Ahrefs Audit Issues (Optional)

If user provided an Ahrefs project ID, pull technical audit findings:

# Use Ahrefs MCP to fetch Site Audit issues
ahrefs_issues = site_audit_issues(
    project_id=user_project_id,
    date=None  # Get latest crawl
)

# Parse issues by type:
# - Title/meta description issues
# - H1/heading hierarchy issues
# - Broken links
# - Mobile optimization issues
# - Crawlability issues
# Store for reference in final report

If user doesn't have Ahrefs project ID:

• Skip this step
• Continue with content-only analysis

HAIKU AGENT — Site-Level (one agent per audit)

Step 4: Entity Signal Extraction

Run once per audit (not per URL). Extract signals that establish whether the brand is recognized as a trusted entity by AI systems.

Checks:

# 1. Google Knowledge Panel — fetch SERP for brand name
curl -s -A "Mozilla/5.0" "https://www.google.com/search?q=[Brand+Name]" | python3 -c "
import sys; html = sys.stdin.read()
print('knowledge_panel_detected:', 'kp-wholepage' in html or 'knowledge-panel' in html)
"

# 2. Wikipedia presence
curl -s -o /dev/null -w "%{http_code}" "https://en.wikipedia.org/wiki/[Brand_Name]"
# 200 = exists, 404 = not found

# 3. sameAs in Organization schema (from homepage JSON-LD already extracted)
# Check if any sameAs value contains: linkedin.com/company, wikidata.org, wikipedia.org

Output — add to Haiku payload (site-level, run once):

"entity_signals": {
  "knowledge_panel_detected": false,
  "wikipedia_exists": false,
  "wikipedia_url": null,
  "linkedin_sameas_present": false,
  "wikidata_sameas_present": false,
  "organization_schema_present": false,
  "nap_fields_found": ["name", "url"],
  "nap_consistent_across_pages": null
}

NAP consistency: Extract name, url, address, telephone from Organization schema on each page. Flag if values differ across pages.

Cross-platform consensus proxy: If Ahrefs data available, count referring domains that are news/media/industry sites (not directories). Store count as authoritative_referring_domains.

Step 5: Site Structure Sampling

Run once per audit. Goal: map content cluster architecture to assess topical authority.

Steps:

1. Fetch /sitemap.xml (or check robots.txt for sitemap URL). Parse all URLs.
2. Group by path segment (e.g., /blog/, /guides/, /learn/).
3. For each section: identify if a pillar/index page exists (path depth 1) vs sub-pages (depth 2+).
4. Fetch homepage HTML → extract top-level <nav> links.
5. For each pillar page found: count internal links to sub-pages and from sub-pages back to pillar.

Output — add to Haiku payload (site-level):

"site_structure": {
  "sitemap_found": true,
  "total_urls_in_sitemap": 87,
  "content_sections": [
    {
      "section": "/blog/",
      "pillar_page_exists": false,
      "sub_page_count": 34,
      "internal_links_to_pillar": 0
    }
  ],
  "nav_links": ["About", "Blog", "Pricing"],
  "orphaned_pages_detected": true
}

If sitemap not found, attempt to discover sections from homepage navigation links only. Note the limitation.

HAIKU AGENT — Per-URL (one agent per URL)

Step 6: Content Gap Analysis (SERP Fallback — skip if Ahrefs available)

If Ahrefs project ID provided: Use Ahrefs Content Gap tool instead. Pass competitor keyword gaps as content_gap.gap_subtopics in the payload.

If no Ahrefs access: For each target URL, run SERP-based gap analysis:

# 1. Infer primary keyword from page H1/title (already extracted in Step 4)
# 2. Fetch Google SERP for that keyword
curl -s -A "Mozilla/5.0" "https://www.google.com/search?q=[primary+keyword]" | python3 << 'EOF'
import sys, re
html = sys.stdin.read()
# Extract People Also Ask questions
paa = re.findall(r'data-q="([^"]+)"', html)
# Extract top organic result URLs (first 3)
urls = re.findall(r'href="/url\?q=(https://[^&"]+)', html)[:3]
print("PAA:", paa[:8])
print("Competitor URLs:", urls)
EOF

# 3. For each competitor URL, fetch and extract H2/H3 headings
curl -s "[competitor_url]" | python3 -c "
import sys, re
html = sys.stdin.read()
headings = re.findall(r'<h[23][^>]*>([^<]+)</h[23]>', html)
print(headings)
"

Output — add to per-URL Haiku payload:

"content_gap": {
  "primary_keyword_inferred": "best project management tools",
  "method": "serp_fallback",
  "paa_questions": ["What is the best PM tool for small teams?"],
  "competitor_subtopics": ["Integrations", "Pricing comparison", "Free tier breakdown"],
  "subtopics_covered_on_page": ["Features", "Pricing"],
  "gap_subtopics": ["Integrations", "Free tier breakdown"]
}

Diff logic: gap_subtopics = competitor_subtopics − subtopics_covered_on_page (fuzzy match on keywords, not exact string).

Step 7: Crawl Target Pages, Extract JSON-LD & Content Signals

⚠️ CRITICAL: JSON-LD extraction is mandatory on every page. Do ONE fetch per URL (not two) to ensure efficiency.

⚠️ CRITICAL: When analyzing static HTML, distinguish between:

• "Empty static HTML" (JS-rendered SPA): Does NOT mean "not indexable by Google." Modern Googlebot executes JavaScript. However, it DOES mean poor crawlability for other crawlers (Bingbot, AI answer engines, feed readers).
• "No content in static HTML": Valid finding for crawlability audit. Report it as a crawlability gap, not an indexing problem.

For each target URL, extract all raw signals in a single pass. This step combines fetching, JSON-LD extraction, and content signal extraction.

Environment Detection & Fetch Strategy

Before fetching, detect which tools are available:

• Claude Code (Bash available): Use curl to fetch raw HTML, extract JSON-LD and content signals immediately
• Claude Web (WebFetch only): Use web_fetch, JSON-LD will be stripped during conversion

Fetch & Extract Implementation

If Bash is available (Claude Code):

curl -s "https://example.com" 2>&1 | python3 << 'EOF'
import sys, re, json
html = sys.stdin.read()
# Find all JSON-LD blocks
blocks = re.findall(r'<script[^>]*type=["']application/ld\+json["'][^>]*>(.*?)</script>', html, re.DOTALL)
extracted_jsonld = []
if blocks:
  for i, block in enumerate(blocks):
    try:
      data = json.loads(block.strip())
      extracted_jsonld.append(data)
      print(f"=== JSON-LD Block {i+1} ===")
      print(json.dumps(data, indent=2))
    except json.JSONDecodeError as e:
      print(f"Error parsing JSON-LD block {i+1}: {e}")
else:
  print("No JSON-LD found")
EOF

If only WebFetch is available (Claude Web):

result = web_fetch(url, text_content_token_limit=50000)
# Note: JSON-LD is stripped during conversion. Store HTML as-is.
# Extracted schema will be empty; will note limitation in report.

Content Elements to Extract (from stored HTML)

# Parse from stored HTML:
- Total word count of main content
- Paragraph structure and sentence complexity
- Lists (<ul>, <ol>) and tables
- Presence of FAQ sections, direct answers to questions
- Formatting: bold, code blocks, callouts
- Links: internal links, citation links, source attribution
- Images: presence of descriptive captions

Authority & Freshness Signals to Extract (from stored HTML)

# Look for in stored HTML:
- Author information (name, title, credentials)
- Publication date (<meta name="article:published_time"> or datePublished in schema)
- Last updated date (dateModified or "Updated:" text)
- Organization/author credentials or bio
- External citations and source links

Extract Internal Links from Stored HTML

# From stored HTML, extract <a href="..."> where:
- href starts with "/" or contains the same domain
- Not pointing to: #anchors, mailto:, tel:, javascript:, files (.pdf, .jpg, etc.)
- Not duplicate URLs
# Store for optional content sampling (Step 5)

Step 8: Required Representative Sampling

To ensure consistent, reproducible findings, crawl at least 2 representative pages per page type present on the site. This sampling is required — not optional. Skipping dynamic or category pages is the most common cause of missed critical findings (CSR rendering gaps, listing schema gaps).

Page types to identify and sample:

Sampling rules:

• Review the user-specified URLs and identify which types are already covered
• For each type not yet covered, find and add 1–2 pages of that type (crawl the homepage, check nav links, or follow href patterns like /discover/, /blog/, /products/)
• For dynamic pages: fetch with curl regardless; if content is missing from raw HTML, that is a finding (CSR gap), not a reason to skip
• Maximum 10 additional pages beyond user-specified URLs
• If fetch fails, include the URL with "error": "..." — do not omit it

For each sampled page: Use Step 7 methodology (environment-aware fetch + JSON-LD extraction + content signal extraction, store HTML for parsing).

Haiku Output Contract

Each Haiku agent outputs one JSON payload per URL. This is the only data the Sonnet agent receives — it never accesses raw HTML.

{
  "url": "https://example.com/page",
  "status_code": 200,
  "fetch_method": "curl",
  "json_ld_blocks": [
    { "@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [...] }
  ],
  "json_ld_extraction_attempted": true,
  "word_count": 847,
  "headings": [
    { "level": "h1", "text": "..." },
    { "level": "h2", "text": "..." }
  ],
  "has_lists": true,
  "has_tables": false,
  "has_code_blocks": false,
  "faq_sections_detected": 2,
  "author_markup_found": true,
  "author_text": "Jane Smith, Senior Editor",
  "date_fields_found": ["datePublished"],
  "date_modified_found": false,
  "external_citation_links": 3,
  "internal_links": ["https://example.com/related-page"],
  "image_count": 4,
  "images_with_captions": 2,
  "content_gap": {
    "primary_keyword_inferred": "...",
    "method": "serp_fallback",
    "paa_questions": [],
    "competitor_subtopics": [],
    "subtopics_covered_on_page": [],
    "gap_subtopics": []
  },
  "ahrefs_issues": [],
  "entity_signals": {
    "knowledge_panel_detected": false,
    "wikipedia_exists": false,
    "wikipedia_url": null,
    "linkedin_sameas_present": false,
    "wikidata_sameas_present": false,
    "organization_schema_present": false,
    "nap_fields_found": [],
    "nap_consistent_across_pages": null
  },
  "site_structure": {
    "sitemap_found": false,
    "total_urls_in_sitemap": 0,
    "content_sections": [],
    "nav_links": [],
    "orphaned_pages_detected": false
  },
  "token_usage": {
    "model": "claude-haiku-4-5-20251001",
    "input_tokens": 0,
    "output_tokens": 0
  }
}

Notes:

• json_ld_extraction_attempted must always be true — never report "no schema found" without attempting extraction
• If fetch failed, include "status_code": null and "error": "..." — do not omit the URL from results
• ahrefs_issues is populated only on the Ahrefs agent payload, not per-URL
• token_usage must be populated by every Haiku agent. Use the actual token counts from the API response metadata if available; otherwise estimate based on prompt + output length.

SONNET AGENT

The Sonnet agent receives all Haiku JSON payloads and the Ahrefs issues data. It never fetches URLs. All analysis, judgment, and report writing happens here.

Token tracking: At the end of your output, include your own token usage:

{
  "sonnet_token_usage": {
    "model": "claude-sonnet-4-6",
    "input_tokens": 0,
    "output_tokens": 0
  }
}

Use actual API response metadata if available; otherwise estimate from input/output length.

Step 9: Schema Validation

Using JSON-LD blocks from Haiku payloads:

• Check if schema type matches content type (FAQPage for FAQs, Article for blog posts, etc.)
• Identify missing required fields (author, datePublished, answer properties, etc.)
• Flag schema that doesn't match visible content signals (e.g., FAQPage present but faq_sections_detected: 0 in payload)

Do not validate "no schema found" without confirming json_ld_extraction_attempted: true in the Haiku payload.

Step 10: Entity Layer Assessment

Using entity_signals from the Haiku payload. This is the foundation — if the brand isn't recognized as an entity, schema and content improvements have limited AEO impact.

Fix guidance:

• Add Organization schema with sameAs array pointing to LinkedIn, Wikipedia (if exists), Wikidata, and Crunchbase
• To earn a Knowledge Panel: ensure Wikipedia article exists or claim Google Business Profile; build consistent brand mentions on authoritative external sites
• NAP inconsistency: standardize name, url, address across all page-level Organization schema

Step 11: Content Cluster Assessment

Using site_structure from the Haiku payload. Topical depth through clustering is how AI systems assess subject matter authority — individual pages aren't enough.

Checks:

• ❌ Content section has 5+ sub-pages but no pillar/index page (sub-articles floating without a hub)
• ❌ Pillar page exists but internal_links_to_pillar: 0 (cluster is broken — sub-pages don't reinforce the hub)
• ❌ orphaned_pages_detected: true — pages in sitemap not reachable from navigation
• ❌ Sitemap not found — AI crawlers can't discover full content scope
• ✅ Each content section has a pillar page + 3+ supporting sub-articles with bidirectional internal linking

Priority: 🔴 Critical if a key topical section has 5+ pages with no pillar. 🟡 Important for linking gaps and orphaned content.

Step 12: Schema Markup & Structure Validation

Analyze all crawled pages for JSON-LD completeness and AEO readiness:

Schema Validation (HIGH PRIORITY)

Missing Schema for Content Type:

• ❌ FAQ/Q&A content with no FAQPage schema
• ❌ Articles with no Article or BlogPosting schema
• ❌ How-to content with no HowTo schema
• ❌ Product pages with no Product schema
• ❌ Organization pages with no Organization schema
• ❌ Reviews with no Review or AggregateRating schema
• ✅ Good: Schema matches content type with all required properties

Incomplete Schema:

• ❌ FAQPage present but missing author, datePublished, or mainEntity
• ❌ Article missing datePublished or author information
• ❌ Schema properties incomplete or marked with placeholder values
• ✅ Good: Schema has all required fields + recommended fields (author, date, description)

Schema Quality:

• ❌ Schema doesn't match visible content (e.g., FAQPage claims 10 Q&As but page shows 3)
• ❌ Nested schema incorrectly structured (e.g., Answer not properly nested in Question)
• ✅ Good: Schema structure is valid and matches content accurately

Content Structure for AI (MEDIUM PRIORITY)

Direct Answer Formats:

• ❌ Content doesn't answer main question in first paragraph
• ❌ Answers buried in prose; no clear Q&A or summary
• ✅ Good: First sentence answers the question; FAQ/TL;DR at top

Scannable Formatting:

• ❌ Content is all prose; no lists, tables, or visual breaks
• ❌ No numbered steps for how-to content
• ✅ Good: Bulleted lists, comparison tables, numbered steps, short paragraphs

Topic Coherence:

• ❌ Content jumps between unrelated subtopics
• ❌ Sections don't connect logically
• ✅ Good: Clear section topics; content flows logically; related pages linked

Step 13: Content Quality and Structure (SEO and AEO)

Evaluate all content for SEO quality and AEO (Answer Engine Optimization)—how well it serves both traditional search engines and AI systems like ChatGPT, Perplexity, and Google AI Overviews.

Topic Coverage & Clarity

User Intent & Comprehensiveness

• ❌ Content doesn't clearly address the stated topic (from title/H1)
• ❌ Content is too shallow for user intent
• ✅ Good: Comprehensive coverage matching search intent
• ✅ Good: First paragraph directly answers the main question

Content Gap Analysis (from content_gap payload field)

• ❌ PAA questions unaddressed — list each specific unanswered question (e.g., "Page doesn't answer: 'What is the best PM tool for small teams?'")
• ❌ Competitor subtopics missing — list specific H2/H3 gaps vs top 3 ranking pages
• ✅ Good: Page covers all identified PAA questions and matches competitor subtopic depth
• Note the method used: serp_fallback (less precise, no volume data) vs ahrefs_content_gap (with keyword volume)

Direct Answer Formats (AEO Priority)

• ❌ Content doesn't answer specific questions directly; answers buried in prose
• ❌ No summary or abstract at the beginning
• ✅ Good: Clear questions as H2/H3 headings with immediate answers
• ✅ Good: Executive summary or TL;DR at top; definitions early in content
• ✅ Good: FAQ sections with explicit Q&A format

Keyword & Semantic Usage

Keyword Placement

• ❌ Target keywords missing or poorly placed
• ✅ Good: Keywords naturally used in title, H1, H2s, and first paragraph
• ✅ Good: Related/semantic keywords present throughout

Content Originality & Specificity

• ❌ Generic, thin content; only rehashed information
• ✅ Good: Original research, specific examples, data, or expert analysis
• ✅ Good: Matches user intent (informational vs. commercial vs. transactional)

Content Structure & Scannability

Heading Hierarchy & Descriptiveness

• ❌ Flat structure, generic headings, skipped heading levels
• ✅ Good: Descriptive headings that can stand alone; logical H2 → H3 progression
• ✅ Good: Each section addresses one clear subtopic

List-Based & Semantic Structure (AEO Priority)

• ❌ Information only in prose; no lists, comparisons, or checklists
• ❌ Content jumps between unrelated topics
• ✅ Good: Key points in numbered/bulleted lists; comparison tables; checklists
• ✅ Good: Content stays focused; related subtopics logically connected
• ✅ Good: Short paragraphs with varied formatting for scannability

Schema Markup for AI Extraction (CRITICAL) These are the #1 issues AI systems care about. Verify schema extraction before marking as missing.

• ❌ No FAQ schema on Q&A content (major AEO issue)
• ❌ No HowTo schema for step-by-step guides
• ❌ Missing Article/BlogPosting schema with author, date, and structure
• ❌ Missing Organization schema on homepage
• ❌ No BreadcrumbList schema for navigation
• ✅ Good: FAQPage schema with complete Q&A pairs
• ✅ Good: HowTo schema with HowToStep items
• ✅ Good: Article/BlogPosting with author info and publication dates
• ✅ Good: Organization, BreadcrumbList, or other relevant schema types

Authority & Citability (AEO Priority)

Expertise & Author Signals

• ❌ No author information, credentials, or expertise signals
• ✅ Good: Author bio with relevant credentials; "Written by [Name], [Title]"
• ✅ Good: Author schema markup

Source Attribution & Evidence

• ❌ Claims without sources or supporting links
• ✅ Good: Direct links to original sources and citations
• ✅ Good: "According to [Source], ..." format; statistics and data attributed

Freshness Indicators

• ❌ No date information; outdated without update signals
• ✅ Good: Clear publish date and "Last updated: [date]" for freshness
• ✅ Good: datePublished and dateModified in schema; references recent information

Experience Proof (AEO Priority)

AI systems deprioritize content they could have generated themselves. Score on three dimensions using content signals from the Haiku payload:

• ❌ Zero firsthand evidence — AI deprioritizes content it could generate itself
• ❌ All statistics link to aggregators (Forbes, HubSpot roundups) not primary sources — indirect citations reduce citability
• ✅ Named examples + quantitative outcomes present (e.g., "Acme reduced churn by 23% using X")

Natural Language Optimization (AEO Priority)

Conversational & Accessible Language

• ❌ Overly technical jargon, corporate speak, or fragmented sentences
• ✅ Good: Explains concepts in plain language; answers like a human would
• ✅ Good: Complete sentences with necessary context; can extract any paragraph and it makes sense
• ✅ Good: Uses "you" to address the reader; includes clear definitions

Topic Coherence

• ❌ Content jumps between unrelated topics; no clear focus
• ✅ Good: Each section connects logically to others
• ✅ Good: Internal links to related topics on separate pages

Content Patterns for AI (AEO Priority)

Identify and optimize for AI-friendly formats:

• How-To Content: "How to [task]" format, numbered steps, time estimates, prerequisites
• Comparison Content: "[X] vs [Y]" titles, side-by-side tables, pros/cons, clear recommendation
• Definitive Guides: "Complete Guide" or "Everything You Need to Know" format, table of contents, multi-section coverage
• Best/Top Lists: "Best [X] for [Use Case]" format, clear ranking criteria, descriptions with reasoning

Priority Summary

Step 14: Authority & Citability Assessment

Evaluate how well pages establish expertise and enable AI systems to cite the content.

Author Credibility Signals

Observable signals:

• ❌ No author information on any page
• ❌ Author listed but no credentials, title, or bio
• ❌ No author schema markup (Author property in schema)
• ✅ Good: Author name + title/credentials visible; Author schema present

Impact on AEO: AI systems check author credibility before citing. Missing author signals = low citability.

Source Attribution & Citations

Observable signals:

• ❌ Claims made without sources or supporting links
• ❌ Statistics cited without attribution ("trusted data" but no link to source)
• ❌ No distinction between original data and curated information
• ✅ Good: Direct links to sources; "According to [Source]" format; statistics attributed
• ✅ Good: Original research/data clearly marked; methodology explained

Impact on AEO: AI systems prioritize citing well-sourced content. Direct links increase citability.

Freshness Indicators

Observable signals:

• ❌ No publication or update date visible
• ❌ Outdated information without update signals
• ❌ No datePublished or dateModified in schema
• ✅ Good: Clear "Published [date]" and "Updated [date]" visible
• ✅ Good: datePublished and dateModified in schema; content references recent data

Impact on AEO: AI systems deprioritize stale content. Dates signal ongoing relevance.

Expertise Depth

Observable signals:

• ❌ Shallow coverage; content could be written by anyone
• ❌ No evidence of specialized knowledge or experience
• ⚠️ Good domain knowledge but not explicitly stated
• ✅ Good: Domain expertise evident (specific examples, methodology, credentials)
• ✅ Good: Depth of coverage exceeds surface-level information

Step 15: Prioritize Content & AEO Gaps

Group all identified issues into three priority tiers:

🔴 High Priority (Critical for AEO)

Issues that significantly impact AI citability and content quality:

• No Organization schema (AI has no machine-readable brand identity — entity layer foundation missing)
• No Knowledge Panel + no Organization schema (brand not recognized as a trusted entity by AI)
• Content section with 5+ sub-pages but no pillar page (no topical authority hub; AI can't assess depth)
• Missing schema for content type (e.g., no FAQPage on FAQ content, no Article on blog posts)
• No author/expertise signals (missing author name, credentials, or author schema)
• Content doesn't directly answer main question (answer buried in prose)
• Missing publication date (no datePublished in schema or visible date)
• Incomplete schema (FAQPage present but missing required fields like author, question, answer)

🟡 Medium Priority (Improves AEO)

Issues that enhance content quality and extractability:

• Missing Wikipedia page or sameAs schema links (LinkedIn, Wikidata not cross-referenced — entity recognition incomplete)
• NAP inconsistency across pages (conflicting Organization schema signals reduce AI confidence)
• Pillar page exists but sub-pages don't link back (broken cluster; topical authority signal diluted)
• Orphaned pages (in sitemap but unreachable from navigation)
• Content gaps vs competitors (PAA questions unaddressed; competitor subtopics missing)
• Zero firsthand evidence or original data (content is replicable by AI; low citability)
• Thin content (<300 words for informational pages; missing depth vs competitors)
• No source citations (claims made without supporting links or attribution)
• Only prose formatting (no lists, tables, or scannable structure for how-to/comparison content)
• Missing dateModified (no update signal for content refresh)
• Poor topic structure (content jumps between topics; sections not logically connected)
• Complex language (jargon-heavy without explanations; not conversational)

🟢 Low Priority (Enhancements)

Nice-to-have improvements:

• Add comparison/HowTo schema (improves featured snippets and AI citations)
• Improve conversational tone (makes content more readable and extractable)
• Add specific examples and data (supports claim substantiation for AI search)
• Internal linking to related topics (improves content coherence and crawlability)

For each issue, include:

• What's wrong: Clear description (e.g., "FAQ schema incomplete—missing 'answer' field in Q&A pairs")
• Why it matters: Specific AEO impact (e.g., "AI systems can't extract answers without complete schema")
• How to fix: Specific steps (e.g., "Add 'answer' property to each Q&A item in FAQPage schema")
• Affected pages: URLs with this issue
• Estimated effort: Quick (<30 min), Moderate (1-3 hours), Major (4+ hours)

Step 16: Generate Content & AEO Report

Create a well-structured document (markdown or docx) with:

Executive Summary

• Tone: Analytical and data-driven (see TONE-GUIDE.md)
• Total pages analyzed
• Google indexing status (if reported as problem): Clearly state whether actual indexing was verified via GSC/site: operator or if this is based on crawler simulation analysis. Important distinction: "Static HTML shows no crawlable content (gap for non-Google crawlers)" vs. "Not indexed by Google (requires GSC verification)."
• Summary of Ahrefs findings (if available): "Ahrefs identified X technical issues across Y pages"
• Overall AEO readiness score (based on schema, content, authority signals)
• Top 3-5 critical gaps (prioritized by AEO impact and effort)
• Estimated improvement: "With these changes, content will be 40-50% more extractable by AI systems"
• Total research cost: $— (one line; full breakdown in Token Usage appendix at end of report)

Prioritized Recommendations

Writing style for recommendations: See TONE-GUIDE.md for detailed style guidelines. Key principles:

• Use neutral language without dramatic framing
• Quantify impact with specific data
• Avoid vague benefits (no "better SEO" without specifics)
• Explain mechanisms and provide realistic effort estimates

What to include:

• All 🔴 Critical issues and 🟡 Important issues — no cap, no omissions
• Top 3 🟢 Enhancement items, selected by highest impact
• If more than 3 enhancements were identified, append: > _N additional enhancements not listed — see Priority Summary for full list._

Priority tiers:

Order within each tier by impact × effort. Begin with a summary table — one row per recommendation — then list full details for each item below the table.

Summary table (one row per recommendation):

Detailed recommendations (one section per item, matching table order):

For each item:

• What to do: Specific, actionable instruction with affected page count or URLs
• Why it matters: Data-backed impact (e.g., "Affects 8 of 11 pages" / "Missing schema blocks AI extraction")
• Category: Technical SEO / Content / AEO / Information Architecture / Content Presentation
• Effort: Quick (<30 min) / Moderate (1–3 hrs) / Major (4+ hrs)

Detailed Findings

Writing style guidelines: See TONE-GUIDE.md. Key principles:

• State issues factually without editorializing
• Explain specific mechanism of impact
• Use metrics: "3 of 11 pages" not "some pages"
• Distinguish between content quality and schema completeness

Entity & Brand Authority

• Knowledge Panel status (detected vs not)
• Wikipedia and Wikidata presence
• sameAs cross-platform links in Organization schema
• NAP consistency across pages
• Authoritative referring domain count (if Ahrefs data available)

Site Structure & Content Clusters

• Sections with pillar pages vs floating sub-articles
• Internal linking gaps (pillar → sub and sub → pillar)
• Orphaned pages (sitemap vs navigation reachability)
• Sitemap presence and coverage

Schema Markup Gaps

For each page/content type:

• Missing or incomplete schema (e.g., "FAQPage present but 3 of 10 Q&As missing 'answer' field")
• Affected pages (X of Y total)
• Impact on AEO (e.g., "AI systems can't cite answers without complete schema")
• Specific fix (e.g., "Add 'answer' property to all Question items")

Content Quality Issues

• Thin content vs competitors (word count, depth analysis)
• Content gap analysis: PAA questions unaddressed, competitor subtopics missing (list specific gaps per URL)
• Experience proof gaps: zero firsthand evidence, statistics only from aggregator sources, no replication barrier
• Dire

…(truncated)