Dev Blog Posts skill for Claude Code

A post is done when it makes one point a developer did not know before, proves it with specifics (numbers, code, graphs, failures), and a reader who stops after the first paragraph still learns what the point is. It is not documentation (no completeness required) and not marketing (no adjectives without evidence).

Ground rules

• One idea per post, statable in a sentence: “Moving our queue from Redis to Postgres cut p99 job latency by 40% because of X.” If you need “and” twice, split the post.
• Specific beats general. Real numbers, real error messages, real config, the thing that actually broke.
• Show the dead ends. What you tried that failed is often the most useful part.
• Respect the reader’s time: 1,000–2,500 words for most posts; long deep dives earn their length with sections readers can skip to.
• Clear anything sensitive: customer names, security details, internal hostnames, unreleased plans. Get the review your company requires.

Pick the shape

Type	Reader gets	Structure
War story / incident	A failure mode to recognize	Symptom → investigation → wrong turns → cause → fix → lessons
How we built X	Design reasoning they can reuse	Problem/constraints → options → choice → implementation highlights → results → what we’d change
Deep dive	Understanding of a mechanism	Question → mental model → layers of detail → surprising consequence → practical takeaway
Benchmark / migration	Evidence for a decision	Context → method → results (charts) → caveats → recommendation
Tutorial	A working thing	Goal + final result shown first → steps with code → next steps (see technical-writing)
Opinion / lessons	A reframing	Claim → evidence and examples → counterarguments → implications

Workflow

- [ ] 1. Write the one-sentence point and the target reader
- [ ] 2. Gather evidence: numbers, graphs, code, error output, timeline
- [ ] 3. Outline (shape from the table above)
- [ ] 4. Draft the hook and title last-but-one, after the body exists
- [ ] 5. Draft fast; code and figures first
- [ ] 6. Edit: cut 30%, tighten, check every claim
- [ ] 7. Technical review + sensitive-info review
- [ ] 8. Package: title, description, images with alt text, links

1. Point and reader

Point: <one sentence with the surprising or useful claim>
Reader: <e.g. backend engineers running Postgres at moderate scale>
They will leave with: <technique, number, decision rule, or warning>

4. Title and hook

Titles: specific, honest, ideally with the subject and the result.

Before	After
“Lessons Learned From Scaling”	“How a 40-byte index entry cost us 2 TB: Postgres bloat at 3B rows”
“Our Journey to Kubernetes”	“We moved 140 services to Kubernetes. Here’s what took 80% of the time”
“Understanding React Rendering”	“Why your React context re-renders everything (and the 3-line fix)”
“You Won’t Believe This Bug”	“A timezone bug that only happened on the last Sunday of October”

Hook (first 2–4 sentences): drop the reader into the problem or lead with the result. No throat-clearing.

Before	After
“In today’s fast-paced world of software, performance matters more than ever. At Acme, we’re always looking for ways to improve…”	“At 02:13 on a Tuesday, our job queue stopped draining. 400,000 jobs piled up, and the only clue was a Postgres log line we’d never seen before.”
“In this post, we will discuss how we approached caching.”	“Our API’s p95 dropped from 900 ms to 120 ms after we deleted most of our cache. This is why.”

5. Draft

• Narrative paragraphs short (2–4 sentences); subheadings every 200–400 words that tell the story when read alone.
• Every claim with a number links to or shows its evidence (graph, benchmark setup).
• Code samples: the minimum that makes the point, runnable or clearly marked as excerpt, with language tags. Prefer a diff to show a change:

- const user = await db.user.findUnique({ where: { id } });
- const orders = await db.order.findMany({ where: { userId: id } });
+ const user = await db.user.findUnique({ where: { id }, include: { orders: true } });

• Diagrams for architecture and flows; graphs for before/after with labeled axes and units. Alt text on every image describing what it shows, not “diagram”.
• Name trade-offs and limits: when the approach does not apply.
• End with the takeaway restated as something actionable, plus links to code or docs. No “Thanks for reading! We’re hiring!” as the only conclusion (a one-line hiring note after the conclusion is fine).

6. Editing pass

1. Read the draft and write its point in one sentence. If it differs from step 1, fix the draft or the point.
2. Cut the first paragraph if the second one is the real start (it usually is).
3. Cut 25–35%: repeated explanations, history nobody needs, hedges, “basically”, “very”, “in order to”.
4. Replace adjectives with numbers: “much faster” → “3.4× faster on the same hardware”.
5. Check every code sample runs or compiles; every link resolves.
6. Read aloud; fix sentences you stumble on.

For a line-level edit, use prose-editing.

Gotchas

• Writing the “how” without the “why”: readers can find the API docs; they came for the reasoning and the failure modes.
• Benchmarks without method (hardware, versions, dataset, runs, variance) are dismissed by the audience that matters.
• Overclaiming generality from one system: say what about your situation made it work.
• Screenshots of code (not searchable, not accessible); use code blocks.
• Insider jargon and internal service names without explanation.
• Publishing details that help attackers (exact versions of unpatched systems, internal topology).

Verification

• The one-sentence point is recoverable from the title + first paragraph alone.
• Every number has a source in the post or a link.
• Code samples tested; links checked; images have alt text.
• A reviewer from the target audience (not the author’s team) read it and could explain the takeaway.
• Sensitive-information and legal review completed if your company requires it.

Output contract

---
title: <specific title with subject and result>
description: <~150 characters: the point, for previews and search>
author: <name>
date: <YYYY-MM-DD>
---

<Hook: 2–4 sentences with the problem or result>

## <Context: what we had and why it mattered>
## <The problem, with evidence>
## <What we tried (including what failed)>
## <What worked and why>
## <Results: numbers, graph>
## <Trade-offs and when not to do this>
## <Takeaway + links>