seo-machine

SEO Machine

End-to-end engine for building organic search traffic. Ships dozens of programmatic landing pages — alternatives, comparisons, use-cases, playbooks — backed by real keyword research, with a persistent roadmap the user resumes across sessions.

Conversion-first (alternatives + comparisons before blogs). Publish-early (a thin page indexed today beats a perfect page indexed in three weeks). Stack-native (writes into the user's framework — Next.js, Astro, Rails+Inertia, or a portable markdown fallback).

Two modes, auto-detected

Detection rule on every invocation: check docs/seo-machine.md at repo root (or the path recorded in .seo/config.json). No file → Initialize. File exists → Resume. The user does not need to remember which mode they're in.

Publishing Order (the load-bearing decision rule)

The roadmap orders patterns by conversion intent first, traffic intent second. This is the single most important decision the skill makes — it's why the alternatives + comparison pages ship before the playbooks + blog posts.

Why this order matters: alternatives pages convert 5–20× blog posts at 1/10 the search volume. Shipping one alternatives page is worth ten generic blog posts on the same topic. The roadmap should reflect this — Phase 0 (tech audit) → Phases 1–N (alternatives, then comparisons, then use-cases) → late phases (playbooks) → never (blogs, unless explicitly requested by the user).

Striking-distance boosts (pages already ranking pos 5–20 in GSC) jump the queue when they exist — fastest wins per hour of work.

On Activation

1. Load brand context where present: brand/keyword-plan.md, positioning.md, competitors.md, audience.md, stack.md. Missing files are fine.
2. Surface what loaded:

Backend Selection

Validate KD/competition with OpenSEO get_keyword_metrics / get_serp_results before generating pages; consume openseo-keyword-clustering outputs when present. Qualitative research uses Exa-stack (or manual) per the shared ordered resolver — record research_backend in .seo/config.json. Full contract: skills/openseo/references/backend-contract.md.

Brand context loaded:
├── Keyword Plan    ✓/✗  (seeds the roadmap; ✗ → generate during Initialize)
├── Positioning     ✓/✗  (drives /compare and /alternatives angles)
├── Competitors     ✓/✗  (target list for /alternatives pages)
├── Audience        ✓/✗  (intent buckets for /for/<persona> pages)
└── Stack           ✓/✗  (selects references/stacks/<framework>.md)

Progressive enhancement: with zero brand files the skill still works — it derives signal from the repo during Initialize Step 2. With full brand context it skips re-discovery and goes straight to research + roadmap.

Exa recipes: references/exa-recipes.md + references/api-stack-recipes.md. Manual fallback: references/manual-research.md. Ahrefs is an optional paid overlay only (see Exa recipes appendix).

Hard prerequisites

Initialize mode

Goal: end the run with a written docs/seo-machine.md containing keyword research, a phase tracker grouped by pattern, and technical-audit findings — plus .seo/brand.md and .seo/link-inventory.md.

Step 1 — Detect stack + frontend convention

Read references/stacks/detection.md. Identify framework family, routing convention (file-based vs controller-based), component language, and existing marketing pages (git ls-files | grep -iE 'marketing|landing|pages/(home|about|pricing)'). Resolve ambiguity with AskUserQuestion. Persist to .seo/config.json.

Step 2 — Detect brand + product context

Read every signal first, propose .seo/brand.md, then ask only about gaps. Signals: CLAUDE.md, README.md, package.json / Gemfile.lock, tailwind.config.* or design-token CSS, app/views/marketing/* or pages/index.*, pricing page.

If brand/voice-profile.md and brand/positioning.md already exist (mktg-native project), read them and skip 80% of the questions — those files already say who the buyer is and what the brand sounds like.

Otherwise use a single AskUserQuestion (3–4 questions max) to fill gaps. Required to know:

• Product one-liner (≤20 words)
• Primary persona (e.g. "B2B SaaS founder", "indie agency owner")
• 3–7 direct competitors by name
• Brand voice tags (e.g. "honest, technical, no-jargon")
• Free tier? (drives the "is [brand] free" keyword strategy)
• Anti-positioning — what the product does NOT do (used in honest comparison sections)

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

Step 3 — Keyword research (Exa-native stack)

Follow references/exa-recipes.md — 7 Exa-native recipes that replace the Ahrefs cookbook:

Then pull cross-API compound recipes from references/api-stack-recipes.md for moves Ahrefs alone can't do — pain-point cluster discovery (/last30days + mktg-x + Exa deep search), OSS competitor teardown (gh + DeepWiki + Exa), outreach prospect discovery (Exa Websets + people-research), newcomer surveillance (Exa Websets cron).

When Exa is unavailable, fall back to references/manual-research.md (paste-from-UI workflow). When the user has paid Ahrefs, layer it on top per the appendix in exa-recipes.md — don't replace.

Cache the raw output to .seo/keyword-research.json. Curate the decision-ready summary into the Keyword Research Appendix section of docs/seo-machine.md.

Step 4 — Technical foundations audit

Run scripts/tech_audit.py (sitemap, robots, meta-tag uniqueness, schema). Whatever it finds becomes Phase 0 in the roadmap. Day-0 crawl shapes Google's understanding of the site for months — retroactive fixes are harder.

Step 5 — Generate the roadmap

Fill assets/roadmap-template.md with:

• Site facts (domain, DR, stack, brand colors, fonts) from steps 1–2
• Reference data — paths to controllers / page files this skill will edit
• Keyword Research Appendix — curated, grouped by pattern
• Phase Status Tracker — auto-populated:
  • Phase 0: technical foundations fixes
  • Phase 1+: one row per page candidate
  • Group by pattern. Within a pattern, order by traffic_potential desc → volume desc → KD asc
  • Striking-distance boosts near the front (fastest wins on existing sites)
  • Off-page checklist (directories + outreach) tail-end, one phase per category

Write to the configured path (default docs/seo-machine.md). Print the path back and recommend a human review pass before Phase 0.

Step 6 — Generate .seo/link-inventory.md

Every phase reads this file to pick internal links. Use assets/link-inventory-template.md. Pre-populate from existing routes (features, tools, pricing, blog posts). Each phase appends to it as new pages ship.

Step 7 — Hand off

✓ Initialize complete

  Roadmap:        docs/seo-machine.md
  Brand context:  .seo/brand.md
  Keyword cache:  .seo/keyword-research.json
  Link inventory: .seo/link-inventory.md
  Config:         .seo/config.json

Next: review docs/seo-machine.md, then run me again to execute Phase 0.

Do not auto-execute Phase 0. Pattern priorities and competitor lists are decisions worth a human pass.

Resume mode

Goal: pick the next phase from the tracker, execute end-to-end with quality gates, hand back so the user can commit/PR.

Step 1 — Read state

Load docs/seo-machine.md, .seo/brand.md, .seo/link-inventory.md, .seo/config.json. Find the Phase Status Tracker, identify the next pending phase with the lowest number, print it back along with the two phases that follow.

Step 2 — Confirm scope

Single AskUserQuestion:

• "Continue with Phase N: [title]?"
• Options: "Yes, start Phase N" / "Pick a different phase" / "Re-audit (refresh research)" / "Just show the tracker"

"Different" → list pending phases. "Re-audit" → loop back into Initialize steps 3–5. "Show" → print tracker and stop.

Step 3 — Execute

Pattern → reference mapping:

For page-generating phases, the flow is always:

1. Re-research — current competitor pricing, feature changes. Don't trust 60-day-old cached data on commercial-intent terms.
2. Generate the page payload — output format follows the stack (references/stacks/<framework>.md) or references/stacks/markdown-fallback.md.
3. Verify against the quality bar (word count, internal links, schema, honesty section on alts). Run scripts/word_count.py and scripts/link_audit.py. If a check fails, fix it — don't ship under-spec work.
4. Update .seo/link-inventory.md with the new page.
5. Update the tracker row in docs/seo-machine.md — status completed, PR ref or commit SHA. Same edit batch as the page work so reviewers see both in one diff.

Step 4 — Hand off (do NOT auto-commit)

✓ Phase N complete: [title]

Files changed:
  app/controllers/marketing_controller.rb  (added entry)
  app/frontend/pages/Alternatives/Show.tsx (no change — uses existing layout)
  docs/seo-machine.md                      (tracker updated)
  .seo/link-inventory.md                   (new page registered)

Quality gates:
  ✓ Word count: 712 / 600 min
  ✓ Internal links: 2 alts, 1 feature, 1 tool
  ✓ FAQ JSON-LD attached
  ✓ Honesty section present (3 rows)

Suggested commit: "SEO Phase N: ship /alternatives/[slug]"

Next phase pending: Phase N+1 — [title]

Open a PR only if the user has expressed they want that cadence. Otherwise let them drive git.

Interactive principles

Adjacent skills (route here vs there)

Anti-patterns

File map

Outputs

The skill writes to project paths, not brand/. This is why writes: in skills-manifest.json is [] — the manifest declares only brand/*.md writes, and seo-machine's outputs live in the user's repo, not in brand memory.

This follows the Long-Arc Sprint Persistence Pattern documented in AGENTS.md — docs/seo-machine.md is the canonical doc that survives session interruption.

/cmo integration

/cmo routes here under Playbook #9 — SEO Authority Build, Path B (programmatic sprint). On a cold project /cmo first spawns mktg-brand-researcher, mktg-audience-researcher, mktg-competitive-scanner in parallel (foundation), runs keyword-research to populate brand/keyword-plan.md, then hands off here. After every phase, /cmo spawns mktg-content-reviewer + mktg-seo-analyst in one message to score the page batch before the user commits.

See skills/cmo/rules/playbooks.md and skills/cmo/rules/sub-agents.md for the full handoff contract.