Technical Blog Post

Technical Blog Post from Raw Data

Overview

A process skill for turning raw project material into a structured technical blog post. Complements sams-voice (which handles tone and language): this skill handles structure and workflow.

REQUIRED: Always invoke sams-voice skill alongside this one. Voice = how it sounds. This skill = how it's organized.

When to Use

• Sam asks to write a blog post about a project
• Raw source material exists (research notes, session logs, drafts, code)
• The post is technical: "I built/decoded/reverse-engineered/automated X"

When NOT to Use

• Opinion pieces or commentary (no raw data to process)
• Short announcements (no structure needed)
• Non-technical content

Process

Phase 1: Gather

Find and read all source material in the project repo. Look for:

Key: Don't just read: extract the narrative arc. What was the problem? What failed? What worked? What was surprising?

Phase 2: Extract the Story

Pull out the six-beat narrative from the source material:

1. The hook: What's the one-sentence version? (e.g., "Five years of telemetry trapped in a proprietary format")
2. The problem: Why did this matter? What was at stake? What failed before?
3. The approach: How was it tackled? What was the methodology? What tools?
4. The discoveries: What were the key technical findings? Order by "aha moment", not chronology.
5. The validation: How was each discovery confirmed? Real numbers, cross-checks.
6. The result: What was delivered? Links, numbers, concrete output.

Phase 3: Write Using This Structure

---
title: "[Action verb]-ing [specific thing] [qualifier]"
pubDate: YYYY-MM-DD          # Use the actual project date, not today
description: "One sentence. Specific. Includes key technologies and outcome."
tags: ["relevant", "specific", "tags"]
draft: false
---

[HOOK: 1-2 sentences. Jump straight in. No "In today's..." opener.]

## [The problem / context section]

[2-3 paragraphs: what existed, what didn't work, why it mattered.
Include real specifics: dates, model names, circuit names, file sizes.]

## [The approach / methodology]

[How it was tackled. The human-AI split if relevant.
The loop: hypothesis > test > validate > next.]

## [Technical deep-dive]

[The meat. Structured by component/layer, not chronology.
Include:]
- ASCII struct diagrams
- Hex dump snippets with annotations
- Code blocks (keep short: 5-15 lines each)
- Real numbers from real data
- Cross-validation results

[Break into subsections with ### headers for each component.]

## [Validation]

[How each discovery was confirmed with real-world data.
Specific numbers: "<1% error", "exactly 9.81 m/s^2", etc.]

## [Result + what it means]

[Concrete deliverables. Links to repo, videos, docs.
Open questions if any remain.
What worked well, what needed human judgment.]

Phase 4: Voice Check

Before finalizing, run these checks (from sams-voice):

• No LLM-isms (delve, leverage, navigate, landscape, etc.)
• No em dashes: use colons instead
• No performative writing ("So here's the story", "Buckle up")
• Opens by jumping straight into the topic
• Affirmative statements, not question-led setups
• Real numbers everywhere (not "a few hours" but "4 hours")
• Varied paragraph lengths (some one sentence, some five)
• Parenthetical asides for clarification and humor
• Strong opinions backed with evidence

Phase 5: Astro Frontmatter

For Sam's blog specifically (site/src/content/blog/):

---
title: string              # Lowercase after first word unless proper noun
pubDate: YYYY-MM-DD        # The actual project completion date, not publication date
description: string        # 1 sentence, specific, includes key tech
tags: string[]             # Lowercase, specific (not "technology" but "python")
draft: boolean             # false when ready
image: string              # Optional, path to hero image
heroImage: string          # Optional, path to AI-generated hero (e.g. "/heroes/my-post.jpg")
heroImagePrompt: string    # Optional, the prompt used to generate heroImage (shown on page)
---

Back-publishing: When writing about past projects, set pubDate to the project date. The blog should read as a timeline of work, not a dump of posts all dated today.

Phase 6: OG Hero Image Prompt

Generate an image generation prompt (for Gemini/Imagen) to create a hero image for the post's Open Graph social preview. The image will be used as a background in a 1200×630 OG card with a dark overlay and text on top.

Prompt template:

A dark moody digital illustration of [SCENE SPECIFIC TO THE POST'S CORE CONCEPT]. [KEY VISUAL ELEMENT 1] and [KEY VISUAL ELEMENT 2]. Color palette: deep navy (#101218), electric blue (#468CDC) accents, [ONE ADDITIONAL ACCENT COLOR RELEVANT TO THE TOPIC]. Technical illustration style, slightly stylized, 16:9 landscape, dark background suitable for text overlay.

Rules for good prompts:

Output format: Include the prompt in a fenced block at the end of the blog post draft, tagged for easy extraction:

<!-- og-hero-prompt
[The full image generation prompt here]
-->

The author generates the image externally (Gemini, DALL-E, etc.), saves it as site/public/heroes/{slug}.jpg, and adds both fields to the frontmatter:

heroImage: /heroes/my-post-slug.jpg
heroImagePrompt: "The full prompt used to generate this image"

The blog template displays the hero image above the article content with a collapsible "AI-generated image — show prompt" caption that reveals the heroImagePrompt text. This is intentional transparency about AI-generated visuals.

Common Mistakes