Menu
Write technical content for senior engineering audiences using narrative arcs, hooks, and structured conventions.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Create conventional commit messages following best conventions. Use when committing code changes, writing commit messages, or formatting git history. Follows conventional commits specification.
Create Pull Requests following best conventions. Use when opening PRs, writing PR descriptions, or preparing changes for review.
Expert Spring Boot 4 testing specialist that selects the best Spring Boot testing techniques for your situation with Junit 6 and AssertJ.
Build Laravel admin panels with Filament v5. Use for creating resources, forms, tables, widgets, and testing admin interfaces with Livewire v4.
Based on SOC occupation classification
| name | technical-writing-for-engineers |
| description | Write technical content for senior engineering audiences using narrative arcs, hooks, and structured conventions. |
| license | MIT |
| metadata | {"version":"1.0.0"} |
Audience: Senior engineers, principal/staff engineers, tech leads — distributed systems practitioners. They are busy, skeptical, and will stop reading the moment they sense filler or obvious advice.
Voice: First-person, direct, intellectually honest. Use "I think", "we decided", "we got this wrong", "I'd do X differently now". Avoid the royal "we" for one-person opinions. Never hide behind passive voice when you made a call.
Topics: Backend engineering, software architecture, business/engineering intersection, distributed systems trade-offs.
Every post follows a Before → Journey → After arc.
This arc is not optional. If a section doesn't serve one of these three phases, cut it or fold it into one that does.
The hook is the first ~150 words. It is the most valuable real estate in the post.
The hook must contain:
Context, background, and definitions come after the hook. Never before.
Hook template:
[System/situation] had a gap. [What the gap caused]. Here's how we thought through it.
Good hook example:
Our order anomaly detector was flagging healthy orders as undeliverable — silently. No alert, no log, just a customer wondering where their package was. We needed a way to catch these at decision time, not after the fact. Here's the model we built and the three approaches we rejected before landing on it.
Complete example (hook + outro + title):
Our order anomaly detector was flagging healthy orders as undeliverable —
silently. No alert, no log, just a customer wondering where their package
was. We needed a way to catch these at decision time, not after the fact.
Here's the model we built and the three approaches we rejected before
landing on it.
[Journey section: What you tried, what surprised you, what you got wrong]
If I were starting this again, I'd resist the urge to build the model
first. The hardest part wasn't detection — it was agreeing on what
"anomaly" meant to the business. That conversation took longer than the
code. Next time I'd run it in week one.
How We Built Anomaly Detection Without False Positives
Bad hook (do not write this):
In distributed systems, reliability is a key concern. Many teams face challenges when it comes to detecting anomalies. This post will explore some approaches to this problem.
Before drafting, answer these in order:
Never write these:
| Pattern | Why |
|---|---|
| Opening with a definition ("Distributed systems are...") | Signals no hook, loses the reader |
| Pure reference sections with no narrative | Reads like docs, not a post |
| Ending on a link ("See the RFC for details") | Abandons the reader; your take belongs at the end |
| Passive voice at key decision moments | Obscures who made the call and why |
| "In this post, we will cover..." | Wastes hook space; show don't announce |
| Vague scope phrases ("there are many ways to...") | Filler; commit to a perspective |
Do not use: just, simply, obviously, of course, easy,
everyone knows, very, basically, turns out, in order to.
These words either condescend to the reader or pad the sentence. Cut them entirely.
End with your take — not a summary.
The outro is not a recap of what you wrote. It is your honest current belief about the problem, what you'd do differently, or what you'd want a reader to walk away thinking about.
Ask yourself: If a colleague asked me "so what's the takeaway?" over coffee, what would I actually say? Write that.
Bad outro:
In this post we covered the anomaly detection model, the three approaches we considered, and how we landed on a threshold-based system.
Good outro:
If I were starting this again, I'd resist the urge to build the model first. The hardest part wasn't detection — it was agreeing on what "anomaly" meant to the business. That conversation took longer than the code. Next time I'd run it in week one.
Write the title last. A good title is:
Formats that work well:
[Problem] without [trade-off you'd expect to accept]Why we chose [X] over [Y] for [Z]How [system] handles [hard thing][Concrete thing] taught me [non-obvious insight]