---
name: snappy-blog
role: Blog channel operator (interview-driven MDX generation for snappy.ai/blog)
loaded-by: preload-skill-context hook
---

# snappy-blog -- Agent Loader

You are operating as the blog channel for Snappy. This file is the operational contract. The full SKILL.md exists for reference but the rules below are load-bearing -- if you deviate, the post is wrong or the build fails on Vercel.

snappy-blog owns **content production** for the blog format only. Methodology comes from `snappy-content`. Publishing (git, MDX validation, Vercel) belongs to `snappy-publish`. Hero/og images come from `snappy-image`. This skill is the bridge between an interview and a finished MDX file.

## API module

```typescript
import { listBlogPosts, validateFrontmatter } from "../snappy-blog/api.ts";
```

Or CLI:
```bash
npx tsx ~/.claude/skills/snappy-blog/api.ts list              # list blog posts in the snappy.ai repo
npx tsx ~/.claude/skills/snappy-blog/api.ts validate <path>   # validate MDX frontmatter
```

## API functions

| Function | Purpose |
|----------|---------|
| `listBlogPosts()` | List all MDX blog posts from the snappy.ai repo (slug, title, date, category, featured) |
| `validateFrontmatter(mdxContent)` | Validate MDX frontmatter against snappy-publish schema (required fields, category, tags, word count) |

## The 6-step workflow -- never skip, never reorder

```
1. INTERVIEW → 2. DRAFT → 3. SELF-EDIT → 4. APPROVAL GATE → 5. ASSEMBLE MDX → 6. HANDOFF
```

Approval gate is **always** Step 4. Hero image generation, MDX assembly, and handoff happen **after** copy approval -- never before.

## Step 0 -- Check for existing source material

Before running a fresh interview, check if relevant material already exists:

- **Krisp transcripts:** `~/.claude/corpus/krisp/YYYY/MM/*.md` -- full conversation transcripts. Search by topic/person name.
- **Mined nuggets:** `~/.claude/corpus/mined/` -- extracted content atoms from prior mining runs.
- **Content atoms DB:** `content_atoms` table on `rb-content-engine.fly.dev` (Neon Postgres) -- query via `snappy-mine`'s persist script or direct SQL.
- **Prior blog drafts:** `/tmp/snappy-blog-*.mdx` -- drafts saved from previous sessions.

If existing material covers the topic well, present it to Robert and ask whether to use it as the interview basis (skip to Step 2 with that data) or run a fresh interview anyway. Never silently ignore existing source material.

## Step 1 -- The 4-question interview (inherited from snappy-content)

Use `AskUserQuestion`. Ask all 4 in one call. Default to suggested options but allow free text.

| # | Question | Push For |
|---|----------|----------|
| 1 | "What's the core topic or thesis?" | A surprising claim or contrarian take, not a generic topic |
| 2 | "What's a specific story or example to anchor it?" | Real names, real numbers, real moments -- never invented |
| 3 | "What's your contrarian or non-obvious insight?" | A take you can defend with evidence |
| 4 | "Who is the primary reader?" | A specific persona, not "developers" |

### Follow-up probes (if vague)

| Vague | Follow-up |
|-------|-----------|
| "It was impactful" | "How much time/money? Compared to what?" |
| "Recently" | "Which month?" |
| "Someone said" | "Who? What was the context?" |
| "We saved time" | "How much per week? What did you replace?" |

**The 50% rule:** at least 50% of sentences in the final draft must contain a specific name, number, date, tool, or personal detail. If not, route back to the interview for more material -- do NOT invent.

## Step 2 -- Draft

Every claim must trace to interview data. No invented numbers. No placeholder brackets like `[X]`, `[Y]`, `[N]`. If the user gave no number, write qualitatively.

### Voice

| Rule | Value |
|------|-------|
| Tone | Direct, opinionated, developer-to-developer |
| Persona | Smart friend at a whiteboard, not a press release |
| Sentence length | Vary 5-25 words; avoid uniform rhythm (an AI tell) |
| Paragraphs | One idea per paragraph; 1-4 sentences |
| Hedging | None -- no "it depends", "may be", "could potentially" |

### Structure (every blog post)

```
[Hook]       ← First sentence is the opinion/thesis. No setup, no throat-clearing.
[Intro]      ← What's broken or misunderstood (1-2 paragraphs)
[Body]       ← Contrarian insight + the story from question 2 (2-3 sections)
[Solution]   ← What to do instead (2-3 paragraphs)
[Takeaway]   ← One-sentence distillation
[CTA]        ← Link to https://snappy.ai/#contact
```

### Length

| Target | Hard limit |
|--------|-----------|
| 800 words | min |
| 1,200 words | max -- `snappy-publish` rejects anything longer |

## Step 3 -- Self-edit against the anti-AI checklist

Run before showing Robert. Don't waste an approval round on AI slop.

### Banned phrases (abbreviated -- full list in snappy-positioning §4a + snappy-content/anti-ai-checklist.md)

Never use any of these:

- "10x" / "Nx" (any multiplier as a marketing claim)
- "the operating system for X"
- "unlock", "supercharge", "leverage" (as a verb)
- "revolutionize", "revolutionary", "transformative"
- "game-changer", "game-changing"
- "cutting-edge", "groundbreaking", "innovative", "seamless", "robust"
- "synergy", "ecosystem", "holistic", "paradigm shift", "disrupt"
- "AI-powered" as a standalone adjective
- "In today's rapidly evolving…", "It's no secret that…", "Let's unpack this…", "Here's the thing…", "I'm excited to share…"
- Empty intensifiers: "incredibly", "absolutely", "literally" (when not literal), "basically", "essentially"
- Em-dash sandwiches that read like ChatGPT default voice
- Three-bullet "Here's why:" framings

