blog-write

---
name: blog-write
description: >
license: MIT
---

# 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)
- 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):

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
```yaml
---
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:

```markdown
> **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:
```markdown
## 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.

1. **Relevant date or study period.** Include it where recency or the measured
   period changes the claim's meaning.

2. **Identifiable source.** Name the publisher and document title when needed
   to distinguish the source and place the citation close to the claim.

3. **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:
  ```markdown
  > **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:
```markdown
[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:
```markdown
[INTERNAL-LINK: anchor text → target description]
```

Example:
```markdown
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:
```markdown
![Descriptive alt text - topic keywords naturally](https://cdn.pixabay.com/photo/...)
```

MDX with Next.js Image (if detected):
```mdx
![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:
```html
<figure>
  <svg viewBox="0 0 560 380" ...>...</svg>
  <figcaption>Source: [Source Name], [Year]</figcaption>
</figure>
```

MDX format:
```mdx
<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):
```markdown
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:
```mdx
<FAQSchema faqs={[
  { question: "Question?", answer: "Complete answer with support where needed." },
]} />
```

For standard markdown:
```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
1. Important claims state their point clearly and include verified support where needed
2. Paragraph and sentence pacing suits the audience; length alone cannot block delivery
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 accurately and specifically summarizes the visible content

#### New Element Verification
10. Optional summary helps the reader and contains no unsupported claims
11. Any information-gain markers point to supported original material
12. Important reusable claims are self-contained and evidence-backed
13. Internal linking zones marked in introduction, H2 sections, FAQ, and conclusion
14. Project voice preferences reviewed where they improve clarity and fit

#### Optional Editorial Voice Review
15. **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.
16. **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`
17. **Contractions** - Use contractions when they fit the selected voice. Their
    presence or absence says nothing about authorship or Google performance.
18. **Rhetorical questions** - Use them only when they help the reader reason
    through a decision. There is no quota.
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`.