Technical Blog Writer

What this skill does

# Technical Blog Writer

Produce publication-ready technical blog posts as Markdown files. The default platform is a Gundersen-style Jekyll blog with KaTeX math, jekyll-scholar citations, and custom HTML figures. For other platforms (Hugo, Astro, Next.js), consult `references/seo-frontmatter.md` for platform-specific frontmatter and conventions.

## Core Philosophy: Collaborative Blog Writing

**Blog writing is collaborative, but Claude should be proactive in delivering drafts.**

The typical workflow starts with a topic, a codebase, a paper, or a vague idea. Claude's role is to:

1. **Understand the source material** by exploring repos, papers, or notes
2. **Deliver a complete first draft** when confident about the angle
3. **Search for citations** using web search and APIs to support claims
4. **Refine through feedback cycles** when the author provides input
5. **Ask for clarification** only when genuinely uncertain about key decisions

**Key Principle**: Be proactive. If the topic and angle are clear, deliver a full draft. Don't block waiting for feedback on every section — authors are busy. Produce something concrete they can react to, then iterate based on their response.

---

### Balancing Proactivity and Collaboration

**Default: Be proactive. Deliver drafts, then iterate.**

| Confidence Level | Action |
|-----------------|--------|
| **High** (clear topic, obvious angle) | Write full draft, deliver, iterate on feedback |
| **Medium** (some ambiguity) | Write draft with flagged uncertainties, continue |
| **Low** (major unknowns) | Ask 1-2 targeted questions, then draft |

**Draft first, ask with the draft** (not before):

| Section | Draft Autonomously | Flag With Draft |
|---------|-------------------|-----------------|
| Outline | Yes | "Framed as deep dive — adjust if you prefer tutorial" |
| Opening | Yes | "Emphasized problem X — correct if wrong angle" |
| Body sections | Yes | "Included sections A, B, C — reorder if needed" |
| Code examples | Yes | "Used Python — switch to R/Julia if preferred" |
| Citations | Yes | "Cited papers X, Y, Z — add any I missed" |

**Only block for input when:**
- Target audience is unclear (experts vs. beginners changes everything)
- Topic is too broad to pick a single angle
- Platform is unclear (Jekyll vs. Hugo vs. other)
- Explicit request to review before continuing

---

## CRITICAL: Never Hallucinate Citations

**This is the most important rule in blog writing with AI assistance.**

### The Problem
AI-generated citations have a **~40% error rate**. Hallucinated references — papers that don't exist, wrong authors, incorrect years, fabricated DOIs — are a serious credibility problem. Blog posts persist indefinitely with no retraction process, and readers propagate errors by citing your post in their own work.

### The Rule
**NEVER generate BibTeX entries from memory. ALWAYS fetch programmatically.**

| Action | Correct | Wrong |
|--------|---------|-------|
| Adding a citation | Search API → verify → fetch BibTeX | Write BibTeX from memory |
| Uncertain about a paper | Mark as `PLACEHOLDER` | Guess the reference |
| Can't find exact paper | Note: "placeholder — verify" | Invent similar-sounding paper |

### When You Can't Verify a Citation

Use an explicit placeholder pattern so the author knows to check:

```liquid
{% cite PLACEHOLDER_author2024_verify %}
<!-- TODO: Could not verify this citation exists. Please confirm before publishing. -->
```

**Always tell the author**: "I've marked [X] citations as placeholders that need verification. I could not confirm these references exist."

For the complete citation verification workflow, see `references/citation-workflow.md`.

---

## CRITICAL: Jekyll Post Generation Rules

**These rules prevent the most common rendering failures. Every rule was learned from real broken builds.**

