Blog Workflow

This skill provides specialized support for blog post creation, metadata management, and publishing workflows.

Blog Post Structure

All blog posts require YAML frontmatter at the top:

---
slug: post-url-slug
title: "Post Title"
date: Month Day, Year
excerpt: "Brief description for previews"
categories: ["Category1", "Category2"]
---

YAML Frontmatter Fields

slug

Purpose: URL-friendly identifier for the post

Format: lowercase-with-hyphens, no spaces or special characters

Best practices:

• Keep it short but descriptive (3-5 words)
• Use keywords from title
• Once published, don't change (breaks links)

Examples:

• ✅ mcp-isnt-dead
• ✅ game-theory-basics
• ✅ weekly-writing-pipeline
• ❌ my-post (too generic)
• ❌ a-very-long-descriptive-title-for-my-post (too long)
• ❌ My Post! (not URL-friendly)

title

Purpose: Display title for the post

Format: Quoted string, Title Case or sentence case

Best practices:

• Compelling and specific
• 3-10 words ideal
• Matches or expands on H1 in content
• Avoid clickbait

Examples:

• ✅ "MCP Isn't Dead—It's Evolving"
• ✅ "Game Theory for Product Decisions"
• ✅ "The Weekly Writing Pipeline That Works"
• ❌ "Post" (too vague)
• ❌ "You Won't Believe What I Learned About Writing!" (clickbait)

date

Purpose: Publication date

Format: Month Day, Year (e.g., "November 22, 2025")

Best practices:

• Use full month name
• Include comma after day
• Four-digit year
• Matches actual publication date

Examples:

• ✅ November 22, 2025
• ✅ January 1, 2024
• ❌ 11/22/2025 (wrong format)
• ❌ Nov 22, 2025 (abbreviated month)
• ❌ 22 November 2025 (wrong order)

excerpt

Purpose: Brief summary for previews, SEO, social sharing

Format: Quoted string, 1-2 sentences

Best practices:

