blog-writer

name	blog-writer
description	Technical blog post enhancement workflow with parallel research agents, perplexity-powered source discovery, and image integration. This skill should be used when writing, enhancing, or publishing blog posts that need authoritative sources, hero images, inline diagrams, and interlinking.

Blog Writer

Enhance technical blog posts with authoritative sources, relevant images, and internal links using parallel research agents.

When to Use

• Writing new blog posts that need research backing
• Enhancing existing posts with sources and images
• Publishing workflow that requires quality gates (sources, images, links)

Enrichment Loop

The core workflow iterates until quality gates pass:

┌─────────────────────────────────────────────────────────────┐
│  BLOG ENHANCEMENT LOOP                                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. LOAD    → Read blog content, extract key topics         │
│      ↓                                                      │
│  2. RESEARCH → Dispatch 1-n haiku agents + bird bookmarks   │
│      ↓                                                      │
│  3. ENHANCE  → Add sources, images, interlinks              │
│      ↓                                                      │
│  4. VALIDATE → Check quality gates                          │
│      ↓                                                      │
│  [LOOP back to step 2 until gates pass]                     │
│                                                             │
│  EXIT CONDITIONS:                                           │
│  ✓ 5-10 authoritative sources                               │
│  ✓ 2-3 inline images + 1 hero                               │
│  ✓ Internal links to related posts                          │
│  ✓ Further Reading section                                  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Quality Gates

Gate	Requirement	Validation Command
Sources	5-10 external links	grep -c 'https://' post.mdx
Hero Image	1 after intro	head -20 post.mdx | grep -c '!\['
Inline Images	2-3 throughout	grep -c '!\[' post.mdx
Interlinks	Related internal posts	grep -c '/blog/' post.mdx
Further Reading	Section at end	grep -c '## Further Reading' post.mdx

Step 1: Load Blog Content

Read the post and extract key elements:

cat ~/k/presence/www/content/logs/<post>.mdx

Identify:

1. Title and topic - Main subject
2. Key terms - Concepts needing authoritative backing
3. Sections - Where images add value
4. Related posts - Internal linking opportunities

Step 2: Research with Multiple Sources

2A: Parallel Haiku Agents via Perplexity

Dispatch multiple haiku agents for cost-efficient parallel research:

# Parallel dispatch pattern
Task(subagent_type=general-purpose, model=haiku,
     prompt="Use mcp__perplexity-mcp__search for '[topic] 2025 authoritative'")
Task(subagent_type=general-purpose, model=haiku,
     prompt="Use mcp__perplexity-mcp__reason for '[complex topic] explanation'")

2B: Bird CLI for Fresh AI Resources

Fetch recent bookmarks from X/Twitter for bleeding-edge sources:

# Get AI-related bookmarks
bird bookmarks -n 30 --json | jq -r '
  .[] | select(.text | test("AI|LLM|agent|RAG|Claude|GPT"; "i"))
  | "\(.user.name): \(.text[0:100])... \(.url)"
'

# Filter by specific topic
bird bookmarks -n 50 --plain | grep -i "agent\|orchestration\|swarm"

Bird CLI Reference:

bird bookmarks -n <count>     # Fetch N bookmarks
bird bookmarks --all          # Fetch all (paged)
bird bookmarks --json         # JSON output for parsing
bird bookmarks --plain        # Stable text output

Note: Requires X/Twitter auth configured in ~/.config/bird/config.json5

2C: Perplexity Direct Queries

For deep research, call perplexity tools directly:

mcp__perplexity-mcp__search   → Quick authoritative sources
mcp__perplexity-mcp__reason   → Deep explanations, comparisons
mcp__perplexity-mcp__deep_research → Comprehensive analysis

Query Patterns

Topic	Query Template
Technical	"[term] tutorial 2025 2026 authoritative"
Benchmarks	"[domain] benchmarks statistics 2025"
Best Practices	"[topic] best practices patterns 2025"
Comparisons	"[A] vs [B] comparison 2025"