If any appear, rewrite before the approval gate. If `snappy-positioning` and this list disagree, positioning wins.

### Visual identity -- Ink Journal constraints

Snappy blog visuals are **Ink Journal**. When briefing `snappy-image` for hero or inline images, the brief MUST enforce:

| Constraint | Value |
|------------|-------|
| Background | Cream paper (off-white, slight texture, no pure white) |
| Ink | Black ink only -- hand-drawn linework feel |
| Border | Thin black border framing the canvas |
| Typography | Serif (when text appears in image) |
| Style | Editorial journal sketch -- no gradients, no neon, no 3D renders, no stock photography |
| Aspect ratio | 16:9 hero (1600x900) unless specified otherwise |

If `snappy-image` returns something that violates these constraints, reject and re-brief. Do not ship a hero that breaks the visual identity.

## Step 4 -- Approval gate

Show Robert the **full markdown body**, not a summary. He needs to read the actual content.

```
╭─ BLOG DRAFT ───────────────────────────────────────────────────╮
│  [full markdown body]                                            │
├──────────────────────────────────────────────────────────────────┤
│  Title: [title]                                                  │
│  Slug:  [slug]                                                   │
│  Words: [n]   (must be 800-1200)                                 │
│  Anti-AI: PASS                                                   │
│  50% specificity: [X]%                                           │
╰──────────────────────────────────────────────────────────────────╯
```

Then `AskUserQuestion`:

| Option | Action |
|--------|--------|
| Ready to publish | Continue to Step 5 |
| Run council critique | Route through `snappy-content/expert-council-method.md`, then re-present |
| Revise with notes | Collect notes, re-run Step 2 with notes injected (interview data stays) |
| Start over | Re-run Step 1 |

**Max 3 revision rounds** before suggesting council or a fresh interview. More rounds = the interview was too thin.

## Step 5 -- Assemble MDX

Slug rules: lowercase, hyphens, no punctuation, < 60 chars, must match filename `<slug>.mdx`.

Frontmatter must match `snappy-publish` schema **exactly** or gray-matter validation fails:

```mdx
---
title: "<title>"
description: "<1-2 sentence summary, < 160 chars>"
date: 2026-04-07
author: Robert Boulos
authorRole: "AI Developer & Technical Partner"
category: <Strategy|Engineering|AI|Business|Case Study>
featured: false
tags:
  - <tag1>
  - <tag2>
  - <tag3>
---
```

| Field | Critical rule |
|-------|---------------|
| `date` | UNQUOTED ISO date -- gray-matter parses as Date object. Quoting it breaks the build. |
| `featured` | `false` by default. Only ONE post in the repo can be `true`. |
| `tags` | YAML array, never a comma string. 3-5 lowercase-hyphenated. |
| `image` / `ogImage` | CDN URL only, never local path. From `snappy-image`. |

### Approved MDX components

Only `<Callout>` (max 2) and `<Quote>` (max 1). Anything else (`<Tabs>`, `<Mermaid>`, `<Image>`, `<Card>`, `<Steps>`, Nextra/Docusaurus/Fumadocs components) breaks the build.

## Step 6 -- Handoff

`AskUserQuestion`:

| Option | Action |
|--------|--------|
| Publish now | Hand to `snappy-publish` with the contract below |
| Save for later | Write to `/tmp/snappy-blog-<slug>.mdx`, return path |
| Make changes | Back to Step 4 |

### Handoff contract to snappy-publish

| Field | Value |
|-------|-------|
| `slug` | generated from title |
| `title` | from interview |
| `description` | meta description |
| `mdx_body` | full file content (frontmatter + body) |
| `category` | chosen category |
| `tags` | YAML array |
| `hero_image_url` | optional CDN URL from `snappy-image` |
| `featured` | `false` unless explicitly demoting another post |

The git/Vercel pipeline (clone, validate, commit, push, verify) lives in `snappy-publish` -- do NOT execute it from this skill.

### Hero image handoff to snappy-image

Only after Step 4 approval. Brief includes:

- Topic + thesis from interview
- **Visual identity: Ink Journal** (cream paper, black ink, thin border, serif if text)
- Aspect ratio 16:9 (1600x900) unless user specified otherwise
- Return CDN URL -- never local path
- **Canva sync:** hero image auto-imports to Canva (Blog Heroes folder `FAHGsVN6qK4`). Use `canvaImport(path, {folder:"blog", topic, format:"blog-hero"})` from `snappy-image/api.ts` or pass `--canva-folder FAHGsVN6qK4` to `generate.sh`

Drop the returned URL into the MDX `image:` and `ogImage:` fields before handoff to `snappy-publish`.

## What you produce as output

When asked to draft a blog post, your final output before the approval gate is:

```
TITLE: <title>
SLUG:  <slug>
DESCRIPTION: <meta, < 160 chars>
CATEGORY: <Strategy|Engineering|AI|Business|Case Study>
TAGS: <tag1>, <tag2>, <tag3>

DRAFT:
<full markdown body -- hook, intro, body sections, takeaway, CTA>

WORDS: <n>   (800-1200)
ANTI-AI: PASS
50% SPECIFICITY: <X>%
HERO IMAGE: <requested | none>
```

Then ask "Ready to publish, council critique, revise, or start over?" Never assemble MDX or hand off before explicit approval, even if the user said "publish it" earlier -- confirm the rendered draft first.

## Rules

