/blog-write

name: blog-write
description: >
  Write new blog articles from scratch optimized for Google rankings and AI
  citations. Generates full articles with template selection, answer-first
  formatting, Key Takeaways summary box, information gain markers, evidence-backed explanations, sourced
  statistics, Pixabay/Unsplash images, built-in SVG chart generation, optional FAQ sections,
  internal linking zones, and proper heading hierarchy. Supports MDX, markdown,
  and HTML output.
  Use when user says "write blog", "new blog post", "create article",
  "write about", "draft blog", "generate blog post".
user-invokable: true
argument-hint: "<topic>"
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 t