How to Set Up Codex E-E-A-T Content Analysis (Full SKILL.md Included)

---
name: codex-seo-content
description: Use when the user gives a URL or article and asks to evaluate content quality, E-E-A-T, readability, thin content, AI-citation readiness, who-how-why authority signals, byline trust, or whether a page justifies its rankings. Triggers on "content quality check", "is this content authoritative", "which page should I refresh", "E-E-A-T audit", "is this AI slop".
---
# Content Quality & E-E-A-T Analysis

One URL, two reports. The scanner fetches the page and collects the evidence;
you score the four E-E-A-T factors and the content mechanics against the
anchors below, then write the recommendations.

## Run

```bash
python3 ~/.codex/skills/codex-seo-content/scripts/content_scan.py <url> [--json]
```

The scanner reports words, sentences, words-per-sentence, average paragraph
length, an estimated Flesch reading ease score, primary-keyword guess
(two first non-generic title words) and whether it appears in the first 100
words, H1/H2 counts, internal/external link counts, quotable sentences with
numbers or attributed claims, images/videos/table-of-contents presence,
author meta, Person schema, byline text, datePublished, and trust signals
(contact, privacy policy, email/phone, address).

Content behind login or client-side-rendered shells cannot be judged from
raw HTML. Say so and analyze only what the HTML proves.

## Google's "Who / How / Why" test

Every page passes Google's own three-question heuristic first (helpful-content
guide):

| Question | What to look for |
|---|---|
| **Who** created it? | Visible byline, author bio page, credentials. Required where readers expect it; non-negotiable for YMYL. |
| **How** was it created? | Process disclosure where readers would reasonably ask, especially for AI-assisted content. Original research, first-hand evidence, lived experience. |
| **Why** does it exist? | "To help people" rather than "to attract clicks". Watch for niche entry without expertise, churn for freshness signals, content written to a word-count target. |

When all three answers are weak, the page is at risk under the core ranking
system's helpfulness signals (merged into core during the March 2024 update).

## E-E-A-T framework (Sept 2025 QRG; currency-checked 2026)

E-E-A-T is a concept in the Quality Rater Guidelines, not a direct ranking
score. Trust is the most important member of the family; Experience,
Expertise, and Authoritativeness support the assessment of Trust.

### Experience (20% of this skill's score) - first-hand signals

- Original research, case studies, before/after results
- Personal anecdotes, process documentation, "I tested this"
- Unique data, proprietary insights
- Photos/screenshots from direct experience (not stock)

Strong: multiple first-hand signals. Moderate: some evident. Weak: generic,
no personal touch. None: clearly AI-generated or scraped.

### Expertise (25%) - demonstrated knowledge

- Author credentials, certifications, bio
- Technical accuracy and depth appropriate for the audience
- Claims supported by evidence or sources
- Specialized vocabulary used correctly; up to date with the field

Strong: verified credentials, deep accuracy. Moderate: demonstrable
knowledge. Weak: surface-level, no credentials. None: factual errors.

### Authoritativeness (25%) - recognition by others

- Site and author recognized in the niche
- Content cited by other authoritative sources
- Industry awards, consistent publication history, media coverage

Strong: widely cited. Moderate: some external validation. Weak: no external
recognition. None: known for misinformation.

### Trustworthiness (30%) - most important

- Clear contact info (address, phone, email)
- Privacy policy, terms of service, return/refund policy
- HTTPS with valid certificate
- Transparent about who creates content and why
- Visible corrections and update history
- No deceptive practices (hidden ads, clickbait, back-button hijacking)

Strong: full transparency. Moderate: good signals, minor gaps. Weak: missing
key signals. None: deceptive practices, scam indicators.

The weight split (20/25/25/30) is this skill's own scoring model. Google
publishes no numbers, only that trust is most important - so do not use an
equal 25/25/25/25 split. Overall bands: 90+ exceptional, 70-89 strong,
50-69 moderate, 30-49 weak, 0-29 very low with trust issues.

## Content metrics

### Word count floors (coverage floors, not targets)