- **Interview skipped.** User says "just write a blog about X" → STOP. Run the 4-question interview first. Never generate from a topic alone.
- **Banned phrase appears and user insists.** STOP. Surface `snappy-positioning` §4a. Ask user to confirm override in writing.
- **No specific data after interview** (50% rule fails). STOP. Re-interview for numbers/names/moments. Never invent.
- **Word count outside 800-1200.** STOP. `snappy-publish` will reject. Cut or expand before approval gate.
- **User asks for unsupported MDX component** (`<Tabs>`, `<Mermaid>`, etc). STOP. Offer markdown alternative -- these break the Vercel build.
- **`featured: true` requested but another post is already featured.** STOP. Ask user explicitly which post to demote.
- **Hero image violates Ink Journal identity.** Reject the image, re-brief `snappy-image`. Do not ship.
- **More than 3 revision rounds.** STOP. Suggest council critique or a fresh interview -- the source material is too thin.

## Reference (read only if needed)

- Full SKILL.md in this directory -- workflow detail, examples, frontmatter template, slug generator
- `snappy-content/SKILL.md` -- interview methodology, voice rules, expert council
- `snappy-content/anti-ai-checklist.md` -- full banned-words list
- `snappy-content/expert-council-method.md` -- 5-expert critique protocol
- `snappy-publish/SKILL.md` -- git/Vercel publishing pipeline
- `snappy-publish/mdx-validation.md` -- frontmatter validation rules
- `snappy-positioning` -- canonical voice/banned-phrases source (overrides this file on conflict)

Default to this AGENTS.md. Read the SKILL.md only when this file doesn't cover the case.

<!-- SKILL-INDEX-START -->
[snappy-blog Index]|root: ~/.claude/skills/snappy-blog|IMPORTANT: Prefer these files over pre-training assumptions for this domain. Read the relevant file when the AGENTS.md summary is insufficient.|root:{SKILL.md}
<!-- SKILL-INDEX-END -->

## Used by

- `snappy-image`

<!-- SNAPPY-CONTRACT-VERBS-START -->
## Contract verbs

Generated from `api.ts` `HAND_CONTRACT`. Do not hand-edit this block.

| Verb | Contract arguments | Effect | First call |
|---|---|---|---|
| `list` | — | `read` | `npx tsx ~/.claude/skills/snappy-blog/api.ts list` |
| `validate` | `path` | `read` | `npx tsx ~/.claude/skills/snappy-blog/api.ts validate <path>` |

## Show the result

When an answer carries `face_hint`, show it with one `snappy_present(<answer>)` call.
See `/snappy-faces` for face selection. Human-facing images must crop to the
element, render at 2x on Retina, and fill the destination channel instead of
placing a small card in a full-page screenshot.
<!-- SNAPPY-CONTRACT-VERBS-END -->

---
name: snappy-blog
reports_to: growth
head: false
description: >
  Interview-driven blog post generation for the Snappy website (snappy.ai/blog). Runs the
  4-question content interview, drafts opinion-first 800-1200 word MDX with the exact
  frontmatter format required by snappy-publish, runs the snappy-content anti-AI checklist,
  routes through writer/council approval gates, and hands the finished MDX to snappy-publish
  for git deployment. WRITING ONLY -- it does not deploy; snappy-publish owns git and Vercel.
  NOT for long-form aimed anywhere other than snappy.ai/blog (see article).
  Triggers on: write blog post, snappy blog, create blog post, new blog
  article, blog for snappy, write an article, blog draft, draft blog, opinion piece for
  snappy, mdx blog post, snappy.ai blog, blog post about, write a post for the website.
---

# Snappy Blog -- Interview-Driven Blog Generator

**Voice & Brand:** Always read `snappy-positioning` before creating any outbound content. It holds the one-liner, voice rules, banned phrases, and property map. If this skill disagrees with positioning, positioning wins.

## Purpose

Create opinion-first, 800-1200 word blog posts for snappy.ai/blog. snappy-blog owns the **content production** for blog format only -- voice methodology comes from `snappy-content`, and the **publishing** (git, MDX validation, Vercel deploy) is owned by `snappy-publish`. This skill is the bridge between an interview and a finished MDX file.

## When to Use This Skill

- "Write a blog post" / "new blog article" / "draft a blog"
- "Blog about [topic]" -- when Robert has a topic but no draft
- "Write an opinion piece for the website"
- A blog content slot fires from `snappy-ops` (Wednesday content rhythm)
- A YouTube video transcript needs to become a blog post (repurposing path)
- A sales call transcript needs to become a case study blog (with permission)

Do NOT use for:
- Publishing a finished MDX file → `snappy-publish`
- Writing social posts → `snappy-content` + `snappy-post`
- Writing emails → `snappy-email` (uses `snappy-content` methodology)
- Updating non-blog pages on snappy.ai → `snappy-website`

---

## Workflow

**Inputs (skills that feed this one):**
- `snappy-content` -- provides the methodology (interview framework, voice rules, anti-AI checklist, expert council)
- `snappy-transcripts` -- provides raw transcripts of meetings, calls, workshops as source material
- `snappy-video` -- provides Whisper transcripts of long-form video to seed blog repurposing
- `snappy-knowledge` -- provides contact context for case studies and personalization
- `snappy-sales` -- provides sales call recordings (with permission) for case study blogs
- `snappy-positioning` -- voice rules and §4a trip-wires (canonical source) <!-- learning from 2026-04-07 session -->

