SEO

---
name: seo
description: "The whole organic stack for a site or app: SEO, answer engines (AEO/GEO), programmatic pages, editorial content, free tools, technical health, claim accuracy, off-page briefs and distribution. Each run measures, ranks every action on one scale, does the best one. Run daily. Use for SEO, AEO, GEO, LLMO, organic traffic, rankings, Search Console, GSC, Bing, IndexNow, indexing, sitemap, robots.txt, llms.txt, AI crawlers, AI citations, AI visibility, 'what does ChatGPT say about us', keyword research, 'what should I publish next', guides, how-tos, listicles, comparisons, alternatives or /compare/ or /for/ pages, programmatic SEO, free tool for leads, striking distance, content decay or refresh, canonical, redirects, schema, JSON-LD, Core Web Vitals, site audit, technical SEO, internal links, orphan pages, backlinks, directories, outreach, competitor teardown, 'why don't we rank', 'we need traffic', or the next best SEO move."
metadata:
  version: 2.2.0
---

# SEO

One skill owns the whole organic stack: classic search, answer engines, programmatic pages, editorial content, free tools, technical health, product-claim accuracy, off-page briefs and distribution. Each run measures first, ranks every kind of action on one scale, does the single best one, verifies it, and writes down what it did and what it did not do. Run it again tomorrow and it picks the next-best thing. `/seo` is a daily operator, not a content quota.

Correcting what is already live (`correct`, `repair`, `refresh`, `consolidate`, `prune`, `verify-product`) is scored against creating something new, and usually wins. A run that ends in "nothing beats the bar today, here is what I measured" is a successful run.

## What matters most

Four things decide whether any of this works. Every run measures all four, every candidate is scored on which of them it moves, and the run record prints them as a vitals block so a month of records reads as a trend.

| Vital | Measured by | Acted on through |
|---|---|---|
| **Speed of the site** | `health_diff.py` records time to first byte and HTML weight per page every run; Lighthouse or PageSpeed on the top pages weekly. | `repair`: heavy pages, slow TTFB, render-blocking assets, image weight. A speed regression on a winning page outranks a new page. |
| **Relevance of keywords and topic** | Every page maps to a radar seed or coverage-map cluster; `answer_owner` and `intent owner` on every candidate; GSC wrong-query state. | `refresh` (retarget) or `prune`. A page off the site's topic is a cost, not a free lottery ticket. |
| **Click rate on Google** | Per-page CTR against the expected CTR at its position, from the saved Search Console pulls; the census flags `low-ctr`. | `refresh` of title and snippet first, because it is the cheapest lever on the site. Site CTR and the impressions-weighted gap are in every run record. |
| **Health of links** | `health_diff.py --check-links`: broken and redirecting internal links, orphans, inbound counts; `depth_check.py` for click depth; backlink spam score monthly. | `repair` for broken and redirecting links and orphans; `offpage-brief` for authority; never buy links. |

These are not four more rules. They are the lens the rubric's `strategic` axis scores against, and the reason `repair` and `refresh` can beat `create`.

## Modes

| Invocation | What happens |
|---|---|
| `/seo` | Daily run. Measure → select across all actions → execute one → verify → register. |
| `/seo measure` | Measure and write the run record. Select nothing. |
| `/seo fix <what>` | Force the fix lane on a named page, claim, or defect. |
| `/seo write [topic]` | Force one editorial piece. |
| `/seo sprint` | Force the programmatic lane, next roadmap phase. |
| `/seo tool [idea]` | Force a free-tool build. |
| `/seo aeo [snapshot\|audit\|plan\|fix]` | Force the answer-engine lane. `snapshot <domain>` needs no foundation. |
| `/seo tech` | Force a site-health pass: run the diff, repair the worst violation. |
| `/seo census` | Whole-inventory review. No create candidates. Execute the best prune, merge or refresh and write the portfolio trend. Runs itself once a month. |
| `/seo offpage` | Write the next outreach or directory brief. |
| `/seo distribute [url]` | Force the distribute lane on the newest undistributed piece, or the named URL. |
| `/seo needs-you` | Print the queue of decisions only the human can make, and nothing else. |
| `/seo setup` | Print what is connected and what each missing connection would unlock, in value order. Nothing else. |
| `/seo upgrade` | Detect the repo's state (fresh, legacy, partial, current), show the migration plan, apply it on confirmation. |

A forced mode still measures first (cheaply) and still registers. It just skips the cross-lane vote.

## The loop

Read the step reference when you reach it. Everything below the table is rules and routing; the mechanics live in `references/`.

| Step | Reference | Runs |
|---|---|---|
| 0. Foundation | `references/foundation.md` | Every run: `upgrade_state.py` (free when current). The interview only once. |
| 1. Measure | `references/measure.md` | Every run. Cheap panels always, paid panels on cadence. |
| 2. Select | `references/select.md` | Every run except forced modes. |
| 3. Execute | `references/lanes/<lane>.md` | The chosen lane. |
| 4. Verify | The lane's Gates section | Every run. Non-waivable. |
| 5. Register | `references/register.md` | Every run, including measure-only. |
| 6. Report | `references/register.md` §6 | Every run. The final message, written for a reader who has not opened a single file. |

### Step 0. Foundation

`.seo/` is the only state directory. Repos arrive in four states: fresh (nothing yet), legacy (state from earlier versions of this skill), partial (an older v2 layout), or current. `scripts/upgrade_state.py` detects which and, with `--apply`, moves, merges and fills without overwriting or duplicating anything, then stamps `config.version`. Run it first, every run; on a current repo it costs nothing. `references/foundation.md` then builds only what is still missing: config, brand and voice contract, the truth ledger, the attribute matrix, link inventory, keyword cache, content ledger, roadmap, radar seeds. Never overwrite a foundation file that exists.

The skill runs with whatever is connected. On the first run the foundation checkpoint, the one stop the skill makes, also shows what is connected and the top three missing connections with what each would unlock (`references/setup.md`), and asks whether to connect anything before continuing. The full report follows in the final message. After that it is one line per run until each item is declined.

### Step 1. Measure

The scoreboard comes before any decision. `references/measure.md` runs the panels, cheap ones every run and paid ones on cadence: Search Console states per page and index