seo-optimization

name	seo-optimization
description	Technical/on-page SEO, Core Web Vitals, structured data, GEO/LLM SEO, and quality-gate signals.

SEO Optimization

Reference material for seo-specialist. Stack-agnostic — applies to any framework that renders HTML for a public, indexable surface.

Detection Signals — When SEO Is Required

A project counts as "needs SEO" when any of these hold. Use this table to decide whether seo-specialist must be spawned, not just invited.

Signal type	Examples
Project category	Institutional/marketing site, landing page, e-commerce/online store, blog, documentation portal, portfolio — any surface meant to be found via search or cited by an AI answer
File presence	sitemap.xml, robots.txt, next-seo.config.*, astro.config.* with site: set, gatsby-config.js, CMS content directories (content/, posts/, blog/)
Route shape	Product detail pages, category/listing pages, checkout funnel entry pages, blog post routes, /blog/, /produtos/, /p/
Dependency signals	next-seo, react-helmet, vue-meta, schema-dts, astro-seo, sitemap generator packages
Explicit request	User mentions SEO, ranking, Google, meta tags, structured data, sitemap, Core Web Vitals, ou "otimizar para IA/LLM"

Not required for: internal admin panels, authenticated-only dashboards, CLIs, backend services with no rendered HTML, mobile-only apps with no web surface.

---

Technical SEO Checklist

• robots.txt present, not blocking pages that should be indexed, and pointing to the sitemap
• sitemap.xml generated (static or dynamic), includes all indexable routes, excludes noindex/private routes
• Canonical URL (<link rel="canonical">) on every page — prevents duplicate-content splitting
• One <h1> per page, logical heading hierarchy (h1 → h2 → h3, no skipped levels)
• hreflang tags when the project serves more than one locale
• HTTPS enforced, no mixed content
• Clean, descriptive URLs (no query-string-only routing for canonical content, no unnecessary IDs)
• 404s return real 404 status, not 200 with a "not found" page (soft 404)
• Redirects use 301 for permanent moves, never chained more than one hop

On-Page SEO Checklist

• <title> unique per page, 50–60 characters, primary keyword near the front
• Meta description unique per page, 140–160 characters, includes a reason to click
• Image alt text descriptive (not keyword-stuffed), decorative images use alt=""
• Internal linking uses descriptive anchor text, not "click here"
• Content answers the query in the first 1–2 sentences before elaborating (also serves GEO — see below)
• Open Graph (og:title, og:description, og:image, og:url) and Twitter Card tags present for shareable pages

Off-Page Signals (advisory, not gated)

• Structured internal linking supports topic authority — flag orphaned pages with no inbound internal links
• Flag broken outbound links found during review
• Backlink strategy, PR, and external outreach are outside this agent's scope — note when the user should involve marketing/growth, don't attempt to execute them

---

Core Web Vitals — Thresholds ("Good")

Metric	Threshold	What it measures
LCP (Largest Contentful Paint)	≤ 2.5s	Perceived load speed
INP (Interaction to Next Paint)	≤ 200ms	Responsiveness
CLS (Cumulative Layout Shift)	≤ 0.1	Visual stability

Common fixes: preload the LCP image/font, avoid layout shift from late-loading web fonts or images without explicit width/height, defer non-critical JS, avoid render-blocking CSS.

---

Structured Data (schema.org / JSON-LD)

Emit as <script type="application/ld+json">. Pick the type that matches the page's real content — never mark up content that isn't visible to the user (Google Rich Results Test and other engines penalize mismatches).

Page type	Schema type	Key fields
Homepage / brand	Organization	name, url, logo, sameAs (social profiles)
Landing / service page	Service or WebPage	name, description, provider
Product page	Product	name, image, description, offers (price, priceCurrency, availability), aggregateRating if reviews exist
Blog post / article	Article or BlogPosting	headline, author, datePublished, dateModified, image
FAQ section	FAQPage	mainEntity array of Question/Answer pairs — only for content genuinely visible as Q&A on the page
Navigation trail	BreadcrumbList	ordered itemListElement matching the visible breadcrumb
Local business	LocalBusiness	address, openingHours, telephone

Validate with structured-data testing tools before shipping when the project has one configured; otherwise flag as "unverified, spot-check recommended."

---

GEO — SEO for LLMs / AI Search (Generative Engine Optimization)

Search is increasingly answered by AI systems (chat assistants, AI Overviews, agentic browsers) that read and cite pages rather than only ranking them. These practices make content easier to extract and cite correctly:

• llms.txt at the site root — a plain-Markdown index of the site's key pages for LLM consumption: a short site description, then a linked list of the most important pages with a one-line summary each. Keep it accurate — a stale llms.txt is worse than none, since it misdirects the citation.
• Answer-first structure — state the direct answer to the likely query in the first sentence or two of a section, then elaborate. LLMs extract from the top of a block; burying the answer under preamble reduces citation accuracy.
• Self-contained sections — each h2/h3 section should make sense read in isolation (LLMs often extract a section, not the whole page). Avoid "as mentioned above" references that only work in full-page context.
• Explicit entities — name the product, company, or concept by its full name near the top of the page instead of relying on pronouns or implied context established elsewhere.
• Clean semantic HTML — proper <article>, <section>, heading hierarchy, and lists (<ul>/<ol>) over div-soup; extraction quality tracks markup quality.
• Structured data doubles as GEO signal — the same JSON-LD that helps traditional search also gives LLM crawlers unambiguous facts (price, author, date) instead of forcing them to infer from prose.
• Avoid content gated behind JS-only rendering with no server-rendered fallback — some AI crawlers do not execute JavaScript; SSR or static generation ensures the content is visible to both search and AI crawlers.
• robots.txt AI-crawler directives — if the project has a stated policy on AI training/crawling (e.g. GPTBot, ClaudeBot, Google-Extended), reflect it explicitly rather than leaving it to each crawler's default.

---

Quality Gate Output Format

Use this exact structure when reporting an SEO review (see agents/seo-specialist.md for when it is mandatory vs. advisory):

## SEO Quality Gate

### Technical SEO
[PASS / ISSUE / BLOCKER] — [finding]

### On-Page SEO
[PASS / ISSUE / BLOCKER] — [finding]

### Core Web Vitals
[PASS / ISSUE / BLOCKER] — [finding, with measured value if available]

### Structured Data
[PASS / ISSUE / BLOCKER] — [finding]

### GEO / LLM Readiness
[PASS / ISSUE / BLOCKER] — [finding]

### Verdict
[APPROVED / APPROVED WITH NOTES / BLOCKED]

BLOCKER = missing sitemap/robots.txt, missing canonical on a duplicated route, broken structured data, LCP/CLS in "poor" range, or a soft-404. Everything else non-passing is ISSUE. BLOCKED verdict when any BLOCKER is present.