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

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):
   • Search: site:pixabay.com [topic] wide banner (preferred)
   • Alternative: site:unsplash.com [topic] wide
   • Fallback: site:pexels.com [topic] wide banner
   • 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 sub-skill (if nanobanana-mcp configured)
   • See skills/blog/references/visual-media.md for cover image sizing details
3. Find 3-5 inline images from open-source platforms:
   • Pixabay (preferred): Search site:pixabay.com [topic keywords]
     • Extract image URL from page
     • Direct URLs: https://cdn.pixabay.com/photo/YYYY/MM/DD/HH/MM/filename.jpg
     • Verify with curl -sI "<url>" | head -1 returns HTTP 200
   • Unsplash (alternative): Search site:unsplash.com [topic keywords]
     • Build URL: https://images.unsplash.com/photo-<id>?w=1200&h=630&fit=crop&q=80
   • Pexels (fallback): Search site:pexels.com [topic keywords]
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 nanobanana-mcp configured):
   • 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
   • Stock photos remain default - AI generation supplements, never replaces
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
   • Treat NotebookLM responses as Tier 1 sources (user's own primary documents)
   • 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 posit