**Outputs (skills that consume this one):**
- `snappy-publish` -- receives the finished MDX file + slug + frontmatter and ships it to snappy.ai
- `snappy-post` -- routes the blog draft to snappy-publish and to email/social repurposing
- `snappy-email` -- receives the live blog URL to write "I just published" newsletter emails
- `snappy-linkedin` -- receives the blog as source material for a standalone LinkedIn post
- `snappy-skool` -- receives the blog as source material for a Skool discussion post

**Channels (where output is delivered):**
- `content/blog/<slug>.mdx` in the snappy-website repo
- After publish: `https://snappy.ai/blog/<slug>` (Vercel deploy)

**Orchestrator:**
- `snappy-ops` triggers this skill on the Wednesday content block (matches the YouTube video output) and during the weekly Monday planning if drafts are queued

---

## Quick Start -- The 6-Step Workflow

```
1. INTERVIEW ──▶ 2. DRAFT ──▶ 3. SELF-EDIT ──▶ 4. APPROVAL GATE ──▶ 5. ASSEMBLE MDX ──▶ 6. HANDOFF
                       │
                       └── (optional) Council critique via snappy-content/expert-council-method.md
```

| Step | What Happens | Output |
|------|-------------|--------|
| 1. Interview | Run the 4-question interview via `AskUserQuestion` | Raw interview answers |
| 2. Draft | Write the post using interview data as the foundation | First draft |
| 3. Self-Edit | Run the `snappy-content/anti-ai-checklist.md` against the draft | Clean draft |
| 4. Approval Gate | Show full draft + word count, ask "ready or revise?" | Approved draft (or back to step 2) |
| 5. Assemble MDX | Wrap in frontmatter matching `snappy-publish` schema | Valid MDX file body |
| 6. Handoff | Hand to `snappy-publish` (or save to disk) | MDX in `content/blog/` or `/tmp` |

---

## Step 1: The Interview

Use `AskUserQuestion` and ask all 4 questions in a single call. Default to suggested options but always allow free text.

| # | Question | Suggested Options | Push For |
|---|----------|-------------------|----------|
| 1 | "What's the core topic or thesis?" | AI agents for startups; Technical debt reality; Why agencies fail; Developer productivity | A surprising claim or contrarian take, not a generic topic |
| 2 | "What's a specific story or example to anchor it?" | Client project; Personal building experience; Industry observation; Contrarian take | Real names, real numbers, real moments -- never invented |
| 3 | "What's your contrarian or non-obvious insight?" | Conventional wisdom is wrong because...; Everyone focuses on X but the real issue is Y; The counterintuitive truth is...; What worked for me contradicts popular advice | A take you can defend with evidence |
| 4 | "Who is the primary reader?" | Technical founders (post-PMF); CTOs scaling teams; Solo developers going enterprise; Non-technical founders with dev teams | A specific persona, not "developers" |

### Follow-up Probes (If Answers Are Vague)

| Vague | Follow-up |
|-------|-----------|
| "It was impactful" | "How much time/money? Compared to what?" |
| "Recently" | "Which month?" |
| "Someone said" | "Who? What was the context?" |
| "We saved time" | "How much per week? What did you replace?" |

For the full interview methodology and the 50% specificity rule, see `snappy-content/SKILL.md` and `snappy-content/quality-rules.md`.

---

## Step 2: Draft

Write the post using interview answers as the foundation. Every claim must trace back to interview data -- no invented numbers, no placeholder brackets like `[X]` or `[Y]`.

### Voice

|rule|value|
|----|-----|
|tone|Direct, opinionated, developer-to-developer|
|persona|Smart friend explaining at a whiteboard, not a press release|
|sentence_length|Vary 5-25 words; avoid uniform rhythm (an AI tell)|
|paragraphs|One idea per paragraph; short paragraphs (1-4 sentences)|
|hedging|None -- no "it depends" / "may be" / "could potentially"|
|filler|None -- see `snappy-content/anti-ai-checklist.md` banned words/phrases|

### Structure

```
[Hook]              ← First sentence is the opinion / thesis (no setup)
[Problem]           ← What's broken or misunderstood (1-2 paragraphs)
[Insight]           ← The contrarian take, with the story from question 2 (2-3 paragraphs)
[Solution]          ← What to do instead (2-3 paragraphs)
[CTA]               ← Link to https://snappy.ai/#contact
```

### Length

|target|hard_limit|
|------|----------|
|800 words|min|
|1,200 words|max -- rejected by snappy-publish if exceeded|

---

## Step 3: Self-Edit Against Anti-AI Checklist

Before showing the draft to Robert, run it through `snappy-content/anti-ai-checklist.md`. The full list lives there; the highest-impact items to scan for:

|category|examples|
|--------|--------|
|Banned corporate buzzwords|leverage, game-changer, synergy, disrupt, paradigm shift, ecosystem, holistic, scalable|
|Banned AI filler|innovative, cutting-edge, groundbreaking, seamless, robust, transformative, revolutionize|
|Banned phrases|"In today's rapidly evolving...", "It's no secret that...", "Let's unpack this...", "Here's the thing...", "I'm excited to share..."|
|Structural tells|5-point list with alliteration, false anecdote, manufactured statistic, generic metaphor, summary paragraph|
|Empty intensifiers|incredibly, absolutely, truly, literally (when not literal), basically, essentially|

**The 50% Rule:** At least 50% of sentences must contain a specific name, number, date, tool, or personal detail. If less, route back to the interview for more material.

If the draft fails any banned-word check, fix it before showing Robert. Don't waste an approval round on AI slop.

---

## Step 4: Approval Gate

Present to Robert:

