---
name: "seo_basics"
description: "On-page SEO fundamentals an agent can apply while generating HTML pages: title tags, meta descriptions, heading hierarchy, semantic markup, canonical URLs, sitemaps, Open Graph tags, and what NOT to do (keyword stuffing, cloaking, bought links). Triggers on: make this page SEO-friendly, SEO checklist, optimize page for search, title tag, meta description, Open Graph, sitemap."
metadata: { "includeInPrompt": true }
---

# SEO Basics

## Purpose

Give an agent the on-page fundamentals to bake into every HTML page it generates: the tags, structure, and metadata that make a page legible to search crawlers, plus the anti-patterns that actively hurt. Scoped to what the agent *controls* — its own pages. Nothing here promises rankings or traffic: those are decided by search engines, not by this checklist.

## Workflow

1. **Write one title tag per page.** Place it in `<head>`. Aim for under ~60 characters with the page's core topic early — titles get truncated in results, and front-loading keeps the topic visible. Every page gets a unique title; duplicate titles across pages waste the strongest on-page signal you own.

2. **Write one meta description per page.** Keep it to ~140–160 characters of plain human summary. As of 2026-09, Google docs describe the meta description as not a direct ranking factor, but it shapes the snippet shown under your title and therefore what people click — verify before relying on it. Never duplicate it across pages.

3. **Use one `<h1>` per page, then nest downward.** The `<h1>` states the page's topic (it may match the title but needn't repeat it verbatim). Use `<h2>` for sections, `<h3>` for subsections; don't skip levels (`<h1>` straight to `<h3>`). No heading may be used purely for styling — headings are structure, not font sizes.

4. **Use semantic markup.** Wrap content in `<main>`, `<article>`, `<header>`, `<nav>`, `<footer>` where they fit. Give every informative `<img>` a real `alt` description (decorative images get `alt=""`). Keep the primary content in the HTML itself — anything a crawler can only reach via heavy client-side rendering may be seen late or incompletely.

5. **Set a canonical URL.** Every page that can be reached by more than one URL (trailing slash, query params, `http`/`https` variants) should declare its preferred address: `<link rel="canonical" href="https://example.com/page/">`. When the page *is* canonical, point it at itself. This is a hint, not a command — search engines may still choose a different canonical — but it resolves most duplicate-content cases.

6. **Add Open Graph tags for sharing.** Crawlers read these when the page is pasted into social apps; they don't affect search ranking, but they control how the page *looks* when shared. Minimum set:

```html
<head>
  <meta charset="utf-8">
  <title>WidgetCo — Stainless Bottle Capper (2026)</title>
  <meta name="description" content="Cap glass bottles by hand with the WidgetCo Stainless Bottle Capper. Rust-proof, one-hand operation, ships free.">
  <link rel="canonical" href="https://widgetco.example/bottle-capper/">
  <meta property="og:title" content="WidgetCo — Stainless Bottle Capper (2026)">
  <meta property="og:description" content="Rust-proof, one-hand bottle capper. Ships free.">
  <meta property="og:type" content="website">
  <meta property="og:url" content="https://widgetco.example/bottle-capper/">
  <meta property="og:image" content="https://widgetco.example/img/bottle-capper-1200.jpg">
  <meta name="twitter:card" content="summary_large_image">
</head>
```

7. **Publish a sitemap.** For a static site, one `sitemap.xml` at the site root listing every canonical page URL with its last-modified date is enough; reference it from `robots.txt` (`Sitemap: https://example.com/sitemap.xml`). It helps crawlers discover pages — it does not make them rank.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://widgetco.example/bottle-capper/</loc>
    <lastmod>2026-09-20</lastmod>
  </url>
</urlset>
```

8. **Avoid the three page-killers.**
   - **Keyword stuffing:** repeating the same phrase unnaturally ("best bottle capper, cheap bottle capper, bottle capper sale...") reads as spam to crawlers and to humans. Write the phrase once where it belongs, then stop.
   - **Cloaking:** never serve different content to a crawler than to a visitor (different HTML by user-agent, hidden text via CSS). It is the fastest route to being de-indexed.
   - **Bought/placed links:** the agent cannot build links, so it cannot buy them — and it shouldn't fake them either (hidden links, link farms, auto-generated comment spam). Skip link schemes entirely; this skill covers only on-page factors.

## Output Contract

After applying this skill, a generated page should contain:

- A `<head>` with a unique `<title>` (~60 chars or fewer, topic front-loaded), one unique `meta[name="description"]` (~140–160 chars), and a self-referencing `rel="canonical"`.
- Exactly one `<h1>`; `<h2>`/`<h3>` nested without skipped levels; no heading used for styling alone.
- Semantic landmarks (`<main>`, `<header>`, `<nav>`, `<footer>` as applicable) and meaningful `alt` text on informative images.
- Open Graph tags (`og:title`, `og:description`, `og:url`, `og:image`) plus a Twitter card tag, so shares render correctly.
- No keyword stuffing, no cloaking, no hidden or purchased links.
- For multi-page sites: a `sitemap.xml` listing canonical URLs and a `robots.txt` that references it (do not block real pages in `robots.txt` by accident — `Disallow: /` applies to the whole site).

## Operating Rules

- **Promise nothing about rankings.** Never claim this checklist will rank a page, bring traffic, or change Google's behavior. Rankings are decided by the search engine's algorithm; this skill controls only on-page fundamentals. Say "I don't know" rather than guessing how a search engine will react.
- **Time-sensitive claims get dated and softened.** Anything about what Google docs say, what crawlers support, or what a Search Console feature shows must be written as "as of 2026-09, Google docs say X; verify before relying on it" — or left out entirely. Never invent Search Console features, metrics, or screenshots.
- **One title, one description, one h1.** Duplication across pages is the most common real-world failure; enforce uniqueness mechanically when generating many pages.
- **Structure over styling.** Headings, landmarks, and alt text describe meaning, not appearance. If a page looks right but its heading outline is nonsense, the page is broken.
- **Canonicals are hints.** `<link rel="canonical">` is a strong suggestion to the crawler, not an enforcement mechanism. Don't build flows that assume the engine will obey it.
- **Stay on-page.** This skill does not cover link building, paid promotion, local listings, or structured data beyond Open Graph. If asked for ranking tactics or off-page work, decline the scope rather than improvising — an honest "that's outside this skill" beats invented advice.