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:

1. Owned site (organic Google ranking)
2. SERP including AI Overviews
3. AI assistant citations (ChatGPT, Perplexity, Claude, Gemini, Copilot, You.com)
4. Local pack (out of scope for blog content; use claude-seo for local)
5. 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

1. 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)
2. 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).

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

   Signal	Template
   "How to...", process, steps	how-to-guide
   "Best X", "Top N", list format	listicle
   Client result, before/after, metrics	case-study
   "X vs Y", comparison, alternatives	comparison
   Broad topic, comprehensive guide	pillar-page
   "Is X worth it", product evaluation	product-review
   Opinion, prediction, industry take	thought-leadership
   Expert quotes, multi-source collection	roundup
   Code walkthrough, tool demo, technical	tutorial
   Breaking news, algorithm update, event	news-analysis
   Survey results, experiment, original data	data-research
   Q&A, knowledge base, "What is X"	faq-knowledge

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

3. Adapt the outline - Use the template's section structure, heading patterns, and word count guidance to shape Phase 3's outline

4. 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):

1. 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
2. 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
3. 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
4. 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
5. 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
6. 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
7. 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)
- Hook with surprising statistic
- 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 bullets, 40-60 words combined)

## H2: [Question Format] (300-400 words)
- Answer-first paragraph (40-60 words with stat + source)
- Supporting evidence
- [Image placement]
- Practical advice
- [CITATION CAPSULE placeholder]
- [INTERNAL-LINK: anchor text → target description]

## H2: [Question Format] (300-400 words)
- Answer-first paragraph
- [Chart: type + data description]
- Analysis and implications
- [CITATION CAPSULE placeholder]
- [INTERNAL-LINK: anchor text → target description]

## H2: [Statement for Variety] (300-400 words)
- Answer-first paragraph
- Real-world example or case study
- [Image placement]
- [CITATION CAPSULE placeholder]

## H2: [Question Format] (300-400 words)
- Answer-first paragraph
- [Chart: type + data description]
- Step-by-step guidance
- [CITATION CAPSULE placeholder]
- [INTERNAL-LINK: anchor text → target description]

## H2: [Question Format] (200-300 words)
- 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]

## FAQ Section (3-5 questions, 40-60 words each answer)
- [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):

1. Select chart type using the diversity rule (no repeated types per post)
2. Invoke blog-chart sub-skill with: chart type, title, data values, source, platform format
3. Embed the returned SVG directly in the post within a <figure> wrapper
4. Target 2-4 charts per 2,000-word post
5. 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: "[Question-format title with primary keyword]"
description: "[Fact-dense, 150-160 chars, includes 1 statistic]"
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 statistic] ([Source], year)
> - [Second key insight or recommendation]
> - [Third actionable takeaway]

Requirements:

• 3-5 bullet points, 40-60 words combined
• Must be self-contained - understandable without reading the article
• Include 1 specific statistic with source name
• 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. Answer-First Formatting (Critical)

Every H2 section MUST open with a 40-60 word paragraph containing:

• At least one specific statistic with source attribution
• A direct answer to the heading's implicit question

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.]

FLOW evidence triple (drafting requirement, not just audit):

Every public statistic must carry three components AT DRAFTING TIME:

1. Year anchor in prose. Write "In 2026," or "As of Q1 2026," BEFORE the statistic, in the sentence body. Year buried inside parentheses does not count. Example:

   • GOOD: "In 2026, Ahrefs found a 58% lower CTR for position one when an AI Overview was present."
   • WEAK: "Position-one CTR dropped 58% (Ahrefs, 2026)."

2. Inline citation with publisher and title. Name both the publisher and the document title (or report name), not just a brand. Example:

   • GOOD: "Ahrefs, [document or report title], 2026"
   • WEAK: "Ahrefs reported..."

3. URL plus retrieval date in the source block at the bottom of the post. Provenance discipline lets future readers and AI crawlers verify the source still says what was claimed. Format:

   • "[Publisher], [Title], retrieved YYYY-MM-DD, [full URL]"

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, AI detector test, schema, PAA rewording, ChatGPT visibility), see /blog flow optimize.

5d. Information Gain Markers

Distribute at least 2-3 information gain markers throughout the article. These signal to search engines and AI systems that the content contains original value not available elsewhere.

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]

• Minimum 2 per post, target 3 for comprehensive articles

These markers map directly to the "Originality/unique value markers" criterion in the Content Quality scoring category (see skills/blog/references/quality-scoring.md).

5e. Citation Capsules

For each major H2 section, generate a citation capsule - a 40-60 word self-contained passage designed so AI systems can extract and quote it directly.

Requirements per capsule:

• 40-60 words, self-contained (makes sense in isolation)
• Contains: one specific claim + one data point + source attribution
• Written in a declarative, quotable style
• Placed within the H2 section body (not as a separate block)

Example:

According to a 2026 Gartner study, 58% of enterprise buyers now consult AI
assistants before contacting a vendor ([Gartner](https://www.gartner.com), 2026).
This shift means B2B content must answer specific questions concisely enough
for AI systems to extract and cite in their responses.

Capsules map to the "AI Citation Readiness" scoring category (15 points) in skills/blog/references/quality-scoring.md.

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

• Every paragraph: 40-80 words (never exceed 150)
• Every sentence: max 15-20 words
• 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 (60-70% as questions)
• H3s for subsections only - never skip levels
• Include primary keyword naturally in 2-3 headings

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 3-5 FAQ items with 40-60 word answers when user questions warrant it. Each answer must contain a verified statistic when a relevant source-backed number exists.

FAQPage is optional entity markup only. Google FAQ rich results have been limited primarily to well-known, authoritative government and health sites since the 2023 guidance, 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: "40-60 word answer with statistic and source." },
]} />

For standard markdown:

## Frequently Asked Questions

### Question text here?

Answer with statistic and source attribution (40-60 words).

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

1. Every H2 opens with a statistic + source
2. No paragraph exceeds 150 words
3. All statistics have named tier 1-3 sources
4. 2-4 charts with type diversity
5. 3-5 inline images with descriptive alt text
6. Cover image present in frontmatter (coverImage + ogImage)
7. FAQ section present with 3-5 items when warranted by user questions
8. Heading hierarchy is clean (H1 -> H2 -> H3)
9. Meta description is 150-160 chars with a stat

New Element Verification

10. TL;DR box present after introduction (40-60 words, contains statistic + source)
11. At least 2-3 information gain markers ([ORIGINAL DATA], [PERSONAL EXPERIENCE], or [UNIQUE INSIGHT])
12. Citation capsules present in major H2 sections (40-60 words, self-contained, quotable)
13. Internal linking zones marked in introduction, H2 sections, FAQ, and conclusion
14. No AI-detectable phrases from banned list (see agents/blog-writer.md)

Burstiness and Naturalness Check

15. Sentence length variance - Verify a mix of short (8-word) and long (25-word) sentences. Uniform sentence length signals AI authorship.
16. Banned AI phrase scan - Check for and remove:
    • "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
17. Contractions - Verify natural use of contractions ("it's", "we've", "don't", "isn't"). Formal AI prose avoids contractions; natural writing uses them.
18. Rhetorical questions - Verify at least one rhetorical question every 200-300 words to break up declarative patterns.
19. 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.