seo-audit

• The user says: "audit this page", "check SEO", "analyze my URL", "quick SEO check", "what's wrong with my page"
• No specific depth is requested — this is the default entry point
• The user needs a fast, readable summary rather than a comprehensive technical breakdown

seo-audit-full

Tip: For deep technical audits, advanced on-page SEO, or full reports, use the

seo-audit-full

skill.

Limitation: This audit is based on visible page content and publicly available signals only. Source code, GSC data, crawl logs, and performance metrics are not available for this audit.

Each script exits with code `0` (all pass/warn) or `1` (any fail/error).

**STRICT SCOPE — do not add any check not listed below. No exceptions.**

Allowed site-level checks (in `{{site_checks_html}}`):
- robots.txt · sitemap.xml · 404 Handling · URL Canonicalization · i18n / hreflang

Allowed E-E-A-T checks (in `{{eeat_checks_html}}`):
- About Us · Contact · Privacy Policy · Terms of Service · Media/Partners (only if present)

Allowed page-level checks (in `{{page_checks_html}}`), output in this exact order:
PageSpeed (Mobile) · PageSpeed (Desktop) · URL Slug · Title Tag · Meta Description · H1 Tag · Canonical Tag · Image Alt Text · Word Count · Keyword Placement · Heading Structure · Internal Links · Schema (JSON-LD)

  Image Alt Text logic:
  - Parse <img> tags from static HTML
  - Pass: all images have non-empty alt (decorative images with alt="" are OK)
  - Warn: any content image missing alt attribute
  - Unverified (status-info): 0 images found in static HTML → likely JS-rendered, cannot verify

⛔ HARD RULE — Output ONLY the check rows defined in report-template.html.
If a check is not in the allowed lists above, do NOT output it — not even if you find issues.
No exceptions. No "bonus" checks. No improvisation.
The template is the single source of truth. Treat it as a strict whitelist.

Still BANNED (belong to seo-audit-full): OG tags · Twitter Card · Social tags · Page Weight · Core Web Vitals · Robots Meta

**How to use the JSON output:**
- Map each field's `status` → `pass` / `warn` / `fail` / `error` directly to the report check table
- Use each field's `detail` string as the starting point for the Evidence line in findings
- Do not contradict the script output unless you have additional observable evidence
- Separate check groups with `<div class="subsection-label">Label</div>` inside `{{site_checks_html}}`:
  `Crawlability` · `URL Canonicalization` · `i18n / hreflang` · `Schema (JSON-LD)`
  and `<div class="subsection-label">E-E-A-T Trust Pages</div>` before `{{eeat_checks_html}}`

**LLM review — mandatory when `llm_review_required: true`:**

The script flags fields that require semantic or quality judgment it cannot perform.
Never leave `llm_review_required: true` unresolved — always make an explicit judgment call.

**H1 — triggered when `keyword_match == "partial"`:**

• Consider synonyms, natural variants, topic coverage
• yes → downgrade to "pass", note the variant
• no → keep "warn" or upgrade to "fail", explain the gap

**Title — triggered when `keyword_match == "partial"` OR `keyword_position != "start"`:**

1. Does the title semantically cover the keyword's search intent?
2. Is the title grammatically correct and naturally readable?
3. Keyword position — apply different standards by page type:
   • Homepage : Brand + core keyword is correct (e.g. "Acme | AI Workflow Automation") Do NOT flag brand-first as a problem.
   • Inner pages: Core keyword should lead (e.g. "AI Workflow Automation for Teams — Acme") Flag if keyword is buried mid-title without good reason.

• Years (e.g. "2026") → signal freshness, increase CTR — treat as positive unless the page is explicitly evergreen content where dating would hurt longevity.
• Numbers (e.g. "5 best", "Top 10", "3 steps") → set clear expectations, consistently outperform non-numeric titles in CTR — always treat as a plus.
• Specific qualifiers ("Open-Source", "Self-Hosted", "Free") → narrow intent and attract higher-quality clicks — do not penalize.

**URL Slug — triggered when `keyword_match != "full"` or `is_homepage == false`:**

1. Does the slug contain the primary keyword or a natural variant?
2. Is the path hierarchy logical? (/category/keyword is ideal)
3. Is it concise and human-readable? Homepage (is_homepage: true): skip — no judgment needed.

**Meta Description — always triggered when content is present:**

1. Complete sentence(s)? (1-2 sentences, no fragments)
2. Mentions a concrete result — not vague fluff? Good: "Cut design time by 60% with AI-powered templates" Bad: "The best tool for all your design needs"
3. Keyword or natural synonym used once — not stuffed?
4. More specific than what a typical competitor would write?

• Years (e.g. "2026") → signal freshness, improve CTR for time-sensitive queries. Only note the year if the page is explicitly evergreen content where dating hurts.
• Numbers (e.g. "5 best", "3 steps") → concrete specificity, strong CTR signal.
• Trailing "and more." → minor style note at most, never a Warning or Fail.

---

1. Acknowledge scope — confirm this is a basic audit; note any missing data
2. Infer primary keyword — fetch the page with

   fetch-page.py

   , then determine the primary keyword:
   • If the user explicitly provided a keyword → use it directly
   • If not → read the page H1, title, and first paragraph, then infer the single most likely target keyword phrase (what would a searcher type to find this page?)
   • State the inferred keyword explicitly before running checks:

     "Inferred primary keyword: open source claude alternatives"