```
╭─ BLOG DRAFT ───────────────────────────────────────────────────╮
│                                                                  │
│  [Show the full markdown body -- not just a summary]              │
│                                                                  │
├──────────────────────────────────────────────────────────────────┤
│  Title: [title]                                                  │
│  Words: [n]   (must be 800-1200)                                 │
│  Anti-AI: PASS                                                   │
│  50% rule: PASS ([X]% specific sentences)                        │
╰──────────────────────────────────────────────────────────────────╯
```

Use `AskUserQuestion`:

| Option | Action |
|--------|--------|
| "Ready to publish" | Continue to Step 5 |
| "Run council critique first" | Route through `snappy-content/expert-council-method.md` (5 expert critiques + moderator synthesis) before re-presenting |
| "Revise with notes" | Collect notes via `AskUserQuestion`, re-run Step 2 with notes injected |
| "Start over" | Re-run Step 1 (new interview) |

### Revision Loop

If revising:

1. Collect specific notes (what to change, what to keep)
2. Re-run the writer prompt with notes appended (interview data stays)
3. Re-run Step 3 (anti-AI check)
4. Re-present at Step 4
5. Repeat until approved or Robert chooses "start over"

**Max 3 revision rounds** before suggesting the council method or a fresh interview. More rounds means the interview data wasn't strong enough.

---

## Step 5: Assemble MDX

Generate the slug from the title (lowercase, hyphens, no special chars, < 60 chars, must match the filename `<slug>.mdx`).

Wrap the body in the **exact** frontmatter format required by `snappy-publish` -- anything else fails the gray-matter validation:

```mdx
---
title: "<title>"
description: "<1-2 sentence summary, under 160 chars>"
date: 2026-04-07
author: Robert Boulos
authorRole: "AI Developer & Technical Partner"
category: <Strategy|Engineering|AI|Business|Case Study>
featured: false
tags:
  - <tag1>
  - <tag2>
  - <tag3>
---

[Markdown body here]

[Optional MDX components -- see below]

[CTA paragraph linking to https://snappy.ai/#contact]
```

### Frontmatter Field Rules

|field|format|notes|
|-----|------|-----|
|`title`|quoted string|< 60 chars for SEO|
|`description`|quoted string|< 160 chars; meta description|
|`date`|`YYYY-MM-DD`|UNQUOTED ISO date -- `gray-matter` parses this as a Date object|
|`author`|`Robert Boulos`|Always exactly this, unquoted|
|`authorRole`|`"AI Developer & Technical Partner"`|Always quoted, exact|
|`category`|enum|`Strategy` \| `Engineering` \| `AI` \| `Business` \| `Case Study`|
|`featured`|boolean|`false` by default -- only ONE post in the repo can be `true`|
|`tags`|YAML array|3-5 lowercase-hyphenated tags|

For optional fields (`image`, `ogImage`, `authorUrl`, `canonical`, `updated`) and the full validation rules, see `snappy-publish/mdx-validation.md` and `snappy-publish/images-and-frontmatter.md`.

### Approved MDX Components

The Snappy website's MDX provider supports two components. Use them sparingly -- overuse looks like docs, not opinion.

```mdx
<Callout type="info" title="Optional Title">
Body content. Supports **markdown** inline.
</Callout>

<Callout type="tip" title="Pro Tip">
Body content.
</Callout>

<Callout type="warning" title="Heads Up">
Body content.
</Callout>

<Quote author="Person Name">
Quote text. Single line or short paragraph.
</Quote>
```

|component|max_per_post|
|---------|-----------|
|`<Callout>`|2|
|`<Quote>`|1|

**Unsupported components** (will break the build): `<Image>`, `<Tabs>`, `<Card>`, `<Mermaid>`, `<CodeGroup>`, `<Steps>`, anything from Nextra/Docusaurus/Fumadocs. Use markdown instead. See `snappy-publish/mdx-validation.md` for the full unsupported list.

---

## Step 6: Handoff

Use `AskUserQuestion`:

| Option | Action |
|--------|--------|
| "Publish now" | Hand the MDX file body, slug, title to `snappy-publish` for the git workflow |
| "Save for later" | Write to `/tmp/snappy-blog-<slug>.mdx`, return the path |
| "Make changes" | Back to Step 4 |

### Publishing Handoff Contract

When handing off to `snappy-publish`, provide:

|field|value|
|-----|-----|
|`slug`|generated from title|
|`title`|from interview/user|
|`description`|the meta description|
|`mdx_body`|the full MDX file content (frontmatter + body)|
|`category`|the chosen category|
|`tags`|the YAML array|
|`hero_image_url`|optional CDN URL from `snappy-image` (if requested)|
|`featured`|`false` unless explicitly demoting another post|

The actual git/Vercel pipeline (clone, validate, commit, push, verify deploy) lives in `snappy-publish/SKILL.md`.

---

## ❌ WRONG / ✅ CORRECT

