/seo-page

name: seo-page
description: >
  Analyze one supplied URL across on-page, content, technical metadata, schema,
  images, and performance. Use only for a single-page review.
user-invocable: true
argument-hint: "[url]"
license: MIT
metadata:
  author: AgriciDaniel
  version: "2.6.0"
  category: seo

Single Page Analysis

Step 1: Run the Deterministic Checks

Run this first. It does the mechanical on-page checks in code, so they are repeatable and you do not recount them from the HTML by hand:

`"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run page_checks.py --url <url>`

For saved HTML (no network request; `--headers-json` is optional):

`"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run page_checks.py --file page.html --base-url <url> --headers-json headers.json`

For a JavaScript-rendered page, save the rendered HTML first with `"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run fetch_page.py <url> --render auto --output page.html`, then use `--file`.

The JSON holds `facts` (lengths and counts), `findings` (each with a stable `id`, a `severity`, a `message` and the `evidence` that triggered it), `not_checked`, `thresholds`, and a `summary` count per severity. An `X-Robots-Tag` rule addressed to a crawler other than Googlebot is not a finding; it is listed in `facts.x_robots_other_agents`, so mention it when the user cares about that crawler. It covers 47 checks:

| Area | Finding ids | |------|-------------| | Title, description | `missing-title`, `title-too-long`, `title-too-short`, `missing-meta-description`, `meta-description-too-long`, `duplicate-meta-tags` | | Headings | `missing-h1`, `multiple-h1`, `heading-level-skip` (main content only) | | Canonical, robots | `missing-canonical`, `canonical-points-elsewhere`, `og-url-differs-from-canonical`, `noindex`, `noindex-header`, `nofollow`, `meta-refresh-redirect`, `hreflang-missing-self` | | Document basics | `missing-doctype`, `missing-charset`, `charset-mismatch`, `missing-lang`, `missing-viewport`, `uses-frames`, `deprecated-html-tags`, `placeholder-text` | | Images | `images-missing-alt`, `images-missing-dimensions`, `first-image-lazy-loaded` | | Links | `links-without-text`, `generic-anchor-text`, `links-to-http`, `mixed-content` | | URL | `url-too-long`, `url-has-parameters`, `url-uppercase`, `url-underscores`, `url-non-ascii`, `url-double-slash` | | Size | `html-over-2mb`, `deep-dom`, `wide-dom-node` | | Social, schema | `missing-open-graph`, `missing-og-image`, `invalid-jsonld` | | Content | `title-not-reflected-in-content`, `description-not-reflected-in-content`, `thin-content` |

How to use the result:

• Take every length, count and id from the JSON. Do not recount by hand and do

not re-derive a check the script ran. An id that appears in neither `findings` nor `not_checked` passed.

• Your work is judgment: decide whether each finding matters for this page and

explain why in plain language, quoting the evidence. A `noindex` on a thank-you page is intended, `thin-content` on a contact page is fine, and `multiple-h1` rarely matters on its own.

• `severity` is the script's default (Critical, High, Medium, Low, as in

Issues Found below). Raise or lower it when the page context justifies it, and say why.

• The length thresholds (`thresholds`, from quality-gates.md) are

display-truncation heuristics. Google publishes no title or description length limit: say "may be truncated in results", never "too long for Google".

• `not_checked` lists checks that could not run (no response headers with

`--file`; word counts on Chinese, Japanese or Thai text). Report them as not checked, never as passed.

• `word_count` is checked against one type-blind floor. Compare it with the

page type minimum in quality-gates.md yourself.

• If the script prints `{"error": ...}` and exits non-zero, follow Error

Handling below.

The sections below list everything a page review covers. Where the script has a finding id for an item, use its result; the rest still needs your own analysis.

What to Analyze

On-Page SEO

• Title tag: 30-60 characters (see quality-gates.md), includes primary keyword, unique
• Meta description: 120-160 characters (see quality-gates.md), compelling, includes keyword
• Meta description is not a restatement of the title: run

`"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run metadata_template.py --title "<title>" --description "<desc>" --json` (heuristic, deterministic string comparison). A description that opens by repeating its own title and closes on a stock CTA ("Try it free now.", "Start free!") is templated metadata, the shape bulk generation jobs produce site-wide, and duplicated or templated metadata is a documented content-quality problem regardless of how original the body copy is

• H1: exactly one, matches page intent, includes keyword
• H2-H6: logical hierarchy (no skipped levels), descriptive
• URL: short, descriptive, hyphenated, no parameters
• Internal links: sufficient, relevant anchor text, no orphan pages
• External links: to authoritative sources, reasonable count

Content Quality

• Word count vs page type minimums (see quality-gates.md)
• Readability: Flesch Reading Ease score, grade level
• Keyword use: natural use of the topic, entities, and variations; no target density (Google publishes none); flag unnatural repetition as keyword stuffing
• E-E-A-T signals: author bio, credentials, first-hand experience markers
• Content freshness: publication date, last updated date

Technical Elements

• Canonical tag: present, self-referencing or correct
• Meta robots: index/follow unless intentionally blocked
• Open Graph: og:title, og:description, og:image, og:url
• Twitter Card: twitter:card, twitter:title, twitter:description
• Hreflang: if multi-language, correct implementation

Schema Markup

• Detect all types (JSON-LD preferred)
• Validate required properties
• Identify missing opportunities
• Never recommend HowTo (deprecated) or FAQ for rich results (retired May