blog-builder

Blog Builder Skill

Purpose

Create a polished, engaging blog post from a North Star document and plan (produced by idea-refiner). Output is a single versioned Markdown file with YAML frontmatter, ready for publishing.

When To Use

• User asks to create a blog post, article, or written piece for publication
• A North Star and plan exist (from idea-refiner) or user provides equivalent context
• Content should be engaging, well-structured, and publish-ready

Output Format

File: <slug>-blog-v<N>.md

Document Template

---
title: "<Title>"
author: "<Author>"
date: "<YYYY-MM-DD>"
tags: [<tag1>, <tag2>, <tag3>]
description: "<150-160 char meta description for SEO>"
draft: true
version: v<N>
---

# <Title>

<Hook/Lede — first 50 words must grab attention. Start with a surprising fact, a provocative question, a vivid scene, or a bold statement. The reader decides whether to continue in the first two sentences.>

## Introduction

<1-2 paragraphs: establish the topic, why it matters NOW, what the reader will learn. End with a clear thesis or preview of what's coming.>

## <Section 1 Title>

<2-5 paragraphs per section. Each section explores one aspect of the topic.>

<Include: examples, data, quotes, code snippets, or anecdotes as appropriate.>

## <Section 2 Title>

<same pattern>

## <Section 3 Title> _(optional, as needed)_

<same pattern>

## <Section 4 Title> _(optional, as needed)_

<same pattern>

## <Section 5 Title> _(optional, as needed)_

<same pattern>

## Conclusion

<1-2 paragraphs: synthesize the key points, restate the thesis with the weight of evidence behind it, provide a forward-looking statement or call to reflection.>

## Call to Action

<1-2 sentences: what should the reader do next? Try something, share the post, comment, explore a resource.>

---

*<Optional: author bio, related posts, acknowledgments>*

---

Writing Rules

1. Hook in the first 50 words. The opening must earn the reader's attention. Techniques: surprising statistic, provocative question, vivid scene-setting, bold contrarian take, personal anecdote. Never start with "In today's world..." or "Have you ever wondered..."
2. Maximum 3-4 sentence paragraphs. Long paragraphs are walls of text on screens. Break them up. One idea per paragraph.
3. Subheadings every 200-300 words. Readers skim. Subheadings serve as signposts. Each subheading should be descriptive enough to convey the section's point to a skimmer.
4. Conversational tone by default. Write like you're explaining to a smart colleague over coffee. Contractions are fine. First person is fine. Rhetorical questions are fine. Can be adjusted per North Star.
5. Show, don't tell. Instead of "This is important," show WHY it's important with an example, a story, or a data point.
6. Code examples are runnable. If the post includes code snippets, they must be syntactically correct, properly formatted with language-specific code fences, and ideally self-contained enough to copy-paste and run.
7. SEO considerations. The YAML frontmatter includes a meta description (150-160 chars). The title should contain the primary keyword. Subheadings should use natural language that matches search intent. Don't keyword-stuff — write for humans, optimize for robots.
8. Images and diagrams. Mark locations for images with <!-- IMAGE: description of what should go here -->. Don't leave blank spaces — describe what the reader would see.
9. Internal linking. If referencing other posts or resources, use descriptive link text (not "click here").
10. End with a CTA. Every post should give the reader a clear next step.

---

Per-Section Success Criteria

Opus 4.7 follows instructions literally. A loose section template ("write a section about X") produces something that technically matches the prompt but misses intent. Before drafting each section, lock the success criteria - what the reader knows or feels by the end of it. Carry these into the draft and check against them in the review tier.

Section	Done When
Introduction	Reader has the hook, knows who the post is for, and knows what they will leave knowing. ≤ 100 words.
Body sections (1-5)	Each section makes ONE point with at least one concrete example or piece of evidence. The skimmer can derive the section's point from the subheading alone. No section restates the previous section's conclusion.
Conclusion	Synthesizes - does NOT repeat. Names what changes for the reader after they finish reading.
Call to Action	Single, specific next step. Not "learn more", not "let me know what you think". A real verb + a real link.

If your draft satisfies the section template but cannot pass the Done When criteria, the section needs a rewrite, not a polish.

---

Engagement Patterns

Techniques to keep readers engaged throughout:

• Pattern interrupts — break expected patterns with humor, a question, or a surprising aside
• Concrete examples — abstract concepts need concrete instances to land
• Callback references — reference earlier points to create cohesion ("Remember when we said X? Here's where it pays off.")
• Progressive complexity — start simple, build to complex. Each section should build on the previous.
• Emotional variety — mix analytical sections with stories or personal reflections

