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:

| Source Type | Where to Find | What It Contains | |-------------|---------------|------------------| | README | Root | Project summary, usage, results | | Research notes | RESEARCH_NOTES.md, docs/ | Chronological narrative of discoveries | | Format specs | *_SPEC.md, *_FORMAT.md | Technical details, struct layouts | | Session logs | SESSION_LOG.md | Claude Code session summaries | | Drafts | .nocommit/, docs/drafts/ | Reddit, LinkedIn, or blog drafts | | Code | src/, *.py, *.go | Implementation details | | Tests | tests/, *_test.* | Validation approach, edge cases | | Binary data | *.hex, hex dumps in notes | Raw data examples |

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: " 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:**

| Rule | Why |
|------|-----|
| Anchor to the post's central metaphor | A post about binary reverse-engineering → hex dumps flowing over a race car, not a generic "code on screen" |
| Always specify dark background (#101218) | The OG template uses dark theme colors; a bright image won't blend |
| Include the accent blue (#468CDC) | Maintains brand consistency across all cards |
| Add one topic-specific accent color | Warm amber for legacy systems, orange for racing/speed, green for git |
| Say "suitable for text overlay" | Prevents the generator from filling the entire frame with detail |
| Keep it 16:9 landscape | Matches the 1200×630 OG dimensions |
| "Technical illustration, slightly stylized" | Avoids photorealism (uncanny) and pure cartoon (unprofessional) |
| Reference concrete objects from the post | Not "technology concept" but "weathered terminal connected to modern API" |

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

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:

```yaml
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

| Mistake | Fix | |---------|-----| | Chronological dump of session notes | Structure by component/discovery, not timeline | | Too much Claude praise | Focus on what was built, not the tool | | Vague "it was hard" | Specific: "tried Unix epoch, dates were 40 years off" | | Missing validation | Every claim needs a cross-check with real data | | Wall of code | Max 15 lines per block. Annotate, don't dump. | | Burying the result | Concrete deliverable in first 3 paragraphs |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sam-dumont
• Source: sam-dumont/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.