```
WRONG:   Generate a post from a topic without interviewing first
CORRECT: Always run the 4-question interview -- interview data is the foundation

WRONG:   Use placeholder brackets like [X] or [Y] for missing numbers
CORRECT: If the user didn't provide a number, write without numbers -- qualitative language

WRONG:   date: "2026-04-07"   (quoted)
CORRECT: date: 2026-04-07     (unquoted ISO date -- gray-matter requires Date object)

WRONG:   tags: "ai, agents, startups"   (comma string)
CORRECT: tags:                          (YAML array)
           - ai
           - agents
           - startups

WRONG:   featured: true   (when another post is already featured)
CORRECT: featured: false  (default; only swap with explicit instruction)

WRONG:   1500-word blog post
CORRECT: 800-1200 words (hard limit; snappy-publish rejects longer)

WRONG:   Use <Tabs> or <Mermaid> components
CORRECT: Only <Callout> and <Quote> are supported by the website's MDX provider

WRONG:   Slug = "Why-Agents-Matter!"  (capitals, punctuation)
CORRECT: Slug = "why-agents-matter"   (lowercase, hyphens only)

WRONG:   Hand off to snappy-publish before approval gate
CORRECT: Approval gate first, MDX assembly second, handoff last

WRONG:   Show Robert a summary of the draft
CORRECT: Show the full markdown body -- he needs to read the actual content

WRONG:   Skip the anti-AI checklist before the approval gate
CORRECT: Self-edit ALWAYS happens before showing Robert; don't waste a round on AI slop

WRONG:   Generate hero image before copy is approved
CORRECT: Copy approved first (Step 4), then route to snappy-image if hero requested

WRONG:   Restart the whole pipeline on revision
CORRECT: Re-run only the writer with notes injected; interview data stays
```

---

## Navigation Guide

|need_to|read_this|
|-------|---------|
|Run the interview methodology (full 4-question framework + 50% rule)|`snappy-content/SKILL.md` and `snappy-content/quality-rules.md`|
|Run the anti-AI self-edit|`snappy-content/anti-ai-checklist.md`|
|Run an expert council critique on a draft|`snappy-content/expert-council-method.md`|
|Validate MDX frontmatter before commit|`snappy-publish/mdx-validation.md`|
|Add hero/og images to a post|`snappy-publish/images-and-frontmatter.md`|
|Ship the finished MDX to snappy.ai|`snappy-publish/SKILL.md`|
|Repurpose the blog into email/LinkedIn/Skool|`snappy-content/repurposing-paths.md`|

---

## Quick Reference

### Frontmatter Template (Copy-Paste)

```mdx
---
title: ""
description: ""
date: 2026-04-07
author: Robert Boulos
authorRole: "AI Developer & Technical Partner"
category: AI
featured: false
tags:
  - 
  - 
  - 
---
```

### Slug Generator

```bash
TITLE="Why Agents Matter For Founders"
SLUG=$(echo "$TITLE" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | sed 's/[^a-z0-9-]//g' | cut -c1-60)
echo "$SLUG"   # why-agents-matter-for-founders
```

### Existing Posts Reference

```
~/Projects/v0-prototypes/v0-snappy-website-0c/content/blog/
```

Match the frontmatter format of existing posts exactly. See `why-technical-founders-get-stuck.mdx` for a known-good reference.

### Approval Gate Output Template

```
╭─ BLOG DRAFT ───────────────────────────────────────────────────╮
│  [full markdown body]                                            │
├──────────────────────────────────────────────────────────────────┤
│  Title: [title]                                                  │
│  Slug:  [slug]                                                   │
│  Words: [n]                                                      │
│  Anti-AI: PASS / FAIL                                            │
│  50% specificity: [X]%                                           │
╰──────────────────────────────────────────────────────────────────╯

Options: Ready to publish | Run council critique | Revise with notes | Start over
```

---

## Related Skills

|skill|why_it_relates|
|-----|--------------|
|`snappy-content`|Methodology source -- interview framework, voice rules, anti-AI checklist, expert council, 50% rule|
|`snappy-publish`|Receives the finished MDX, owns the git/Vercel pipeline, validates frontmatter|
|`snappy-post`|Distribution router -- routes the blog draft to snappy-publish and triggers email/social repurposing|
|`snappy-image`|Generates hero images and inline images (CDN URLs go in frontmatter `image:` / `ogImage:`)|
|`snappy-email`|Consumes the live blog URL to write newsletter emails (repurposing path)|
|`snappy-linkedin`|Consumes the blog as source material for a standalone LinkedIn post|
|`snappy-skool`|Consumes the blog as source material for a Skool discussion post|
|`snappy-transcripts`|Provides raw transcripts as interview material for repurposing|
|`snappy-video`|Provides Whisper transcripts of long-form video -- primary repurposing source|
|`snappy-knowledge`|Provides contact context for personalization and case studies|
|`snappy-sales`|Provides sales call recordings (with permission) for case study blogs|
|`snappy-ops`|Orchestrates the Wednesday content block where this skill runs|

---

**Skill Status**: COMPLETE

<!-- SNAPPY-NEAR-NEIGHBOURS-START -->
## Near neighbours

A model confuses this hand with `snappy-client-total`, `snappy-content`, `snappy-deploy`, `snappy-docs`, `snappy-dom-cartographer`, `snappy-freshbooks`, `snappy-gmail`, `snappy-inbound`, `snappy-nightshift`, `snappy-os-operator`, `snappy-post`, `snappy-publish`, `snappy-update`, `snappy-watchtower`, `snappy-website`. Open one of those when its job is the job.
<!-- SNAPPY-NEAR-NEIGHBOURS-END -->

#!/usr/bin/env npx tsx
/**
 * snappy-blog/api.ts -- Blog MDX operations for all snappy-* skills.
 *
 * Usage:
 *   npx tsx api.ts list                    # list blog posts in the snappy.ai repo
 *   npx tsx api.ts validate <path>         # validate MDX frontmatter
 *
 * Or import as module:
 *   import { listBlogPosts, validateFrontmatter } from "../snappy-blog/api.ts";
 */

import { existsSync, readFileSync, readdirSync, realpathSync } from "fs";
import { join } from "path";
import { env } from "../snappy-settings/load.ts";
import { boundRows, limitSchema, takeLimit } from "../snappy-settings/read-limit.ts";
import { refusalTable } from "../snappy-settings/refusal-codes.ts";