| Page type | Floor |
|---|---|
| Homepage | 500 |
| Service page | 800 |
| Blog post | 1,500 |
| Product page | 300+ (400+ for complex products) |
| Location page | 500-600 |

Word count is NOT a direct ranking factor. These are topical-coverage floors:
a 500-word page that completely answers the query outranks a 2,000-word page
that doesn't. Flag thin pages, never recommend padding to hit a number.

### Readability

- Flesch reading ease 60-70 for a general audience (scanner estimates it)
- Average sentence 15-20 words; paragraphs 2-4 sentences
- Flesch is NOT a direct ranking factor either (Google confirms it doesn't
  use basic readability scores). It is a content-quality indicator: a page at
  20 (dense legalese) or 90 (sentence fragments) for a general audience is a
  usability concern, not an SEO emergency.

### Keyword and structure

- Primary keyword in title, H1, first 100 words; natural 1-3% density plus
  semantic variations; no stuffing
- Logical heading hierarchy, descriptive headings, bullets where appropriate,
  table of contents for long-form content

### Links and multimedia

- 3-5 relevant internal links per 1,000 words, descriptive anchors, no
  orphans
- Cite authoritative external sources; reasonable count

## Low-quality AI content markers (QRG, Sept 2025)

AI authorship itself is not penalized. Raters assess patterns:

- Generic phrasing without specificity
- No original insight or unique perspective
- No first-hand experience signals
- Factual inaccuracies
- Repetitive structure across pages
- No author attribution

"Using generative AI tools to generate many pages without adding value" is
explicitly named under scaled content abuse (spam policy, 2026-05-15). Human
oversight and unique value are the difference.

## AI citation readiness

For ChatGPT, Perplexity, Google AI Overviews, and AI Mode:

- Clear, quotable statements with statistics or facts (the scanner lists
  sentences containing digits, percentages, or attributed claims)
- Answer-first formatting for key questions; strong H1->H2->H3 flow
- Tables and lists for comparative data, structured data for data points
- First-party research is the most-cited material

Per Google's official AI optimization guide (2026-06-29), AEO/GEO is a
rebranded label for SEO grounded in the same quality systems, and you do not
need new AI files, markup, or AI-specific rewrites. Never claim a structured
data change "earns AI citations" - that is not a documented guarantee.

## Freshness

- Publication date visible; date modified if revised (scanner reports it)
- Flag content older than 12 months without an update in fast-changing topics

## Output contract

```
Content Quality Score:        XX/100
AI Citation Readiness:        XX/100

E-E-A-T Breakdown
| Factor            | Score | Key signals |
|-------------------|-------|-------------|
| Experience        | XX/20 | ... |
| Expertise         | XX/25 | ... |
| Authoritativeness | XX/25 | ... |
| Trustworthiness   | XX/30 | ... |

Issues (with priority) -> Recommendations
```

Every recommendation gets the prove-it check. Examples: "add a byline, then
verify it appears in the rendered article on the live URL"; "add dateModified,
then check the JSON-LD - if Google's crawler shows the old date, say so and
re-request indexing"; "add author credentials to the bio page, then confirm
that page links from the post and the bio is linked in the footer".

## Errors

| Scenario | Action |
|---|---|
| URL unreachable | Report the error, never guess content |
| 402/403 or login wall | Analyze only visible meta and headers, note the limitation |
| Under ~100 words retrievable | Report as-is, flag possible JS rendering, ask for the full text |
| Keyword guess off | Say the guess is heuristic and ask for the real primary keyword |

#!/usr/bin/env python3
"""Content quality and E-E-A-T signal collector. Standard library only."""

import html as htmlmod
import json
import re
import sys
import urllib.error
import urllib.request

TIMEOUT = 15
UA = ("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
      "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36 "
      "codex-seo-content/1.0")


def fetch(url):
    req = urllib.request.Request(url, headers={"User-Agent": UA})
    try:
        resp = urllib.request.urlopen(req, timeout=TIMEOUT)
        return resp.status, resp.geturl(), resp.read().decode("utf-8", "replace")
    except urllib.error.HTTPError as e:
        return e.code, url, ""
    except Exception as e:
        return "ERR:" + str(e), url, ""


