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:

yaml

---
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)

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)

bash

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

The make new command:

•Prompts for blog metadata (title, slug, date, excerpt, categories)
•Creates file in blog/ directory
•Substitutes variables in template
•Opens file in editor

Method 2: Manual Creation

•Copy templates/blog.md
•Save to blog/your-slug.md
•Replace all {{PLACEHOLDERS}}
•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

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:

•Lowercase everything
•Replace spaces with hyphens
•Remove special characters
•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:

•Problem-Solution: "Everyone faces [problem]. Here's why [solution works]."
•Contrarian: "Everyone thinks [common belief]. But here's why they're wrong."
•Curiosity Gap: "I discovered [surprising thing] while [doing X]."
•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:

•Scan for keywords: What topics appear most?
•Check existing categories: Which fit best?
•
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

bash

make export-blog POST=blog/filename.md

This command:

•Strips YAML frontmatter (not needed in PDF)
•Converts markdown to PDF using Pandoc
•Applies style.css if available
•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:

yaml

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

Wrong date format:

yaml

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

Categories not in array format:

yaml

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

Slug not URL-friendly:

yaml

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

Validation Script

Search for posts with potential frontmatter issues:

bash

# 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:

markdown

---
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:

markdown

---
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:

bash

# 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

code

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

code

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:

•Always validate frontmatter - check format and completeness
•Auto-generate missing metadata - suggest slug, excerpt, categories
•Respect pipeline stage - different depth for draft vs. revision
•Enforce house rulebook - clean markdown, valid links
•Suggest export test - make export-blog before publishing
•Track publishing checklist - ensure all steps complete
•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