• Compelling hook that makes reader want more
• 15-30 words ideal
• Complete sentences
• No spoilers (save the punchline for the post)
• Standalone (doesn't require reading the post)

Examples:

• ✅ "Everyone thinks MCP failed. But the reports of its death are greatly exaggerated—here's why."
• ✅ "Game theory isn't just for economists. It's a mental model that transforms how you make product decisions."
• ❌ "This post is about writing." (too vague)
• ❌ "In this post I'll discuss..." (boring construction)

categories

Purpose: Topical tags for organization and filtering

Format: Array of quoted strings (JSON array syntax)

Best practices:

• 1-3 categories per post
• Use existing categories when possible (consistency)
• Broad enough to group posts, specific enough to be useful
• Title Case

Examples:

• ✅ ["Writing", "Productivity"]
• ✅ ["AI", "Product"]
• ✅ ["Engineering"]
• ❌ Writing, Productivity (missing brackets and quotes)
• ❌ ["writing", "productivity", "tools", "techniques", "tips"] (too many)

Common Categories in Vault

Based on existing blog posts:

• "AI"
• "Writing"
• "Product"
• "Engineering"
• "Productivity"
• "Opinion"
• "Tutorial"

When creating new categories:

• Check existing posts first: make search TERM="categories:"
• Keep list manageable (10-15 categories max)
• Merge similar categories

Blog Creation Workflow

Method 1: Use Make Command (Recommended)

make new
# Select "blog" when prompted
# Fill in template variables

The make new command:

1. Prompts for blog metadata (title, slug, date, excerpt, categories)
2. Creates file in blog/ directory
3. Substitutes variables in template
4. Opens file in editor

Method 2: Manual Creation

1. Copy templates/blog.md
2. Save to blog/your-slug.md
3. Replace all {{PLACEHOLDERS}}
4. Start writing

Pipeline Integration

Blog posts follow the weekly writing pipeline:

Monday-Tuesday: Capture & Cluster

• Fragments go in daily notes, not blog drafts
• Group related ideas to identify blog-worthy topics

Wednesday: Outline

• Create blog post file with frontmatter
• Write outline in markdown
• Don't worry about prose yet

Thursday: Draft

• Fast draft using outline
• Mark gaps with [TK: ...]
• Don't edit yet

Friday: Revise ⭐

• Full revision: Structure → Style → Mechanics
• Use revision-agent for systematic improvement
• Use argument-strengthener for logic
• Resolve TK placeholders (or note research needed)

Saturday: Review

• Share with outside reader
• Get feedback: where bored, unclear, unnecessary
• Address critical issues

Sunday: Publish

• Final polish
• Validate frontmatter
• Run checks (lint, links, export)
• Move to final state

Publishing Checklist

Before publishing a blog post:

Content Complete

• No [TK: ...] placeholders remaining
• Opening hooks reader
• Closing delivers
• All claims supported
• Examples are clear and relevant

Frontmatter Valid

• Slug is URL-friendly and descriptive
• Title is compelling
• Date is correct format
• Excerpt is 1-2 sentences and compelling
• Categories are appropriate (1-3 tags)

Quality Checks

• Run make lint - no formatting issues
• Run make check-links - no broken internal links
• Run make search TERM="[TK:" - no TK placeholders
• Read aloud once - catches awkward phrasing

Export Test

• Run make export-blog POST=blog/filename.md
• Review PDF - formatting looks good
• PDF matches markdown (no export errors)

Git Commit

• Clear commit message
• Staged only the blog post (not unrelated changes)

Frontmatter Generation

Auto-generating Slugs

Convert title to slug:

1. Lowercase everything
2. Replace spaces with hyphens
3. Remove special characters
4. Remove articles (a, an, the) if too long

Examples:

• "MCP Isn't Dead" → mcp-isnt-dead
• "The Weekly Writing Pipeline" → weekly-writing-pipeline
• "5 Game Theory Principles" → 5-game-theory-principles

Auto-generating Excerpts

Techniques for creating compelling excerpts:

1. Problem-Solution: "Everyone faces [problem]. Here's why [solution works]."
2. Contrarian: "Everyone thinks [common belief]. But here's why they're wrong."
3. Curiosity Gap: "I discovered [surprising thing] while [doing X]."
4. Big Promise: "Here's how [technique] changed [outcome]."

From blog opening:

• If opening is strong, it often works as excerpt
• If not, write dedicated excerpt (don't excerpt later content)

Auto-generating Categories

Based on post content:

1. Scan for keywords: What topics appear most?
2. Check existing categories: Which fit best?
3. Primary + Secondary: Main topic + approach
   • Example: ["AI", "Product"] = AI topic, product angle
   • Example: ["Writing", "Tutorial"] = writing topic, how-to format

Decision tree:

• Is it about AI/technology? → "AI"
• Is it about writing craft? → "Writing"
• Is it about product decisions? → "Product"
• Is it about engineering/code? → "Engineering"
• Is it a how-to? → "Tutorial"
• Is it an opinion piece? → "Opinion"
• Is it about productivity? → "Productivity"

Export to PDF

Basic Export

make export-blog POST=blog/filename.md

This command:

1. Strips YAML frontmatter (not needed in PDF)
2. Converts markdown to PDF using Pandoc
3. Applies style.css if available
4. Outputs to blog/filename.pdf

Export Requirements

• Pandoc installed
• xelatex or lualatex installed (for PDF generation)

Export Troubleshooting

Error: "pandoc not found"

• Install: brew install pandoc (macOS)

Error: "xelatex not found"

• Install: brew install --cask mactex (macOS)

Export works but formatting is wrong

• Check style.css exists
• Verify markdown is clean (run make lint)

Frontmatter Validation

Manual Check

Review each field:

• Slug: lowercase-with-hyphens, no spaces?
• Title: quoted, compelling?
• Date: "Month Day, Year" format?
• Excerpt: quoted, 1-2 sentences?
• Categories: ["Category1", "Category2"] format?

Common Frontmatter Errors

Missing quotes around title/excerpt:

❌ title: My Post
✅ title: "My Post"

Wrong date format:

❌ date: 11/22/2025
✅ date: November 22, 2025

Categories not in array format:

❌ categories: Writing, AI
✅ categories: ["Writing", "AI"]

Slug not URL-friendly:

❌ slug: My Post!
✅ slug: my-post

Validation Script

Search for posts with potential frontmatter issues:

# Find posts without proper frontmatter
grep -L "^---" blog/*.md

# Find posts with malformed categories
grep -E "categories: [^[]" blog/*.md

Blog Post Templates

Standard Blog Post

Use templates/blog.md - works for most posts.

Essay Format

For longer, more formal pieces:

---
slug: slug-here
title: "Title"
date: Month Day, Year
excerpt: "Excerpt"
categories: ["Opinion", "Writing"]
---

# Title

[Opening hook - 1-2 paragraphs]

## I.

[First major section]

## II.

[Second major section]

## III.

[Third major section]

---

[Closing reflection]

Tutorial Format

For how-to posts:

---
slug: how-to-x
title: "How to X"
date: Month Day, Year
excerpt: "Learn how to X in Y steps"
categories: ["Tutorial", "Engineering"]
---

# How to X

## What You'll Learn

- Point 1
- Point 2
- Point 3

## Prerequisites

- Requirement 1
- Requirement 2

## Step 1: [Action]

[Instructions]

## Step 2: [Action]

[Instructions]

## Conclusion

[Summary and next steps]

Archiving Published Posts

When a blog post is complete and published:

Option 1: Keep in blog/

• Most blog posts stay in blog/ directory
• They're published, not archived
• Only archive if removing from active blog

Option 2: Archive

If post is no longer part of active blog:

# Move to archive preserving structure
mv blog/old-post.md archive/blog/old-post.md
make check-links  # Fix any broken references

Multi-Part Series

For blog series (multiple related posts):

Approach 1: Separate Files

blog/
  game-theory-part-1.md
  game-theory-part-2.md
  game-theory-part-3.md

Each has:

• Frontmatter with series indicator in categories: ["Game Theory", "Series"]
• Links to other parts at top and bottom

Approach 2: Project Then Extract

projects/
  game-theory-series/
    full-manuscript.md
    outline.md
    part-1-notes.md

blog/
  [extracted posts when ready]

Work on full project, extract blog posts when sections are complete.

Related Make Commands

Content Creation

• make new - Create new blog post (interactive)
• make daily - Create daily note (for capture stage)

Publishing

• make export-blog POST=blog/post.md - Export to PDF
• make wordcount FILE=blog/post.md - Check word count

Quality

• make lint - Check formatting issues
• make lint-fix - Auto-fix formatting
• make check-links - Validate internal links
• make search TERM="[TK:" - Find placeholders

Discovery

• make search TERM="categories:" - See all category usage
• make recent - See recently modified posts
• make stats - Vault statistics (includes blog post count)

Instructions for Claude

When working with blog posts:

1. Always validate frontmatter - check format and completeness
2. Auto-generate missing metadata - suggest slug, excerpt, categories
3. Respect pipeline stage - different depth for draft vs. revision
4. Enforce house rulebook - clean markdown, valid links
5. Suggest export test - make export-blog before publishing
6. Track publishing checklist - ensure all steps complete
7. Reference existing categories - maintain consistency

When creating new blog posts:

• Suggest using make new for template
• Auto-generate slug from title
• Draft compelling excerpt based on opening
• Suggest appropriate categories based on content

When revising blog posts:

• Check frontmatter validity first
• Ensure no TK placeholders before publish
• Validate excerpt matches content
• Suggest make check-links and make lint

When publishing:

• Walk through publishing checklist
• Test export: make export-blog POST=path
• Verify frontmatter format
• Confirm ready for next stage

For more details, see:

• frontmatter-spec.md - Complete frontmatter reference