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, citation capsules, sourced statistics, Pixabay/Unsplash images, built-in SVG chart generation, FAQ schema, 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".
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, citation capsules, sourced statistics, Pixabay/Unsplash images, built-in SVG chart generation, FAQ schema, 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
id
blog-write
domain
content
invoked_by
["blog-writer"]
depends_on
[]
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/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:
Owned site (organic Google ranking)
SERP including AI Overviews
AI assistant citations (ChatGPT, Perplexity, Antigravity, Gemini, Copilot, You.com)
Local pack (out of scope for blog content; use antigravity-seo for local)
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
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)
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).
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
Load the matching template: Read from skills/blog/templates/<type>.md
Adapt the outline - Use the template's section structure, heading patterns,
and word count guidance to shape Phase 3's outline
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):
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)
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
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 seo-image-gen sub-skill
Stock photos remain default - AI generation supplements, never replaces
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
Find relevant YouTube videos (2-3 per post):
Use seo-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 positions
- Single focused CTA per post (266% more conversions)
- [CTA: contextual call-to-action matching article topic]
## FAQ Section (3-5 questions, 40-60 words each answer)
- [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):
Select chart type using the diversity rule (no repeated types per post)
Invoke blog-chart sub-skill with: chart type, title, data values, source, platform format
Embed the returned SVG directly in the post within a <figure> wrapper
Target 2-4 charts per 2,000-word post
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
---title:"[Question-format title with primary keyword]"description:"[Fact-dense, 150-160 chars, includes 1 statistic]"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:
> **Key Takeaways**> - [Core finding with statistic] ([Source], year)> - [Second key insight or recommendation]> - [Third actionable takeaway]
Requirements:
3-5 bullet points, 40-60 words combined
Must be self-contained - understandable without reading the article
Include 1 specific statistic with source name
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. Answer-First Formatting (Critical)
Every H2 section MUST open with a 40-60 word paragraph containing:
At least one specific statistic with source attribution
A direct answer to the heading's implicit question
Pattern:
## 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.]
FLOW evidence triple (drafting requirement, not just audit):
Every public statistic must carry three components AT DRAFTING TIME:
Year anchor in prose. Write "In 2026," or "As of Q1 2026," BEFORE
the statistic, in the sentence body. Year buried inside parentheses
does not count. Example:
GOOD: "In 2026, Ahrefs found a 58% lower CTR for position one when
an AI Overview was present."
Inline citation with publisher and title. Name both the publisher
and the document title (or report name), not just a brand. Example:
GOOD: "Ahrefs, AI Overviews CTR update, December 2025"
WEAK: "Ahrefs reported..."
URL plus retrieval date in the source block at the bottom of the post.
Provenance discipline lets future readers and AI crawlers verify the
source still says what was claimed. Format:
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, AI detector test, schema,
PAA rewording, ChatGPT visibility), see /blog flow optimize.
5d. Information Gain Markers
Distribute at least 2-3 information gain markers throughout the article. These
signal to search engines and AI systems that the content contains original value
not available elsewhere.
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:
> **Our finding:** [original observation backed by specific data]
Minimum 2 per post, target 3 for comprehensive articles
These markers map directly to the "Originality/unique value markers" criterion
in the Content Quality scoring category (see skills/blog/references/quality-scoring.md).
5e. Citation Capsules
For each major H2 section, generate a citation capsule - a 40-60 word self-contained
passage designed so AI systems can extract and quote it directly.
Requirements per capsule:
40-60 words, self-contained (makes sense in isolation)
Contains: one specific claim + one data point + source attribution
Written in a declarative, quotable style
Placed within the H2 section body (not as a separate block)
Example:
According to a 2026 Gartner study, 58% of enterprise buyers now consult AI
assistants before contacting a vendor ([Gartner](https://www.gartner.com), 2026).
This shift means B2B content must answer specific questions concisely enough
for AI systems to extract and cite in their responses.
Capsules map to the "AI Citation Readiness" scoring category (15 points) in
skills/blog/references/quality-scoring.md.
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:
[INTERNAL-LINK: anchor text → target description]
Example:
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
Every paragraph: 40-80 words (never exceed 150)
Every sentence: max 15-20 words
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 (60-70% as questions)
H3s for subsections only - never skip levels
Include primary keyword naturally in 2-3 headings
5i. Image Embedding
Standard markdown:
MDX with Next.js Image (if detected):
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):
Organic CTR declined 61% with AI Overviews ([Seer Interactive](https://www.seerinteractive.com/), 2025).
5m. FAQ Section
Add 3-5 FAQ items with 40-60 word answers. Each answer must contain a statistic.
For MDX with FAQSchema component:
<FAQSchema faqs={[
{ question: "Question?", answer: "40-60 word answer with statistic and source." },
]} />
For standard markdown:
## Frequently Asked Questions### Question text here?
Answer with statistic and source attribution (40-60 words).
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
Every H2 opens with a statistic + source
No paragraph exceeds 150 words
All statistics have named tier 1-3 sources
2-4 charts with type diversity
3-5 inline images with descriptive alt text
Cover image present in frontmatter (coverImage + ogImage)
Contractions - Verify natural use of contractions ("it's", "we've", "don't", "isn't"). Formal AI prose avoids contractions; natural writing uses them.
Rhetorical questions - Verify at least one rhetorical question every 200-300 words to break up declarative patterns.
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 per skills/blog/references/blog-delivery-contract.md. The user is never the first reviewer; the gates are.
Steps:
Capability discovery + hero: run python scripts/blog_preflight.py --draft <folder> --gate 1 to enumerate available paths. If nanobanana-mcp is loaded, generate the hero via the MCP tool. Otherwise run python scripts/generate_hero.py --topic "<title>" --tags "<tags>" --out <folder> (uses the Gemini, Unsplash, Pexels, Pixabay, Openverse ladder).
Format completeness: render the canonical .md to .html and .pdf via python scripts/blog_render.py --md <slug>.md --out-dir <folder>. All three artifacts plus hero.<ext> must end up in the draft folder.
Content review (blocking): dispatch the blog-reviewer agent (Task tool) against the rendered .html. The agent emits its scorecard to <folder>/review.md ending with BLOCKING: true|false (reason). Threshold: overall score 90/100 or higher AND zero P0 issues per editorial-heuristics.md.
Visual + asset gates: run python scripts/blog_preflight.py --draft <folder> --strict. This runs Gate 3 (visual verification via patchright at 3 viewport widths), Gate 4 (reads review.md BLOCKING line), and Gate 5 (asset + link integrity). Exit 0 = ship; exit 1 = block.
Iteration: on any block, capture the failure diagnostic from <folder>/preflight-report.json, re-dispatch the blog-writer agent with the diagnostic as input, and re-run from step 1. Maximum 3 iterations. On the 3rd failure, STOP and present the failure diagnostic instead of the draft.
The orchestrator holds the loop counter; this sub-skill never loops itself.
Phase 7: Delivery
Present the completed article ONLY after Phase 6.5 returns all gates passing. Include the screenshots from <folder>/preview/*.png in the summary so the user can see what they are getting before reading the prose.
Summary template:
## Blog Post Complete: [Title]
### Template Used
- [Template name] (or "generic outline - no template matched")
### Statistics
- [N] sourced statistics from tier 1-3 sources
- [N] unique sources cited
### Visual Elements
- Cover image: [source - Pixabay/Unsplash/Pexels or generated SVG]
- [N] inline images (Pixabay/Unsplash/Pexels)
- [N] SVG charts (types: bar, lollipop, donut, line)
- [N] YouTube video embeds (titles: ...)
### Dual-Optimization Elements
- TL;DR box: present (N words)
- Information gain markers: [N] ([types used])
- Citation capsules: [N] across H2 sections
- Internal linking zones: [N] marked
### Structure
- [N] H2 sections with answer-first formatting
- [N] FAQ items with schema
- Word count: ~[N] words
- Estimated reading time: [N] min
### Naturalness
- Sentence length variance: [pass/fail]
- AI phrase scan: [pass/fail]
- Contractions used: [yes/no]
- Rhetorical questions: [N] (target: 1 per 200-300 words)
### Next Steps
- Review and customize for your brand voice
- Resolve [INTERNAL-LINK] placeholders with actual URLs
- Add internal links to your existing content
- Run `/blog analyze <file>` to verify quality score
- Generate VideoObject schema: `/blog schema <file>` (includes video markup)
- Generate audio narration: `/blog audio generate <file>` (optional)
Extended SEO Content Writer Capabilities (from seo-content-writer)
Creates SEO content that aligns with search intent, integrates keywords naturally, and stays usable for readers.
Quick Start
Write an SEO-optimized article about [topic] targeting the keyword [keyword]
Here's my content brief: [brief]. Write SEO-optimized content following this outline.
Skill Contract
Expected output: a ready-to-use draft plus the standard handoff summary for memory/content/.
Reads: the brief, target keywords, entity inputs, and quality constraints.
Writes: a user-facing content deliverable and reusable summary.
Promotes: approved angles, messaging choices, missing evidence, and publish blockers to memory/hot-cache.md and memory/open-loops.md; propose durable decisions as pending-decision items.
Done when: the draft satisfies the target intent with the primary keyword placed naturally; H1/H2 structure, meta description, and at least one snippet-targetable block are present; and every claim needing a source is either cited or flagged.
Primary next skill: seo-content when the draft is ready for gating.
Use ~~SEO tool and ~~search console when connected; otherwise ask for keywords, intent, and competitors. See CONNECTORS.md.
Instructions
When a user requests SEO content, run these nine steps:
Gather Requirements — confirm primary and secondary keywords, word count, content type, audience, intent, tone, CTA, and competitors.
Load CORE-EEAT Constraints — apply the 16 high-weight items listed in the companion reference.
Research and Plan — analyze the SERP, map keywords, and choose the content angle.
Create Optimized Title — keep it concise, keyword-led, and aligned with intent.
Write Meta Description — include the keyword, value proposition, and CTA.
Structure Content and Write — use a clean H1 > intro > H2/H3 > FAQ > conclusion flow.
Apply On-Page Best Practices — manage keyword placement, readability, snippets, and supporting visuals.
Add Internal / External Links — include relevant internal and authoritative external links.
Run Final SEO + CORE-EEAT Review — score the draft, auto-fix small issues, and surface any decisions that still need the user.
Any factual claim, statistic, or quote that requires a source must be cited or explicitly flagged [needs source]; never invent figures, studies, dates, or attributions to fill a gap.
Quality bar: before handing off, confirm the draft passes — (1) intent match: a reader with the target query gets their answer above the fold; (2) keyword placement reads naturally (no stuffing) in title, H1, first 100 words, and one H2; (3) structure is scannable (H2/H3, lists, one snippet-ready block); (4) zero fabricated facts — every source-needing claim is cited or [needs source]. If any item fails, fix it or report it in the handoff, do not ship silently.
Reference: See Instructions Detail for the compact workflow, pre-write checklist, issue-classification rules, and self-check format.
Example
Sample outcome: a keyword-led H1, optimized meta description, clear H2 structure, FAQ section, and a brief Changes Made block after the self-check. See references/seo-writing-checklist.md for the copy-start checklist and article template.