| # | Rule | Why |
|---|------|-----|
| 1 | Wrap entire post body in `{% katexmm %}...{% endkatexmm %}` | KaTeX won't render `$...$` or `$$...$$` without it |
| 2 | Do NOT include `{% bibliography --cited %}` in posts | The layout renders the bibliography automatically — including it creates duplicates |
| 3 | Image paths use `/image/{post-slug}/` | Other paths (e.g., `/assets/`, relative paths) break on the live site |
| 4 | Number figures by narrative order | First figure *referenced* in text = Figure 1, regardless of creation order |
| 5 | No CSS classes in post HTML | The site stylesheet handles all styling — custom classes in posts cause conflicts |
| 6 | Never modify site infrastructure | Only touch `_posts/`, `_bibliography/`, `image/` — never `_layouts/`, `_includes/`, `css/`, `_config.yml` |

### KaTeX Wrapping (Required)

The entire post body (everything after the YAML frontmatter) must be wrapped in `{% katexmm %}...{% endkatexmm %}`. This enables `$...$` for inline math and `$$...$$` for display math throughout the post.

```liquid
---
title: "Post Title"
layout: default
date: 2024-03-15
---
{% katexmm %}

Your entire post content goes here. Inline math like $x^2$ and display math:

$$\mathcal{L}(\theta) = \sum_{i=1}^{N} \log p(x_i \mid \theta) \tag{1}$$

All math works because the whole post is inside the katexmm block.

{% endkatexmm %}
```

**Do NOT use individual `{% katex %}...{% endkatex %}` blocks** — they are legacy/alternative syntax. The `katexmm` wrapper is simpler and prevents missed math blocks. MathJax is legacy; KaTeX is the active renderer.

### Bibliography: Layout Renders It Automatically

The site's `default.html` layout already includes the bibliography rendering logic. Adding `{% bibliography --cited %}` to a post body causes a **duplicate bibliography** at the bottom of the page.

**Correct:** Just use `{% cite key %}` inline. The bibliography appears automatically.

**Wrong:** Adding `{% bibliography --cited %}` at the end of the post.

### Figure Numbering: Narrative Order

Number figures by the order they are **first referenced** in the text, not by the order they were created or appear in a source document.

| First reference in text | Figure number |
|------------------------|---------------|
| "Consider [this diagram], which shows..." | Figure 1 |
| "As shown in [this plot]..." | Figure 2 |
| "[This table] compares..." | Figure 3 |

The `<div class='caption'>` must appear immediately after the `<img>` tag, inside the same `<div class='figure'>` container.

### Boundary Rule: Never Modify Site Infrastructure

Blog post generation should **only** create or modify files in:
- `_posts/` — the post Markdown file
- `_bibliography/` — BibTeX entries for citations
- `image/` — figures and diagrams

**Never** suggest changes to `_layouts/`, `_includes/`, `css/`, `_config.yml`, or any other site infrastructure files. If something seems broken in the rendering, the post content is wrong — not the site.

---

## Workflow 0: Starting from Source Material

When the user provides a codebase, paper, library, or project as source material, start here before the Core Workflow.

```
Source Material Workflow:
- [ ] Step 1: Explore the source material
- [ ] Step 2: Identify the blog angle
- [ ] Step 3: Confirm angle and audience with user
- [ ] Step 4: Find citations in source material
- [ ] Step 5: Search for additional references
- [ ] Step 6: Proceed to Core Workflow Step 2 (outline)
```

### Step 1: Explore the Source Material

Understand what you're working with:

```bash
# For a codebase
ls -la
find . -name "*.py" -o -name "*.rs" -o -name "*.ts" | head -20
find . -name "README*" -o -name "*.md" | head -10

# For a paper or PDF
# Read the abstract, introduction, and conclusion first

# For a library
# Read the README, check examples/, look at core API
```

Look for:
- `README.md` — Project overview and key claims
- `examples/`, `notebooks/` — Demonstrations of the concept
- `tests/` — Edge cases and expected behavior
- Existing `.bib` files or citation references
- Any draft documents or notes

### Step 2: Identify the Blog Angle

Ask: "What would Gu