From d7d788497c68370bba6246cdd635f46c153609d9 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 6 Feb 2026 22:56:33 +0000 Subject: [PATCH] Add blog post authoring skill to website Interactive blog post authoring skill with structured Q&A that produces draft blog post files with inline guidance comments. Supports three formats: pyramid principle, best sales deck, and release post. Includes: - /blog-planner command to initiate outline authoring - /blog-image-brief command for header image generation prompts - /blog-review command to review prosed-up posts - Format references for pyramid principle, best sales deck, release post https://claude.ai/code/session_01AhRy1tUkjNrMkXNg4aM1xB --- .gitignore | 1 + website/.claude/commands/blog-image-brief.md | 198 ++++++++++++++ website/.claude/commands/blog-planner.md | 32 +++ website/.claude/commands/blog-review.md | 235 ++++++++++++++++ website/.claude/skills/blog-planner/SKILL.md | 256 ++++++++++++++++++ .../references/best-sales-deck.md | 124 +++++++++ .../references/pyramid-principle.md | 141 ++++++++++ .../blog-planner/references/release-post.md | 89 ++++++ 8 files changed, 1076 insertions(+) create mode 100644 website/.claude/commands/blog-image-brief.md create mode 100644 website/.claude/commands/blog-planner.md create mode 100644 website/.claude/commands/blog-review.md create mode 100644 website/.claude/skills/blog-planner/SKILL.md create mode 100644 website/.claude/skills/blog-planner/references/best-sales-deck.md create mode 100644 website/.claude/skills/blog-planner/references/pyramid-principle.md create mode 100644 website/.claude/skills/blog-planner/references/release-post.md diff --git a/.gitignore b/.gitignore index 75f390eaf5..0ba042a9be 100644 --- a/.gitignore +++ b/.gitignore @@ -27,3 +27,4 @@ sst-*.log **/coverage response.tmp .claude +!website/.claude/ diff --git a/website/.claude/commands/blog-image-brief.md b/website/.claude/commands/blog-image-brief.md new file mode 100644 index 0000000000..2215f27b06 --- /dev/null +++ b/website/.claude/commands/blog-image-brief.md @@ -0,0 +1,198 @@ +# Blog Image Brief + +Generate a detailed image brief and ChatGPT DALL-E prompt for a blog +post header image. Collaborates with the author to develop visual +metaphors, analyses reference images for style, and produces +ready-to-use generation prompts. + +## Process + +### Step 1: Gather context + +- What is the blog post about? (Read the outline if one exists) +- What is the core argument or thesis? +- What are the key concepts, products, or technologies involved? +- What feeling should the reader get from the image? + +### Step 2: Develop visual metaphors + +This is the creative core of the brief. The goal is to find a visual +concept that captures the *idea* of the post, not a literal +illustration of the subject matter. + +Work iteratively with the author. Ask questions, build on their ideas, +help them think through combinations. Don't generate a list cold — +draw the concepts out of the conversation. + +**Questions to explore:** +- What are the 2-3 core concepts this post is about? +- Are there concrete objects or scenes that represent these concepts? +- Is there a relationship between concepts that could be a scene? +- Can brand elements (Electric elephant/lightning bolt, product icons, + product colours) become characters or objects in the scene? +- Is there a surprising or playful angle? +- What existing header images does the author like? What works about them? + +**Examples of good visual metaphors from Electric posts:** +- "Durable sessions for collaborative AI" → robots collaborating to + wrap a skyscraper in threads (collaboration + enterprise + durability) +- "Super-fast apps on sync" → an electric elephant in a racing car + by a TanStack palm tree (speed + Electric brand + TanStack brand) + +**What makes a good visual metaphor:** +- Captures the *feeling* or *relationship*, not the literal subject +- Works at thumbnail size — the concept is readable even when small +- Surprising or playful enough to catch the eye in a blog listing +- Doesn't require reading the title to make sense as an image +- Makes sense *in combination with* the title — the image is always + displayed next to the title, so they should work as a pair +- Can incorporate brand elements naturally, not as forced logos + +**What to avoid:** +- **Text in the image** — unless 100% required by the concept, there + must be no text. The title is overlaid by the website layout +- Generic tech imagery (circuit boards, abstract networks, code on + screens) +- Literal illustrations of the product UI +- Images that only make sense after reading the post +- Overloaded scenes with too many concepts competing + +**Goal:** Through conversation, shortlist 3 candidate concepts. Each +described as a one-sentence scene with a note on what it conveys. + +### Step 3: Collect reference images + +Once the 3 concepts are shortlisted, ask the author for 2-5 reference +images they like the *style* of (separate from concept). These can be: +- Existing Electric blog header images +- Images from other blogs or sites +- Screenshots, photos, illustrations — anything that captures the vibe + +For each reference image, analyse and note: +- Colour palette and dominant tones +- Composition style (centered, asymmetric, geometric, organic) +- Level of abstraction (photographic, illustrative, diagrammatic, + abstract) +- Rendering style (3D rendered, flat illustration, painterly, + photorealistic, low-poly, isometric) +- Mood (technical, warm, dramatic, minimal, playful) +- Use of lighting and depth +- How well it would crop at different aspect ratios + +### Step 4: Synthesise the style direction + +Identify common threads across the reference images. Present a summary: + +- **Visual style**: e.g. "3D rendered, soft lighting, slightly playful" +- **Colour direction**: e.g. "dark background, purple/cyan accents" +- **Composition**: e.g. "centered subject with breathing room for crop" +- **Mood**: e.g. "technical but not cold, confident, a touch of whimsy" +- **Rendering**: e.g. "clean 3D, not photorealistic — stylised" + +Get confirmation or adjustments. + +### Step 5: Generate the output + +Produce one shared prompt covering technical requirements, style, and +brand context, plus three separate concept variants the author can +each copy-paste into ChatGPT independently. + +**Output format:** + +``` +## Shared prompt (paste this first, then add one concept below) + +Create a blog header image, 1536 x 950 pixels, 16:9 aspect ratio. + +Style: [Rendering style, level of detail, lighting — from step 4.] + +Colour palette: Dark background required. Use these brand colours +as accents: +- #D0BCFF (Electric purple — primary brand) +- #00d2a0 (Electric green) +- #75fbfd (Durable Streams cyan) +- #F6F95C (PGlite yellow) +- #FF8C3B (TanStack DB orange) +[Specific colour direction from step 4.] + +Composition: Key content must be centered within the inner 70% of +the frame to survive responsive cropping at different aspect ratios. +Breathing room on all edges. [Specific composition notes.] + +Mood: [From step 4.] + +CRITICAL: No text in the image unless absolutely required by the +concept. Dark background. The image will be displayed alongside the +post title — they should work as a pair. Keep the upper area +relatively clean as the website may overlay elements. Master as +high-quality JPG. + +--- + +## Concept A: [one-line label] + +Concept: [Full scene description — what's in the image, what the +elements represent, how they relate to each other. Be specific +about characters, objects, actions, spatial relationships.] + +Brand elements: [Which product mascots, icons, or colour associations +to include and how they appear in the scene.] + +--- + +## Concept B: [one-line label] + +Concept: [...] + +Brand elements: [...] + +--- + +## Concept C: [one-line label] + +Concept: [...] + +Brand elements: [...] +``` + +### Step 6: Iterate + +The author generates images from the concepts, comes back with +feedback. Refine the prompt based on what worked and what didn't. + +## Brand reference + +**Colours:** +- `#D0BCFF` — Electric purple (primary brand, logo) +- `#00d2a0` — Electric green +- `#75fbfd` — Durable Streams cyan +- `#F6F95C` — PGlite yellow +- `#FF8C3B` — TanStack DB orange +- `#7c40ff` — CTA purple + +**Assets:** +- Lightning bolt logo: `website/public/img/brand/icon.svg` +- Full logo: `website/public/img/brand/logo.svg` +- Product icons: `website/public/img/icons/` + - `electric.svg` — Postgres Sync + - `durable-streams.svg` — Durable Streams + - `pglite.svg` / `pglite.product.svg` — PGlite + - `tanstack.svg` — TanStack DB + +**Site context:** +- Dark theme forced (always dark mode) +- Font: OpenSauceOne +- Header images served via Netlify image proxy with compression +- OG/social crop: 1200 x 630px center-center fit=cover +- Blog listing: responsive center-center crop + +## Image requirements checklist + +- [ ] Aspect ratio: 16:9 to 16:10 (~1536 x 950px) +- [ ] High-quality JPG +- [ ] Dark background +- [ ] No text in image (unless 100% required by concept) +- [ ] Key content in inner ~70% frame (survives responsive crop) +- [ ] Works at thumbnail size in blog listing +- [ ] Brand colours used as accents, not overwhelming +- [ ] Saved to `website/public/img/blog//header.jpg` diff --git a/website/.claude/commands/blog-planner.md b/website/.claude/commands/blog-planner.md new file mode 100644 index 0000000000..683470f8d3 --- /dev/null +++ b/website/.claude/commands/blog-planner.md @@ -0,0 +1,32 @@ +# Blog Planner + +Interactive blog post authoring for the Electric blog. Walks through +structured Q&A to produce a draft blog post file with outline, inline +guidance comments, and meta briefs that the author proses up in place. + +## Instructions + +Follow the authoring flow defined in the blog-planner skill +(`website/.claude/skills/blog-planner/SKILL.md`). Work through all +phases in order: + +1. **Intake** — Understand the raw idea, identify the author, read any + existing material +2. **Sharpen intent** — Nail down what the post is about, why it matters, + reader takeaway, CTAs, and authority +3. **Choose format** — Recommend and confirm one of: Pyramid Principle, + Best Sales Deck, or Release Post +4. **Draft the outline** — Section-level outline per the chosen format, + with inline HTML comments for structural guidance +5. **Ethos / creative angle** — For pyramid and sales deck formats, + draw out the author's personal angle +6. **Evaluate** — Check the outline delivers on the intent +7. **Fill in the meta** — Title brief, description brief, excerpt brief, + image prompt, open questions +8. **Gather assets** — Inventory code samples, diagrams, demos, screenshots +9. **Write the file** — Save to `website/blog/posts/YYYY-MM-DD-slug.md` + with `published: false` + +Ask one question at a time. Be direct and useful. + +$ARGUMENTS diff --git a/website/.claude/commands/blog-review.md b/website/.claude/commands/blog-review.md new file mode 100644 index 0000000000..e4287d8c33 --- /dev/null +++ b/website/.claude/commands/blog-review.md @@ -0,0 +1,235 @@ +# Blog Review + +Review a prosed-up blog post against its outline, chosen format, and +execution guidelines. Run this after the author has expanded the outline +into full prose. + +## Invocation + +``` +/blog-review [optional: path-to-original-outline] +``` + +If an original outline exists (the version before prose-up with the +commented meta footer intact), read it for reference. Otherwise review +the post on its own merits. + +## Review process + +### Step 1: Read the post and context + +- Read the blog post +- If an outline exists, read it and note the intended format, + intent, and evaluation criteria +- Identify the format (pyramid principle, best sales deck, release post) + from the meta footer or from the structure + +### Step 2: Identify the core editorial questions + +Before launching into detailed review, answer these four questions. +They are the primary frame for the entire review — everything else +is in service of them. + +**1. Does the post have a clear point?** + +Can you state the takeaway in one sentence — like a hashtag, elevator +pitch, or tweet? If you can't, the post doesn't have a clear enough +point yet. This is not the same as the topic. The topic is what the +post is *about*; the point is what the post *says*. A post about +"local-first sync" might have the point "sync makes apps feel instant +because reads never wait on the network." If the point is fuzzy, +nothing else in the review matters until it's fixed. + +Test: write a single sentence summary. If it takes more than one +sentence, or if you have to use "and" to join two different ideas, +the point isn't sharp enough. + +**2. Does the post have clear CTAs?** + +After reading, does the reader know exactly what to do next? CTAs +should be: +- Specific (not "check out the docs" — which docs? for what?) +- Earned by the content (the CTA follows naturally from what was argued) +- Appropriately ambitious (a thought leadership piece earns a + "rethink how you build X" CTA; a release post earns a + "try it now" CTA) +- Present both at the end *and* where relevant inline (e.g. a code + example that links to the getting started guide) + +Flag posts where the CTAs feel bolted-on, generic, or disconnected +from the argument. + +**3. Are the title, excerpt, content, and image coherent?** + +These four elements are always displayed together (in blog listings, +social cards, RSS). They must tell the same story: +- Does the title promise what the content delivers? +- Does the excerpt accurately represent the post's point (from Q1)? +- Would the image make sense next to this title in a blog listing? +- If you read only the title + excerpt, would you have the right + expectation for what's inside? + +Flag any mismatch: a title that oversells, an excerpt that describes +a different post, an image concept that doesn't relate to the content, +or a description optimized for SEO keywords that don't match the +actual argument. + +**4. Are there dissonant tonal elements or gaps in the argument?** + +Read the post as a skeptical but fair reader: +- Does the tone shift unexpectedly? (e.g. technical and precise in + one section, then hand-wavy marketing in the next) +- Are there logical gaps where the argument skips a step? +- Are there claims that aren't supported or examples that don't + land? +- Does the post assume knowledge it hasn't established? +- Is there a section that feels like it belongs in a different post? +- Does the creative angle / ethos element feel authentic or forced? + +These are the "something feels off" issues that readers sense but +can't always articulate. Name them specifically. + +### Step 3: Launch review agents + +Run the following review agents in parallel. Each agent should +address the core questions above within its domain, in addition +to the specific checks listed. + +**Agent 1: Structure and format** + +*Core question focus:* Does the structure serve the point (Q1)? +Does the argument hold without gaps (Q4)? + +- Does the post follow the chosen format's structure? +- Does the TLDR opener deliver the point immediately? +- Do the sections flow logically? +- Does the post deliver on the stated intent? +- For pyramid: does the SCQA logic hold? Does the expansion + follow from the answer? Are there gaps where the logic + skips a step? +- For best sales deck: is the big change undeniable? Does the + promised land describe outcomes not features? Do gifts deliver + on the promised land or is there a gap? +- For release: can the reader understand what shipped in 30 seconds? + Can they get started immediately? +- Is there a single clear takeaway, or does the post try to make + multiple points? (Report finding for Q1) +- Do the CTAs follow from the argument or feel disconnected? + (Report finding for Q2) + +**Agent 2: Writing quality and tone** + +*Core question focus:* Is the tone consistent throughout (Q4)? +Does the prose deliver the point clearly (Q1)? + +- Is the prose clear, direct, and specific? +- Are bullets expanded naturally or does it read like inflated + bullet points? +- Is there unnecessary preamble or throat-clearing? +- LLM tells: flag any instances of "it's worth noting", + "importantly", "in conclusion", "let's dive in", "at its core", + "in today's landscape", "let's explore", "in the world of", + "when it comes to", "it's important to note" +- Banned words: flag "robust", "scalable", "flexible", "leverage", + "ecosystem", "game-changing", "revolutionary", "seamlessly", + "holistic", "synergy" +- Is the tone consistent across sections? Flag any shifts — e.g. + technical precision giving way to vague marketing, or confident + assertions followed by unnecessary hedging (Report finding for Q4) +- Does the ethos / creative angle land or feel forced? +- Could you summarize the post's point in a single hashtag-length + phrase? If the prose makes this hard, the point is getting lost + in the writing (Report finding for Q1) + +**Agent 3: Packaging and execution** + +*Core question focus:* Are title, excerpt, content, and image +coherent (Q3)? Are CTAs specific and earned (Q2)? + +- **Coherence check (Q3):** + - Read title, description, excerpt, and image path/brief together + - Do they all describe the same post? + - Does the title promise what the content delivers? + - Does the excerpt capture the point (not just the topic)? + - Is the image concept aligned with the title and content? + - Would title + excerpt set the right expectation in a blog + listing or social card? +- **CTA check (Q2):** + - Is there a clear next-steps / CTA section? + - Are CTAs specific? ("Read the getting started guide" not + "check out the docs") + - Do CTAs appear inline where natural, not just at the end? + - Are the CTAs earned by the content that precedes them? +- Typesetting: + - Non-breaking spaces (` `) used where appropriate to + avoid widows and orphans? + - Non-breaking hyphens used in compound terms that shouldn't break? + - Can use Unicode literal `\u00A0` in frontmatter title + - HTML entities in body text +- Title: uses sentence case, not Title Case? +- Frontmatter complete? (title, description, excerpt, authors, + image, tags, outline, post: true) +- Description: no HTML, suitable for SEO meta tags? +- Excerpt: max 3 short sentences, consistent word length with + other posts on the blog? +- Image: path exists or is clearly marked as TODO? + Aspect ratio guidance followed? +- Code samples: correct language hints, runnable, well-formatted? +- Links: all internal links use root-relative paths? + External links valid? +- Assets: all asset placeholders from the outline resolved? +- `published: false` still set (or intentionally flipped)? +- Check how title and opening will look at mobile widths — + flag overly long titles + +### Step 4: Synthesise findings + +Combine agent findings. Structure the synthesis around the four +core questions first, then detail issues by severity. + +**Core assessment** (2-3 sentences): +- State the post's point as you understand it (Q1). If you can't + state it crisply, that's the first finding. +- Note whether title/excerpt/content/image are aligned (Q3). +- Note the overall quality: ready to publish, needs a revision + pass, or needs structural work. + +**Issues by category:** + +*Must fix* — Factual errors, broken structure, missing sections, +LLM tells, incomplete frontmatter, unclear point (Q1), missing +or generic CTAs (Q2), title/content mismatch (Q3), logical gaps +in the argument (Q4) + +*Should fix* — Weak sections, unclear prose, typesetting issues, +tone inconsistencies (Q4), CTAs that could be more specific (Q2), +excerpt that doesn't capture the point (Q3) + +*Consider* — Suggestions for strengthening specific sections, +alternative framings, missing opportunities + +### Step 5: Present review + +Present the review to the author with: +- The core assessment (2-3 sentences) +- The post's point stated back as a single sentence — the author + can confirm or correct this, which often clarifies everything +- Issues grouped by category (must fix / should fix / consider) +- Specific line references where possible +- For each issue: what's wrong and a concrete suggestion for fixing it + +Don't nitpick. Focus on things that materially affect the reader's +experience or the post's effectiveness. The four core questions +take priority over checklist items. + +## Comparison with outline + +If the original outline is available, also check: +- Does the final post deliver on the intent stated in the outline's + meta footer? +- Were all planned sections covered? +- Were all assets from the asset checklist included? +- Does the creative angle / ethos element survive the prose-up? +- Any sections that were strong in the outline but weakened in prose? +- Is the point sharper or fuzzier than in the outline? +- Are the CTAs the same ones planned, or did they drift? diff --git a/website/.claude/skills/blog-planner/SKILL.md b/website/.claude/skills/blog-planner/SKILL.md new file mode 100644 index 0000000000..0ede1db570 --- /dev/null +++ b/website/.claude/skills/blog-planner/SKILL.md @@ -0,0 +1,256 @@ +--- +name: blog-planner +description: > + Interactive blog post authoring. Produces a draft blog post file + with structured outline, inline guidance comments, and meta briefs that + the author proses up in place. Supports pyramid principle, best sales deck, + and release post formats. +--- + +# Blog Planner + +Plan and outline blog posts for the Electric blog. The output is a draft +markdown file placed directly in `website/blog/posts/` with +`published: false`. The author works through the outline in place, expanding +compressed bullets into prose and swapping in assets. + +## Invocation + +``` +/blog-planner [optional: path to existing draft or reference material] +``` + +If the user provides a path to existing material (drafts, docs, PRDs, notes), +read it for context and content. Understand what it contains but do not +over-index on its structure — the outline's structure comes from the chosen +format, not the source material. + +## Authoring flow + +Work through these phases in order. Ask one question at a time. Be clear, +honest, and useful. Don't gamify the questioning or perform — add value +and get out of the author's way. + +### Phase 1: Intake + +Understand the raw idea. + +- What is the post about? +- Who is the author? (Use author keys from the Electric blog: `thruflo`, + `kyle`, `samwillis`, `icehaunter`, `balegas`, `oleksii`, `purva`) +- Is there existing material to reference? (Drafts, PRDs, RFCs, demos, + PRs, docs.) If so, read it now. + +### Phase 2: Sharpen intent + +Nail down why this post deserves to exist. Push until each answer is crisp. + +- **What is this post about?** — One sentence. +- **What's interesting about it?** — Why would the reader care? What's the hook? +- **What's the reader takeaway?** — After reading, what does the reader know + or believe that they didn't before? +- **What are the CTAs / next steps?** — What should the reader do after reading? +- **Why are we / the author the right people to write this?** — What authority + or experience makes this credible? + +These answers form the Intent block in the output file's meta section. + +### Phase 3: Choose format + +Based on the intent, recommend one of the three formats and confirm with +the author. If the author picks a format, use that format — don't second-guess. + +| Format | When to use | +|--------|-------------| +| **Pyramid Principle** | You have a clear point to make and need to build a logical argument. Good for technical explanations, "how we built X", opinion pieces with substance. | +| **Best Sales Deck** | You're introducing a concept or paradigm shift. A narrative flow that names a big change in the world, shows winners and losers, teases the promised land, and introduces the solution. Good for product launches that represent a category shift, thought leadership. | +| **Release Post** | You shipped something. Communicate it clearly. The workhorse format for incremental releases and new features. Always be shipping. | + +Once confirmed, load the corresponding reference file from `references/`. + +### Phase 4: Draft the outline + +Produce the section-level outline per the chosen format. + +- Present the outline section by section for feedback +- Bullets are compressed meaning — each should expand to 1-2 sentences + of prose with minimal rewording +- Include inline HTML comments explaining what each section is doing + structurally and what tone/content the author should aim for +- Mark where assets will go with `` comments +- For pyramid principle and best sales deck: the TLDR + info box comes + before the format-specific structure +- Iterate until the author is satisfied with the structure and content + +**Writing style for outline bullets:** +- Compressed, direct, specific +- Each bullet carries one clear idea +- Bullets often combine into fresh prose because they are compressed + expressions of meaning — optimise for this +- Avoid: "robust", "scalable", "flexible", "leverage", "ecosystem", + "game-changing", "revolutionary" — say what you actually mean +- No LLM tells — no "it's worth noting", "importantly", "in conclusion", + "let's dive in", "at its core", "in today's landscape" + +### Phase 5: Ethos / creative angle + +For **pyramid principle** and **best sales deck** formats only. + +Draw out the author's personal angle: +- Is there a specific moment, experience, or anecdote that makes this real? +- Is there a creative framing that makes the setup more vivid? + +Weave this into the outline bullets for the Situation/Complication (pyramid) +or Big Change (best sales deck) sections. Annotate with comments explaining +how the creative element works structurally. This is done now, not left to +the author to figure out during prose-up. + +### Phase 6: Evaluate + +Assess whether the outline delivers on the intent from Phase 2. + +- Does the structure serve the point of the post? +- Does the logic hold? (Informal — does it hang together, not a PhD defence) +- Are there gaps or weak sections? +- Would the reader reach the intended takeaway by following the outline? +- Is the hook strong enough? + +Raise any issues and iterate with the author. + +### Phase 7: Fill in the meta + +Return to the footer meta section. Draft briefs for: + +- **Title brief** — Direction for the final title. Titles use sentence case, + not Title Case. +- **Description brief** — For SEO. No HTML. What should it convey? +- **Excerpt brief** — For the blog listing card. Max 3 short sentences. + Match word length of existing post excerpts for consistent listing display. +- **Image prompt** — See image brief guidelines below. If a detailed image + brief is needed, suggest the author use the `/blog-image-brief` command. +- **Open questions** — Anything unresolved. + +### Phase 8: Gather assets + +Now that the outline is solid, inventory the assets needed: + +- Code samples, diagrams (existing or to-be-created, mermaid or manual), + demo videos, screenshots, embedded tweets, external blog post links +- Map each asset to its location in the outline +- Note whether each asset exists or needs creating +- Record in the Asset checklist in the meta footer + +### Phase 9: Write the file + +Save the outline to `website/blog/posts/YYYY-MM-DD-slug.md`. + +- Use today's date for the filename prefix +- Derive the slug from the working title (kebab-case) +- Set `published: false` in frontmatter +- Use `...` placeholders for frontmatter fields that need finalising + (title, description, excerpt) — the briefs in the commented footer + guide the author on what to write + +## Output format + +The output is a real blog post file that the author works through in place. + +### Frontmatter + +```yaml +--- +title: '...' +description: >- + ... +excerpt: >- + ... +authors: [author-key] +image: /img/blog/slug/header.jpg +tags: [...] +outline: [2, 3] +post: true +published: false +--- +``` + +Use `...` for title, description, and excerpt. These get filled in by the +author using the briefs in the meta footer. Tags can be populated from +the intent discussion. + +### Body structure + +All formats follow this pattern: + +1. **TLDR opener** — 1-2 short paragraphs stating what this is and why it + matters. Compressed, no setup, no marketing tone. Technical audience + wants the point immediately. Followed by an info box with key links. +2. **Format-specific body** — Section structure per the chosen format + reference. Inline HTML comments guide the author on each section's + purpose and tone. +3. **Next steps** — CTAs, links, what to do now. +4. **`***` separator** +5. **Commented meta footer** — Intent, title brief, description brief, + excerpt brief, image prompt, asset checklist, open questions. + Prefixed with instruction to delete before publishing. + +### Inline comments + +Use HTML comments for: + +- **Structural guidance**: What this section is doing in the format's logic +- **Tone direction**: How the author should write this section +- **Asset markers**: `` where assets go +- **Author notes**: Specific instructions for expanding particular bullets + +Comments don't render in markdown and the author deletes them as they +prose up each section. + +## Typesetting guidelines + +Include these as a checklist in the meta footer: + +- Use non-breaking spaces (` ` in HTML, `\u00A0` in frontmatter) + and non-breaking hyphens where appropriate to avoid widows and orphans +- Titles MUST use sentence case, not Title Case +- Check title, image, and general post at different screen widths +- Avoid LLM tells: "it's worth noting", "importantly", "in conclusion", + "let's dive in", "at its core", "in today's landscape" + +## Reference blog posts + +Existing posts by Electric authors that exemplify good execution. Use these +to calibrate tone, structure, and quality. + +**Pyramid principle / narrative:** +- [Durable sessions for collaborative AI](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2026-01-12-durable-sessions-for-collaborative-ai.md) — thruflo +- [Bringing agents back down to earth](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-08-12-bringing-agents-back-down-to-earth.md) — thruflo +- [Building AI apps on sync](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-04-09-building-ai-apps-on-sync.md) — thruflo + +**Best sales deck / concept:** +- [Announcing Durable Streams](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-12-09-announcing-durable-streams.md) — kyle, samwillis +- [Super-fast apps on sync with TanStack DB](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-07-29-super-fast-apps-on-sync-with-tanstack-db.md) — thruflo + +**Release post:** +- [Electric 1.0 released](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-03-17-electricsql-1.0-released.md) — thruflo +- [Announcing Hosted Durable Streams](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2026-01-22-announcing-hosted-durable-streams.md) — kyle + +## Image brief (quick version) + +For a quick image direction, note in the meta footer: +- Subject/concept for the image +- Aspect ratio: 16:9 to 16:10 (target ~1536x950px) +- Master as high-quality JPG +- Center-center composition — key content in inner frame + (responsive cropping will cut edges) +- Brand colors: `#D0BCFF` (purple), `#00d2a0` (green), `#75fbfd` (cyan), + `#F6F95C` (yellow), `#FF8C3B` (orange) +- Dark theme background +- Site uses OpenSauceOne font + +For a detailed image brief with reference image analysis and a full +ChatGPT DALL-E prompt, use the `/blog-image-brief` command separately. + +## Review + +Once the author has prosed up the outline, use `/blog-review` to review +the draft against the outline, format, and execution guidelines. diff --git a/website/.claude/skills/blog-planner/references/best-sales-deck.md b/website/.claude/skills/blog-planner/references/best-sales-deck.md new file mode 100644 index 0000000000..6407c24af1 --- /dev/null +++ b/website/.claude/skills/blog-planner/references/best-sales-deck.md @@ -0,0 +1,124 @@ +# Best Sales Deck + +Based on Andy Raskin's "Greatest Sales Deck I've Ever Seen" framework: +name a big change, show winners and losers, tease the promised land, +deliver magic gifts. Adapted for technical blog posts — the structure +does the persuasion, the tone stays Ronseal straight. + +## When to use + +You're introducing a concept, pattern, or paradigm shift to a technical +audience. You want to sell an idea — not with marketing language but with +the logic of "the world changed, here's what that means, here's how to +be on the right side of it." + +Good for: product launches that represent a category shift, thought +leadership on emerging patterns, "why X matters now" concept pieces. + +## Reference examples + +- [Announcing Durable Streams](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-12-09-announcing-durable-streams.md) — kyle, samwillis +- [Super-fast apps on sync with TanStack DB](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-07-29-super-fast-apps-on-sync-with-tanstack-db.md) — thruflo + +## Structure + +The outline names each step of the narrative flow explicitly. The labels +are working structure — in the final prose they dissolve into section +headings that feel natural, not formulaic. + +``` +[TLDR + info box — standard, see SKILL.md] + +The big change: + +- Name an undeniable shift that's happening in the world +- This should be observable, not a claim — the reader can verify it +- Keep it factual and concrete, not hyperbolic +- This is NOT your product or company — it's the world changing + +Winners and losers: + +- This change creates stakes — show who benefits and who doesn't +- Make it concrete: "teams doing X ship in days, teams doing Y are + still gluing together retry logic" +- The reader should see themselves (or want to see themselves) + in the winners column + +The promised land: + +- Paint what life looks like on the right side of this shift +- Don't introduce the solution yet — describe the outcome +- This should feel desirable and specific, not utopian +- The reader should want this before knowing how to get it + +The magic gifts: + +- Now introduce the thing that gets you there +- Each gift is a specific capability, not a feature list item +- Frame as "this is what makes the promised land reachable" +- These become the ## headings for the body + +## Gift a + +- What it is, how it works, why it matters +- Evidence: benchmarks, code samples, demos + +## Gift b + +- ... + +## Gift c + +- ... + +*** + +Next steps: + +- CTAs, links, what to do now +``` + +## Ethos / creative angle + +Same as pyramid principle — the Big Change and Winners/Losers sections +should be enhanced with a specific story or moment drawn from the author. +The logic comes first, then the creative angle makes it land. + +The key difference from pyramid: here the anecdote grounds the *change*, +not the *shared reality*. It answers "how do I know this change is real?" +with lived experience rather than assertion. + +## Tone guidance + +- The structure is a sales deck. The tone is Ronseal +- The TLDR already gave the reader the punchline — the body gives them + the reasoning to believe it +- No: "revolutionary", "game-changing", "unlock the power of" +- Yes: specific numbers, concrete scenarios, "here's what this looks + like in practice" +- Technical audience respects being shown, not told +- The persuasion comes from the logic of the narrative arc, not from + the language used to express it + +## Key principles from Raskin's framework + +- **Start with change, not pain.** The big change is not "you have a + problem" — it's "the world shifted." This reframes the conversation + from selling to informing. +- **The promised land is not your product.** It's the outcome the reader + wants. The product is how you get there. Keep these separate. +- **Magic gifts earn the promised land.** Each gift should clearly connect + to the promised land. If a gift doesn't advance the reader toward + the outcome, cut it. +- **Show proof.** The framework works because each step builds credibility + for the next. The big change is verifiable. The winners/losers are + observable. The promised land is desirable. The gifts are demonstrable. + +## Evaluation criteria + +- Is the big change genuinely undeniable or are we asserting something + self-serving? +- Do the winners/losers feel real or is it a strawman? +- Does the promised land describe outcomes, not features? +- Do the magic gifts actually deliver the promised land or is there a gap? +- Would a skeptical engineer read this and nod, or roll their eyes? diff --git a/website/.claude/skills/blog-planner/references/pyramid-principle.md b/website/.claude/skills/blog-planner/references/pyramid-principle.md new file mode 100644 index 0000000000..2346836da3 --- /dev/null +++ b/website/.claude/skills/blog-planner/references/pyramid-principle.md @@ -0,0 +1,141 @@ +# Pyramid Principle + +Based on Barbara Minto's Pyramid Principle: Situation, Complication, Question, +Answer, expanded as a MECE pyramid. Adapted for technical blog posts with a +compressed, no-nonsense tone. + +## When to use + +You have a clear point to make and need to build a logical argument. The reader +should arrive at your conclusion feeling like they reached it themselves. + +Good for: technical explanations, "how we built X", opinion pieces with +substance, "why X matters" arguments. + +## Reference examples + +- [Durable sessions for collaborative AI](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2026-01-12-durable-sessions-for-collaborative-ai.md) — thruflo +- [Bringing agents back down to earth](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-08-12-bringing-agents-back-down-to-earth.md) — thruflo +- [Building AI apps on sync](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-04-09-building-ai-apps-on-sync.md) — thruflo + +## Structure + +The outline uses explicit SCQA labels as working structure. The Question is +often edited out or made implicit in the final prose. The Answer bullets +become the `##` headings for the body. + +``` +[TLDR + info box — standard, see SKILL.md] + +Situation: + +- Head-nodding statements the reader already believes +- Establish shared reality — no persuasion, just recognition +- 3-5 bullets. If the reader disagrees with any, the post isn't for them +- Every bullet should be so obvious it feels almost boring — that's the point + +Complication: + +- Introduce tension. Something changed, or something's broken +- The reader should feel "yes, that's my problem" +- This is the hook — if this doesn't land, they stop reading +- Keep it concrete: specific scenarios, not abstractions + +Question: + +- The question the complication naturally raises +- Stated explicitly in the outline as a working tool +- Often edited to be implicit in the final prose + +Answer: + +- a — first component of the answer +- b — second component +- c — third component +- These become the ## headings for the body +- Order by importance + +## a + +- Supporting argument / evidence / detail +- Sub-bullets become ### subsections where needed + +### Sub-point of a + +- ... + +## b + +- ... + +## c + +- ... + +*** + +Next steps: + +- CTAs, links, what to do now +``` + +## Ethos / creative angle + +The Situation and Complication should be enhanced with a specific anecdote, +moment, or creative framing drawn from the author during the outline +authoring process. This is not a separate section — it's woven into how +the S and C are expressed. + +The logic comes first (establish S and C as bullet points), then the +creative angle refines how they land. The author's personal experience +makes the shared reality vivid and earns the right to make the argument. + +Annotate the creative angle inline in the outline: + +``` +Situation: + +- Statement the reader agrees with +- Another shared reality point + + + +Complication: + +- But X is broken / has changed +- The reader recognises this tension +``` + +## MECE expansion + +The Answer bullets expand into the body of the post as a loosely MECE +(mutually exclusive, collectively exhaustive) pyramid: + +- Each Answer bullet becomes a `##` section +- Sub-arguments become `###` subsections where warranted +- Each section should stand alone — a reader who skips to one section + should still get value +- Assess the logic informally: does the expansion hang together and feel + complete? Are there overlapping sections or obvious gaps? +- This is a blog post, not a PhD thesis — the logic should be sound + but don't nitpick mutual exclusivity + +## Tone guidance + +- Situation bullets should be matter-of-fact, confident, no persuasion yet +- Complication should make the reader lean in — emotional, not just logical +- Answer should be direct and clear — state the thesis, don't hedge +- Expansion sections: show, don't tell. Code, examples, evidence +- Bullets are compressed meaning — expand each into 1-2 sentences with + minimal rewording. The compression often produces fresh prose naturally + +## Evaluation criteria + +- Does the situation establish genuine shared reality or is it hand-waving? +- Does the complication create real tension or is it manufactured? +- Does the answer actually resolve the complication? +- Do the expansion sections follow logically from the answer bullets? +- Would the reader reach the same conclusion if they followed the logic? +- Is the ethos / creative angle woven in or missing? diff --git a/website/.claude/skills/blog-planner/references/release-post.md b/website/.claude/skills/blog-planner/references/release-post.md new file mode 100644 index 0000000000..a2e9f28641 --- /dev/null +++ b/website/.claude/skills/blog-planner/references/release-post.md @@ -0,0 +1,89 @@ +# Release Post + +Ship often, communicate clearly, don't overthink it. The workhorse format +for incremental releases, new features, and point releases. + +## When to use + +You shipped something and want to tell people about it. This is the +keep-it-simple format for ticking-along releases. Bigger launches that +represent a category shift should use the Best Sales Deck format instead. + +## Reference examples + +- [Electric 1.0 released](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-03-17-electricsql-1.0-released.md) — thruflo +- [Announcing Hosted Durable Streams](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2026-01-22-announcing-hosted-durable-streams.md) — kyle + +## Structure + +No narrative arc needed. Lead with what shipped and why it matters. +The TLDR *is* the what and why — no separate setup section. + +``` +[TLDR — this IS the what and why. 1-2 paras: what shipped, + why it matters, key benefit. Info box with key links.] + +## Context + +- Brief orientation for readers not already tracking this +- 2-3 bullets max. If it needs more, link to a previous post +- Not a backstory — just enough to make the rest make sense + +## What's shipping + +- Concrete capabilities, numbers, facts +- Lead with benefits, follow with specifics +- Each bullet is a thing the reader can now do that they couldn't before + + + + + +## Get started + +- Code samples, commands, steps +- Show don't tell — the reader should be able to try it + +## Coming next + +- Brief roadmap tease. 2-3 bullets +- Keeps momentum, shows we're not stopping + +*** + +Next steps: + +- CTAs: docs, cloud signup, discord +``` + +## Tone guidance + +- Factual and brisk. This is a shipping cadence post, not an essay +- Dry is fine — let the content do the work +- Liven it up with: a good header image, video with poster frame, + embedded tweets, external blog post image tiles +- No preamble, no throat-clearing. The TLDR opens the post and + that's the pitch +- Celebrate shipping without overselling what shipped + +## Visual elements + +Release posts benefit from visual variety to break up what can +otherwise be a dry feature list: + +- Demo video with a poster frame +- Screenshots of new UI or output +- Embedded tweets showing community need or positive reactions +- External blog post tiles linking to deeper dives +- Code samples showing the new thing in action + +## Evaluation criteria + +- Can the reader understand what shipped and why they should care + in the first 30 seconds? +- Are benefits concrete or vague? +- Is there a visual element breaking up the text? +- Can the reader get started immediately from this post? +- Is the context section brief enough or is it becoming a backstory?