agentleFS
ThibaultbmThibaultbm/claude-seo-geo/skills/seo-content-blog/SKILL.md

seo-content-blog

Skill18 starsChanged 11 days agoMITView on GitHub

Spec, audit, competitor benchmark and build for blog articles and the blog template, so a post ranks on Google and gets cited by AI engines (ChatGPT, Perplexity, AI Overviews). Input: a keyword, topic, draft or post URL. Phase 1 spec: BLOG rows on top of the common page spec, covering the 12-element answer-first skeleton and the page template (author line with photo and dates, sticky table of contents, sidebar author and CTA cards, in-content CTA, author box with real social profiles, related posts, key takeaways, sources, hub cards with covers). Phase 2 audits the article, the hub and the home with seo_audit.py and section_audit.py. Phase 3 benchmarks the top 3-5 SERP results with page_benchmark.py and names the information gain. Phase 4 builds and re-runs the scripts. Output: spec scorecard, findings, benchmark, the publish-ready article with metadata and JSON-LD, acceptance. Use when writing, rewriting, refreshing or auditing a blog post or the blog template, or when one will not rank or get cited.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 6 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every C row applies to the article, the hub and the author page.

    line 51
  2. Distinctive:

    Run both scripts on the article, the hub, the home (publisher entity, BLOG-35) and the author page:

    line 107
  3. Distinctive:

    Every article page must carry a capture popup that opens only once the visitor is actually reading.

    line 270
  4. Distinctive:

    Chunk autonomy: every H2 section must stand alone: direct answer in 2-4 sentences, then development, with no "as we saw above" references.

    line 355
  5. Distinctive:

    Invented FAQ questions: Use People Also Ask; made-up questions match no real query and no fan-out sub-query.

    line 441
  6. Distinctive:

    Search Engine Land, query fan-out optimization guide: https://searchengineland.com/guide/how-to-optimize-for-query-fan-out

    line 459

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

SEO Blog Content That Ranks and Gets Cited

A blog article captures informational searches and hands that traffic and authority to the pages that sell; in AI engines it is the passage that gets lifted as the answer. It fails in two ways: text that restates the SERP with the answer buried under context, or good text in a bare template with no author, no dates, no table of contents and no call to action. This skill specifies both layers on a 12-element skeleton (field methodology from 115+ agency audits, layered with 2024-2026 citation research), audits them, benchmarks the pages that rank, and builds the article.

Company knowledge first (Obsidian)

If the working environment contains an Obsidian vault or any local knowledge base (a folder of .md notes, often with a .obsidian directory), read the relevant notes before acting: brand and product facts, target keywords, competitors, and the SEO action log of what was already tried. Ground every recommendation in that context instead of asking the user for facts the vault already holds. At the end of the session, append the actions taken to the vault's SEO action log so the next session starts informed.

When to use

  • Writing a new blog article from a keyword, topic, or brief.
  • Rewriting or refreshing a published post that decayed or never ranked.
  • Reviewing a human-written or AI-generated draft before publication.
  • Producing an outline or content brief for a writer.
  • Building or auditing the article template, the author page or the blog hub, including a site generated by an agent.
  • Planning publication cadence for a blog launch or an established site.
Adjacent jobSkill
Choosing the target keyword, mapping intent, splitting overlapping topics (merge test)seo-keyword-research
Product, service, collection page copyseo-content-product-page, seo-content-service-page, seo-content-collection-page
Homepage copy, including its latest-articles blockseo-content-homepage
Standalone "X vs Y" and alternatives pagesseo-content-comparison-page
Block gaps on other page typesseo-page-sections
Site-level link routing and silosseo-internal-linking
JSON-LD field rules, breadcrumb markupseo-schema-markup
News sitemap, RSS, AI crawler access, scaled content indexationseo-technical
Passage-level citability, AI citation trackinggeo-visibility, geo-tracking
Full site diagnosisseo-geo-audit

Phase 1. The spec

Lock the target before reading the spec:

  • Primary keyword and the intent behind it (informational or commercial investigation).
  • Language and market: a French SERP and a US SERP rarely reward the same article.
  • The commercial pages this article must support with internal links.
  • Whether an existing article already covers this intent. If yes, rewrite it instead of creating a new one (BLOG-01).

Common requirements C-01 to C-27: skills/seo-geo-audit/references/common-page-spec.md

Every C row applies to the article, the hub and the author page. The rows below are blog-specific; "tightens C-xx" means the row sets the blog value of a common row, which still applies. Thresholds are field heuristics from 115+ agency audits unless marked measured.

Article text (the 12-element skeleton, detailed in Phase 4)