Source Quality Criteria

Prefer sources that are:

• Recent (2024-2026)
• Authoritative (official docs, papers, major tech companies)
• Actionable (tutorials, guides, implementation patterns)
• Diverse (mix of blogs, docs, papers, videos, tweets)

Step 3: Enhance Post

Adding Sources

Weave sources naturally into the text:

# Good - inline with context
Research shows [layered mitigation strategies reduce hallucinations by 25-45%](https://arxiv.org).

# Avoid - citation dump at end only

Adding Images

Strategic placement:

1. Hero image - After intro paragraph, before first H2
2. Section images - At start of major sections
3. Diagrams - For complex concepts (pipelines, architectures)

![Descriptive alt text](/static/image-name.png)

Image Generation

Use free AI tools for technical diagrams:

• Perchance AI - No signup, quick generations
• Canva Magic Media - Free tier with export
• Stable Diffusion - Best for technical illustrations

Prompt pattern:

"clean flowchart of [concept], minimalist line art, dark background,
high contrast, vector style, labeled nodes"

Adding Interlinks

Link to related internal posts:

See our [AI Dictionary](/blog/logs/003-ai-dictionary) for term definitions.
This connects to [YAML to Agentic Runners](/blog/logs/002-yaml-to-agentic-runners).

Step 4: Validate and Loop

Run validation:

echo "=== Quality Gate Validation ==="
echo "Sources:"; grep -c 'https://' post.mdx
echo "Images:"; grep -c '!\[' post.mdx
echo "Further Reading:"; grep -c '## Further Reading' post.mdx
echo "Interlinks:"; grep -c '/blog/' post.mdx

Decision:

• All gates pass → COMPLETE
• Gates not met → Return to Step 2 with refined queries

MDX Format Reference

---
title: "Post Title"
date: 2026-01-14
description: "Short description under 200 chars"
tags: ["tag1", "tag2", "tag3"]
published: true
---

Important: Do NOT use ESM imports in MDX. Standard markdown only.

Best Practices

SEO and Readability

• Use H2 for major sections, H3 sparingly
• Bold key terms at first use
• Keep paragraphs short (2-4 sentences)
• Include code examples where relevant

Source Integration

• Weave sources into explanations naturally
• Use descriptive link text, not "click here"
• Prefer deep links to specific sections
• Mix inline sources + Further Reading section

Image Optimization

• Use descriptive alt text for accessibility
• Keep file sizes under 500KB
• Use PNG for diagrams, WebP for photos
• Name files descriptively (not image1.png)

Example Enhancement Session

1. LOAD: ~/k/presence/www/content/logs/004-growth-architect.mdx
   → Topics: K-factor, viral loops, B2B SaaS benchmarks, MBTI personas

2. RESEARCH (parallel):
   → Haiku Agent 1: "B2B SaaS conversion benchmarks 2025"
   → Haiku Agent 2: "viral coefficient K-factor optimization"
   → Haiku Agent 3: "MBTI buyer personas B2B marketing"
   → Bird CLI: bird bookmarks -n 30 --json | filter AI/growth

3. ENHANCE:
   → Add 9 inline sources (First Page Sage, Kurve, WDG Agency...)
   → Add hero image placeholder
   → Add 1 section image
   → Add Further Reading with 9 sources
   → Interlink to AI Dictionary and YAML post

4. VALIDATE:
   → Sources: 12 ✓
   → Hero: 1 ✓
   → Images: 1 (need 2 more)
   → Interlinks: 2 ✓

5. LOOP (need more images):
   → Generate 2 more section images
   → Re-validate

6. COMPLETE:
   → All gates pass

Troubleshooting

Bird CLI Auth Issues

# Check auth status
bird whoami

# Configure auth (add to ~/.config/bird/config.json5)
{
  "chromeProfile": "Default"  // or firefoxProfile
}

MDX Rendering Errors

• Remove all import statements
• Use standard markdown image syntax ![]()
• Avoid JSX components