references/REFERENCE.md

GitHub

seo-audit — Reference Guide

This document provides detailed field definitions, audit scope, edge case guidance, and agent instructions for the seo-audit basic SEO audit skill.


Positioning

seo-audit is the default, lightweight entry point for SEO auditing. It covers the most essential SEO signals that can be assessed quickly, without requiring source code access, crawl data, or performance tooling.

Target audience:

  • Users doing a first-pass check on a page
  • Clients who want a readable summary, not a technical report
  • Scenarios where only the live URL is available

Not suitable for:

  • Deep technical audits (use seo-audit-full)
  • Multi-page site audits
  • Audits requiring performance tooling, GSC data, crawl logs, or CWV metrics

Script + LLM Division of Responsibility

The check-page.py script uses a two-layer design for H1 keyword analysis:

Layer Who What
Layer 1 Script Mechanical checks: uniqueness, length, full/partial/no string match
Layer 2 Agent (LLM) Semantic judgment: does H1 cover the keyword's search intent?

When h1.llm_review_required == true: The script found a partial string match (e.g. keyword = "AI computer", H1 = "Best Personal AI"). It cannot determine if this qualifies as a valid natural variant — that requires language understanding. The agent must read h1.values[0] + the keyword and judge:

  • Does the H1 semantically cover the keyword's search intent?
  • Would a user searching for this keyword consider this H1 relevant?
  • Is this a natural variant (acceptable) or a keyword gap (needs fix)?

keyword_match field values:

Value Meaning LLM action required
"full" Keyword string found verbatim in H1 None
"partial" At least one keyword word (>3 chars) found Yes — semantic judgment
"none" No keyword words found None — flag as missing
"unverified" No --keyword passed None — note as unverified

Audit Scope — What Basic Report Checks

Site-Level Checks

Check What to Verify Pass Condition
sitemap.xml Does {domain}/sitemap.xml return a valid XML sitemap? HTTP 200, valid XML, at least one <url> entry
robots.txt Does {domain}/robots.txt exist? Any obvious blocking rules? HTTP 200, no Disallow: / for Googlebot

How to check:

  • Attempt to fetch {url_origin}/sitemap.xml and {url_origin}/robots.txt
  • If the page URL is the only available input, note that site-level checks rely on public accessibility

Edge cases:

  • Sitemap may be referenced in robots.txt under Sitemap: directive — check both
  • Some sites use non-standard paths (e.g. /sitemap_index.xml) — note this as a finding if the default path fails
  • If robots.txt is inaccessible (non-200), flag as a moderate issue

Page-Level Checks

Check What to Verify Pass Condition
H1 uniqueness Is there exactly one <h1> on the page? Exactly 1 H1 tag present
H1 content Does the H1 reflect the page's primary topic? H1 is descriptive and keyword-relevant
Title tag Is <title> present, non-empty, and within 50–60 characters? Present, 50–60 chars recommended
Meta description Is <meta name="description"> present and within 120–160 characters? Present, 120–160 chars recommended
Canonical tag Is <link rel="canonical"> present and pointing to the correct URL? Present, self-referencing or correct canonical

Basic audit scope note: The above checks represent the current basic audit scope. Additional checks (performance metrics, Core Web Vitals, social tags, etc.) are out of scope for this skill — use seo-audit-full.


Trigger Keywords

This skill should activate when the user says (among others):

  • "audit this page"
  • "check my SEO"
  • "quick SEO check"
  • "analyze this URL"
  • "what SEO issues does this page have"
  • "SEO report" (without specifying depth)
  • "page audit"
  • "check my meta tags"

Agent Instructions

Output quality rules

  1. Be specific. Never say "the title tag could be improved." Say: "The title tag is 82 characters, exceeding the recommended 60-character limit. Truncation in SERPs may reduce click-through rates."
  2. Evidence first. Always ground findings in observable evidence before stating impact.
  3. Mark assumptions clearly. If you cannot verify a check due to missing data, write: [ASSUMPTION] or [UNVERIFIED] next to the finding.

Handling missing data

If source HTML is unavailable:

"On-page checks are based on rendered page content only. Results may differ if the page relies on JavaScript rendering or server-side logic not visible in the public response."

If site-level checks fail due to access restrictions:

"Site-level checks (sitemap, robots.txt) could not be completed. The domain may restrict public access to these files, or a firewall/CDN may be blocking automated requests."

Scope escalation — when to recommend seo-audit-full

Suggest upgrading to seo-audit-full when:

  • More than 3 issues are found that require deeper investigation
  • User mentions: performance metrics, Core Web Vitals, competitor comparison, content strategy, crawl budget
  • The page has unusual technical setup (SPA, heavy JavaScript rendering, paywalled content)
  • User asks: "is that everything?" or "what else should I check?"

Finding Format Reminder

Every important finding must be structured as:

**Finding: [Title]**
- **Evidence:** ...
- **Impact:** ...
- **Fix:** ...

If evidence is not available, write:

- **Evidence:** [UNVERIFIED] Unable to confirm — [reason]. Assumption: [what is assumed].

Limitations Disclosure

Always include a limitations section in the final report. Use language like:

This audit is based on publicly accessible page signals at the time of analysis. It does not include: source code review, JavaScript rendering audit, performance metrics, Core Web Vitals metrics, Google Search Console data, crawl log analysis, or competitive benchmarking. For a full audit, use seo-audit-full.