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.