seo-content

name	seo-content
description	Create high-quality, SEO-optimized content that ranks AND reads like a human wrote it. Performs live SERP gap analysis, writes with anti-AI detection techniques, and adds schema markup. Use when someone needs a blog post, article, SEO page, or wants content that drives search traffic. Triggers on 'SEO content', 'blog post', 'article', 'SERP', 'programmatic SEO', 'content at scale', 'write a post about', 'rank for', or 'search-optimized content'. Two modes: single article or programmatic SEO at scale.
category	copy-content
tier	must-have
reads	["brand/voice-profile.md","brand/keyword-plan.md","brand/audience.md"]
writes	["assets.md"]
triggers	["blog post","SEO article","long-form content","rankable content","programmatic SEO","pages at scale","write SEO content for X","create article for keyword","refresh article","update blog post"]

/seo-content -- Publication-Ready SEO Content

SEO content has a reputation problem. Most of it is low-value -- keyword-stuffed, AI-sounding, says nothing new. It ranks for a month, then dies.

This skill creates content that ranks AND builds trust. Content that sounds like an expert sharing what they know, not a content mill churning out filler.

The goal: Would someone bookmark this? Would they share it? Would they come back?

If yes, Google will reward it. If no, no amount of optimization saves it.

---

On Activation

1. Read brand/ directory: load voice-profile.md, keyword-plan.md, audience.md, positioning.md, competitors.md, learnings.md if present.
2. Show what loaded:

   Brand context loaded:
   ├── Voice Profile   ✓ "{tone summary}"
   ├── Keyword Plan    ✓ {N} pillars, {N} briefs
   ├── Audience        ✓ "{audience summary}"
   ├── Positioning     ✓ "{primary angle}"
   ├── Competitors     ✓ {N} competitors profiled
   └── Learnings       ✓ {N} entries
   

3. If files missing, note suggestions at the end (e.g., run /brand-voice).
4. Check for existing content file at ./campaigns/content/{keyword-slug}.md.
   • If exists --> Content Refresh Mode (see below).
   • If not --> Full Creation Mode.
5. Determine mode: Single article or Scale mode (programmatic SEO).
6. Read brand/landscape.md if it exists — check the Claims Blacklist before making ecosystem or competitive claims. If stale (>14 days) or missing, warn that market claims may be outdated.