IDRequirementThresholdVerified byWhy
BLOG-01One angle = one article0 other URLs on the site targeting the same intentmanual (site: search, Search Console query to pages; merge test in seo-keyword-research)Two articles on one intent cannibalize each other and split clicks, links and signals
BLOG-02Title phrased as a reason to click, on the query-type pattern (tightens C-01)30-60 characters, keyword near the front, pattern from the title tabletitle_short, title_long, manual for the patternBeyond roughly 60 characters Google truncates; a label earns fewer clicks than a promise
BLOG-03Length at or above the SERP benchmark, never shorter than the page it replaces (sets the C-08 floor)Competitor median or above; 300 minimum, 500+ competitive, 750+ commercial-adjacent, under 180 critically thinarticle_short (under 800), thin_content, page_benchmark.py "words"Shorter rewrites are one of the most common self-inflicted ranking losses
BLOG-04Answer-first block, shown as a labeled key takeaways box ("In short", "Key takeaways", "En bref")2-4 sentences or 3-5 bullets, directly after the H1 block, within the first screenmanualThe most cited passage of a page and featured snippet material; the highest-leverage GEO element
BLOG-05Intro opens on the keyword in bold and links the first authority source (tightens C-09, C-10)Keyword bold in the first sentence; first external source inside the introkw_not_bold, kw_not_in_intro, manual for the source positionConfirms the topical match at once and marks the article as sourced from the first screen
BLOG-06Question H2s, each section self-contained (tightens C-13)H2 as a question whenever the section answers one; direct answer in 2-4 sentences, then development; no "as seen above"no_question_h2, manual for autonomyMaps to People Also Ask and AI sub-queries; engines retrieve isolated chunks
BLOG-07Comparison table for anything comparable1+ on an 800+ word articleno_table, section_audit "any_table", "comparison_table"The most extractable comparison format
BLOG-08Expert quote and sourced statistics (tightens C-14)1+ expert quote, 2+ statistics with sources cited inlineCITABILITY quotes and stats, no_statsMeasured +41% (quotes) and +32% (statistics) generative visibility
BLOG-09External sources of three accepted types3-5; government or institutional, major media, scientific studies; followed; zero competitorsfew_sources (under 3), manual for type, competitor and nofollowWhat raters and fact-checking systems treat as ground truth; a competitor link donates authority
BLOG-10Internal links to the pages that sell, visibly styled (tightens C-16)3-5 to products, services, collections, pricing; underlined plus a distinct colorno_cta_money, TEMPLATE "money links in body", manual for the styleConverts informational traffic and authority into commercial rankings
BLOG-11Conclusion restates the answer, bolds the takeaway, ends on one CTA1 CTA to the most relevant commercial pagemanual, section_audit "cta"Second-most-read block for skimmers; no next step wastes the traffic
BLOG-12FAQ from real People Also Ask questions3 questions, 2-4 sentence answers eachsection_audit "faq", manual for the PAA matchEach pair is an autonomous chunk that matches a real sub-query
BLOG-13Three images (C-15 governs alt, format, weight)1 cover + 2 in the bodysection_audit "images", manual countBreaks text walls, ranks in image search, alt is the only image text AI crawlers read
BLOG-14Information gain1+ element the current top 5 do not havemanual (Phase 3)A page that restates the SERP gives the index no reason to rank it and AI engines no reason to cite it

Article template (built once, repeated on every post: references/blog-templates.md)

IDRequirementThresholdVerified byWhy
BLOG-15Author line under the H1Photo 40px of a real person (alt = name), name linked to the author page, role, published date, updated date, reading timeauthor_missing, author_page_link, date_missing, section_audit "author_block", "freshness_signal"E-E-A-T accountability at first glance; dates are a freshness signal Perplexity and AI Overviews weigh visibly
BLOG-16Cover image as the LCP element (tightens C-15)1200px+ wide, WebP or AVIF, under 200 KB, eager with fetchpriority high, width and height set, max-image-preview:largelcp_lazy, image_weight, image_format, image_dimensionsLazy-loading the cover is the most common blog speed mistake; Discover needs 1200px+
BLOG-17Sticky table of contentsAnchor links to every H2 generated from the headings; sticky in the sidebar on desktop with the current section highlighted; collapsible block under the intro on mobile; stable readable H2 idstoc_missing, manual for sticky and highlightOrientation on long pages, jump links in results, the subtopic map for machine readers
BLOG-18Sidebar author cardPhoto, name, role, one-line credential, link to the author page, real social profile iconsauthor_page_link, social_placeholder, manualKeeps the expert visible while reading; links the author entity across platforms
BLOG-19Sidebar CTA cardOne offer, one button, to the commercial page matching the article intentmanual, section_audit "cta"Readers convert when the next step is always on screen
BLOG-20In-content CTA block1 visually distinct block after roughly 40% of the body, to the commercial page closest to the intentno_cta_money, manual for positionMost readers never reach the conclusion
BLOG-21End-of-article author boxPhoto 96-120px, name, role, 2-4 line bio with verifiable credentials, author page link, real social profiles (never a network homepage)author_missing, social_placeholder, manualThe full E-E-A-T statement where readers decide whether to trust
BLOG-22Sources sectionBefore the FAQ, each source listed with what it supportsfew_sources, manualShows the work; the sourced-content signal measured in the GEO layer
BLOG-23Hub link"Continue on {topic}" link to the topic hub or category pagemanualCloses the silo loop
BLOG-24Related posts3 cards with cover, title, one-line excerpt, same category firstmanual, section_audit "internal_links"Internal links within the silo, pages per session
BLOG-25Final CTA bannerFull width before the footer: promise, social proof, buttonmanual, section_audit "cta"The last conversion surface
BLOG-26Article JSON-LD (tightens C-18)BlogPosting + Person (image, jobTitle, url, sameAs) + BreadcrumbList; publisher by @id; real dates; no empty FAQ nodesschema_article, schema_fields, jsonld_invalidEntity graph for AI engines; a template that ships empty FAQ markup breaks every post
BLOG-27Honest freshnessVisible dates; dateModified moves only with real content changes; comparative listicles refreshed every 60-90 daysdate_missing, manualGoogle compares versions; a date-only refresh is deceptive freshness
BLOG-28Glossary linksFirst mention of each defined term per article links to its glossary page, when a glossary existsmanualInternal linking at scale and definitions AI engines can cite

