Engineering Blog Skill

.claude/skills/eng-blog/ — workflow reference

Takes raw engineer rambles — voice transcripts, Slack threads, meeting notes — and produces polished engineering blog posts published to Notion. Diagrams generated via Nano Banana 2. Trigger with /eng-blog or any subcommand.

      graph TD
        IN["Raw Input
voice / transcript / slack"] --> ING["1. Ingest"] ING --> SPL{"Multiple
topics?"} SPL -->|Yes| SPLIT["2. Split
into separate posts"] SPL -->|No| OUT_REF SPLIT --> OUT_REF["3a. Reference Selection
pick 3 best-fit articles from 8"] OUT_REF --> OUT_R["3b. Outline Generation
3 agents × 3 lenses × 3 outlines"] OUT_R --> OUT_S["3c. Score + Mashup
rank 9 → pick best + create hybrid"] OUT_S --> OUT_C{"User
approves?"} OUT_C -->|Yes| DRF["4. Draft
voice rules + anti-slop"] OUT_C -->|"No — show backups"| OUT_ALT["Show backup
outlines"] OUT_ALT --> OUT_C DRF --> DIA["5. Diagrams
Nano Banana 2"] DIA --> REV["6. Review
6-dim rubric + scorecard"] REV --> PASS{"Score >= 3.5?"} PASS -->|Yes| SEO["7. SEO Brief
Ahrefs keywords + metadata"] PASS -->|No| FAIL{"Anti-slop
3+ fails?"} FAIL -->|Yes| DRF FAIL -->|No| REV SEO --> ASM["8. Assemble & Share
HTML review page + Cloudflare"] SEO -.->|"skip SEO"| ASM ASM --> CF[("Cloudflare Pages")] ASM --> REVISE["9. Revise
process team comments"] REVISE --> REVCHK{"3+ changes?"} REVCHK -->|Yes| REV REVCHK -->|No| PUB["10. Publish
to Notion"] PUB --> BLOG[("Blog Drafts DB")] ING -.-> IDEAS[("Idea Tracker DB")] classDef inputNode fill:#0d737722,stroke:#0d7377,stroke-width:2px classDef splitNode fill:#b5761422,stroke:#b57614,stroke-width:2px classDef outlineNode fill:#2563eb22,stroke:#2563eb,stroke-width:2px classDef draftNode fill:#1e3a5f22,stroke:#1e3a5f,stroke-width:2px classDef diagramNode fill:#7c4dbd22,stroke:#7c4dbd,stroke-width:2px classDef reviewNode fill:#be123c22,stroke:#be123c,stroke-width:2px classDef seoNode fill:#d9770622,stroke:#d97706,stroke-width:2px classDef assembleNode fill:#6366f122,stroke:#6366f1,stroke-width:2px classDef reviseNode fill:#ea580c22,stroke:#ea580c,stroke-width:2px classDef publishNode fill:#05966922,stroke:#059669,stroke-width:2px classDef dbNode fill:#78716c22,stroke:#78716c,stroke-width:2px classDef decisionNode fill:#b5761411,stroke:#b5761488,stroke-width:1px class IN inputNode class ING inputNode class SPL,PASS,FAIL,OUT_C,REVCHK decisionNode class SPLIT splitNode class OUT_REF,OUT_R,OUT_S,OUT_ALT outlineNode class DRF draftNode class DIA diagramNode class REV reviewNode class SEO seoNode class ASM assembleNode class REVISE reviseNode class PUB publishNode class BLOG,IDEAS,CF dbNode
Ingest
Split / Decision
Outline
Draft
Diagrams
Review
SEO
Assemble
Revise
Publish
Notion DB

Pipeline Phases

1
Ingest
/eng-blog ingest
  • Accept voice transcript, pasted text, Slack thread, or meeting notes
  • Identify the engineer(s) by name
  • Extract: problem, what was tried (including dead ends), solution, real numbers, code snippets
  • Save raw transcript for Notion toggle block
lindy-voice.md transcribe_audio.py
2
Split
auto — during ingest

If the ramble covers multiple distinct topics, split into separate posts. Each topic gets its own draft pipeline. The user picks which to draft first.

phases/split.md
3
Outline
auto — after split
  • 3a. Reference: 1 agent picks the 3 most relevant articles from the 8-blog reference pool
  • 3b. Generate: 3 parallel agents with distinct lenses (narrative, technical, contrarian) — each proposes 3 outlines with a drafted first paragraph (9 total)
  • 3c. Score + Mashup: 1 agent ranks all 9, picks winner, creates a 10th hybrid outline
  • User checkpoint: approve winner or browse 3 backups (2 runners-up + 1 mashup)
style-patterns.md phases/outline.md
4
Draft
/eng-blog draft
  • Structure: hook → problem → journey (with dead ends) → solution → what's next
  • Real code blocks, real numbers, engineer names
  • Mark diagram opportunities with [DIAGRAM: ...]
  • End with what's unsolved, not a tidy conclusion
lindy-voice.md notion-schema.md ai-slop-patterns.md
5
Diagrams
auto — after draft
  • Generate via Nano Banana 2 (Gemini 3.1 Flash Image)
  • Architecture diagrams, flowcharts, sequence diagrams
  • 2 variations per diagram, reviewer picks
  • Every diagram must communicate something prose can't
generate_diagram.py phases/diagrams.md
6
Review
/eng-blog review
  • Score against 6-dimension rubric (weighted avg)
  • Pass threshold: weighted score ≥ 3.5/5
  • If hook < 4: generate 2 alternative hooks
  • If any dimension scores 1: auto-fail
  • Run anti-slop gate — 3+ fails = rewrite from scratch
review-rubric.md lindy-voice.md ai-slop-patterns.md
7
SEO Brief
/eng-blog seo
  • Ahrefs keyword research (3 API calls: overview, related terms, SERP)
  • Meta title (differs from H1) + meta description + URL slug
  • Schema markup (TechArticle JSON-LD) + Open Graph tags
  • Diagram alt text (keyword-aware, 125 chars max)
  • SEO confidence score (High / Medium / Low)
  • Never modifies the draft — metadata layer only
phases/seo.md seo-guidelines.md
8
Assemble & Share
/eng-blog share
  • Build HTML review page via build script + template
  • Embed diagrams as base64, scorecard, outlines, transcript, SEO brief
  • Inline KV commenting system (Google Docs-style highlights)
  • Deploy to Cloudflare Pages + verify with curl retry
  • Shareable URL for team review
phases/assemble.md review-page.html
9
Revise
/eng-blog revise
  • Fetch comments from KV worker API
  • Classify: actionable, questions, praise, already-addressed
  • Version draft before editing (draft-v1.md, draft-v2.md, etc.)
  • Reply to each commenter via API
  • If 3+ changes: re-run Review + redeploy
phases/revise.md fetch_comments.py
10
Publish
/eng-blog publish
  • Create page in Blog Drafts DB via Notion MCP
  • Include: callout, blog content, collapsed transcript, scorecard, SEO brief
  • Set status to "Draft" for engineer review
  • Update Idea Tracker entry to "In progress"
notion-schema.md phases/publish.md

Notion Databases

Blog Drafts DB
9804fd452a994510959330f6fe6e0b91
Draft In Review Approved Published
Idea Tracker DB
30c20490ab1880a2aa3cfbbfe0d2ffe6
Idea In progress Published Killed

Guardrails

Applied to every draft
Voice
"We" for team, name individual engineers. Casual but not sloppy. Real code, real configs, real error messages. Show dead ends. End with what's unsolved.
Anti-Slop
Never: delve groundbreaking revolutionary game-changing unprecedented. Replace leverage with "use". No sandwich structure or zoom-out conclusions.
Numbers
"40ms to 2ms" not "significantly faster". Real metrics, timestamps, tool names. Every claim backed by a specific data point.
No Marketing
Eng-to-eng, not a press release. No "we're excited to announce". No "harness the power" or "unlock the potential". Just say what happened.