def syllables(word):
    w = re.sub(r"[^a-z]", "", word.lower())
    if not w:
        return 0
    groups = len(re.findall(r"[aeiouy]+", w))
    if w.endswith("e") and groups > 1 and not w.endswith("le"):
        groups -= 1
    return max(groups, 1)


def main():
    url = sys.argv[1] if len(sys.argv) > 1 else ""
    if not url:
        print("usage: python3 content_scan.py <url> [--json]")
        sys.exit(1)
    want_json = "--json" in sys.argv
    if not url.startswith("http"):
        url = "https://" + url
    status, final, html = fetch(url)
    r = {"url": url, "status": status, "final_url": final}
    if not html:
        r["error"] = "no HTML body; status=" + str(status)
        print(json.dumps(r, indent=2) if want_json else r["error"])
        sys.exit(0 if status == 200 else 1)

    def m(p):
        return re.findall(p, html, re.I)

    text = re.sub(r"(?is)<script.*?</script>|<style.*?</style>|<pre.*?</pre>|<code.*?</code>|<[^>]+>", " ", html)
    text = htmlmod.unescape(re.sub(r"\s+", " ", text).strip())
    words = text.split()
    sentences = [s for s in re.split(r"(?<=[.!?])\s+", text) if len(s.strip()) > 8]
    syl = sum(syllables(w) for w in words)
    wc, sc, words_per_sent = len(words), max(len(sentences), 1), len(words) / max(len(sentences), 1)
    flesch = 206.835 - 1.015 * words_per_sent - 84.6 * (syl / wc) if wc else 0

    paras = [p for p in m(r"(?is)<p[^>]*>(.*?)</p>") if len(re.sub(r"<[^>]+>", " ", p).split()) > 3]
    para_words = [len(re.sub(r"<[^>]+>", " ", p).split()) for p in paras]

    # keyword: assume primary phrase = first two non-generic title words
    title = (m(r"<title[^>]*>([^<]+)</title>") or [""])[0]
    tkw = title.split()
    kw = " ".join([w for w in tkw if w.lower() not in ("a", "an", "the", "how", "to", "in", "of", "&", "and")][:2])
    first100 = " ".join(words[:100]).lower()

    quotes = [s.strip() for s in sentences if re.search(r"\d|%|£|\$|€| from | by ", s)]
    quotes = [q for q in quotes if len(q) < 240][:6]

    domain = re.search(r"https?://([^/]+)", final)
    dom = domain.group(1) if domain else ""
    links = m(r'<a\s[^>]*href=["\']([^"\']+)["\']')
    internal = [l for l in links if l.startswith("/") or dom in l]
    external = [l for l in links if l not in internal and l.startswith("http")]

    trust = {
        "privacy_policy": bool(re.search(r"(?i)\bprivacy\s*policy\b", text) or
                               re.search(r"privacy", " ".join(links))),
        "contact": bool(re.search(r"(?i)\bcontact\b", text)),
        "email_or_phone": bool(re.search(r"[\w.+-]+@[\w-]+\.[\w.-]+|\+?\d[\d\s()-]{6,}\d", text[:3000])),
        "address": bool(re.search(r"(?i)\b(addr(ess)?|street|suite)\b", text[:3000])),
    }

    dates = m(r'(?i)(?:datePublished|pub_date|published_time|dateModified|modified_time)\s*["\']?\s*[:>]?\s*["\']?([\d-]{4,10})')
    h1 = m(r"<h1[^>]*>")
    h2 = m(r"<h2[^>]*>")
    toc = bool(re.search(r"(?i)\b(table of contents|toc|contents)\b", text[:2000])) or \
        bool(re.search(r'href=["\']#[\w-]+["\']', html))

    r["content"] = {
        "words": wc,
        "sentences": len(sentences),
        "words_per_sentence": round(words_per_sent, 1),
        "avg_paragraph_words": round(sum(para_words) / len(para_words), 1) if para_words else 0,
        "flesch_reading_ease": round(flesch, 1),
        "primary_keyword_guess": kw,
        "keyword_in_first_100": kw.lower() in first100 if kw else False,
        "h1_count": len(h1), "h2_count": len(h2),
        "quotable_sentences": quotes,
    }
    r["links"] = {
        "internal": len(internal),
        "external": len(external),
        "internal_per_1000_words": round(1000 * len(internal) / wc, 2) if wc else 0,
    }
    r["multimedia"] = {"images": len(m(r"<img\b")), "videos": len(m(r"<video\b|<iframe\b")),
                       "toc_or_anchor_nav": toc}
    r["eeeat"] = {
        "author_meta": m(r'<meta[^>]+name=["\']author["\'][^>]+content=["\']([^"\']{1,120})["\']'),
        "person_schema": [t for t in m(r'"@type"\s*:\s*"([A-Za-z]+)"') if t in ("Person", "Author")],
        "byline_present": bool(re.search(r"(?i)\b(autho?red by|written by)\b", text)),
        "date_published": dates[0] if dates else None,
        "trust_signals": trust,
    }
    if want_json:
        print(json.dumps(r, indent=2))
    else:
        c = r["content"]
        print("content_scan %s" % r["url"])
        print("  words %d  sentences %d  %.1f w/s  para %d w  flesch %s" %
              (c["words"], c["sentences"], c["words_per_sentence"],
               c["avg_paragraph_words"], c["flesch_reading_ease"]))
        print("  kw guess: %r  in first 100: %s  h1 x%d h2 x%d" %
              (c["primary_keyword_guess"], c["keyword_in_first_100"],
               c["h1_count"], c["h2_count"]))
        print("  links: %d internal (%.1f/1000w), %d external" %
              (r["links"]["internal"], r["links"]["internal_per_1000_words"], r["links"]["external"]))
        print("  media: img %d video %d toc %s | date %s | author %s" %
              (r["multimedia"]["images"], r["multimedia"]["videos"],
               r["multimedia"]["toc_or_anchor_nav"], r["eeeat"]["date_published"],
               r["eeeat"]["author_meta"] or r["eeeat"]["person_schema"] or "-"))
        print("  trust: " + ", ".join(k for k, v in r["eeeat"]["trust_signals"].items() if v) or "  none of privacy/contact detected")