Author page, blog hub, site

IDRequirementThresholdVerified byWhy
BLOG-29Author page linked from every bylineH1 name and role, large photo, 150-300 word bio with verifiable facts, social profiles, the author's articles as cards with covers, CTA; ProfilePage JSON-LD with the same Person @idauthor_page_link, seo_audit on the author URL, manualThe page that proves the expertise
BLOG-30Every hub card carries its coverCover 16:9 (alt = topic), category label, title, 1-2 line excerpt, date, reading time, author photo and namehub_no_covers (3+ posts, covers on fewer than half)A text-only list looks abandoned and loses clicks and image entry points
BLOG-31Hub image loadingFirst row of covers eager, the rest lazylcp_lazy on the hub, manualThe first row is above the fold; the rest should not compete for bandwidth
BLOG-32Crawlable hub structureCategories are real pages with an intro; pagination with real URLs (/blog/page/2/), never only "load more"manualCategory pages rank on head terms; a button with no URL hides older posts
BLOG-33Hub JSON-LDBlog with a blogPost list, or ItemListschema_none, manualHands the post inventory to machines in one block
BLOG-34Hub layout and growthBreadcrumb, H1 keyword + promise, 2-3 line intro, featured card, CTA after the first 6 cards; topic hubs at 3+ posts per theme; search at about 12+ posts, search pages noindexmanualSilos rank on the head term of each theme; readers find the post they came for
BLOG-35Publisher entity on the homeOrganization node (@id #organization) on the homepage at least; footer social profiles real and identical to sameAsschema_entity and social_placeholder on the homeThe publisher every BlogPosting points to must exist
BLOG-36Media hygieneVideo embedded from YouTube, never self-hosted; Substack or Medium mirrors set to noindexmanualPage weight, a second surface, no duplicate outranking the original
BLOG-37Year in titles computed, never typedAny year in the title tag, H1, og:title or twitter:title is the current year rendered at build or request time from the clock (a template variable), never a hard-coded "2026"; exception: a year that belongs to a dated external source being cited ("State of SEO 2025 report") stays as writtenstale-year check in the decay finder, manualA typed year goes stale every January on every post at once; a computed year never does, and a cited source keeps its real date

Phase 2. Audit the existing page

Run both scripts on the article, the hub, the home (publisher entity, BLOG-35) and the author page:

python3 skills/seo-geo-audit/scripts/seo_audit.py https://example.com/ /blog/ /blog/<post>/ /author/<name>/
python3 skills/seo-page-sections/scripts/section_audit.py --type blog https://example.com/blog/<post>/

seo_audit.py classes each URL: blog_hub (last path segment blog, articles, news, guides, resources and similar, or Blog schema) and article (Article or BlogPosting schema, or a URL under a blog-like segment). The template checks run only on those kinds. A post at a root slug with no BlogPosting schema is classed page and skips them: that is itself a BLOG-26 failure, so audit it by hand against BLOG-15 to BLOG-28. Read the BOLD, PLACEMENT, CITABILITY, TEMPLATE, BLOG HUB, SOCIAL and SCHEMA FIELDS lines and the FINDINGS list.

Finding or script lineSpec rows
article_short, thin_contentBLOG-03, C-08
kw_not_bold, kw_not_in_intro, kw_placement_lowBLOG-05, C-09, C-10
no_question_h2BLOG-06, C-13
no_table, section_audit "any_table"BLOG-07
no_stats, CITABILITY quotes=0BLOG-08, C-14
few_sourcesBLOG-09, BLOG-22
no_cta_moneyBLOG-10, BLOG-20, C-16
author_missing, section_audit "author_block"BLOG-15, BLOG-21
author_page_linkBLOG-15, BLOG-18, BLOG-29
date_missing, section_audit "freshness_signal"BLOG-15, BLOG-27
toc_missingBLOG-17
lcp_lazy, image_weight, image_format, image_dimensionsBLOG-16, BLOG-31, C-15
schema_article, schema_fields, jsonld_invalidBLOG-26, C-18
social_placeholder, social_missingBLOG-18, BLOG-21, BLOG-35, C-20
hub_no_coversBLOG-30
schema_entity on the homeBLOG-35
breadcrumb_missingC-19
em_dashesC-25

Rows no script sees (BLOG-01, 02 pattern, 04, 06 autonomy, 09 source types, 11, 12 PAA match, 14, 17 sticky behavior, 19, 23 to 25, 28, 32 to 34, 36): read the page in a browser at desktop and mobile width. Mark every BLOG and C row Pass, Fail or Not verifiable; Not verifiable is the honest status when the page is client-rendered (C-21) or the draft is not live, in which case grade the draft text by hand. For a new article, skip the article audit but still audit one existing post and the hub: the template is shared, so its failures will repeat on the new post.

Refresh mode: which posts to rewrite first. When the job is "refresh the blog" rather than one post, rank the posts before auditing any of them. Export Pages.csv from Search Console for the last 3 months, the 3 months before, and the same 3 months a year earlier, crawl the site, then run the decay finder:

python3 skills/seo-internal-linking/scripts/site_crawl.py https://example.com --out crawl.json
python3 skills/seo-traffic-drop/scripts/content_decay.py --current last3m.csv --previous prev3m.csv --last-year ly3m.csv --crawl crawl.json

It returns a refresh queue: posts losing 20%+ of their clicks, classified as ranking loss (refresh the content and benchmark the pages that passed it), CTR loss (rewrite title and meta, sharpen the answer-first block, check for an AI Overview), demand loss (widen, merge or accept) or seasonal (no action), with stale posts (a past year in the title, no update for 12+ months) first. Take the queue top-down through Phases 2 to 4; this is the rewrite-first rule (Rules and thresholds) made measurable.

Phase 3. Benchmark the competitors

page_benchmark.py also prints the vocabulary gap: the terms and two-word phrases that half or more of the competitors use and the article never does, with the competitor H2/H3 that carry them. Treat it as the coverage checklist for the outline (a missing subtopic becomes a section), never as words to sprinkle.

Read the SERP before writing a single line. Pick the top 3-5 Google results for the keyword in the target market (articles answering the same intent; if forums or videos dominate, that is a format signal to record), plus any page ChatGPT, Perplexity or AI Overviews cite when asked the query. Run:

python3 skills/seo-geo-audit/scripts/page_benchmark.py --type blog https://client.com/blog/<post>/ https://rival1.com/a/ https://rival2.com/b/ https://rival3.com/c/

For a new article, pass the closest existing post as the client argument: it benchmarks the template, and the competitor columns set the bar. Read the block x competitor table, the blocks most competitors have and the client lacks, the schema types they use, and the metrics below the median (words, bold, h2, question_h, tables, statistics, money_links, the toc, author and dates columns). Record by hand what the script cannot see:

Per competitorWhy it matters
Word countSets the length floor; never come in under the median (BLOG-03)
H2 structure and questions answeredThe subtopics Google already rewards; this is the coverage checklist (BLOG-06)
Tables, images, videos usedThe formats the query expects (BLOG-07, BLOG-13)
Publication and update datesThe freshness bar; an aging SERP is an opening (BLOG-27)
People Also Ask questionsRaw material for the FAQ and the question H2s (BLOG-12)

Why: the SERP is the specification. Google is showing what it already considers a satisfying answer for this query; writing blind produces a worse copy of it.

Set the length. Target the median of the ranking pages or above (thresholds below). Never plan a rewrite shorter than the page it replaces: replacing long ranking content with shorter content is one of the most common self-inflicted ranking losses observed in audits.

Define the information gain (BLOG-14). Name at least one element the current top 5 do not have:

  • Original data: your numbers, a small survey, aggregated anonymized client results.
  • First-hand experience: you ran the process, with outcomes and photos.
  • An expert quote collected for this article.
  • A comparison table no competitor built.
  • A fresher statistic, with its source linked.

Why: Google holds a patent on scoring pages by information gain (US 11,354,342, "Contextual estimation of link information gain"; a patent signals research direction, not confirmed production use); a page that restates the SERP gives the index no reason to rank it and gives AI engines no reason to cite it. This step is also what makes AI-assisted drafting safe (rules below).

Phase 4. Build

Step 1. Draft on the 12-element skeleton

Apply every element. Each one exists because its absence showed up as a recurring loss across 115+ agency audits. Write the body first; write the title and meta description last, they are sharper once the article exists.

1. Title tag + meta description (C-01, C-02, BLOG-02). Title 30-60 characters with the primary keyword near the front, phrased as a reason to click, not a label. When the title carries a year, it is computed from the current date by the template, never typed (BLOG-37). Meta description 120-160 characters, written by hand. Why: beyond roughly 60 characters Google truncates the title; a hand-written description controls the SERP pitch instead of letting Google assemble one from random page text, and the snippet is the first conversion surface of the article.

2. Cover image + single H1 + breadcrumb (C-03, C-19, BLOG-16). Exactly one H1, containing the primary keyword. A visible breadcrumb trail (markup details: seo-schema-markup). Why: multiple H1s blur the topical focus of the page; the breadcrumb tells crawlers and AI engines where the page sits in the site hierarchy.

3. Visible author + reading time (BLOG-15, BLOG-21). Real name, photo, role, linked to an author page, published and updated dates, plus an author box at the end with credentials and real social profiles (never a placeholder link to a network homepage). Show a short byline under the H1 and the full author card in the side column next to the article, sticky on desktop, alongside the table of contents. A byline that reads as the company name ("By Brand.com") does not count. Why: E-E-A-T accountability. Anonymous content is easier for quality systems and AI engines to discount, especially on money or health adjacent topics. A card that stays in view while the reader scrolls keeps the expertise visible at every depth, not only on the first screen. Reading time sets expectations and reduces pogo-sticking.

4. Table of contents (BLOG-17). Anchor links to every H2, generated from the headings, sticky in a sidebar on desktop with the current section highlighted, collapsible under the intro on mobile. Why: orients readers on long pages, can produce jump links in Google results, and hands machine readers the subtopic map in one block.

5. Answer-first summary block (BLOG-04). Directly after the H1 or first paragraph: give THE answer to the title query in 2-4 sentences, before any background. Why: AI engines extract passages and economize tokens; a complete answer at the top is the answer served directly, and it is the most cited passage of a page. It doubles as featured snippet material. This is the highest-leverage GEO element in the skeleton.

6. Intro with bolded keyword + first authority link (BLOG-05). The first sentence contains the primary keyword in bold. The first of the external sources is linked inside the intro. Why: instantly confirms topical match for readers, parsers, and ranking systems; an early citation marks the article as sourced from the first screen (citing sources is measured at +30% generative visibility, see GEO layer).

7. Body sections (BLOG-06, BLOG-07, BLOG-08, C-09). H2s phrased as real questions whenever the section answers one. Secondary keywords and key facts in bold (semantic bolding, not decoration). Several images, comparison tables for anything comparable, expert quotes where claims need weight. Why: question H2s map to People Also Ask and to the sub-queries AI engines generate; tables are the most extractable comparison format; quotes and statistics carry measured citation gains.

8. External sources: 3-5, three accepted types only (BLOG-09, BLOG-22). Government or institutional sites, major media, scientific studies. Never a competitor. Followed links, not nofollow. First one in the intro. Why: these source classes are what quality raters and fact-checking systems treat as ground truth; linking a competitor donates authority and a citation path on your own keyword; nofollow on a source you hand-picked signals you do not vouch for your own evidence.

9. Internal links: 3-5 to pages that sell (BLOG-10). Target products, services, collections, pricing. Visible style: underlined plus a distinct color. Why: articles capture informational traffic; internal links are the mechanism that converts that traffic and authority into commercial rankings (articles lift commercial pages). An invisible link gets no clicks, and internal click-through is a usage signal. Site-wide routing: seo-internal-linking.

10. Conclusion with bold + CTA (BLOG-11, BLOG-19, BLOG-20). Restate the answer, bold the takeaway, end on one call to action pointing at the most relevant commercial page (offer, product, service, quote or contact). The same target also gets a sidebar CTA card and one in-content CTA block after roughly 40% of the body. Use the side columns: on desktop, the reading column is 700-800 px wide and leaves two empty margins on a 1440 px screen; put a sticky call to action in them, left and right of the article (for example the author card and table of contents on one side, a CTA card to the money page on the other). On mobile, where the side columns collapse, place one CTA block right after the answer-first summary and one mid-article. Why: the conclusion is the second-most-read block for skimmers, most readers never reach it, and an article without a next step wastes the traffic it earns. Field heuristic from agency audits: a sticky side CTA is in view at every scroll depth, while the conclusion CTA only reaches the readers who finish.

11. FAQ: 3 questions from People Also Ask (BLOG-12). Pull real PAA questions for the keyword and answer each in 2-4 sentences. Why: FAQ rich results are gone (deprecated for most sites by Google in August 2023, fully retired by May 2026), but the question-answer format remains one of the most extracted structures in AI answers: each pair is an autonomous chunk that matches a real sub-query.

12. Three images (BLOG-13, C-15). 1 cover + 2 in the body. Every image: descriptive alt text, WebP format, 200 KB max. Why: images break up text walls (dwell time), rank in image search, and alt text is the only image content text-based AI crawlers can read. Oversized images degrade Core Web Vitals.

Step 2. Layer the GEO elements

  • Answer-first block at the top (BLOG-04).
  • Self-contained H2 sections (chunk autonomy, BLOG-06).
  • At least one expert quote and at least two statistics with sources cited inline (BLOG-08).

These are the interventions with measured visibility gains in generative engines (see GEO layer).

Step 3. Place the links

  • 3-5 external authority sources, the first inside the intro (BLOG-09).
  • 3-5 internal links to commercial pages, styled visibly (BLOG-10), plus the hub link (BLOG-23), related posts (BLOG-24) and glossary links (BLOG-28).

Anchor rules and site-level architecture: seo-internal-linking.

Step 4. Finalize assets and metadata

  • 3 images (1 cover + 2 in body), alt text on all, WebP, 200 KB max each.
  • FAQ built from 3 real People Also Ask questions.
  • Title 30-60 characters, meta description 120-160 characters.
  • Natural-language slug containing the keyword (C-23; measured citation gap in the GEO layer).

Step 5. Build the page template, not only the text

Read references/blog-templates.md whenever the article page or the blog hub is being built, generated by an agent, or audited for the first time. The text skeleton says nothing about the page around it, and a bare template ships every post without an author photo, a sticky table of contents, dates, CTAs or real social profiles. The reference gives the article layout (breadcrumb, author line, cover, key takeaways box, sticky sidebar with table of contents, author card and CTA card, in-content CTA, sources section, author box, hub link, related posts, final CTA banner, optional share buttons), the author page, the blog hub (cards with cover images, categories, crawlable pagination), the BlogPosting + Person + BreadcrumbList JSON-LD and a framework-free sticky table of contents. Templates are built once and repeated on every post: one omission becomes N omissions.

Step 6. Acceptance test

Re-run the Phase 2 commands on the live or staged URLs. The finish line: TEMPLATE, BLOG HUB and SOCIAL lines clean; BOLD above zero with the keyword among the samples; no high finding; no toc_missing, author_missing, author_page_link, date_missing, no_cta_money, few_sources, hub_no_covers, schema_article or schema_fields; word count at or above the Phase 3 median; then re-run page_benchmark.py: every block present on most competitors is now present. Any remaining Fail is fixed or recorded as a written owner decision. Then verify every line of the pre-publish checklist and report failures to the user:

  • Title 30-60 characters, keyword near the front (BLOG-02)
  • Any year in the title, H1 or social titles is computed, not typed; only a cited dated source keeps its own year (BLOG-37)
  • Meta description 120-160 characters, hand-written (C-02)
  • One H1 containing the keyword; breadcrumb present (C-03, C-19)
  • Author line visible: photo, name linked to the author page, role, published and updated dates, reading time (BLOG-15)
  • Sticky table of contents in the sidebar (collapsible on mobile) (BLOG-17)
  • Author shown as a real person, never the company name
  • Sidebar CTA card, one in-content CTA block and the conclusion CTA, all to a commercial page (BLOG-11, 19, 20)
  • CTA in the side columns, left and right of the article, sticky on desktop; on mobile, a CTA block after the summary and one mid-article
  • End-of-article author box with credentials and real social profiles (no placeholder links) (BLOG-21)
  • BlogPosting + Person (with sameAs) + BreadcrumbList JSON-LD, no empty FAQ nodes (BLOG-26)
  • Answer-first block within the first screen (BLOG-04)
  • Primary keyword bolded in the first sentence; secondary keywords and key facts bolded in the body (the audit counts bold and flags zero) (BLOG-05, C-09)
  • No term above 2.5% density (the audit flags it; above 7% is stuffing) (C-11)
  • First external source linked in the intro; 3-5 total; gov, media, or study only; followed; zero competitors (BLOG-09)
  • 3-5 visible internal links to commercial pages (BLOG-10)
  • Every H2 section self-contained (no "as seen above") (BLOG-06)
  • FAQ = 3 real People Also Ask questions (BLOG-12)
  • Article template carries a capture popup: 30% scroll AND 15 s of visible reading, 2 shows per 7 days, silent 7 days after a close, never after a conversion or on utm_medium=email visits, native <dialog>, analytics event, markup at the end of the body
  • 3 images, all with alt text, WebP, 200 KB max (BLOG-13, C-15)
  • Length at or above the SERP benchmark (BLOG-03)
  • Information gain named and actually present in the text (BLOG-14)
  • Zero em dashes and zero en dashes anywhere in the deliverable, commas instead (C-25)

Then sweep the Common mistakes list.

Mandatory on every article page: reading-triggered capture popup

Every article page must carry a capture popup that opens only once the visitor is actually reading. This is a page-template requirement, not part of the article text: build it once in the blog template so every article inherits it.

  • Trigger: 30% scroll depth of the article AND 15 seconds of visible reading time (both, not either). Count reading time only while the tab is visible (document.visibilityState === "visible"), the way GA4 counts engaged time. Never on landing.
  • Cap: 2 shows per visitor per 7 days (at most one per visit); nothing for 7 days after a close; never again after a conversion; never on visits tagged utm_medium=email (the reader already is a subscriber).
  • Offer: one concrete incentive tied to the business (free audit or plan, tool result, catalog or price list, discount on a first order, checklist or guide). A bare "subscribe to our newsletter" converts poorly. One call to action only.
  • Form: one field when the offer is an audit or a tool (the site URL); first name + email otherwise (add phone only for high-ticket B2B or local services).
  • Technical: a native <dialog> opened with showModal(), closed by its button, Escape or a click on the backdrop; never full-screen on mobile (a card with margins that fits the screen, so Google does not treat it as an intrusive interstitial). Inject the markup at the end of the body, never at the top of the DOM, so it does not break the heading hierarchy. Keep the display state in local storage (shows, close date, conversion) and the visit flag in session storage; a blocked storage shows it at most once per page.
  • Measure: send an analytics event on show, close and submit with the offer, the page type and the trigger (for example popup_view with offer, page_type, trigger), no personal data.
  • Why: blog visitors arrive on informational intent and most are not ready to buy on the first visit; without capture they leave and never come back. Waiting for real reading (scroll and visible time) shows the offer to readers instead of bouncers, and the caps keep it from becoming a nuisance.

Rules and thresholds

Word count (field heuristics from 115+ agency audits, not Google statements), BLOG-03:

Word countVerdict
Under 180Critically thin: rewrite, expand, or merge into another article
300Minimum standard for a simple informational query
500 or moreRequired when the SERP is competitive
750 or moreComfortable baseline for most commercial-adjacent topics
Master ruleBenchmark the top 3-5 ranking pages and close the gap; the live SERP overrides every fixed number above

seo_audit.py flags article_short under 800 words; the Phase 3 median decides.

Why rewrite-first: an existing URL has age, links, and impression history; lifting it from position 8 to position 3 outperforms a new URL starting from zero. Never republish with only a new date: Google compares content versions, and a date-only refresh is deceptive freshness (BLOG-27). Flag this risk whenever a user asks for it.

Publication cadence (field heuristics):

SituationCadence
Niche topic volumeEstimate the total addressable topics first (for example 500-600 exploitable subjects around one city) to size the corpus and the runway, separate from the monthly pace
Blog launch45-75 articles for the initial corpus, up to 100 in a content-rich niche
Established siteAround 20 articles per month
Hand-written daily capRoughly 20 pieces per day; past that, quality and information gain slip
Programmatic scaleSome sites publish 2000-4000 templated pages in a single day and get them indexed, but this is exactly the pattern Google's scaled content abuse policy targets: each page must add real value for users, not merely be unique (policy and indexation conditions in seo-technical)
Priority orderRewrite existing articles that already earn impressions BEFORE creating new ones
Comparative listiclesRefresh every 60-90 days with real changes, an honest dateModified, and a visible date on page (BLOG-27)

Volume versus cadence: the topic-volume estimate tells you how big the opportunity is and how long it will take to cover; the monthly cadence is the sustainable pace. Size the niche once, then pace against it. The daily cap governs hand-written articles; the 2000-4000 per day figures are programmatic generation, a different lane that lives or dies on per-page uniqueness, not on editorial craft (field heuristics from 115+ agency audits).

Breaking-news lane: for genuinely time-sensitive topics, the Top stories and News surfaces can index a fresh article within minutes and draw sharp traffic spikes. There is no approval step anymore: Google News inclusion has been automatic for policy-compliant sites since Publisher Center stopped accepting publication submissions in April 2024, and Top stories has not required Google News inclusion since 2019. What earns the surface is news-grade freshness plus a News sitemap and an RSS or Atom feed (see seo-technical). Treat this as a separate lane, not a tactic for evergreen content (field heuristic from 115+ agency audits).

Google Discover lane: for most publishers Discover is a bigger organic surface than Google News. It cannot be targeted with keywords; it rewards the same fundamentals plus its documented specifics: large images (1200px+, enabled via max-image-preview:large, BLOG-16), honest non-clickbait titles, E-E-A-T, and topical entity clarity (https://developers.google.com/search/docs/appearance/google-discover). Discover traffic is volatile by design; report it separately and never build a forecast on it.

Title and answer-block patterns (BLOG-02, BLOG-04):

Query typeTitle patternAnswer-first block shape
How-toHow to <task>: <number or benefit>Outcome, number of steps, time required, the one critical warning
DefinitionWhat Is <term>? <scope>Term, category, differentiator, main use case, in 2-4 sentences
ComparisonBest <category> for <audience> (<year>, computed: BLOG-37)The winner, for whom, the runner-up, the deciding criterion
Cost<thing> Cost: <range or factors>The realistic range first, then the 2-3 factors that move it

Why patterns instead of creativity: the top block must answer the query in the retrieval frame engines use; cleverness belongs in the development, the first screen belongs to the answer.

AI-assisted drafting:

RuleDetail
Google's positionAI involvement is not penalized as such; content with no added value is, whoever wrote it
Mandatory orderRead the top 5 SERP results FIRST (Phase 3), then write with a named information gain (BLOG-14)
Risk to flagGenerating articles that restate what already ranks, at scale, is what the scaled content abuse spam policy targets
What winsInformation gain beats word count: original data, tested experience, expert input

Punctuation, non-negotiable: never ship an em dash (C-25).

Client-facing copy carries zero em dashes (U+2014) and zero en dashes (U+2013). Replace every one with a comma; use a colon, a period or parentheses when a comma loses the sense. The em dash is the single most recognizable tell of AI-written text: one is enough for a reader, or the client, to file the whole page as machine output, and the trust cost lands on the site, not on the draft. The rule covers every character you deliver: body copy, H1 and H2s, title tag, meta description, FAQ answers, alt text, CTAs, schema strings, image captions. Sweep the finished draft for both characters before handing it over. Hyphens in compound words and ranges written with "to" are untouched.

Media (BLOG-13, BLOG-16, BLOG-36):

ElementRuleWhy
VideoEmbed from YouTube, never upload to your own serverPage weight stays low and the video earns a second surface (YouTube search) plus a multi-channel signal
Images3 per article, alt text on all, WebP, 200 KB maxSpeed, image SERPs, and machine-readable descriptions
Substack or Medium mirrorSet the syndicated copy to no-index; rank the canonical version on the owned site (a WordPress or similar)The owned site carries the SEO; the mirror serves the email or follower audience. A crawlable duplicate splits signals and can outrank the original, so de-index the copy (field heuristic from 115+ agency audits)

GEO layer

How the skeleton performs in generative engines, with measured numbers:

  • Measured (Princeton GEO study, KDD 2024, 10,000 queries): adding expert quotes raised generative visibility by roughly 41%, adding statistics by roughly 32%, citing sources by roughly 30%, fluency improvements by roughly 28%. Keyword stuffing DECREASED visibility. These wins map directly to skeleton elements 6, 7, and 8 (BLOG-05, BLOG-08, BLOG-09).
  • Measured (Ahrefs, 1.4M ChatGPT prompts): semantic similarity between the title plus content and the fan-out sub-queries is the strongest citation predictor; the answer-first block and question-form H2s exist to match those sub-queries (BLOG-04, BLOG-06). Pages with natural-language slugs were cited in 89.78% of eligible cases vs 81.11% for opaque slugs (C-23). Median age of cited pages is around 500 days: authority compounds on a URL, so rewrite in place and never churn URLs.
  • Measured (ALM Corp): comparative listicles ("Best X for Y") draw roughly 32.5% of AI citations. Maintain comparison content deliberately and refresh it every 60-90 days (BLOG-27).
  • Google AI Overviews: assembled from indexed, extractable passages; the answer-first block and self-contained H2 sections are the units it lifts.
  • Perplexity: favors fresh, well-sourced pages; visible dates and inline-cited statistics matter most there (BLOG-15, BLOG-08).
  • Chunk autonomy: every H2 section must stand alone: direct answer in 2-4 sentences, then development, with no "as we saw above" references. AI engines retrieve isolated chunks without surrounding context; a dependent chunk is an unusable chunk (BLOG-06).

Boundaries: passage-level citability rules live in geo-visibility; AI crawler access (robots.txt, user agents, rendering) lives in seo-technical; measuring AI citations and traffic lives in geo-tracking.

Deliverable

Deliver every job in this exact structure. For an outline or brief, part 4 stops at the metadata and the H2 plan; for a template job, part 4 is the block list and JSON-LD from references/blog-templates.md.

## 1. Spec scorecard
| ID | Requirement | Status (Pass / Fail / Not verifiable) | Evidence |
(every BLOG row, then every C row that fails or cannot be verified)

## 2. Audit findings
(seo_audit.py SEO and GEO scores, high and medium findings with their spec IDs, the TEMPLATE,
BLOG HUB and SOCIAL lines, section_audit.py blocks; or "new article" plus the template audit
of one existing post and the hub)

## 3. Competitor benchmark
(page_benchmark.py table; per competitor: words, H2 questions answered, tables, images, videos,
dates, PAA; blocks and schema types the client lacks; metrics below the median)
- SERP benchmark: top results at <N1>, <N2>, <N3> words; target <N> words
- Information gain: <the element the top 5 do not have>

## 4. Build
### Article metadata
- Primary keyword: <keyword> | Intent: <informational / commercial investigation>
- Title (30-60 chars): <title>
- Meta description (120-160 chars): <description>
- Slug: /blog/<natural-language-slug-with-keyword>
- Internal link targets: <3-5 commercial URLs>
- External sources: <3-5 URLs, each tagged gov / media / study>

# <H1 containing the primary keyword>

[Cover image: <description> | alt: "<descriptive alt>" | WebP, under 200 KB]

By <author name>, <role>. Published <date>, updated <date>. <X> min read.

[Table of contents: anchor links to all H2s]

**In short:** <the complete answer in 2-4 sentences>

<Intro: first sentence with **primary keyword** in bold; first authority source linked here>

## <Question-form H2>
<Direct answer in 2-4 sentences.>
<Development: bolded secondary keywords, image or comparison table where data is comparable,
expert quote where a claim needs weight, internal link where a commercial page fits.>

[In-content CTA block after roughly 40% of the body: <offer> to <commercial page>]

## <Next H2 sections, same pattern, each self-contained>

## Conclusion
<Restated answer with **bolded takeaway**. One CTA to <commercial page>.>

## Sources
<Each source with what it supports>

## FAQ
### <People Also Ask question 1>
<2-4 sentence answer.>
### <People Also Ask question 2>
<2-4 sentence answer.>
### <People Also Ask question 3>
<2-4 sentence answer.>

[Author box | Related posts x3 | Final CTA banner]
### JSON-LD
(BlogPosting + Person + BreadcrumbList; placeholders {to confirm} for unverified facts)

## 5. Acceptance
(scripts re-run: remaining findings, each fixed or a written owner decision; the pre-publish
checklist with every line checked)

Common mistakes

  • Writing before reading the SERP. Produces a copy of position 1 with less authority: unrankable and uncitable by design.
  • Burying the answer. 300 words of context before the point; AI engines extract from the top of the page, and readers bounce.
  • "As mentioned above" cross-references. Breaks chunk autonomy; the retrieved passage becomes unusable on its own.
  • Citing competitors as sources. Donates authority and a citation path on your own keyword.
  • Nofollow on hand-picked sources. Undermines the sourced-content signal you are trying to send.
  • Shorter rewrites. Replacing a 1500-word ranking page with a 700-word version loses the coverage that earned the ranking.
  • Date-only refreshes. Google compares versions; unchanged content with a new date is deceptive freshness. Flag the risk.
  • Invented FAQ questions. Use People Also Ask; made-up questions match no real query and no fan-out sub-query.
  • Keyword stuffing. Measured to reduce generative visibility (Princeton study) on top of the classic over-optimization risk.
  • Self-hosted video. Page weight up, and the YouTube surface is lost. Embed instead.
  • Zero internal links to money pages. The article ranks and sells nothing; informational traffic dies on the page.
  • Bare template. Perfect text in a page with no author photo, no table of contents, no dates and no CTA. Build the template once from references/blog-templates.md.
  • Blog hub without covers. A text-only list of posts looks abandoned and loses clicks; every card carries its cover image.
  • Placeholder social links. A footer icon pointing to instagram.com/ is a dead promise and a broken entity link; link the real profile or remove the icon.
  • Empty side columns. A narrow reading column with blank margins and a single CTA at the very bottom: the readers who leave halfway never see a next step. Fill the margins with the author card and a sticky CTA.
  • Anonymous byline. "By Brand.com" or no author at all. Put a real person, with photo and credentials, next to the article.
  • Heavy images. A 1.2 MB cover image hurts Core Web Vitals on every visit. Compress to WebP under 200 KB.
  • Em dashes left in the copy. Reads as AI output to readers and to the client. Replace each one with a comma before delivery.
  • Auditing only the text. The template rows (BLOG-15 to BLOG-28) and the hub rows fail on every post at once; audit one post and the hub even when writing a new article.

Sources

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.