SEO Content Generation

---
name: seo-content
description: "When the user wants to produce the next piece of search-optimized content for a site — a content engine that bootstraps its own brand + keyword foundation on first run (no other skill required) and then, each run, researches what to write next, picks the content TYPE (guide, how-to, listicle, comparison, definition, data study, resource/template library, opinion, case study), and ships one deeply-researched, on-brand, in-voice, SEO-optimized piece. Use when the user says 'write the next piece,' 'what should I publish next,' 'content engine,' 'feed the blog,' 'make a new SEO article,' 'next content,' 'write a guide/how-to/listicle/comparison,' 'create new content,' or re-runs after /seo-sprint laid the groundwork. Distinguish from seo-sprint (executes a fixed programmatic-page roadmap), content-strategy (plans topics but doesn't write), and blog-article (writes one post, no opportunity research or dedup ledger). It OWNS the loop: decide → research → write → verify → register, one piece per run."
---

# SEO Content

A content engine. Each invocation produces **one** publishable, deeply-researched, on-brand, in-voice, SEO-optimized piece — and, critically, **decides for itself what that piece should be and what type it should take.** Run it again and it picks the next-best piece. The research that answers "what do I write next?" is the skill's core job, not a step the user does first.

It runs on a small foundation in `.seo/` (brand voice, stack config, link targets, keyword data). **This skill sets that foundation up itself on first run** — drop it into a bare repo and it bootstraps everything it needs (see Step 0). If you've already run `seo-sprint`, that same foundation is already there and this skill just reuses it. Either way, no external skill is required.

The user never specifies a topic or type unless they want to. The default contract is: **"go figure out the best next thing to publish and publish it."**

---

## Relationship to its siblings

| Skill | Owns |
|---|---|
| **seo-sprint** | A *fixed roadmap* of programmatic pages (alternatives/compare/for/playbooks) + technical audit + off-page checklist, executed phase by phase. Optional sibling, **not a prerequisite** — if it's run, the two share the same `.seo/` foundation; if not, this skill builds its own. |
| **seo-content** (this) | The *open-ended editorial loop*. Re-decides the single best next piece every run, chooses its type dynamically, writes it deep. No fixed roadmap — the backlog is regenerated from live data each run. |
| **content-strategy** | Planning only — clusters and calendars. Hands the "what" to this skill; this skill also does its own selection if no plan exists. |
| **blog-article** | Writes one arbitrary post you hand it. No opportunity research, no type selection, no dedup ledger. This skill *can* hand off the actual prose to it but owns everything around it. |

This skill is **fully self-contained**: it bundles its own verification scripts (`scripts/`), its own research + output + setup references (`references/`), and its own foundation templates (`assets/`). It depends on **no other skill.** The `.seo/` foundation it reads is one it creates itself (Step 0) when absent, or reuses untouched when `seo-sprint` already made it — the two coexist on a shared foundation with zero conflict. The augmenting skills below are pure upside when present, never required.

---

## Operating model — one run, one session, one PR

Run this **fresh each time: new chat session, new branch, one PR per piece.** Do **not** loop it repeatedly inside one long session.

The skill is deliberately **stateless across runs**. Everything that must persist between pieces — what's shipped, the scored backlog, the link inventory — lives in the `.seo/` files, not in the conversation (the same reason seo-sprint keeps its roadmap as a doc). So a fresh session loses nothing: it reads those small files and starts warm.

A single run pulls heavy research — full SERP scrapes of 5-10 competitor pages, primary sources, the draft itself. The Step 2 fan-out keeps most of that in *subagents*, so the main thread carries the distilled brief, not the raw piles — but the draft, the brief, and the critique loop still add up. By the third piece in one session you're diluting attention and re-reading stale context. Fresh session = each piece gets clean attention against `.seo/brand.md`, and each PR is an independently reviewable, revertable unit. The only cost is re-reading the small `.seo/` foundation files at the start — cheap, and the point.

**Parallel throughput:** because state is file-based, you can run several pieces at once in separate git worktrees. The only write-contention is the append-only `.seo/content-ledger.md` and `.seo/link-inventory.md` — resolve any merge conflict by keeping both rows. Sequential is simpler; reach for worktrees only when you specifically want volume.

---

## Prerequisites

Only two, and the second one this skill can satisfy itself:

1. **Working directory is a git repo** — `git rev-parse --is-inside-work-tree`. If not, stop: "Run me from inside the repo where your site lives."
2. **A `.seo/` foundation exists — or gets bootstrapped.** Check for `.seo/config.json` and `.seo/brand.md`. If present (you ran `seo-sprint`, or a prior `seo-content` run set them up), reuse them. If missing, **Step 0 creates them** — don't stop, don't tell the user to go run another skill.

At the start of a run, check what's connected — ping `mcp__ahrefs__subscription-info-limits-and-usage` (or look for `mcp__dfs-mcp__*`) and note the **Tools & environment** table below. Adapt to what's present; never refuse for a missing tool.

Read once, up front, every run (after Step 0 has ensured they exist):
- `.seo/brand.md` — voice tags, persona, anti-positioning, differentiators, forbidden words. **Everything you write is governed by this file.**
- `.seo/config.json` — stack, content surface, keyword-tool `project_id`, output paths.
- `.seo/link-inventory.md` — internal link targets.
- `.seo/keyword-research.json` — DR baseline + cached keyword data (treat as stale if >90 days; re-query the slice you need).
- `.seo/content-ledger.md` — **what you've already shipped + the scored backlog.** If it doesn't exist, create it from `assets/content-ledger-template.md` on this run. This is how "run me again for the next piece" works without repeating yourself.
- `docs/seo-sprint.md` if present — so you don't write editorial content that duplicates a programmatic page.

---

## Tools & environment (none required — better with, fine without)

The skill detects what's available and adapts; nothing here is a hard dependency. Connect what you can for higher-quality output.

| Tool / capability | What it unlocks | Without it |
|---|---|---|
| **Ahrefs MCP** *(or **DataForSEO MCP**)* | Real keyword volume/KD, DR baseline, SERP overviews, content-gap, GSC striking-distance, AI-citation gaps — the selection + winnability math | Ahrefs-free fallback: web search + SERP scraping + estimated ranges (`research-recipes.md`) |
| **firecrawl** *(skill or MCP)* | Robust SERP teardown, JS-rendered page extraction, sitemap reads for DB/CMS sites | `WebSearch` + `WebFetch` — works, weaker on SPA-rendered pages |
| **`WebSearch` / `WebFetch`** | Baseline research, fact verification, primary-source hunting — the floor for Step 2 | (usually always present) |
| **Subagent fan-out** *(Agent/Task tool)* | Parallel research in Step 2 + parallel critics in Step 4; keeps the main context clean | Run the angles/critics sequentially — same coverage, slower |
| **Content-store write access** *(CMS API/CLI/MCP — WordPress REST, Sanity CLI, Notion MCP…)* | Create the piece as a **draft** directly in the CMS/DB | Hand off a ready-to-paste artifact + field map (`content-stores.md`) |