3. Run

   check-site.py

   — parse the JSON output for robots, sitemap, 404 handling, and URL canonicalization
   404 check: fetch

   <origin>/this-page-definitely-does-not-exist-seo-audit-check

   • Returns 404 → Pass · Returns 200 (soft 404) → Fail · Returns 301 to homepage → Warn
   URL Canonicalization checks (each is a separate sub-check):
   • HTTP→HTTPS: fetch

     http://<host>

     — must 301 to

     https://

     . Returns 200 → Fail.
   • www consistency: fetch both

     https://www.<host>

     and

     https://<host>

     — one must 301 to the other. Both return 200 → Warn.
   • Trailing slash: compare the URL actually served vs the canonical tag on the page. Mismatch → Warn.
   • Canonical match: canonical tag href must exactly match the final URL after all redirects. Mismatch → Warn.
4. E-E-A-T infrastructure check — for each trust page below, check two layers:
   • Layer 1 — Exists: fetch the URL, check HTTP status (200 = exists, 404/redirect = missing)
   • Layer 2 — Reachable: fetch homepage HTML, check if footer or nav contains a link to this page

   Page	Required
   About Us	Yes
   Contact	Yes
   Privacy Policy	Yes
   Terms of Service	Yes
   Media / Partners	No — include only if present

   Status rules:
   • Page missing (non-200) → Fail
   • Page exists but not linked in footer/nav → Warn
   • Page exists and linked in footer/nav → Pass
   • Optional page missing → skip, do not include row
5. Run

   check-pagespeed.py <url>

   — fetch PageSpeed Insights scores for mobile + desktop
   Thresholds (different per category and strategy):

   Category	Desktop Pass	Mobile Pass	Warn	Fail
   SEO	100	100	90–99	< 90
   Best Practices	100	100	90–99	< 90
   Accessibility	100	100	90–99	< 90
   Performance	≥ 90	≥ 80	Desktop 80–89 / Mobile 70–79	Desktop < 80 / Mobile < 70

   Output two rows in

   {{page_checks_html}}

   : PageSpeed (Mobile) and PageSpeed (Desktop)
6. Run

   check-page.py --keyword "<inferred_keyword>"

   — parse the JSON output for H1, title, meta description, canonical, and URL slug
7. i18n / hreflang check — only run if the page contains hreflang tags or

   <html lang>

   suggests multi-language:
   • Skip entirely (N/A) if no hreflang tags found and site appears single-language
   • If hreflang tags present, check:
     • Reciprocal symmetry: every URL referenced must link back to all other variants — any broken link = Fail
     • Language codes: must be valid BCP 47 (e.g.

       zh-CN

       not

       zh

       ,

       en-US

       not

       en-us

       ) — wrong code = Warn
     • x-default: should be present for language-selector or fallback pages — missing = Warn
     • html[lang] attribute: must match the primary hreflang of the page — mismatch = Warn
     • URL structure: recommended pattern — default language (usually

       en

       ) at root with no prefix, other languages under subpaths (

       /zh/

       ,

       /es/

       ).

       • /page

         (en) +

         /zh/page

         +

         /es/page

         → Pass

       • /en/page

         +

         /zh/page

         → Warn (en prefix is redundant, wastes crawl depth)
       • Only flag if the pattern is clearly inconsistent or en is unnecessarily prefixed
8. Run

   check-schema.py

   — parse the JSON output for schema types and field validation
   bash

   python scripts/check-schema.py https://example.com
   # Or from previously fetched HTML:
   python scripts/check-schema.py --file page.html

   The script extracts JSON-LD blocks, validates

   @type

   and required fields per Schema.org spec.

   llm_review_required: true

   is always set — confirm

   inferred_page_type

   matches actual page content.
   Page type → expected

   @type

   reference:

   Page Type	Expected @type	Min. required fields
   Homepage	WebSite + Organization	name, url, logo
   Blog / Article	Article or BlogPosting	headline, datePublished, author, image
   Product	Product	name, image, offers (price, priceCurrency)
   FAQ	FAQPage	mainEntity[].name, acceptedAnswer.text
   How-to	HowTo	name, step[].text
   Local business	LocalBusiness	name, address, telephone
   Generic landing	—	N/A — skip, no widely-supported type

   • Pass: correct @type present, all required fields valid, no conflicts
   • Warn: @type present but missing recommended fields
   • Fail: expected @type missing entirely
   • N/A: generic landing page — do not penalize
9. Summarize findings — each finding must follow the Evidence / Impact / Fix format
10. Priority actions — list the top 3 highest-impact fixes
11. Render report — save to

    reports/<hostname>-<slug>-audit.html

    , then ask user to open
12. Upgrade prompt — if issues beyond basic scope are found, suggest

    seo-audit-full

Want a deeper analysis? This was a basic SEO audit covering site-level signals and core on-page checks. For advanced technical SEO, content quality scoring, structured data analysis, and full crawl-based findings, use the

seo-audit-full

skill.

• Detailed audit scope and field definitions: references/REFERENCE.md
• Final HTML report template: assets/report-template.html
• Site-level check script: scripts/check-site.py
• Page-level check script: scripts/check-page.py
• Raw page fetcher: scripts/fetch-page.py
• Schema validation script: scripts/check-schema.py