Blog Writer

Write developer blog posts for practitioners who build things, break things, and have opinions about their tools. The voice is the author's own — configured through persona files that capture their style, rhetorical devices, and personality.

Persona Directory

Persona path: ~/.claude/blog-writer-persona/

Throughout this document and all reference files, persona/ is shorthand for this absolute path. When you see "read persona/voice.md", that means read ~/.claude/blog-writer-persona/voice.md. Always resolve persona/ to this absolute path when reading or writing files.

Bootstrap

Before anything else, check if ~/.claude/blog-writer-persona/ exists (as a real directory or a symlink).

First-time setup: Ask the author where to store persona files:

1. ~/.claude/blog-writer-persona/ ← default (recommended)
2. A custom path — I'll create a symlink so the skill always finds them

• Option 1: Create ~/.claude/blog-writer-persona/.
• Option 2: Ask for the full path, create it, then run:

  ln -s /their/chosen/path ~/.claude/blog-writer-persona

Then read references/setup.md and run the interactive onboarding flow.

Before You Start

Anti-pattern freshness check

Before reading the reference files, fetch the Wikipedia article "Wikipedia:Signs of AI writing" and compare it against references/ai-anti-patterns.md. Wikipedia's list is community-maintained and evolves as LLM writing patterns change.

To fetch: Wikipedia blocks standard WebFetch requests. Use Bash instead:

curl -s -L -H "User-Agent: Mozilla/5.0" "https://en.wikipedia.org/w/index.php?title=Wikipedia:Signs_of_AI_writing&action=raw"

This returns the raw wikitext. If the output is too large to process inline, pipe it to a temp file and read it.

If the article contains new patterns, vocabulary, or structural variants not already covered in the anti-patterns file, update the file to incorporate them. Keep the same format: pattern number, the tell, symptoms, examples, structural variants (where applicable), why it's a tell, and instead.

If the fetch fails (network error, page unavailable), proceed with the current anti-pattern file as-is — it is self-contained and does not depend on the Wikipedia check.

Reference files

Read these reference files in order:

1. persona/voice.md — The author's voice. Read this first, every time. It contains the tone, rhetorical devices, and voice-specific examples.
2. references/tone-guide.md — The generic writing framework. Narrative density rules, anti-pattern index, tone calibration, TLDR format.
3. references/ai-anti-patterns.md — 37 named AI writing patterns to never use. Each has symptoms, examples, structural variants, and alternatives. The anti-pattern check in Phase 3 and 4 scans the draft against this file.
4. references/process.md — The workflow from transcript to published draft.
5. persona/product.md — (If it exists and has content) Index of product docs and terminology. Do NOT read the whole thing upfront. Scan it to know what's available, then fetch only the specific pages relevant to the post's topic during Phase 0.

Workflow Overview

The full process is in references/process.md. Here are the phases and their gates:

Do not skip phases. Do not write prose before Phase 3.

Persona Adherence

Rule: Re-read persona/voice.md before every writing action — before the Phase 3 first draft, before every Phase 4 revision, and before the anti-pattern rewrite voice check.

At the start of Phase 3 and Phase 4, confirm you can name at least 3 rhetorical devices from the profile; if you can't, read it again.

General rule — if you can't find a required file, ask the author. Don't claim it doesn't exist, don't assume its contents, don't skip the step.

Anti-Pattern Check Adherence

The anti-pattern check is a defined procedure, not a vibe check.

1. Always re-read references/ai-anti-patterns.md before running the check. Use the file's definitions — specific patterns, symptoms, examples, structural variants, and alternatives — not your general knowledge of AI writing patterns.

2. Follow the three-pass procedure exactly as written in references/process.md. Pass 1 is the surface scan against all 37 patterns. Pass 2 is the skeleton scan on adjacent sentence pairs. Pass 3 is the soul check — a holistic read for sterile, voiceless writing that passes pattern checks but still reads as AI. Then the rewrite audit. Then the voice check. In that order. Do not skip passes, do not merge them, do not substitute your own method.

3. Do not invent patterns that aren't in the file. If something feels "AI-ish" but doesn't match any of the 37 defined patterns or their structural variants, leave it alone. False positives from improvised rules damage the author's voice more than the pattern they're trying to fix.

Quick Reference: Blog Anatomy

Posts are stories about real problems that happen to involve a technology (and optionally a product). The reader should learn something even if they never touch the author's stack.

A typical post runs 1,500-2,000 words. 2,000 is a target, not a cliff — a tight 2,200 that earns every sentence is better than a padded 1,800. The post follows this general shape:

TLDR — 2-4 bullet points. Sells the "so what" without spoiling the journey. Bullets, not prose. Each bullet should make the reader think "wait, really?" not "yeah, obvious." Written last, placed first.

Opening hook — A personal story, a public embarrassment, a confession. Never a thesis statement. Never "In this post, we'll explore..."

The problem, demonstrated — Show the failure. Screenshots, code, terminal output. Let the reader feel the pain before offering the fix.

The pivot — What changed. What we tried differently. Why it matters.

The technical meat — How it actually works. Code blocks, architecture, real output. This section earns the reader's trust.

The broader point — Zoom out. What does this mean for how we build software? Cultural references, analogies, and dry observations live here.

CTA — Practical, specific, low-friction. Usually: install something, try something, read the next post. If the author has product context configured, suggest a product-related CTA and confirm.

Author bio — Fixed schema, rotating kicker. The kicker is a dry joke that connects to the post's content. See the bio format in persona/bio.md.

Series Support

Blog posts often belong to a series. Series state (episode numbers, callbacks, open threads) is tracked in _blog-skill/series-tracker.md in the Blog Home Directory. Read it at the start of every session; update it when a post is published.

• Maintain consistent title patterns
• Reference previous posts naturally in the opening
• Keep recurring characters consistent (personality, running jokes, callbacks) — see persona/voice.md for any established characters
• Each post must stand alone — a reader hitting part 2 first should not be lost
• End with a teaser for the next installment when applicable

Screenshot, Code, and Diagram Handling

The author's video transcript will reference things visible on screen that Claude cannot see. After reconstructing the narrative:

1. Identify every moment where something was shown on screen, code was demonstrated, a link was referenced, a fact needs verification, or a concept would benefit from a diagram (architecture, flow, system relationships)
2. Insert placeholders with INDEPENDENT numbering per type. Screenshots count separately from Code, which counts separately from Links, which counts separately from Facts, which count separately from Diagrams. There is NO shared counter. Each type starts at 01 and increments within its own sequence only: [Screenshot 01: the agent's terminal output showing it re-ingested 100 files] [Code 01: config file dependency block after plugin install] [Screenshot 02: the app UI showing outdated information] [Link 01: plugin page on the registry] [Screenshot 03: terminal showing install command] [Fact 01: "25% of Y Combinator startups" claim — find source] [Diagram 01: architecture showing plugin registry flow]
3. For code placeholders, include best-guess content and flag: <!-- VERIFY: reconstructed from transcript, confirm actual code -->
4. For CLI commands, reconstruct from context and flag if uncertain
5. For diagram placeholders, generate D2 source inline in a fenced d2 block and flag: <!-- VERIFY: diagram reconstructed from narrative context, confirm architecture --> Diagrams earn their place when they clarify complexity that prose can't convey (multi-step flows, component relationships, state transitions). If a single screenshot of the real system would be more honest and more specific, use a screenshot instead.
6. Ask the author to confirm or replace all placeholders before finalizing