When to Use

• Setting up a blog section for SEO
• Writing blog articles for organic traffic
• Creating comparison/review content
• Building content marketing assets
• Any project needing a file-based blog CMS

Prerequisites

Before writing articles, ensure:

1. Blog infrastructure is set up (see Blog Setup)
2. AI image generation capability is available
3. MDX support is configured in your bundler

Quick Start

# 1. Set up blog infrastructure (first time only)
# Copy assets from this skill to your project

# 2. Create article folder
mkdir -p src/content/blog/{slug}

# 3. Generate unique article image using AI
# See Image Generation section below

# 4. Write article using template
# Use assets/templates/article.mdx as base

Workflow Overview

┌─────────────────────────────────────────────────────────────────┐
│  1. SETUP (One-time)                                            │
│     └─> Blog infrastructure                                     │
├─────────────────────────────────────────────────────────────────┤
│  2. RESEARCH                                                    │
│     └─> Keywords → Competitors → Content gaps                   │
├─────────────────────────────────────────────────────────────────┤
│  3. OUTLINE                                                     │
│     └─> Structure → Tables → FAQs                               │
├─────────────────────────────────────────────────────────────────┤
│  4. IMAGE GENERATION                                            │
│     └─> AI-generate unique image for article content            │
├─────────────────────────────────────────────────────────────────┤
│  5. WRITE                                                       │
│     └─> Draft → Optimize → Review                               │
├─────────────────────────────────────────────────────────────────┤
│  6. PUBLISH                                                     │
│     └─> MDX file → Sitemap → Verify                             │
└─────────────────────────────────────────────────────────────────┘

Image Generation (CRITICAL)

Philosophy

Every article MUST have a unique, content-specific image. Do NOT use generic pattern backgrounds. Generate a custom image that:

1. Visually represents the article topic
2. Includes relevant text/title overlay
3. Has a consistent brand style (dark theme, orange accents)
4. Is sized 1200x630 pixels for OG sharing

Image Generation Process

For EACH article, use AI image generation with this template:

