/write-seo — Write SEO-optimized content

Target: $ARGUMENTS

Rules and numbers: ${CLAUDE_PLUGIN_ROOT}/skills/seo-fundamentals/SKILL.md and ${CLAUDE_PLUGIN_ROOT}/skills/seo-fundamentals/references/scoring-spec.md. Writing references: ${CLAUDE_SKILL_DIR}/references/engagement-techniques.md (hooks, APP intro, story structure) and ${CLAUDE_SKILL_DIR}/references/cta-playbook.md.

0. Collect real material first

The article's credibility comes from what only the author has. Before writing, ask once (AskUserQuestion, skip if a brief already supplies it):

• Own data or observations on this topic (numbers from their work, audits, experiments).
• 1–3 real anecdotes or cases (who, when, what happened — with permission to name, or anonymized by the user).
• Tools, versions, dates they actually used.
• Their stance: what they believe, where they are unsure.
• Existing pages to link to; author name and profile URLs for sameAs.

Whatever the user does not supply is not invented. Write [NEEDS REAL DATA: e.g., one client example with a metric] at the spot and list all gaps at the end. Statistics from research must come from sources you fetched, cited inline with the primary-source URL.

1. Pre-writing

If no /research or /content-brief output exists:

• WebSearch the keyword; identify the primary entity (Knowledge Graph entity, not just the keyword), intent, top-10 content types and lengths.
• Fan-out: list 8–12 sub-queries Google's AI Mode would decompose the query into (definition, how-to, comparison, troubleshooting, best practice, alternatives, cost, when). Each becomes an H2 or H3.
• Must-cover entities (what all top results include) and 3–5 information-gain angles — verified against the SERP, filled only with real material.

Architecture: H1 with the primary entity, benefit-driven, <70 chars; 4–7 H2s mapped to sub-queries; H3s for finer sub-queries; target length = SERP median + 20–30% (never padded).

2. Writing

Introduction (100–150 words): hook using one of the five formulas in engagement-techniques.md; then Agree → Promise → Preview. The primary entity appears in the first 50 words as the subject of a sentence.

Each H2/H3: open with a self-contained answer to the heading's implicit question (1–3 sentences, ≤60 words, contains a fact — number, named entity, or date). Then evidence, examples, detail. Definition-style opening ("X is Y that does Z") on concept sections. Short paragraphs (2–4 sentences), mixed sentence length, active voice, inline citations to primary sources.

Engagement elements: 2–3 mini-stories (50–150 words) built from the user's real anecdotes (structure in the reference); first-person stake and at least one honest acknowledgment of trade-offs or uncertainty — in the author's voice, from their input; 2–3 contextual CTAs (soft within 500 words, medium after proof, strong in the conclusion, each specific about what the reader gets); [IMAGE: description] notes where visuals belong.

Conclusion (75–100 words): three takeaways, primary entity reinforced, strong CTA with risk reversal, link to related content.

3. Self-check before delivery

1. Save the draft; run python3 ${CLAUDE_PLUGIN_ROOT}/scripts/text_metrics.py <draft> --keyword "<kw>". Fix anything outside the targets in ${CLAUDE_PLUGIN_ROOT}/skills/seo-fundamentals/references/scoring-spec.md §3 (density >3%, headings sparser than 400 words, Flesch under target, passages <4/1,000 words).
2. Run the humanizer skill as a pass (${CLAUDE_PLUGIN_ROOT}/skills/humanizer/SKILL.md) — it removes AI patterns and checks that the human markers present are real ones.
3. Score with /score (A–G). Deliver only at ≥70/100 and AI Overviews readiness ≥ PARTIAL, or state exactly which criteria the missing real material blocks.

4. Deliver

1. The article in markdown.
2. Meta title, meta description, slug — 3 options each (final polish via /meta-tags).
3. Internal link suggestions (anchor + target), external primary sources used.
4. Schema recommendation: Article + Person (author, sameAs) + BreadcrumbList; FAQ only if Q/A are literally in the body (/schema-gen).
5. A–G scorecard with dual verdict.
6. [NEEDS REAL DATA] gap list for the author.

Offer: /optimize for a deeper pass, /citable-passage for AI-search extractability, /internal-links to wire it into the site.