Prioritization (defer to seo-machine's publishing order)

When the user asks "what should I write next?" — the answer follows seo-machine's conversion-intent-first publishing order, not "whatever has highest volume":

Order	Pattern	Why
1	/alternatives/[competitor]	Highest conversion intent — reader is already in market
2	/compare/[a]-vs-[b]	Be the third option in any two-vendor comparison
3	/for/[use-case] and /for/[audience]	JTBD without competitor name — high TP/volume ratio
4	Long-form playbooks (this skill's wheelhouse)	Authority + AI-citation + inbound link draw
5	Generic blog posts	Lowest conversion — defer until ~10 indexed pages exist

If docs/seo-machine.md exists at the project root, route the user to that skill's Resume mode instead of writing standalone articles — the roadmap there already encodes the priority order. seo-content is the right tool for single articles and playbook-pattern long-form; alternatives/compare/use-case pages belong in seo-machine's programmatic sprint.

---

Brand Memory

Reads (if they exist)

File	What it provides	How it shapes output
voice-profile.md	Tone, personality, vocabulary, rhythm	Directly shapes writing style
keyword-plan.md	Prioritized keywords, content briefs, SERP data	Target keyword, cluster, intent, content type
audience.md	Buyer profiles, sophistication level, pain points	How technical to write, what examples to use
positioning.md	Market angles, differentiators	Unique angle for the piece
competitors.md	Named competitors, their positioning	What angle competitors take
learnings.md	Past performance data	What content approaches worked before

Writes

File	What it contains
./campaigns/content/{keyword-slug}.md	Publication-ready article with frontmatter
./brand/assets.md	Appends entry for the created content piece
./brand/learnings.md	Appends findings after feedback collection

---

Required Inputs

1. Target keyword -- Primary keyword to rank for
2. Keyword cluster -- Related keywords to include naturally
3. Search intent -- Informational / Commercial / Transactional
4. Content type -- Pillar guide / How-to / Comparison / Listicle / etc.
5. Brand voice profile -- (from voice-profile.md, if available)
6. Unique angle -- What perspective makes this different?

Pre-fill from brand memory when available. Ask the user only for what's missing.

---

The Workflow (Single Article)

RESEARCH --> BRIEF --> OUTLINE --> DRAFT --> HUMANIZE --> OPTIMIZE --> SCHEMA --> REVIEW --> SAVE

Phase 1: Research (SERP Analysis)

Use Exa MCP or firecrawl for live SERP research. Analyze top 5 results.

For each result capture: Title/URL, content type, word count, structure, unique angles, gaps, recency, domain type.

Extract SERP features: People Also Ask (ALL of them), Featured Snippet format, AI Overview presence.

Gap analysis: What's missing? What's outdated? What's generic? What's your edge?

Present findings in structured format. See references/serp-analysis-format.md.

If web search unavailable: flag to user, prefix SERP claims with ~, skip to Phase 2 using brand context instead.

Phase 2: Content Brief

Create or enhance an existing brief from /keyword-research. Include: target keyword, secondary keywords, search intent, content type, target word count, audience, unique angle, key points, PAA questions, competitor gaps, internal links, CTA.

Phase 3: Outline

Structure based on content type. See references/content-structures.md for templates (Pillar Guide, How-To, Comparison, Listicle).

Map PAA questions: depth-worthy ones become H2s, brief ones go to FAQ section.

Phase 4: Draft

Voice calibration: Match voice-profile.md if loaded. Default: direct, conversational, specific, opinionated.

Rules:

• Answer the search query in the first 2-3 sentences
• Apply the "So What?" chain -- write from the bottom, not the top
• Specificity over generality (numbers, examples, always)
• Show your work (how you know, not just what you claim)
• Use positioning angle from positioning.md to shape perspective

Phase 5: Humanize (Critical)

This is the soul of the skill. See references/anti-ai-detection.md for the full detection pattern guide.

Summary checklist:

• Kill AI words (delve, comprehensive, crucial, leverage, landscape, etc.)
• Kill AI phrases ("In today's...", "It's important to note...", "Let's dive in")
• Break the triple pattern -- humans are messier
• Inject: personal experience, opinions with reasoning, admitted limitations, specific examples, honest uncertainty, tangents and asides
• Vary rhythm: short punches, long explanations, fragments, questions

The Read-Aloud Test: If you stumble reading it aloud, rewrite it.

Phase 6: Optimize (On-Page SEO)

[ ] Primary keyword in title (front-loaded), H1, first 100 words, 1+ H2, meta, URL slug
[ ] Secondary keywords in H2s naturally
[ ] Meta description: 150-160 chars, compelling, includes keyword
[ ] Internal links: 4-8 per piece
[ ] External links: 2-4 authoritative sources
[ ] Featured snippet optimization (definition/list/table format)
[ ] Image alt text with relevant keywords

Title format: [Primary Keyword]: [Benefit or Hook] ([Year] if relevant) Under 60 characters, front-load keyword.

Phase 7: Schema Markup (JSON-LD)

Generate for EVERY article:

1. Article schema -- headline, description, author, dates, publisher, keywords
2. FAQ schema -- from PAA questions answered in the article
3. HowTo schema -- if content type is how-to tutorial

Include schema in article frontmatter. See references/schema-templates.md.

Phase 8: Quality Review

Run all checklists before saving:

• Content quality: Answers title in first 300 words, 3+ specific examples, unique angle present, all PAA answered, SERP gaps addressed
• Voice quality: No AI-isms, personality present, matches voice-profile.md
• SEO quality: Keywords placed, meta compelling, links included, schema valid
• E-E-A-T: Experience shown, expertise demonstrated, sources cited

See references/eeat-examples.md for 20 top-performing human content examples.

---

Content Refresh Mode

Triggered when content file already exists for the target keyword.

1. Present existing content summary with options: Refresh / Rewrite / Expand / Start Fresh
2. If Refresh: Re-run SERP analysis, compare against article:
   • New competitors since publication?
   • New PAA questions not covered?
   • Featured Snippet format changed?
   • Search intent shifted?
3. Generate specific, actionable update recommendations (not "update the content" but "add section on {topic} after {section} because {evidence}")
4. Apply updates, bump last_updated and serp_snapshot_date in frontmatter

---

Scale Mode (Programmatic SEO)

Triggered when user wants template-driven pages at scale ("programmatic SEO", "pages at scale", "100 pages for...", "location pages", etc.).

Core Principles

1. Unique value per page -- not just swapped variables in a template
2. Proprietary data wins -- hierarchy: proprietary > product-derived > user-generated > licensed > public
3. Clean URL structure -- use subfolders, not subdomains
4. Search intent match -- pages must answer what people are searching
5. Quality over quantity -- 100 great pages beat 10,000 thin ones

The 12 Playbooks

Playbook	Pattern	Example
Templates	"[Type] template"	"resume template"
Curation	"best [category]"	"best website builders"
Conversions	"[X] to [Y]"	"$10 USD to GBP"
Comparisons	"[X] vs [Y]"	"webflow vs wordpress"
Examples	"[type] examples"	"landing page examples"
Locations	"[service] in [location]"	"dentists in austin"
Personas	"[product] for [audience]"	"crm for real estate"
Integrations	"[product A] + [product B]"	"slack asana integration"
Glossary	"what is [term]"	"what is pSEO"
Translations	Content in multiple languages	Localized content
Directory	"[category] tools"	"ai copywriting tools"
Profiles	"[entity name]"	"stripe ceo"

See references/pseo-playbooks.md for detailed implementation of each playbook.

Choosing a Playbook

If you have...	Consider...
Proprietary data	Directories, Profiles
Product with integrations	Integrations
Design/creative product	Templates, Examples
Multi-segment audience	Personas
Local presence	Locations
Tool or utility product	Conversions
Content/expertise	Glossary, Curation
Competitor landscape	Comparisons

You can layer multiple playbooks (e.g., "Best coworking spaces in San Diego").

Scale Mode Implementation

1. Keyword pattern research -- identify repeating structure, variables, combinations
2. Data requirements -- what populates each page, how it's updated
3. Template design -- page structure with conditional content for uniqueness
4. Internal linking architecture -- hub and spoke model, no orphan pages
5. Indexation strategy -- prioritize high-volume, noindex thin variations, separate sitemaps by type

Scale Mode Quality Checks

• Each page provides unique value (not just variable swaps)
• Unique titles and meta descriptions per page
• Proper heading structure and schema markup
• Connected to site architecture, no orphan pages
• In XML sitemap, crawlable, no conflicting noindex

---

Worked Example

Target keyword: 'is doordash organic' SERP gap: Top 5 results are forum posts and outdated blog articles. No definitive guide exists.

Article outline:

1. H1: Is DoorDash Organic? The Complete Guide for Health-Conscious Families
2. Quick answer (Featured Snippet target): 'DoorDash itself doesn't verify verification status...'
3. How to find verified-source restaurants on DoorDash (step-by-step with screenshots)
4. The problem with DoorDash's verification filter (cross-contamination, no certification)
5. Better alternatives for guaranteed verified meal delivery
6. FAQ schema: 'Does DoorDash have verified-source options?' / 'How do I know if a restaurant is really verified?'

Word count: 1,800 (benchmark: top 3 results average 1,200 — we go deeper)

---

File Output Format

File Location

./campaigns/content/{keyword-slug}.md

Slug: lowercase kebab-case, remove stop words if over 60 chars.

Frontmatter

---
title: "{SEO-Optimized Title}"
meta_description: "{150-160 character meta description}"
primary_keyword: "{target keyword}"
secondary_keywords: ["{kw1}", "{kw2}", "{kw3}"]
content_type: "{pillar-guide / how-to / comparison / listicle}"
search_intent: "{informational / commercial / transactional}"
target_word_count: {number}
actual_word_count: {number}
author: "{author name}"
date_created: "{YYYY-MM-DD}"
last_updated: "{YYYY-MM-DD}"
status: "draft"
serp_snapshot_date: "{YYYY-MM-DD}"
paa_questions_answered: {number}
schema_article: |
  {Article JSON-LD}
schema_faq: |
  {FAQ JSON-LD}
---

---

Chain Offers

After saving, present:

• /content-atomizer -- distribute across social (3-5 LinkedIn, 8-12 Twitter, 2-3 IG carousels)
• /newsletter -- feature article in next edition
• /email-sequences -- nurture readers into subscribers
• /seo-content -- write next article from keyword plan
• "Refresh" to update this article later

---

Error States

• No web search: Skip Phase 1, note limitation, proceed with brand context
• No target keyword: Ask user or suggest /keyword-research
• No voice profile: Use defaults (direct, conversational), suggest /brand-voice
• Can't save: Display content for manual copy, suggest checking permissions

---

Anti-Patterns

Anti-pattern	Instead	Why
Skipping Phase 5 (Humanize) to save time	Cut research depth before cutting humanization	Unhumanized content reads like AI slop — readers bounce, Google devalues it, and the brand takes a credibility hit. Content that sounds like a committee wrote it doesn't earn trust, links, or shares.
Skipping schema markup	Always add Article + FAQ JSON-LD — it takes minutes	Schema compounds over time: rich results, AI citations, and structured search features for the life of the content. Skipping it leaves free visibility on the table.
Keyword-stuffing headings	One keyword in H1, natural secondary keywords in H2s	Google detects keyword stuffing and users find it off-putting. If every heading reads like an SEO template, it's over-optimized.
Starting with a generic intro	Answer the search query in sentence one	"In today's digital world..." tells the reader nothing. The search query brought them here — if the value prop isn't instant, they bounce.

---

Implementation Notes

1. Never skip SERP analysis when web search is available -- it's the differentiator
2. Always check for existing content first -- refresh mode is high value
3. Always generate schema markup -- Article + FAQ JSON-LD minimum
4. Always save to disk -- the file IS the deliverable
5. PAA questions are mandatory -- every one appears as H2 or FAQ entry
6. Phase 5 (Humanize) is non-negotiable -- run the full AI detection checklist
7. Always offer chain to /content-atomizer -- one article = 10+ social assets
8. Register every piece in ./brand/assets.md
9. Feedback closes the loop -- always present, always log