Agent skill · writing content · marcelorodrigo
technical-writing-for-engineers
Write technical content for senior engineering audiences
Why this skill is useful
Provides structured conventions and narrative techniques for writing technical content that the AI wouldn't reliably generate on its own.
What it needs
About 5k tokens when loaded. Last updated 2026-08-02. 15 stars on the source repository.
What this skill does
Technical Writing for Engineers Author Profile 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. --- The Story Frame Every post follows a Before → Journey → After arc. Before: What was broken, missing, or unclear? What did it cost? Who felt it? Journey: What did we try? What surprised us? What did we get wrong first? After: What did we land on? What would we change? What do we now believe? 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. --- Hook Rule The hook is the first ~150 words. It is the most valuable real estate in the post. The hook must contain: 1. The problem or gap — stated directly, not implied 2. The stakes — what goes wrong if this isn't solved 3. A signal of who this is for 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): Bad hook (do not write this): In distributed systems, reliability is a key concern. Many teams face challenges when it comes to detecting anomalies. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills marcelorodrigo/technical-writing-for-engineers