Scribekit Blog

---
name: scribekit-blog
description: Write or rewrite a state-of-the-art, thoroughly-researched blog post for the current project's website (MDX), optimized for both classic search and AI answer engines (Google AI Overviews, ChatGPT, Perplexity). Use when the user wants to create/write/draft a new post or article, or rewrite/review/fact-check/audit/critique/improve an existing one (add --scan to only report, without changing anything). Each post's on-brand hero image is generated by the companion /scribekit-hero skill (the write flow calls it automatically). Portable - it learns and adapts to whatever project it runs in.
user-invokable: true
argument-hint: "[write|rewrite] [topic | slug-or-path] [--scan]"
---

# scribekit-blog

<!-- protocol-version: 31 -->
<!-- Bump the number above whenever the research/fidelity/verification contract changes materially.
     Pipelines that spawn this skill headless pin the version they were written against and refuse
     to run on an older install - a stale skill re-opens every hole the newer one closed. -->

A portable skill - **one skill, two jobs**: write a post, and rewrite (or just audit) a post, for the
blog of whatever project it is dropped into. **Nothing about any project is baked in.** It **learns the
current project first** (Step 0), then writes and rewrites to match it. Each post's **hero image** is
produced by the companion **[/scribekit-hero](../scribekit-hero/SKILL.md)** skill - the `write` flow calls
it automatically. This file is the router.

## Step 0 - Learn this project (every mode starts here)

Before anything else, discover the project so voice, links, and frontmatter are *this project's*, not
generic. Gather and keep as working notes for the run:

- **Identity, niche, audience** - read `CLAUDE.md` / `AGENTS.md` / `README`, and skim the landing
  page (the site's home route) and its main marketing copy. What does this business do, for whom,
  in what register?
- **Voice reference** - open the 1-2 strongest existing posts. That voice is your calibration
  target for everything you write or judge. ONE of them is the **calibration post** for
  house-style.md's density caps: the one the caller designates when it names one, otherwise your
  pick here, fixed before anything is counted (see house-style.md - never the pivot-heaviest sibling).
- **Where posts live** - find the blog content dir and its reader (a `lib`/`content` module that
  parses MDX frontmatter; common dirs: `blog/`, `content/blog/`, `src/content/`, `posts/`). Note
  the file extension, the **public dir** the site serves at its root (`<public-dir>`, e.g. `public/`,
  `static/`) and the **asset path** heroes live under inside it (`<asset-path>`, e.g. `assets`). A hero
  file at `<public-dir>/<asset-path>/blog/<slug>/hero.<lang>.jpg` is wired as
  `image: "/<asset-path>/blog/<slug>/hero.<lang>.jpg"` - the public dir is never part of the URL
  (see /scribekit-hero SKILL.md Step 0).
- **Frontmatter contract** - from the reader (or existing posts), learn the exact fields the
  project parses and any quirks. Common shape: `title`, `date`, `description`, `keywords`,
  `categories`, `author`, `author-image`, `image`, `updated`. Match it exactly - a field the reader ignores is
  dead weight; a
  malformed required one breaks the build.
- **Languages** - check whether the blog is multi-language: look for `locales` / `defaultLocale`
  in the `Blog` config, or `<lang>.<ext>` files (e.g. `fr.mdx`) inside the post folders. If so,
  note the configured codes and the default locale. A translation is a `<lang>.<ext>` file in the
  post's own `<slug>/` folder (e.g. `<slug>/fr.mdx`), beside the default-language
  `<slug>/<defaultLocale>.<ext>` (e.g. `en.mdx` - favor this locale-named form over `post.<ext>`);
  internal links must stay within the same language.
- **Internal routes** - enumerate the real routes (from the router: `app/` or `pages/`) so links
  point to pages that exist. Never invent routes.
- **Project style rules** - obey the project's own conventions (its `CLAUDE.md`): indentation,
  punctuation (some projects ban em-dashes), British vs US spelling, etc.

If the project genuinely has none of this (a near-empty repo), **ask the user** for the essentials
rather than guessing.

## Pick the mode

- **write** - a new post, or the argument is a topic/idea, or the verb is create / write / draft.
  -> **[write.md](./write.md)** (writes the post **and**, by default, its hero image; on a
  multi-language blog, also its translation for **every** configured locale).
- **rewrite** - audit an existing post **and apply the fixes** (rewrite / overhaul / redo / review /
  audit / fact-check / critique / improve / score), or the argument resolves to an existing post
  file/slug. Add **`--scan`** to only audit and report, changing nothing. -> **[rewrite.md](./rewrite.md)**.

**Hero images** are a separate skill: **[/scribekit-hero](../scribekit-hero/SKILL.md)** (create/update a
post's hero, tune the gradient palette, regenerate every hero). `write` calls it for you; invoke it
directly for standalone hero work.

Edge cases:
- **`rewrite` with no target** -> list the posts in the content dir and ask which.
- **"rewrite / overhaul / redo" an existing post** -> **rewrite** (it audits, then applies the
  fixes, up to a substantial rewrite) - not **write**, which only creates new posts.
- **Ambiguous** (a bare slug that matches a post but the verb suggests a fresh take) -> ask one
  clarifying question first. **Never** run two modes in one invocation.

## Read the shared standards first (all modes)

These are the spec every mode enforces - read them after Step 0, not as background:

- **[house-style.md](./house-style.md)** - how to derive and hold the project's voice; MDX
  formatting; the banned AI-slop lists; the frontmatter contract.
- **[research-protocol.md](./research-protocol.md)** - how to research and cite; never invent a fact.
- **[seo-checklist.md](./seo-checklist.md)** - on-page SEO **and** GEO (AI-answer-engine)
  optimization, plus the 100-point scoring rubric.

## Shipped assets (`assets/`) - the mechanical half of the protocol

- `ledger-verdicts.mjs` - the ONLY way a ledger row's verdict is set (apply refuses rows the verifier
  did not read), and `--check` - the run's closing gate: provenance, `--applied-after`,
  `--post-dir` (proof freshness by hash, gate tokens, style hits, the final audit),
  `--claim-table` (rewrite). Its printed output is the proof.
- `style-tics.mjs` - the regex meter and the digit-gate extraction.
- `fact-verifier-prompt.md`, `style-verifier-prompt.md`, `final-audit-prompt.md`,
  `final-audit-followup.md`, `claim-table-prompt.md` - the verifier prompts, sent VERBATIM with
  only their `<<PLACEHOLDERS>>` substituted; every verifier writes its own answer file. The
  parent never authors a verifier prompt and never retypes a return.

## Non-negotiables (all modes)

- **Never fabricate** a statistic, quote, date, source, or a named customer / case / event.
  Unsupported -> cut or soften to a claim you can defend. Every number is traceable to the sources list.
- **Never start a dev server** (ask the user to run it). **Never create git branches.** Keep changes
  scoped to the post + its hero asset.
- **Today's real date** comes from `date +%F`, never a guess, for `date:` / `updated:`.
- **Match the project, don't impose a house look.** Voice, routes, and frontmatter all come from
  Step 0 - this skill carries craft, not content (heroes match the project too - see /scribekit-hero).