Blog Write

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)

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

1. Load the matching template: Read from skills/blog/templates/<type>.md
2. Adapt the outline - Use the template's section structure, heading patterns, and word count guidance to shape Phase 3's outline
3. 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

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

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

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

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

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

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