SEO Sprint

---
name: seo-sprint
description: "When the user wants to build organic search traffic from scratch on a site or app — a multi-phase SEO sprint that ships programmatic landing pages (alternatives, use-cases, comparisons, playbooks) backed by real keyword research. Also use when the user mentions 'SEO sprint,' 'build organic traffic,' 'rank in Google,' 'build an SEO machine,' 'alternatives pages,' 'comparison pages,' '/for/ pages,' 'programmatic SEO playbook,' 'competitor alternatives,' or vague asks like 'help me with SEO' or 'we need traffic' when there's no existing roadmap — this skill creates one and then executes it phase by phase. Distinguish from seo-audit (one-off diagnostic) and programmatic-seo (page-template scaling only) — this skill owns research, planning, page generation, internal linking, off-page checklist, and the persistent phase tracker across the whole sprint."
---

# SEO Sprint

An end-to-end playbook for building organic search traffic on any app or marketing site, from day-0 setup through ongoing programmatic page expansion. Conversion-first (alternatives and comparison pages before blogs), publish-early (a thin page indexed now beats a perfect page indexed later), and battle-tested across dozens of real production phases.

The skill has two modes:

1. **Initialize** — first run on a new repo. Detects stack and brand, runs keyword research via Ahrefs, audits technical foundations, generates a persistent roadmap doc and link inventory.
2. **Resume** — subsequent runs. Reads the existing roadmap, picks up the next pending phase (or one the user names), executes it end-to-end with quality gates.

The user does not need to remember which mode they're in. On invocation, **detect mode by checking whether `docs/seo-sprint.md` exists at repo root** (or wherever the user chose to put it last time — see `.seo/config.json` if present). No file → Initialize. File exists → Resume.

---

## Hard prerequisites

Before doing anything, verify:

1. **Working directory is a git repo** — `git rev-parse --is-inside-work-tree`. If not, stop and say: "This skill writes a persistent roadmap to your repo. Initialize git first, or run from inside an existing repo."
2. **A stack is detectable** — at least one of `package.json`, `Gemfile`, `composer.json`, `requirements.txt`, `astro.config.*`, `next.config.*`, `nuxt.config.*`, `gatsby-config.*`, `_config.yml`, `config.toml`, `pyproject.toml`. If none, ask the user what stack they're on before continuing.
3. **Ahrefs MCP availability check** — try a small ping: `mcp__ahrefs__subscription-info-limits-and-usage` (no args). If it returns data, you're good. If it errors, the skill works in **manual research mode** — see `references/manual-research.md`. Don't refuse to run; just adjust.

If Ahrefs is available but no `project_id` is on file, prompt the user for one. Store it in `.seo/config.json`. You'll reuse it dozens of times.

---

## Initialize mode — first run

Goal: end this run with a committed (or at least written) `docs/seo-sprint.md` that contains keyword research, a phase tracker grouped by pattern, and the technical audit findings. Plus `.seo/brand.md` (product context) and `.seo/link-inventory.md` (every internal link target available).

### Step 1 — Detect stack + frontend convention

Read `references/stacks/detection.md` for the full signal table. Identify:

- **Framework family**: Rails+Inertia, Next.js (App Router vs Pages), Astro, Nuxt, Remix, SvelteKit, Hugo, Jekyll, plain HTML, or "unknown → markdown fallback."
- **Routing convention**: file-based (Next/Astro/Nuxt) or controller-based (Rails/Django/Laravel).
- **Component language**: TSX, JSX, `.astro`, `.svelte`, `.vue`, `.erb`, or plain HTML.
- **Existing marketing pages**: `git ls-files | grep -iE 'marketing|landing|pages/(home|about|pricing)'`. Note what exists — you'll link to it.

Confirm with the user using `AskUserQuestion` if any signal is ambiguous. Save to `.seo/config.json`.

### Step 2 — Detect brand + product context (hybrid)

Read every signal first, propose `.seo/brand.md`, then ask only about gaps. Signals to read:

- `CLAUDE.md`, `README.md`, `README` — name, one-liner, audience hints
- `package.json` or `Gemfile.lock` — framework version (informs the stack adapter)
- `tailwind.config.*` or design-token CSS file — accent color, fonts
- `app/views/marketing/*`, `pages/index.*`, `src/pages/index.*` — existing hero copy
- `pricing` page (any path) — plan structure, price points

Then use a single `AskUserQuestion` call (3-4 questions) to fill gaps. Required to know:

- **Product one-liner** (≤20 words)
- **Primary persona** (e.g. "B2B SaaS founder," "indie agency owner," "ecommerce ops manager")
- **3-7 direct competitors** (by name; you'll Ahrefs them next)
- **Brand voice tags** (e.g. "honest, technical, no-jargon, slightly irreverent")
- **Whether the product has a free tier** (drives "is [brand] free" keyword strategy)
- **Anti-positioning** — what you do NOT do (used for honest comparison sections later)

Write to `.seo/brand.md` using `assets/brand-template.md` as the skeleton.

### Step 3 — Run keyword research

If Ahrefs MCP is available: follow `references/ahrefs-recipes.md`. The exact recipes:

- **A. Domain rating + baseline.** `mcp__ahrefs__site-explorer-domain-rating` + `site-explorer-metrics` on the user's domain. Record DR. **This is the single most important number** — it caps which keywords are winnable. KD ≤ DR + 5 is the heuristic; if DR < 10, restrict to KD ≤ 30 until your DR climbs.
- **B. Competitor reverse-lookup.** For each competitor name the user gave: `site-explorer-organic-keywords` (top 50 by volume, filtered to KD ≤ DR+20). This is where most of your `/alternatives/[competitor]` candidates come from. Capture `volume`, `kd`, `traffic_potential`, and the SERP for the competitor brand term itself.
- **C. Use-case keyword sweep.** For the persona + product one-liner: `keywords-explorer-matching-terms` with seeds like "[product category] for [audience]", "[verb] [object]" patterns. Filter to KD ≤ DR+10, volume ≥ 30. These become Pattern B/C candidates.
- **D. Comparison volume.** For each competitor pair where both are in the user's list: `keywords-explorer-overview` on "[a] vs [b]". Volumes are usually small (30-500) but conversion intent is the highest of any pattern.
- **E. Striking-distance audit (existing sites only).** `mcp__ahrefs__gsc-keywords` filtered to position 5-20. These are pages one push from rank-3. Each becomes a boost task.