if __name__ == "__main__":
    main()

mkdir -p ~/.codex/skills/codex-seo-content/scripts
# save the two files above at:
#   ~/.codex/skills/codex-seo-content/SKILL.md
#   ~/.codex/skills/codex-seo-content/scripts/content_scan.py
python3 ~/.codex/skills/codex-seo-content/scripts/content_scan.py https://example.com

content_scan https://auspia.ai/blog/codex-seo-technical-audit
  words 2409  sentences 108  22.3 w/s  para 55 w  flesch 50.9
  kw guess: 'Audit Technical'  in first 100: True  h1 x1 h2 x27
  links: 61 internal (25.3/1000w), 2 external
  media: img 16 video 0 toc False | date 2026-08-28 | author -
  trust: privacy_policy, contact

Content Quality Score:        76/100
AI Citation Readiness:        71/100

E-E-A-T Breakdown
| Factor            | Score | Key signals |
|-------------------|-------|-------------|
| Experience        | 15/20 | First-person walkthrough, real scan output shown |
| Expertise         | 21/25 | Technical threshold details, primary-source citations |
| Authoritativeness | 16/25 | Series context, no external recognition signals |
| Trustworthiness   | 24/30 | Privacy + contact site-wide, date present; no structured byline |

Priority fixes:
High - add author meta + Person schema to article pages
Medium - trim longest sentences, target Flesch 60+
Low - add last-updated date under the headline

Read the two code fences marked "The full SKILL.md" and "The scanner script" above.
1. Create ~/.codex/skills/codex-seo-content/SKILL.md with the full content of the SKILL.md fence.
2. Create ~/.codex/skills/codex-seo-content/scripts/content_scan.py with the full content of the script fence.
3. Run: python3 ~/.codex/skills/codex-seo-content/scripts/content_scan.py https://example.com
4. If that works, run the same scan on my own site and produce the full Content Quality + E-E-A-T report with scores and prioritized fixes.
Do not install or modify any other files.