Blog Writer: New Article Generation

Writes complete blog articles from a topic, brief, or outline. Every article

follows the 6 pillars of dual optimization (Google rankings + AI citations).

Key references (paths relative to repo root; references live in the

main blog skill's references directory, not in blog-write/):

• skills/blog/references/synthesis-contract.md: 6 LAWs for synthesis output (v1.8.0; applies whenever the article embeds research-synthesis prose)

• skills/blog/references/content-templates.md: Template selection guide and usage

• skills/blog/references/quality-scoring.md: 5-category scoring (Content 30, SEO 25, E-E-A-T 15, Technical 15, AI Citation 15)

• skills/blog/references/eeat-signals.md: Experience, expertise, authority, trust markers

• skills/blog/references/internal-linking.md: Linking strategy and anchor text rules

• skills/blog/references/visual-media.md: Image sourcing and chart styling

• skills/blog-write/references/delivery.md: delivery contract steps and summary template for this sub-skill

Workflow

Phase 0: Surface Targeting (do this BEFORE research)

Decide which of the FLOW 5 surfaces this post is meant to win. The choice

shapes structure, length, citation density, and call-to-action. The 5 surfaces

in 2026:

• Owned site (organic Google ranking)

• SERP including AI Overviews

• AI assistant citations (ChatGPT, Perplexity, Claude, Gemini, Copilot, You.com)

• Local pack (out of scope for blog content; use claude-seo for local)

• Communities and video (Reddit, YouTube, LinkedIn, Quora, niche forums)

Most posts target surfaces 1, 2, and 3 by default. If the same query also

surfaces in a community (Reddit thread, YouTube comment), apply dual-surface

thinking: optimize the post for extraction AND plan a community echo (covered

in /blog repurpose).

For a deeper surface-by-surface workflow, see

skills/blog/references/flow-alignment.md and /blog flow find.

Phase 1: Topic Understanding

• Clarify the topic - If the user provides just a topic, ask:

• Target audience (who is this for?)

• Primary keyword / search intent

• Desired word count (default: 2,000-2,500 words)

• Platform/format (MDX, markdown, HTML - auto-detect if in a project)

• If a brief exists - Load it and skip to Phase 1.5

Phase 1.5: Template Selection

Select the appropriate content template from the 12 templates in

skills/blog/templates/ (the main blog skill owns the templates directory).

-

Auto-detect content type from the topic and search intent:

-

Load the matching template: Read from skills/blog/templates/<type>.md

-

Adapt the outline - Use the template's section structure, heading patterns,

and word count guidance to shape Phase 3's outline

-

Fallback - If no template clearly fits, use the generic outline structure

in Phase 3 below. Inform the user which template was selected (or that none matched).

See skills/blog/references/content-templates.md for detailed selection criteria and intent mapping.

Phase 2: Research

Spawn a blog-researcher agent (or do inline research with WebSearch):

• Find 8-12 current statistics (2025-2026 data preferred)

• Search: [topic] study 2025 2026 data statistics

• Prioritize tier 1-3 sources (see skills/blog/references/quality-scoring.md)

• Record: statistic, source name, URL, date, methodology

• Find a cover image (wide, high-quality, topic-relevant):

• Prefer original screenshots, product visuals, diagrams, or data graphics when available

• For stock, use official APIs such as Openverse, Unsplash, Pexels, or Pixabay so license, creator, source URL, and download URL are captured

• Download approved assets into the draft folder, store attribution, and never hotlink arbitrary CDN URLs

• Reject javascript:, data:, and file: image URLs

• Target dimensions: 1200x630 (OG-compatible) or 1920x1080

• Or generate a custom SVG cover via blog-chart (text-on-gradient with key stat)

• Or generate a custom AI image via blog-image; prefer gemini-3.1-flash-image, then gemini-3.1-flash-lite-image or gemini-3-pro-image when available, and record the model ID

• See skills/blog/references/visual-media.md for cover image sizing details

• Find 3-5 inline images from open-source platforms:

• Use official APIs or Openverse search; keep license, creator, source URL, and retrieval date with each asset

• Download images locally and reference local paths in the draft

• Validate final URLs with the delivery contract SSRF rules before download

• Plan 2-4 data visualizations from researched statistics

• Select diverse chart types (see skills/blog/references/visual-media.md)

• Map data points to chart formats

• AI image generation (optional, if blog-image is available):

• If stock photo results are insufficient (< 3 good matches) or topic is too niche

• Generate custom hero image and/or inline illustrations via blog-image sub-skill

• Record prompt, provider, and model ID; stock photos remain available, but original and data visuals are preferred when they better serve the topic

• NotebookLM research (optional, if user has relevant notebooks):

• If the user mentions a NotebookLM notebook or the topic aligns with a configured notebook

• Query via blog-notebooklm for source-grounded data from user-uploaded documents

• Inherit the source tier from the underlying document provenance; user's own primary documents can be Tier 1, while copied secondary sources keep their original tier

• Falls back silently if not configured or not authenticated

• Find relevant YouTube videos (2-3 per post):

• Use blog-google youtube command or WebSearch site:youtube.com [topic] [year]

• Apply quality criteria from skills/blog/references/video-embeds.md (min score 50/100)

• Select 2-3 best videos. Falls back silently if none found.

Phase 3: Outline Generation

Create a structured outline before writing. If a template was loaded in Phase 1.5,

adapt this skeleton to match the template's section structure:

# [Title as Question - Include Primary Keyword]

## Introduction (100-150 words)

- Open with the reader's problem, a useful finding, a concrete example, or an

  optional verified statistic when evidence makes that the strongest hook

- Problem/opportunity statement

- What the reader will learn

> **Key Takeaways**

> - [Core finding with statistic and source]

> - [Second key insight or recommendation]

> - [Third actionable takeaway]

> (3-5 concise bullets when a summary helps this content type)

## H2: [Intent-Matched Heading]

- Clear section point with verified support where needed

- Supporting evidence

- [Image placement]

- Practical advice

- [EVIDENCE-BACKED EXPLANATION placeholder]

- [INTERNAL-LINK: anchor text → target description]

## H2: [Intent-Matched Heading]

- Answer-first paragraph

- [Chart: type + data description]

- Analysis and implications

- [EVIDENCE-BACKED EXPLANATION placeholder]

- [INTERNAL-LINK: anchor text → target description]

## H2: [Intent-Matched Heading]

- Answer-first paragraph

- Real-world example or case study

- [Image placement]

- [EVIDENCE-BACKED EXPLANATION placeholder]

## H2: [Intent-Matched Heading]

- Answer-first paragraph

- [Chart: type + data description]

- Step-by-step guidance

- [EVIDENCE-BACKED EXPLANATION placeholder]

- [INTERNAL-LINK: anchor text → target description]

## H2: [Intent-Matched Heading]

- Answer-first paragraph

- Forward-looking analysis

## [CTA Section or Inline Placement]

- See `skills/blog/references/cta-placement.md` for placement rules by content type

- Place CTA after value delivery, not at arbitrary positions

- Single focused CTA per post (266% more conversions)

- [CTA: contextual call-to-action matching article topic]

## Optional FAQ Section (only when real reader questions warrant it)

- [INTERNAL-LINK: anchor text → detailed content]

## Conclusion (100-150 words)

- Key takeaways (bulleted)

- Call to action

- [INTERNAL-LINK: anchor text → next logical content]

Present the outline to the user for approval before writing.

Visual element pacing: Insert [IMAGE], [CHART], [VIDEO], or [CALLOUT] markers

every 300-500 words. Alternate types (no consecutive same-type). See

skills/blog/references/content-rules.md Visual Rhythm section and

skills/blog/references/cta-placement.md for CTA positioning.

Phase 4: Chart Generation (Built-In)

When the researcher identifies chart-worthy data (3+ comparable metrics, trend data,

before/after comparisons):

• Select chart type using the diversity rule (no repeated types per post)

• Invoke blog-chart sub-skill with: chart type, title, data values, source, platform format

• Embed the returned SVG directly in the post within a <figure> wrapper

• Target 2-4 charts per 2,000-word post

• Distribute charts evenly - never cluster them

See skills/blog/references/visual-media.md for chart type selection and styling rules.

Phase 5: Content Writing

Write the full article following these rules:

#### 5a. Frontmatter

---

title: "[Clear title that identifies the page and matches search intent]"

description: "[Accurate, page-specific summary of the visible content]"

coverImage: "[URL from Pixabay/Unsplash/Pexels or generated SVG path]"

coverImageAlt: "[Descriptive sentence about the cover image]"

ogImage: "[Same as coverImage, or custom OG image URL]"

date: "YYYY-MM-DD"

lastUpdated: "YYYY-MM-DD"

author: "[Author name]"

tags: ["keyword1", "keyword2", "keyword3"]

---

If the platform uses a different field name (e.g., image, hero, thumbnail),

adapt to match the project's existing frontmatter convention.

#### 5b. Summary Box (Key Takeaways)

Immediately after the introduction (before the first H2 body section), add a summary box:

> **Key Takeaways**

> - [Core finding with verified support when needed]

> - [Second key insight or recommendation]

> - [Third actionable takeaway]

Requirements:

• 3-5 concise bullet points sized to the material

• Must be self-contained - understandable without reading the article

• Use statistics only when material to the summary and verified

• State the key finding, recommendation, or answer

• Default label: "Key Takeaways". If a persona is active, use the persona's summary_label

• Backward compatible: accept existing TL;DR boxes during rewrites

#### 5c. Purpose-First Formatting (Critical)

State the point of important sections early, then supply the context and

verified evidence the claim needs. Do not force statistics or fixed lengths.

Pattern:

## How Does X Impact Y in 2026?

[Stat from source] ([Source Name](url), year). [Direct answer to the heading

question in 1-2 more sentences, explaining the implication and what this means

for the reader.]

Source record for material public statistics:

Record enough provenance for a reader or editor to verify the claim. Use the

publication's citation style rather than forcing one sentence pattern.

-

Relevant date or study period. Include it where recency or the measured

period changes the claim's meaning.

-

Identifiable source. Name the publisher and document title when needed

to distinguish the source and place the citation close to the claim.

-

Retrievable support. Keep a stable URL. Add a retrieval date for

changeable or undated sources, and record methodology or limitations when

they affect interpretation.

FLOW quality bar (drop or replace):

Public claims must use verified sources OR stay qualitative. If a statistic

cannot be verified, drop it. If it is contradicted by a more recent source,

replace it with the verified alternative. Do not soften vague language to

keep an unsourceable number.

For evidence-led optimization prompts (CTR audit, quality follow-up, schema,

PAA rewording, ChatGPT visibility), see /blog flow optimize.

#### 5d. Information Gain Markers

Use information-gain markers as optional drafting annotations when the article

contains genuinely original data, transparent first-hand evidence, or

distinctive sourced synthesis. The evidence itself helps readers; the marker is

not a search-engine signal and earns no points by its presence.

Tag each with a comment or visible marker:

• [ORIGINAL DATA] - Proprietary surveys, experiments, A/B test results, case

study metrics the author collected first-hand

• [PERSONAL EXPERIENCE] - First-hand observations, lessons learned from direct

involvement, "when we tried X, Y happened" narratives

• [UNIQUE INSIGHT] - Analysis others haven't made, contrarian perspectives

backed by data, novel connections between existing research

Placement:

• Weave into the body text naturally

• Use as inline comments: <!-- [ORIGINAL DATA] --> before the relevant paragraph

• Or as visible callouts if the format supports it:

> **Our finding:** [original observation backed by specific data]

• Use only as many as the supported original material warrants.

#### 5e. Evidence-Backed Explanations

For important reusable claims, create a self-contained, evidence-backed

explanation sized to the material.

Guidance:

• Self-contained and understandable in isolation

• Contains a specific claim plus verified support when the claim needs it

• Written in a declarative, quotable style

• Placed within the H2 section body (not as a separate block)

Example:

[Verified source title], a [method or sample description] published on [date],

found [specific metric] for [audience or market] ([Source name](https://example.com/full-report),

retrieved YYYY-MM-DD). In practical terms, connect the evidence to one action

the reader should take before making a claim or changing a workflow.

Do not pad explanations to a fixed length or add them solely to earn readiness

points.

#### 5f. Internal Linking Zones

Mark internal linking opportunities throughout the article using placeholder

notation. The user (or a follow-up pass) will resolve these to actual URLs.

Zone placement:

• Introduction - Link to related pillar content or topic hub

• Each H2 section - Link to supporting articles, deeper dives, related tools

• FAQ section - Link answers to detailed content that expands on the answer

• Conclusion - Link to the next logical piece of content the reader should consume

Format:

[INTERNAL-LINK: anchor text → target description]

Example:

For a deeper dive into keyword clustering, see our

[INTERNAL-LINK: complete guide to keyword clustering → pillar page on keyword research methodology].

Target 5-10 internal link zones per 2,000-word post. Use descriptive anchor text

(never "click here" or "read more"). See skills/blog/references/internal-linking.md for

anchor text rules and linking strategy.

#### 5g. Paragraph Rules

• Use paragraph and sentence lengths that fit the audience and material

• Split passages when doing so improves comprehension, not to satisfy a quota

• Start each paragraph with the most important information

• Target Flesch Reading Ease: 60-70

#### 5h. Heading Rules

• One H1 (title only)

• H2s for main sections; use question or declarative forms according to intent

• H3s for subsections only - never skip levels

• Keep heading terminology naturally consistent with the page topic; do not

enforce an exact-match keyword quota

#### 5i. Image Embedding

Standard markdown:

![Descriptive alt text - topic keywords naturally](https://cdn.pixabay.com/photo/...)

MDX with Next.js Image (if detected):

![Descriptive alt text - topic keywords naturally](https://cdn.pixabay.com/photo/...)

• Place images after H2 headings, before body text

• Space evenly throughout the post (not clustered)

• Alt text should be a full descriptive sentence

#### 5j. Chart Embedding

Standard markdown/HTML:

<figure>

  <svg viewBox="0 0 560 380" ...>...</svg>

  <figcaption>Source: [Source Name], [Year]</figcaption>

</figure>

MDX format:

<figure className="chart-container" style={{margin: '2.5rem 0', textAlign: 'center', padding: '1.5rem', borderRadius: '12px'}}>

  <svg viewBox="0 0 560 380" ...>...</svg>

</figure>

#### 5k. Video Embedding

Embed YouTube videos using srcdoc lazy-loading pattern from skills/blog/references/video-embeds.md.

Include aria-label, noscript fallback for AI crawlers. Place after relevant H2, 500+ words apart.

#### 5l. Citation Format

Inline attribution (always):

In February 2026, Seer Interactive's AI Overview CTR tracker reported a 2.4% organic CTR on AI Overview SERPs ([Seer Interactive](https://www.seerinteractive.com/), retrieved YYYY-MM-DD).

#### 5m. FAQ Section

Add FAQ items only when user questions warrant them. Answers should be complete

and concise; include verified statistics only when relevant.

FAQPage is optional entity markup only. Google FAQ rich results were fully retired for all sites on 2026-05-07, so do not make FAQ schema a core Google rich-result output or citation lever. Prioritize Article/BlogPosting + Person + Organization + BreadcrumbList; emit FAQPage only when the platform already supports it and the questions genuinely help users.

For MDX with an optional FAQSchema component:

<FAQSchema faqs={[

  { question: "Question?", answer: "Complete answer with support where needed." },

]} />

For standard markdown:

## Frequently Asked Questions

### Question text here?

Answer completely, with source attribution where the claim needs it.

#### 5n. Internal Linking

• 5-10 internal links per 2,000-word post

• Link to relevant existing content naturally

• Use descriptive anchor text (not "click here")

Phase 6: Quality Check

Before delivering, verify:

#### Structure and Content

• Important claims state their point clearly and include verified support where needed

• Paragraph and sentence pacing suits the audience; length alone cannot block delivery

• All statistics have named tier 1-3 sources

• 2-4 charts with type diversity

• 3-5 inline images with descriptive alt text

• Cover image present in frontmatter (coverImage + ogImage)

• FAQ section present with 3-5 items when warranted by user questions

• Heading hierarchy is clean (H1 -> H2 -> H3)

• Meta description accurately and specifically summarizes the visible content

#### New Element Verification

• Optional summary helps the reader and contains no unsupported claims

• Any information-gain markers point to supported original material

• Important reusable claims are self-contained and evidence-backed

• Internal linking zones marked in introduction, H2 sections, FAQ, and conclusion

• Project voice preferences reviewed where they improve clarity and fit

#### Optional Editorial Voice Review

• Sentence rhythm - Vary sentence structure only where it improves clarity,

emphasis, or flow. Do not infer authorship from sentence patterns or enforce

fixed sentence-length bands.

• Configured phrase review - Review these project style-list terms in

context and replace them only when a clearer alternative fits:

• "in today's digital landscape", "it's important to note", "dive into"

• "game-changer", "navigate the landscape", "revolutionize", "seamlessly"

• "cutting-edge", "harness the power of", "leverage" (as verb)

• "delve", "crucial", "elevate", "foster", "landscape" (overused)

• "multifaceted", "robust", "tapestry", "embark"

• Full list in agents/blog-writer.md

• Contractions - Use contractions when they fit the selected voice. Their

presence or absence says nothing about authorship or Google performance.

• Rhetorical questions - Use them only when they help the reader reason

through a decision. There is no quota.

• YouTube videos - 2-3 embeds with lazy loading, aria-labels, and noscript fallback (see skills/blog/references/video-embeds.md)

Phase 6.5: Delivery Contract Enforcement (v1.9.0)

Before Phase 7, run the 5-gate delivery contract (via python3 scripts/blog_preflight.py plus a BLOCKING blog-reviewer agent) per skills/blog/references/blog-delivery-contract.md and the writer-specific checklist in skills/blog-write/references/delivery.md. Use python3 for local scripts. The user is never the first reviewer; the gates are.

On any block, capture <folder>/preflight-report.json, re-dispatch the blog-writer agent with the diagnostic as input, and re-run the gated steps. Maximum 3 iterations. On the 3rd failure, stop and present the failure diagnostic instead of the draft.

Phase 7: Delivery

Present the completed article only after Phase 6.5 returns all gates passing. Include <folder>/preview/*.png screenshots and the compact completion summary described in skills/blog-write/references/delivery.md.