const BLOG_DIR = "/Users/robertboulos/.openclaw/workspace/projects/snappy-website-claude/content/blog";

const REQUIRED_FIELDS = ["title", "description", "date", "author", "authorRole", "category", "featured", "tags"];
const VALID_CATEGORIES = ["Strategy", "Engineering", "AI", "Business", "Case Study"];

interface PostInfo {
  slug: string;
  path: string;
  title: string;
  date: string;
  category: string;
  featured: boolean;
}

interface ValidationResult {
  valid: boolean;
  errors: string[];
  warnings: string[];
}

/** Lists blog posts from the snappy.ai repo. */
export function listBlogPosts(): PostInfo[] {
  if (!existsSync(BLOG_DIR)) return [];
  const files = readdirSync(BLOG_DIR).filter((f) => f.endsWith(".mdx")).sort();
  const posts: PostInfo[] = [];

  for (const file of files) {
    const content = readFileSync(join(BLOG_DIR, file), "utf-8");
    const fm = parseFrontmatter(content);
    posts.push({
      slug: file.replace(".mdx", ""),
      path: join(BLOG_DIR, file),
      title: fm.title || "(untitled)",
      date: fm.date || "(no date)",
      category: fm.category || "(none)",
      featured: fm.featured === true || fm.featured === "true",
    });
  }
  return posts;
}

/** Validates MDX frontmatter against snappy-publish schema. */
export function validateFrontmatter(mdxContent: string): ValidationResult {
  const errors: string[] = [];
  const warnings: string[] = [];
  const fm = parseFrontmatter(mdxContent);

  if (!fm._found) {
    errors.push("No YAML frontmatter found (must start with ---)");
    return { valid: false, errors, warnings };
  }

  for (const field of REQUIRED_FIELDS) {
    if (fm[field] === undefined || fm[field] === null || fm[field] === "") {
      errors.push(`Missing required field: ${field}`);
    }
  }

  if (fm.category && !VALID_CATEGORIES.includes(fm.category)) {
    errors.push(`Invalid category "${fm.category}". Must be one of: ${VALID_CATEGORIES.join(", ")}`);
  }

  if (fm.tags && !Array.isArray(fm.tags)) {
    errors.push("tags must be a YAML array, not a comma string");
  }

  if (fm.description && String(fm.description).length > 160) {
    warnings.push(`description is ${String(fm.description).length} chars (should be < 160)`);
  }

  // Word count check
  const body = mdxContent.split("---").slice(2).join("---").trim();
  const wordCount = body.split(/\s+/).filter(Boolean).length;
  if (wordCount < 800) warnings.push(`Body is ${wordCount} words (minimum 800)`);
  if (wordCount > 1200) warnings.push(`Body is ${wordCount} words (maximum 1200)`);

  return { valid: errors.length === 0, errors, warnings };
}

/** Simple YAML frontmatter parser (no dependencies). */
function parseFrontmatter(content: string): Record<string, any> {
  const match = content.match(/^---\n([\s\S]*?)\n---/);
  if (!match) return { _found: false };

  const result: Record<string, any> = { _found: true };
  const lines = match[1].split("\n");
  let currentKey = "";
  let inArray = false;
  let arrayValues: string[] = [];

  for (const line of lines) {
    if (inArray) {
      if (line.match(/^\s+-\s+/)) {
        arrayValues.push(line.replace(/^\s+-\s+/, "").trim());
        continue;
      } else {
        result[currentKey] = arrayValues;
        inArray = false;
        arrayValues = [];
      }
    }

    const kvMatch = line.match(/^(\w+):\s*(.*)/);
    if (kvMatch) {
      const [, key, val] = kvMatch;
      currentKey = key;
      if (val.trim() === "") {
        inArray = true;
        arrayValues = [];
      } else {
        let parsed: any = val.trim().replace(/^["']|["']$/g, "");
        if (parsed === "true") parsed = true;
        if (parsed === "false") parsed = false;
        result[key] = parsed;
      }
    }
  }

  if (inArray) result[currentKey] = arrayValues;
  return result;
}

// --- CLI ---
/** WHAT THIS HAND ANSWERS, and what each verb does to the world.
 *  Derived from this file's own CLI dispatch by
 *  `snappy-hands/contract-derive.ts` — a verb the code does not implement is
 *  never declared here. Snappy's daemon reads it (`api.ts contract`) to
 *  validate every call, build the argument words in order, decide whether the
 *  act runs now or stages for the owner, and hand the child exactly the
 *  environment keys named in `requires` — never a value, never anything else.
 */
export const HAND_CONTRACT = {
  skill: "snappy-blog",
  description: "Interview-driven blog post generation for the Snappy website (snappy.ai/blog). Runs the 4-question content interview, drafts opinion-first 800-1200 word MDX with the exact frontmatter format required by snappy-publish, runs the snappy-content anti-AI checklist, routes through writer/council approval gates, and hands the finished MDX to snappy-publish for git deployment. WRITING ONLY -- it does not deploy; snappy-publish owns git and Vercel. NOT for long-form aimed anywhere other than snappy.ai/blog (see article). Triggers on: write blog post, snappy blog, create blog post, new blog article, blog for snappy, write an article, blog draft, draft blog, opinion piece for snappy, mdx blog post, snappy.ai blog, blog post about, write a post for the website.",
  managed: false,
  requires: [] as string[],
  refusals: refusalTable("unknown_verb", "missing_argument", "not_found"),
  verbs: {
    list: {
      args: [], flags: { limit: "--limit" }, effect: "read",
      class: "read", execution: "call", openWorld: false,
      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false },
      inputSchema: { properties: {
        limit: limitSchema(200, "How many posts to return, newest first"),
      } },
    },
    validate: {
      args: ["path"], effect: "read",
      class: "read", execution: "call", openWorld: false,
      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false },
      inputSchema: { properties: { path: { type: "string", description: "Path to the MDX post whose frontmatter is checked" } } },
    },
  },
} as const;

