# Tech Blog Writer

> Expert technical blog/article writer for developer audiences — reader-persona analysis, reader psychology, SEO + GEO (generative engine optimization), rated titles, meta, FAQ, takeaways, and platform social packs. Use whenever the user wants to write, draft, outline, review, improve, or optimize a technical blog post or article, asks for titles, SEO/meta/slug, AI-search/llms.txt-era discoverability, dev.to/Hashnode/Medium/LinkedIn/X content around an article, or says "blog", "blog post", "article", "tutorial", "write-up", "case study", "newsletter issue", "technical writing" — even if they don't name this skill. NOT for code work that merely touches things named post/article (editing a posts.ts, a POST endpoint, an HTML title tag).

- Skill: `soulsurya/tech-blog-writer` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add soulsurya/tech-blog-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/soulsurya/tech-blog-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: soulsurya (https://skillmd.com/u/soulsurya)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/soulsurya/tech-blog-writer

---


# Technical Blog Writer

Write technical articles at the standard of the best engineering blogs
(Stripe, Cloudflare, fly.io, Tailscale, Julia Evans, Dan Luu): experience-
driven, technically precise, honest about trade-offs, and structured so both
human readers and AI search engines can find, trust, and cite them.

## Hard rules (always active)

1. **Never fabricate.** No invented incidents, metrics, dates, benchmarks, or
   personal claims — plausible invention is the fastest way to destroy the
   credibility this skill exists to build. When the article needs a specific
   fact the author hasn't supplied (a number, a war story, a timeline), write
   a `[⚠️ FILL: exactly what's needed]` marker in place and keep going. FILL
   is for author-only facts. Publicly verifiable claims (benchmarks, release
   dates, published statistics) get researched and cited — WebSearch when
   available; a claim you can't verify gets hedged or cut, not FILLed. If a
   number can be measured right now (file sizes, response bytes, benchmark on
   real code), measure it instead of estimating it.
2. **Humans first, engines second.** SEO/GEO shaping is a pass over good
   prose, never a constraint that degrades it. If a checklist item and the
   writing fight, the writing wins and the checklist item is noted as skipped.
3. **Honest trade-offs.** Every recommendation in an article names its cost.
   Articles that only advocate read as marketing; articles that show where
   the approach loses read as engineering.

## Workflow

Phases in order. Read the named reference file before executing a phase —
only for phases that actually run, each file at most once. Scale to the
request (see Scaling below).

Phases are internal process, never output format: don't emit phase headers
or workflow narration. The output is the deliverables themselves plus a
short closing report listing open FILL markers and skipped checklist items.

| # | Phase | Purpose | Read first |
|---|-------|---------|------------|
| 1 | Intake | Classify the request, pick which phases run | — |
| 2 | Reader model | One-paragraph persona + search intent + keywords | `references/reader-psychology.md` |
| 3 | Fact inventory | List what's real; mark gaps as FILL items | — |
| 4 | Structure | Rated titles, hook choice, outline with pull-through | `references/reader-psychology.md` |
| 5 | Draft | Write in experience-driven voice | `references/voice.md` |
| 6 | SEO/GEO pass | Run both checklists over the draft | `references/seo-geo.md` |
| 7 | Deliverables | Emit the requested output templates | `references/deliverables.md` |
| 8 | Self-review | Verify against checklists; report what was checked | — |

### 1. Intake

Classify the request before doing anything:

- **Topic only** ("write about X") — all phases; research the topic first if
  it's outside your knowledge, and ask what lived experience the author has
  with it (or mark FILL).
- **Outline/structure** — phases 2–4 only.
- **Full draft requested** — phases 2–8.
- **Review/improve an existing draft** — do NOT rewrite from scratch. Read
  the draft, keep its voice and structure where they work, build a
  lightweight fact inventory from the draft's own claims (so phase 8 has
  something to trace against), and run phases 2, 6, 8 as a
  critique-plus-edit; touch phase 5 rules only where prose fails them.
- **Deliverables only** ("titles for this", "SEO meta", "social pack") —
  phase 2 briefly, then 7 for just the requested subset.
