/blog-writer

name: blog-writer
description: |
  Channel-master writer for long-form blog posts. Owns the SHAPE of a post —
  beat structure, title/preview/slug commitments, per-post container layout,
  per-site voice anchor discovery — and delegates VOICE (prose generation) to
  /authors-voice and PUBLISH mechanics to the openwriter github plugin
  (`add_blog_site` + `post_to_blog`).

  Use when: "/blog-writer", "write a blog post", "blog draft", "brainstorm blog
  topics", "blog beats", "extract beats from this post", "write about this
  feature", "draft a post", "blog title", "preview text", "OG description",
  "blog image", "featured image", "OG image", "integrate", "create the files",
  "wire up the blog post", "publish to blog", "post to blog", "set up blog repo",
  "register blog site".

  Requires: OpenWriter MCP server configured + github plugin enabled +
  `gh auth login` set up locally. Project SHOULD have a `## Blog` section in its
  CLAUDE.md for writing-rules / image-style overrides (optional after setup).
metadata:
  author: travsteward
  version: "0.5.0"
license: MIT

Blog Writer

Channel-master skill for long-form blog content. Owns ideation → beats → draft → image → publish.

**Architecture:** beats-first (v0.5.0) + plugin-backed publish (v0.4.0). Each post lives in its own container with two sibling docs: a `Beats` doc (the structural commitments — beat list + title/preview/slug as B0) and a `Draft` doc (the voice-poured prose). Beats reshape regularly; draft re-pours via `/authors-voice` against a per-site anchor (`voice/anchor-<site-slug>.md`). Publish is a single `post_to_blog` MCP call against a site registered via `add_blog_site`. Mirrors book-writer's discipline at post scale.

**Format rules for blog documents (title, blogContext fields, slug, cover, body, what `post_to_blog` needs) arrive from OpenWriter when the document is opened.** This skill keeps voice, beats, titling, SEO and editorial judgment, and the pipeline.

Convention

This skill obeys the shared writer contract at [WRITER-CONVENTION.md](../WRITER-CONVENTION.md). Brief shape and return shape match that doc. Sub-form values: `long` | `short` | `tutorial` | `announcement`.

OpenWriter's own editing rules arrive with its tools and documents.

**Blog posts ship SEO-complete in the FIRST pass.** A blog post almost always carries SEO — internal/cluster links, meta + slug + tags, snippet-targeted headings, FAQ/schema-eligible content all go into the *initial* draft (the minion brief + first `populate_document`), never bolted on after. Bolting SEO on later forces an edit (→ `write_to_pad`, never a 2nd populate). SEO-strategy-led posts (pillar / landing / comparison) front-end through `/seo-writer` if you have it installed (not bundled with OpenWriter).

**Cover image is a publish gate** (Firm rules). Placement rules: no bottom-band text (the platform renders og:title there), keep the subject center-safe, ≤5–7 words of overlay text, do not echo the title/description. Palette / brand skin comes from the project's `style_doc` (e.g. `recipebox.md`). Generation, canonical size, and the tmp-first rule for text-overlay covers: [docs/images.md](docs/images.md).

**ABOUT TO HAND-EDIT A PUBLISHED POST'S `.md`, ITS `image:` FRONTMATTER, OR DROP A COVER INTO THE REPO'S `public/`? STOP.** The OpenWriter doc is the single source of truth, and `post_to_blog` is the ONLY writer to the blog repo. Edits flow **doc → Accept → Publish** — never doc *and* repo in parallel, because Publish rewrites the post file wholesale and your hand-edits vanish. Never hand-name a cover; never side-channel an image; never `git push` the post yourself. Publish flow: [docs/integrate.md](docs/integrate.md).

Modes

| Mode | Trigger | What it does | Sub-doc | |---|---|---|---| | `setup` | `/blog-writer setup`, "register blog repo", "add blog site" | One-time per blog: `inspect_blog_repo` clones the target, auto-proposes `frontmatter_defaults` + `frontmatter_field_map` from existing posts; `add_blog_site` persists the site config | [docs/setup.md](docs/setup.md) | | `brainstorm` | `/blog-writer brainstorm`, "brainstorm blog topics" | Open a Blog Ideas doc; propose 3-5 candidate angles with tone + length labels; hand off to `beats` when user picks | [docs/brainstorm.md](docs/brainstorm.md) | | `beats` | `/blog-writer beats`, "extract beats", "blog beats" | Query-first beat extraction with 3-pass (short/announcement, 3-5 beats) or 5-pass (long/tutorial, 8-15 beats); 9 blog category tags (CLAIM/REFRAME/MECHANISM/EVIDENCE/DEMO/SCENE/OBJECTION/APHORISM/PIVOT) + HOOK/CTA positional roles; locks title + preview + slug as B0; dopamine arc layered with conversion arc | [docs/beats.md](docs/beats.md) + [docs/titling.md](docs/titling.md) | | `draft` | `/blog-writer draft`, "draft this post", "pour the beats" | Per-beat dispatch to `/authors-voice` Apply Protocol with site-specific anchor; cross-beat coherence pass; supports beat-level reshape loop (re-pour only the affected beats) | [docs/draft.md](docs/draft.md) + [docs/voice-anchor.md](docs/voice-anchor.md) | | `images` | `/blog-writer images`, "blog image", "featured image" | Read style doc, craft prompt, generate the cover; optional inline images | [docs/images.md](docs/images.md) | | `integrate` | `/blog-writer integrate`, "publish", "post to blog" | `post_to_blog` against the registered site once the writer has accepted every pending change; verify the live URL | [docs/integrate.md](docs/integrate.md) | | `pipeline` | `/blog-writer pipeline`, "full blog workflow", "write and publish" | 7-step sequence (Setup → Brainstorm → Beats → Draft → Images → Accept → Publish → Verify) with explicit gates; reshape loop returns to Beats step | [docs/pipeline.md](docs/pipeline.md) |

Modes can chain (pipeline runs them in sequence) or stand alone. Beats reshape → draft re-pour is the inner loop the architecture is designed around.

Setup (per-session vs per-blog)

**Per-session.** Read the project's CLAUDE.md