---

Mid-Draft Quality Check (Mandatory)

Foundation: This skill inherits the quality framework from skills/builders/builder-foundation/SKILL.md. The Mid-Draft Quality Check, Refine-or-Pivot decision, and review tier structure defined there apply here. Below are blog-specific quality prompts.

Blog-Specific Quality Prompts

Dimension	What to Look For
Depth	Do examples use specific details (names, numbers, dates) or generic placeholders? Does each section teach something the reader didn't know?
Originality	Does the hook avoid cliched openings? Does the post offer a perspective that isn't the first Google result for this topic?
Coherence	Does each section build on the previous? Does the conclusion follow from the evidence presented?
Completeness	Are all North Star must-covers addressed? Is the CTA specific and actionable?

Document evaluator optional for blog posts (simpler documents). See builder-foundation for invocation pattern.

---

Cross-Agent Deliverable Review

After drafting, optionally run cross-agent review.

Critic Roles

Codex — Fact Checking & Code Samples

Codex is the fact-checker. Use it to verify every claim, code snippet, URL, and data point.

Fact-check the following blog post content. For each claim, provide:
  1. Verification status: VERIFIED / OUTDATED / INCORRECT / UNVERIFIABLE
  2. Source URL confirming or correcting the claim
  3. Date of source data
  4. Any version-specific concerns

Also check:
  - All code snippets for syntax correctness and runnability
  - All URLs for liveness (LIVE / DEAD / REDIRECT)
  - All statistics and data points against current sources
  Flag unsourced assertions, outdated data, or broken references.

Gemini — Readability & Engagement

Gemini is the engagement and readability specialist. Use it to evaluate flow, pacing, and reader experience.

Review the following blog post for readability and engagement:
  1. Evaluate hook effectiveness — does the opening earn attention in the first 50 words?
  2. Identify engagement dead zones — sections without stories, examples, or data
  3. Check paragraph length — flag any paragraph exceeding 4 sentences
  4. Verify subheading frequency — flag any gap exceeding 300 words without a subheading
  5. Assess overall flow and pacing — does the post build logically?
  6. Confirm conversational tone is maintained throughout
  7. Evaluate the CTA — is it clear and actionable?
  8. Check for monotonous structure — are sections varied in their opening patterns?

Output format:
1) ENGAGEMENT_ISSUES (dead zones, weak hook, missing examples)
2) READABILITY_ISSUES (long paragraphs, missing subheadings, walls of text)
3) FLOW_ISSUES (pacing problems, abrupt transitions, structural monotony)
4) NORTH_STAR_ALIGNMENT (does the post serve the stated goal?)
5) READY_FOR_PUBLISH (yes/no + reason)

Review Procedure

1. Concatenate blog content into inline prompts (never reference file paths for critics)
2. Run critics in parallel with per-agent timeouts (Codex=480s, Gemini=180s)
3. Merge feedback, prioritizing consensus items
4. Triage and apply accepted changes
5. Max 2 rounds for deliverable review

---

Versioning

• v1: First draft from North Star + plan
• v2: After user feedback or cross-agent review
• v3: Final version

Only keep the latest version. Delete previous versions when a new one is created (e.g., delete <slug>-blog-v1.md when <slug>-blog-v2.md is written).

---

Review Checklist

Before finalizing, verify items in priority order. Spend 70% of review effort on Critical Items (where Claude is weakest).

Critical Items (Claude Weak Spots - Review Thoroughly)

• Hook is genuinely surprising or provocative (not "In today's fast-paced world..." or similar AI opening patterns)
• Each section offers a non-obvious insight or concrete example (not generic advice anyone could write)
• No AI writing patterns - no significance inflation, no rule-of-three forcing, no generic positive conclusions
• Examples use real specifics (names, numbers, dates, code) not abstract placeholders
• Post has a clear point of view - not a balanced "on the other hand" fence-sitting piece

Standard Items (Claude Strong Spots - Quick Verify)

• No paragraph exceeds 4 sentences; subheadings every 300 words
• Word count matches North Star target (800-2500); YAML frontmatter complete
• Meta description 150-160 chars; all code examples syntactically correct
• CTA present and actionable; no placeholder text; tone matches North Star

---

Output Rules

• Never write files larger than 200 lines in a single response
• For large files, write in sequential chunks
• If you hit an output token limit, resume where you stopped

---

Version: 2.0.0