A sophisticated hero image for "[ARTICLE TITLE]" blog article.
[DESCRIBE VISUAL CONCEPT THAT MATCHES CONTENT]
Dark background (#0f172a or #1e293b) with orange (#f97316) accents.
Modern, minimalist, professional SaaS style like Linear or Vercel.
Include text overlay: "[TITLE]" and optional subtitle.
1200x630 pixels.

Example Prompts by Article Type

Comparison Article

A sophisticated hero image for "Sunsama Alternatives" comparison article.
Modern minimalist design with floating app icons and comparison cards.
Deep navy background (#0f172a) with orange (#f97316) gradient accents.
Show multiple tools being compared with visual hierarchy.
Include title text overlay. Professional SaaS marketing style.
1200x630 pixels.

Guide/Tutorial Article

A sophisticated hero image for "Time Blocking Guide" tutorial article.
Modern minimalist design showing calendar grid with colorful time blocks.
Dark slate background (#1e293b) with vibrant orange (#f97316) blocks.
Clean 3D floating elements suggesting productivity and organization.
Include title: "TIME BLOCKING GUIDE" and subtitle "Master Your Day".
1200x630 pixels.

VS/Comparison Article

A sophisticated hero image for "Time Blocking vs To-Do Lists" comparison.
Split design: left side shows organized calendar blocks, right side shows
scattered checklist items. Visual contrast between order and chaos.
Dark background with orange (#f97316) and blue (#3b82f6) accents.
Include title text. Editorial style. 1200x630 pixels.

Self-Hosted/Technical Article

A sophisticated hero image for "Self-Hosted Productivity Apps" article.
Server/cloud icon with data flowing to personal devices.
Emphasizes privacy and control with lock/shield symbols.
Dark navy background with green (#22c55e) security accents and orange highlights.
Include title and tagline about privacy/control. 1200x630 pixels.

Routine/Habit Article

A sophisticated hero image for "Daily Planning Routine" habit article.
Morning scene with coffee, notebook, and digital calendar interface.
Soft gradient from deep purple to warm orange (#f97316).
Floating UI elements showing checklist items.
Calm, productive, aspirational mood. Include title. 1200x630 pixels.

Image Naming Convention

Save images with descriptive names:

public/blog-{slug}.png

Examples:
- blog-sunsama-alternatives.png
- blog-time-blocking-guide.png
- blog-self-hosted.png
- blog-daily-planning-routine.png

Updating Frontmatter

After generating, update the article frontmatter:

export const frontmatter = {
  // ...other fields
  image: "/blog-{slug}.png"
};

Blog Infrastructure Setup

Required Files

Copy these from assets/ to your project:

your-project/
├── src/
│   ├── content/
│   │   └── blog/           # MDX articles go here
│   │       └── {slug}/
│   │           └── index.mdx
│   ├── types/
│   │   └── blog.ts         # Copy from assets/templates/
│   ├── lib/
│   │   └── blog.ts         # Copy from assets/templates/
│   ├── components/
│   │   └── blog/
│   │       ├── blog-card.tsx
│   │       └── blog-layout.tsx
│   └── routes/
│       ├── blog.tsx        # Blog listing
│       └── blog.$slug.tsx  # Individual post
└── public/
    └── blog-{slug}.png     # Generated images per article

Vite/React Setup

For Vite projects, use import.meta.glob to load MDX files:

// src/lib/blog.ts
const modules = import.meta.glob('../content/blog/*/index.mdx', { eager: true });

Next.js Setup

For Next.js projects, use @next/mdx or contentlayer:

// next.config.js
import mdx from '@next/mdx';
const withMDX = mdx({ extension: /\.mdx?$/ });
export default withMDX({ pageExtensions: ['ts', 'tsx', 'mdx'] });

Keyword Research

Step 1: Primary Keyword Selection

Use web search to research your topic:

Search queries to run:
- "[topic] 2026"
- "best [topic]"
- "[topic] alternative"
- "[topic] vs [competitor]"

Step 2: Classify Search Intent

Subagent Prompt: Keyword Research

You are an SEO expert. Research keywords for [TOPIC].

Use web search to find:
1. Primary keyword with highest search intent
2. 5 secondary keywords (long-tail variations)
3. Top 5 competitor URLs for analysis
4. Content gaps competitors are missing

Return:
- Prioritized keyword list with intent classification
- Recommended content angle
- Estimated search volume (HIGH/MEDIUM/LOW)

Article Structure

Frontmatter Template

export const frontmatter = {
  title: "SEO Title Under 60 Characters with Primary Keyword",
  description: "Meta description 150-160 chars with keyword and compelling hook.",
  date: "2026-01-30",
  author: "Team Name",
  tags: ["primary-tag", "secondary-tag", "category"],
  readingTime: 10,
  image: "/blog-your-article-slug.png"  // UNIQUE image per article!
};

Article Outline Template

# [Primary Keyword in H1 Title]

## Introduction
- Hook with statistic or pain point
- What reader will learn
- Establish credibility (1-2 paragraphs)

## [Section 2: Definition/Background]
- What is [topic]?
- Why it matters (2-3 paragraphs)

## [Section 3: Core Content / How-To]
- Main value proposition
- Step-by-step if tutorial
- Numbered list for scanability

## [Section 4: Comparison Table]

| Feature | Option A | Option B | Option C |
|---------|----------|----------|----------|
| Price   | Free     | $10/mo   | $25/mo   |
| Feature | ✅       | ✅       | ❌       |

## [Section 5: Detailed Analysis]
- 3-4 paragraphs per option
- Pros and cons
- Best use cases

## Frequently Asked Questions

### What is [primary keyword]?
[2-3 sentence answer targeting featured snippet]

### Is [option A] better than [option B]?
[Honest comparison with recommendation]

## Conclusion
- Summary of key points
- Clear CTA with link to action

Writing Guidelines

SEO Best Practices

Word Count Targets

Complete Article Creation Workflow

Step 1: Research

Use keyword research agent to identify:
- Primary keyword
- Secondary keywords  
- Top 5 competitors
- Content gaps

Step 2: Generate Image

Use AI image generation with article-specific prompt.
Save to public/blog-{slug}.png

Step 3: Create Article Folder

mkdir -p src/content/blog/{slug}
touch src/content/blog/{slug}/index.mdx

Step 4: Write Content

Use article writer agent with:
- Keyword targets
- Word count requirement
- Comparison tables
- FAQ section

Step 5: Update Frontmatter

export const frontmatter = {
  title: "...",
  description: "...",
  date: "YYYY-MM-DD",
  author: "Team Name",
  tags: ["..."],
  readingTime: X,
  image: "/blog-{slug}.png"  // Your generated image
};

Step 6: Add to Sitemap

<url>
  <loc>https://yoursite.com/blog/{slug}</loc>
  <lastmod>{date}</lastmod>
  <changefreq>monthly</changefreq>
  <priority>0.8</priority>
</url>

Step 7: Verify

• Image displays correctly on blog listing
• Article renders properly
• All links work
• Sitemap is valid

Subagent Prompts

Image Generation Agent

Generate a unique blog hero image for: "[ARTICLE TITLE]"

Topic: [brief description]
Style: Dark background, orange accents, modern SaaS aesthetic
Include: Title text overlay, relevant visual elements
Size: 1200x630 pixels

Save as: blog-{slug}.png

Article Writer Agent

Write a [WORD_COUNT]+ word SEO article on [TOPIC].

Primary keyword: [KEYWORD]
Secondary keywords: [KEYWORD_LIST]

Include:
1. Frontmatter with all required fields
2. Introduction with hook/statistic
3. Comparison table with 4+ options
4. Detailed breakdown (3-4 paragraphs per option)
5. FAQ section with 5+ questions using h3 headers
6. Conclusion with CTA linking to [PAGE]

Image has been generated at: /blog-{slug}.png
Include this in frontmatter.

FAQ Writer Agent

Write 7 FAQ questions for article about [TOPIC].

Target keywords:
- [keyword 1]
- [keyword 2]
- [keyword 3]

Use h3 headers (###) for each question.
Each answer should be 2-3 sentences.
Target featured snippet format (direct, concise).

Publishing Checklist

• Unique image generated for this specific article
• Image saved to public/blog-{slug}.png
• Image path in frontmatter matches file
• Primary keyword in title
• Meta description optimized (150-160 chars)
• At least 1 comparison table
• At least 5 FAQ questions
• Internal links added (2-3)
• Reading time calculated
• Tags assigned (2-4)
• Date set correctly
• Article added to sitemap.xml

File References

See assets/ folder for:

Updates

• v1.1 (2026-01-31): Updated to require unique AI-generated images per article
• v1.0 (2026-01-30): Initial skill with complete workflow