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

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:
2. Target audience (who is this for?)
3. Primary keyword / search intent
4. Desired word count (default: 2,000-2,500 words)
5. Platform/format (MDX, markdown, HTML - auto-detect if in a project)
6. 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

1. 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)
2. Search: [topic] study 2025 2026 data statistics
3. Prioritize tier 1-3 sources (see skills/blog/references/quality-scoring.md)
4. Record: statistic, source name, URL, date, methodology
5. Find a cover image (wide, high-quality, topic-relevant):
6. Search: site:pixabay.com [topic] wide banner (preferred)
7. Alternative: site:unsplash.com [topic] wide
8. Fallback: site:pexels.com [topic] wide banner
9. Target dimensions: 1200x630 (OG-compatible) or 1920x1080
10. Or generate a custom SVG cover via blog-chart (text-on-gradient with key stat)
11. Or generate a custom AI image via blog-image sub-skill (if nanobanana-mcp configured)
12. See skills/blog/references/visual-media.md for cover image sizing details
13. Find 3-5 inline images from open-source platforms:
14. Pixabay (preferred): Search site:pixabay.com [topic keywords]
15. Extract image URL from page
16. Direct URLs: https://cdn.pixabay.com/photo/YYYY/MM/DD/HH/MM/filename.jpg
17. Verify with curl -sI "<url>" | head -1 returns HTTP 200
18. Unsplash (alternative): Search site:unsplash.com [topic keywords]
19. Build URL: https://images.unsplash.com/photo-<id>?w=1200&h=630&fit=crop&q=80
20. Pexels (fallback): Search site:pexels.com [topic keywords]
21. Plan 2-4 data visualizations from researched statistics
22. Select diverse chart types (see skills/blog/references/visual-media.md)
23. Map data points to chart formats
24. AI image generation (optional, if nanobanana-mcp configured):
25. If stock photo results are insufficient (< 3 good matches) or topic is too niche
26. Generate custom hero image and/or inline illustrations via blog-image sub-skill
27. Stock photos remain default - AI generation supplements, never replaces
28. NotebookLM research (optional, if user has relevant notebooks):
29. If the user mentions a NotebookLM notebook or the topic aligns with a configured notebook
30. Query via blog-notebooklm for source-grounded data from user-uploaded documents
31. Treat NotebookLM responses as Tier 1 sources (user's own primary documents)
32. Falls back silently if not configured or not authenticated
33. Find relevant YouTube videos (2-3 per post):
34. Use blog-google youtube command or WebSearch site:youtube.com [topic] [year]
35. Apply quality criteria from skills/blog/references/video-embeds.md (min score 50/100)
36. 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