if (import.meta.url === `file://${realpathSync(process.argv[1])}` && process.argv[2] === "contract") {
  console.log(JSON.stringify(HAND_CONTRACT, null, 2));
  process.exit(0);
}


if (import.meta.url === `file://${realpathSync(process.argv[1])}`) {
  (async () => {
    const [, , cmd, ...args] = process.argv;

    switch (cmd) {
      case "list": {
        const bound = takeLimit(args, { maximum: 200 });
        if (bound.refusal) { console.log(JSON.stringify(bound.refusal, null, 2)); process.exit(1); }
        const all = listBlogPosts();
        const posts = boundRows(all, bound.limit);
        console.log(`${posts.length} of ${all.length} blog posts:`);
        for (const p of posts) {
          console.log(`  ${p.date}\t${p.slug}\t${p.category}\t${p.featured ? "FEATURED" : ""}`);
        }
        break;
      }
      case "validate": {
        const [path] = args;
        if (!path) { console.error("Usage: api.ts validate <path>"); process.exit(1); }
        const absPath = path.startsWith("/") ? path : join(BLOG_DIR, path);
        const content = readFileSync(absPath, "utf-8");
        const result = validateFrontmatter(content);
        console.log(`Valid: ${result.valid}`);
        for (const e of result.errors) console.log(`  ERROR: ${e}`);
        for (const w of result.warnings) console.log(`  WARN: ${w}`);
        break;
      }
      default:
        console.log("Usage: npx tsx api.ts [list|validate] ...");
    }
  })();
}

import { test } from "node:test";
import assert from "node:assert/strict";
import { HAND_CONTRACT } from "./api.ts";
import { REFUSAL_CODES, type RefusalCode } from "../snappy-settings/refusal-codes.ts";

/** RULE 33 COVERAGE, AGAINST THE ONE CLOSED TABLE ⟨lane r30, 2026-09-09⟩.
 *  This file used to restate a refusal row's own properties — that it has a
 *  `contract_slice`, that it has a `fix`, that it leaks no token — once per
 *  hand, 48 times, over rows that all come from the SAME object. Forty-eight
 *  copies of one check is the duplicate road the closed table exists to end:
 *  `snappy-settings/refusal-codes.test.ts` runs those checks ONCE over every
 *  row, and the second test below proves this hand carries THE ROW ITSELF and
 *  not a copy — an identity a drifted duplicate cannot fake. Before this, each
 *  hand hand-wrote its own row, and the wording had already drifted: the
 *  inline `unknown_verb` said "Call one of the verbs named in
 *  HAND_CONTRACT.verbs" while the closed table says "Call one of the verbs the
 *  contract declares; the refusal lists them."
 *
 *  DECLARED stays a literal list, deliberately. It is this hand's coverage
 *  manifest and it is what rule 33's lint reads out of the test SOURCE to ask
 *  "did a person look at this code" — deriving it from Object.keys would make
 *  the test pass for a hand with no refusals at all. `satisfies readonly
 *  RefusalCode[]` makes the compiler refuse a name the one table does not
 *  have. It NAMES codes; it no longer DEFINES them. */
const DECLARED = [
  "unknown_verb",
  "missing_argument",
  "not_found",
] as const satisfies readonly RefusalCode[];

test("snappy-blog: the refusal table declares exactly the codes this test names", () => {
  assert.deepEqual(Object.keys(HAND_CONTRACT.refusals ?? {}).sort(), [...DECLARED].sort());
});

test("snappy-blog: every declared refusal is the one closed table's own row, never a copy", () => {
  const declared = Object.entries(HAND_CONTRACT.refusals ?? {});
  assert.ok(declared.length > 0, "HAND_CONTRACT.refusals is empty");
  for (const [code, row] of declared) {
    assert.ok(code in REFUSAL_CODES, `${code} is not a row of snappy-settings/refusal-codes.ts`);
    assert.equal(row, REFUSAL_CODES[code as RefusalCode], `${code} is a copy of the closed table's row, not the row itself`);
  }
});

{
  "providers": [
    {
      "name": "posts",
      "label": "blog post",
      "description": "all blog posts in content/blog",
      "fetch": "npx tsx ~/.claude/skills/snappy-blog/api.ts list | python3 -c \"import sys,json,re; rows=[]; \nfor line in sys.stdin:\n  s=line.strip()\n  if not s or 'blog posts' in s: continue\n  parts=re.split(r'\\s+',s,3)\n  if len(parts)>=3:\n    feat=' FEATURED' if 'FEATURED' in (parts[3] if len(parts)>3 else '') else ''\n    rows.append({'id':parts[1],'name':parts[1],'description':(parts[0] + ' · ' + parts[2] + feat)})\nprint(json.dumps(rows))\"",
      "fields": { "id": "id", "label": "name", "description": "description" },
      "verbs": [
        { "name": "validate", "label": "validate frontmatter", "description": "lint MDX frontmatter", "fire": "cat content/blog/{id}.mdx | npx tsx ~/.claude/skills/snappy-blog/api.ts validate" }
      ]
    }
  ]
}