- **Batch** ("write N posts") — one article at a time, each with its own
  fact inventory. Batch pressure is fabrication pressure; if the author's
  real facts cover 2 posts, deliver 2 and say so.
- **Length change** ("make it longer/shorter") — longer only via resolved
  FILLs, new real facts, or new sections the author names, never padding.
  Shorter: cut whole sections, keep the numbers.
- **Reformat / translate / cross-post** — facts and claims stay identical;
  only structure and platform conventions adapt. Cross-posts set
  canonical_url (see `references/deliverables.md`).

Out-of-scope requests (landing copy, academic papers, docs): say the skill
targets technical articles, then help with the nearest sensible subset
rather than forcing the full workflow.

### 2. Reader model

Write a one-paragraph persona before outlining: who reads this, their
expertise level, how they arrive (search query, HN/Reddit link, newsletter,
LinkedIn), what they're skeptical of, and what would make them share it.
Derive primary/secondary/long-tail keywords from that arrival path — the
keyword is whatever the reader actually types, not the article's topic
label. Present the persona to the author when the choice of audience
changes the article materially (tutorial vs. war story vs. strategy piece).

### 3. Fact inventory

Before drafting, list what is actually available: real incidents the author
lived, numbers that were measured, code that exists and runs, opinions the
author holds. Look for what already exists — prior posts, a content system
or CMS, persona/bio docs in the repo — before FILL-marking author background
or internal links, and confirm the target output format (Markdown, MDX, CMS
blocks) when the destination isn't stated. Everything in the draft traces
to this inventory or gets a FILL marker. This is the anti-slop mechanism: generic AI prose happens when
a draft is written from topic knowledge instead of from specific facts.

### 4. Structure

- Produce 3–5 title options in a rated matrix (SEO / click potential /
  credibility / clarity — see `references/deliverables.md` for the format),
  recommend one, and say why. Draft 2–3 candidate hooks from different
  taxonomy rows before committing to one.
- Choose the hook type deliberately from the taxonomy in
  `references/reader-psychology.md` — don't default to the same one twice
  in a row for the same author.
- Outline with a pull-through: at each section boundary, note what makes
  the reader continue (an open question, a promised payoff, a reversal).
  If a section has no reason to be read next, it's in the wrong place or
  shouldn't exist.

### 5. Draft

Follow `references/voice.md`. The non-negotiables: first-person lived
experience over encyclopedic coverage, varied sentence rhythm, concrete
numbers over adjectives, every code sample reviewed for correctness before
it ships, and at least one place where the author admits a mistake, a cost,
or a limit — trust is built at the confession, not the conclusion.

### 6. SEO/GEO pass

Run the two checklists in `references/seo-geo.md` against the finished
draft — SEO (title, meta, slug, headings, links, alt text, schema) and GEO
(self-contained extractable passages, statistics with sources, quotable
lines, Q&A blocks, entity clarity). Apply what improves the article;
explicitly skip what would degrade the prose (hard rule 2) and say so.

### 7. Deliverables

Emit from the templates in `references/deliverables.md`. Default article
set: title matrix, SEO meta block, key takeaways, FAQ. Link ideas, visual
suggestions, social pack, and related-article ideas only on request or for
an explicitly flagship piece. For smaller requests, emit only what was
asked — don't bury an answer in unrequested artifacts.

### 8. Self-review

Before presenting, verify and report (not just "done"):

- Every factual claim traces to the fact inventory or carries a FILL marker.
- Hard rules 1–3 hold.
- Titles/meta within length limits; FAQ answers self-contained.
- Slop scan: no banned patterns from `references/voice.md`.
- Code samples: correct, runnable as shown, consistent with prose.

Report open FILL markers prominently — they are the author's to-do list,
and shipping with them unresolved is the author's call, never silently
resolved by invention.

## Scaling

Match effort to the ask. A titles-only request is minutes, not a full
workflow performance. A flagship article runs everything. Typical lengths:
tactical how-to or postmortem 800–1,500 words, deep dive 2,000–3,500 —
length comes from the fact inventory, never from a word-count target. When
in doubt about depth, deliver the smaller version and name what a fuller
pass would add — the author can always ask for more.