seo-content
Write publication-ready articles that earn classic rankings AND AI-surface citations (AI Overviews, ChatGPT search, Perplexity) while reading like a human expert wrote them. Use when turning a keyword or content brief into an actual piece. It scrapes the live SERP with parallel agents, captures who the AI surfaces cite and why, drafts in your voice, humanizes, optimizes on two tracks (on-page + GEO), and ships valid 2026 schema. Refresh mode diffs both the SERP and the AI-citation set against your published article.
How do I install this agent skill?
npx skills add https://github.com/boringmarketer/boring-marketing-skills --skill seo-contentIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill facilitates the creation of SEO-optimized articles by scraping search engine results and competitor websites. It executes a local Python helper script to manage branding and requires an API key for Firecrawl to perform deep web scraping.
- Socketpass
No alerts
- Snykfail
Risk: CRITICAL · 2 issues
What does this agent skill do?
/seo-content: Content That Ranks AND Gets Cited
Most informational queries are now answered by an AI surface before anyone clicks. The job is no longer "rank #1". It's "be the source the answer is built from, and convert the smaller, better-qualified traffic that arrives." This skill produces a piece that wins on both boards and sounds like a specific person wrote it from real experience. This is the floor, not the ceiling. When the situation argues for a better path, take it and say why.
Success is measured three ways, together: position for the target query, citation presence on AI surfaces, and conversions from the page. A #3 that holds the AI Overview citation beats a #1 that doesn't.
Context
Only if ./brand/, ./brands/ or MARKETING.md exists (nothing to load otherwise), run:
python3 ${CLAUDE_SKILL_DIR}/../start-here/scripts/brand_context.py --for seo-content
(If the script or python3 is unavailable, read the files named in reads: directly, section-anchored where specified. If none exist, proceed standalone. Ask only for what the task strictly requires.)
If ./brand/learnings.md has entries about content (formats, angles, lengths that performed), apply them. A prior that changed the piece gets one line in the Sources and assumptions note, only if it did.
Freshness check: Load references/ai-search-facts.md before Phase 1.5 and Phase 5. If it's past TTL, refresh it per its header first and say so in one line.
Modes
- Create (default): keyword → published-ready article. If a content brief exists at
./campaigns/content-plan/{keyword-slug}.md(from /keyword-research), load it. Don't re-research what it already settled. If a play exists for the topic (./campaigns/content-plan/play-*.md), find this piece in it: the hub links out to every spoke, each spoke links up to the hub and across to its nearest sibling, and the play's acceptance check for this piece goes in the output. - Refresh: an article already exists at
./campaigns/content/{keyword-slug}.md, or the user points at one. Skip to Refresh Mode below. Always check for an existing file before creating. Never silently overwrite.
Quick Mode applies: if the user pastes a brief and says "just write it," skip the research presentation ceremony: run Phases 1-1.5 quietly, deliver the article, one-line what's-next.
Required inputs
Target keyword (the only hard requirement). Get the rest from the brief, brand context, or one round of questions: search intent, content type, unique angle, and the user's real experience/credentials on this topic (needed for E-E-A-T and voice injection; never fabricate these).
Phase 1: SERP Reality (parallel fan-out)
Search the target keyword. From the results page capture: top 5-7 organic URLs, the related/People-Also-Ask questions as returned in the search results (they come back as data: there is nothing to click), and whether an AI Overview is present.
Then fan out one subagent per top-5 competitor URL, in parallel. Each agent scrapes its page (Firecrawl if FIRECRAWL_API_KEY is set, else WebFetch) and returns a structured evidence pack of FACTS, never estimates:
- True word count (from fetched content, not snippet guesswork)
- Complete H2/H3 map
- Schema types present (parse the JSON-LD blocks in the HTML)
- Publish date and last-updated date
- Whether an answer-first block sits under each major heading
- Original data/stats they present (verbatim, with their sourcing)
- Author identity and credentials shown
- Unique angles; what they miss or get wrong
We use Firecrawl for these page reads: full-page reads, so the word count, heading map and JSON-LD come from the real page (free tier of 1,000 credits a month, no card). Without it, WebFetch reads pages as summaries, so mark word counts and schema ~ and say so.
Run 2-3 keyword variations through search as well to widen the PAA pool. Never present model knowledge as live research: the Sources and assumptions note says how many pages were read and when, in plain words. If scraping is genuinely unavailable, say so, mark everything ~, and ask whether to proceed on general knowledge (the note then says to verify before publishing) or stop.
Gap analysis (from the evidence packs): what's missing, what's outdated, what's generic, and what's your edge: the thing the user can say that no ranking page can. If you can't articulate an edge, flag it now; an aggregation piece will neither rank nor get cited.
Phase 1.5: AI Surface Analysis
This decides whether the piece can earn citations, which is half the win condition. Run it in parallel with Phase 1's competitor agents.
- Capture the AI Overview for the target query: its answer text and every cited source (URL + which claim it supports). If no AIO appears, note that. It means the query still resolves to classic results, and Track B effort shifts from "displace a citation" to "be first in when one appears."
- Run 2-3 LLM-phrasing variants: the question as someone would ask a chatbot, not type into Google ("what is X" → "explain X like I'm evaluating tools," "is X worth it for a small team"). Search each; capture how the answer and citation set shift. Conversational phrasings often cite different sources than the keyword phrasing.
- For each cited source, record WHY it's cited (judge against the drivers in
references/ai-search-facts.md): extractable answer-block format? An original stat the answer quotes? Freshness? Clear entity attribution? Domain authority alone? - Record the AI citation gap alongside the classic SERP gap, in the notes file (
./campaigns/content/{keyword-slug}.notes.md, with the Phase 1 evidence packs). It is working data and is not pasted into chat:
AI SURFACE: "{query}"
AIO present: yes/no · Cited: {domain → why}, {domain → why}, ...
Variant phrasings cited: {any deltas}
Citation gap: {what a page would need that no current citation has,
e.g., "no cited source has post-2025 data; an original benchmark wins this"}
Save the citation set to the frontmatter's aio_citations. Refresh mode diffs against it.
Phase 2: Brief & Structure
Consolidate into a brief (or enrich the one from /keyword-research): keyword + secondaries, intent, content type, audience, unique angle, key points, PAA questions, SERP gap, AI citation gap, internal link targets, CTA.
The brief's core is the coverage map, and /keyword-research's briefs already carry one (its references/coverage-map.md has the full template and a worked example). Building it here, keep the same bones:
- every question verbatim, labelled by where it came from (People Also Ask, AI-native, autocomplete, Search Console), and anything you inferred labelled derived, never passed off as a real question;
- an answer shape per question (direct, definition, list, table, steps, comparison), which sets the block an engine can lift;
- gaps first, each with its observed reason: the brand is absent from the observed answers, the cited answers don't actually answer it, or the answer leans on a thin source a solid page could displace. A gap you can't point at isn't one;
- a depth benchmark from the measured winners on the surface you target (the cited sources for AI answers, the top results for Google): how many standalone answers and concrete facts they carry, not only their word count;
- a claim contract in three plain lists: what the piece may say (self-descriptive facts the business has confirmed, in approved wording), what it must not say, and what needs checking first (comparisons, numbers, outcomes, testimonials, credentials and prices whose only source is the business's own marketing copy). The draft never exceeds the contract. A claim being on the homepage is attribution, not proof.
If every question turns out well answered and nothing is a gap, say so before writing: the piece has no winnable white space, and the user should decide whether it's worth writing.
Structure is information-driven, not length-driven. There is no target word count. List every question and subtopic the piece must cover (intent + PAA + gaps), give each exactly the space it needs, stop. Density wins: AI-assisted SERPs and AI answers both punish padded long-form. A bloated 6,000-word "ultimate guide" is now a liability, not a moat. Length is an output, not an input.
Ordering judgment by content type: pillar/explainer leads with the direct answer then descends from broad to specific; how-to shows the end result first then numbered steps (one action each, troubleshooting inline); comparison opens with the verdict ("Choose X if... Y if...") then a spec table then depth; listicle opens with the full list for skimmers then per-item depth including honest limitations.
PAA coverage, the default bar: every captured question gets answered: as an H2 (deserves depth) or an FAQ entry (deserves two sentences). Use the question's own phrasing in the heading; that's how people search and how LLMs match. Skip a question only when it's genuinely off-intent or belongs on another page, and say which.
Internal links come from real data. Fetch the user's sitemap.xml (or scan the content directory if this is a local repo site) and pick 4-8 genuinely related URLs. Never write "[link to related content]" placeholders: if you can't find the sitemap, ask for 3-5 URLs or omit the links and say why. Descriptive anchor text, varied naturally.
Phase 3: Draft
Load references/humanize.md BEFORE drafting: it's cheaper to write human than to repair AI prose. Calibrate to voice-profile.md if loaded (tone, vocabulary, rhythm, words-to-avoid); otherwise default to direct, conversational, specific, opinionated: a smart friend who happens to be an expert.
Craft rules that govern the draft:
- The first-paragraph rule. Answer the search query in the first 2-3 sentences. Nobody scrolls for the answer anymore, and neither do extraction models.
- The "so what?" chain. For every point, ask "so what?" until you hit something the reader cares about, then write from the bottom of the chain. "Automated sequences" → "follow-ups send themselves" → "you wake up to replies." Write the last one.
- Specificity over generality. "Saves time" is dead weight; "cut outreach from 4 hours to 15 minutes" (illustrative) is an argument. Numbers, examples, named things.
- Show your work. Claims carry their evidence: "after testing N tools," "across N client accounts," "we analyzed N pages." These must be the user's REAL numbers: pull from brand context or ask. A fabricated experience claim is an E-E-A-T liability and a trust breach. Lived examples are an input, not a craft move: ask for them precisely, shaped to the topic ("two shift-swap stories from customers with five or more locations"). If the ask goes unanswered, the piece is thinner and the Sources and assumptions note says so; it never invents one.
- Write from the practitioner's chair. The stance is someone who measured this market writing the piece they wish existed, for a peer. The claim contract is your editor, not your author: prose drafted rule by rule reads like it was drafted rule by rule.
- The reader never sees your instruments. No "this shows up in autocomplete, which means people are asking", no "as of <month>, ChatGPT names...", no strategy talk ("a clear definition can take this slot"). The research decides what the page says; it doesn't appear in it. One deliberate evidence line in reader terms ("we pulled 140 of our own invoices", illustrative) is fine.
- Say each claim once, at full strength. Later sections build on it instead of paraphrasing it down, and the FAQ answers a different question rather than restating the body in new words.
- Truth-safe isn't procedure. Told never to invent, writers fill space with how to call, what to expect and questions about the booking itself. Point the writing at the substance of the work (what fails, how it's diagnosed, what the fix involves, what waiting costs), which is true and specific at once. Cut any paragraph that would make sense for a different business.
- Comparisons earn their verdict. Give a verdict only when each option has at least two facts across at least two of the dimensions the reader weighs. Label where each fact came from (tested, the vendor's own page, editorial judgment) and route the reader: "choose X if..., Y if...". A comparison that always crowns the house product reads as the ad it is.
- Positioning shapes HOW, not WHAT. The keyword dictates the topic; positioning (if loaded) dictates the lens: practitioner stories vs. data-led vs. contrarian. The angle should be visible in every section, not bolted onto the intro.
- Match the quality bar in
references/eeat-examples.md. Load it when you need calibration on what "a specific person wrote this" reads like.
Phase 4: Humanize
Run the full pass from references/humanize.md: word/phrase/structure/voice tells removed, voice injection points added from the user's real experience, rhythm varied, detection checklist green, read-aloud test passed. This phase is the soul of the skill: the full pass is the default; compress it only when the draft already reads human, and say so. A word-swap is not a humanize pass.
One tension to manage deliberately: the answer blocks (Track B below) stay direct and self-contained; the prose around them carries the personality. Humanize the piece, not the extractable blocks into mush.
Phase 5: Optimize: two tracks
Track A: Classic on-page
- Primary keyword: title (front-loaded, ≤60 chars), H1, first 100 words, ≥1 H2, URL slug, meta description.
- Meta description 150-160 chars: direct answer + proof + hook. It's ad copy for the click that still exists.
- Secondary keywords distributed across H2s where natural, never forced.
- Headers are scannable summaries of their sections, logical H2 > H3 hierarchy.
- 4-8 internal links (from the Phase 2 sitemap crawl), 2-4 external links to authoritative sources for factual claims, descriptive alt text on images.
- Featured snippets: don't chase them separately. AI Overviews have cannibalized most of that real estate, and the Track B answer blocks are the same format that wins whatever snippets remain. One format, both targets.
Track B: GEO (citation engineering)
This is what makes the piece extractable and attributable. Apply against the drivers in references/ai-search-facts.md:
- Answer-first block under every H2: 40-80 words, self-contained (no "as mentioned above," no dangling pronouns), directly answering the heading. This is the passage an LLM lifts; it must stand alone out of context.
- ≥1 original, citable stat per major section. First-party data, a computed synthesis (the median of something you measured across the top-ranking pages, stated in reader terms, is itself original data), or the user's real numbers. Each stat phrased so it can be quoted with attribution. If a section has no citable fact, it will be paraphrased without credit: that's the failure mode.
- Quotes and named sources: where a real person at the business can say it, one quotable line attributed by name, and the source named for every number. In the one controlled experiment on generated answers, quotations, statistics and cited sources lifted visibility; keyword stuffing didn't.
- Named-entity consistency: one canonical name per product/company/person used throughout; define each entity on first mention. Engines cite pages they can confidently attribute and disambiguate.
- Freshness signals: visible updated date, current-year facts, no fossil dates in examples.
- Distribution notes for the user (one line each in the output): ping IndexNow on publish (it reaches Bing and Copilot; Google ignores it, and ChatGPT retrieves from OpenAI's own index); check that OAI-SearchBot and GPTBot are allowed in robots.txt and that the core content is in server-rendered HTML. An
llms.txtfile is optional and has no confirmed effect (seereferences/ai-search-facts.md).
Phase 6: Schema
What schema does: it makes the page machine-parseable and clarifies what it is, who wrote
it, and who published it. Generate it for those reasons, with no rich-result promises;
current rich-result status and citation evidence live in references/ai-search-facts.md.
Generate, into the saved file's frontmatter:
- Article: headline, description, datePublished, dateModified, mainEntityOfPage. No
keywordsproperty (dead weight, ignored). - Person (author): name, jobTitle, and
sameAslinks to the author's LinkedIn/X/site. This is the entity-clarity workhorse: it's how engines resolve WHO is behind the page. Ask for the author's profile URLs if brand context doesn't have them. - Organization (publisher): name, url, logo,
sameAs. - FAQPage: only if the article has an FAQ section, and tell the user honestly: this earns no rich result for most sites; its value is giving LLMs a clean Q/A structure to lift.
- Never HowTo. Removed by Google in 2023; generating it is shipping dead code.
Quality gate
Run this check silently before saving: score the draft, rewrite weak dimensions and rescore. About 3 iterations is the practical ceiling; past that the constraint is upstream (angle, experience inventory). The client sees only the passing piece. A weakness that cannot be fixed gets one line in the Sources and assumptions note:
- Answers the query in the first paragraph, better than what's ranking
- Every PAA question answered (H2 or FAQ); SERP gaps from Phase 1 addressed
- AI citation gap from Phase 1.5 addressed: at least one section gives an engine a reason to cite YOU specifically
- Humanize checklist passed (references/humanize.md)
- All experience claims and stats are real (user-sourced) or clearly attributed; zero fabricated numbers; nothing outside the claim contract; no research instruments or strategy talk in the prose
- Track A + Track B items verifiably present (answer blocks, entity consistency, schema valid JSON-LD)
- The bar: would someone bookmark this? Is there one thing here they can't get anywhere else?
Refresh Mode
Trigger: existing file at ./campaigns/content/{keyword-slug}.md, or the user says refresh/update. Read the article and its frontmatter (serp_snapshot_date, aio_citations), then re-run Phase 1 and Phase 1.5 and diff:
SERP diff: new top-5 entrants and their angles · PAA questions not yet covered · intent shift · outdated stats/claims in the article.
AI citation diff (the differentiated half): compare today's AIO citation set against the stored aio_citations. Report movement plainly: "you held the citation for the pricing claim; you lost the definition citation to {domain} since {snapshot date}, because their answer block is fresher and carries a current-year stat." For each loss, name the mechanism (format/stat/freshness/entity) and the specific fix. Remember the base rate from ai-search-facts.md: 40-60% of citations churn monthly: losses are normal and recoverable, which is exactly why refresh is a recurring job worth scheduling.
Edit the current published version; never re-draft from the original brief, which throws away every change made since. Present recommendations as specifics, never "update the content": add H2 "{question}" after "{section}" because {evidence} · replace the {year} stat in {section} with {current} · rewrite the answer block under "{H2}" to ≤80 self-contained words · add FAQ entries for {new PAA}. Apply on confirmation; update last_updated, serp_snapshot_date, and aio_citations; auto-version the old file per the brand-memory protocol.
Output
Worked example: load references/worked-example.md for the end-to-end flow and the clean final output, with clearly labeled sample data.
Save to ./campaigns/content/{keyword-slug}.md (create the directory if needed; slug = lowercase kebab-case, stop words dropped if >60 chars). YAML frontmatter:
---
title: ""
meta_description: ""
primary_keyword: ""
secondary_keywords: []
content_type: ""
search_intent: ""
author: ""
date_created: YYYY-MM-DD
last_updated: YYYY-MM-DD
status: draft
serp_snapshot_date: YYYY-MM-DD
aio_citations: [] # [{domain, claim_cited, why}]: Refresh mode diffs this
play: "" # hub or spoke, and the play file, when the piece belongs to one
acceptance_check: "" # the observable result that proves the piece worked
needs_checking: [] # claims held back until someone confirms them
schema: |
{Article + Person + Organization (+ FAQPage) JSON-LD, ready to paste into the CMS}
---
Body: the full article (H2/H3 structure, FAQ section last). The frontmatter is working data for the CMS handoff and Refresh mode; chat never repeats it.
Then present per the output contract (${CLAUDE_SKILL_DIR}/../start-here/references/output-format.md). Header ## SEO ARTICLE: {title} plus one line of date and what the piece is for, with no data tag or gate score. Then a short summary: the angle in a sentence, the gap it closes that the ranking pages and AI answers leave open, what the owner must confirm or supply before publishing (the needs_checking items, missing lived examples), and the publish steps from Track B. Then one Sources and assumptions note, 10 lines at most: what the piece rests on in plain words (pages read, AI surfaces queried, date), the data quality, and what to confirm. The gap-aware receipt is at most 3 of those lines: what was checked, what could not be, and the one ask that would close the gap, such as "no real job numbers yet, so the cost section quotes ranges from cited sources; send the last 12 months of invoices and it becomes the only local price data on the page". Then Files saved (content file, the notes file, one-line append to ./brand/assets.md) and What's next. No score tables, tool names or per-line data tags.
What's next (pick 2-3 that fit):
/content-atomizer: one article into platform-native social assets (~10 min)/ai-search: full share-of-model audit + citation monitoring routine across your money queries (~20 min)/creative: featured image and social cards for this piece (~15 min)/seo-content: next brief in the keyword plan, or schedule a refresh: citations churn monthly
When the user edits your work
Apply the edit, then make it stick: save a gold case to ./brand/gold/<this skill>/ and
one to three yes/no checks to ./brand/checks.md, and confirm in one line. Before handing
over any work, answer the checks the context block loaded, silently, and fix every no.
How: ${CLAUDE_SKILL_DIR}/../start-here/references/taste-loop.md.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/boringmarketer/boring-marketing-skills/seo-content">View seo-content on skillZs</a>