blog-post-writer

name	blog-post-writer
description	Writes engaging technical blog posts with a strong hook, clear structure, concrete examples, and a memorable takeaway. Use this skill when the user asks to "write a blog post", "draft an article", "turn this into a blog post", "write up a tutorial", "explain X in a post", "create a dev.to / Medium / Hashnode article", or wants help with an engineering blog, technical write-up, announcement post, or developer-facing essay. Covers ideation, outlining, drafting, hooks, headlines, code examples, SEO basics, and editing for clarity.
license	MIT

Blog Post Writer

Overview

This skill produces publishable technical blog posts that readers actually finish: a hook that earns the first scroll, a spine of clear sections, runnable examples, and a takeaway the reader can act on. Keywords: blog post, technical article, dev blog, tutorial, write-up, engineering blog, Medium, dev.to, Hashnode, announcement, essay, headline, hook, SEO.

Use it for tutorials, deep dives, "how we built X" stories, opinion/architecture pieces, release announcements, and concept explainers.

When To Use

• "Write a blog post about ."
• "Turn these notes / this PR / this RFC into an article."
• "I need a catchy intro and outline for a post on ."
• "Edit / tighten this draft."

Process

Follow these steps in order. Do not skip step 1 — most weak posts fail on audience and angle, not prose.

1. Clarify the brief. Establish (ask only if unknown): topic, target reader and their skill level, the single takeaway, desired length, tone, and platform. If the user gave a draft or notes, infer these and confirm the angle in one line.
2. Find the angle. Pick ONE controlling idea (the "so what"). Reject topics that are really 3 posts; split them. Write a one-sentence thesis you can defend.
3. Outline. Produce a section skeleton (H2s) before prose. Use templates/outline.md. Aim for 4-7 sections plus intro and conclusion.
4. Write the hook. Draft the opening using a pattern from references/hooks.md. The first two sentences must create tension or promise a payoff. No "In today's fast-paced world."
5. Draft body. One idea per section. Lead each section with its point, then support with example/code/data. Keep paragraphs 2-4 sentences.
6. Add examples. Every abstract claim gets a concrete instance: code, a command, a number, a before/after, or a short scenario. Code must be minimal, correct, and runnable.
7. Write the takeaway. End with what the reader should now do or believe — a checklist, next step, or crisp summary. Never end on "In conclusion."
8. Title + meta. Generate 3-5 headline options (see references/headlines.md) and a 150-160 char meta description.
9. Edit. Run the pass in references/editing-checklist.md. Then run scripts/readability.py on the draft for objective metrics. Cut 10%.

Structure Template

Title (benefit-driven, specific)
Hook (2-4 sentences: tension/promise)
Context (why this matters now, who it's for) — keep short
Body section 1..N (point → example → implication)
Takeaway (action/summary)
CTA (optional: comment, follow, try the repo)

Decision Framework: Post Type

• Tutorial / how-to → numbered steps, prerequisites block, copy-paste code, end state screenshot/output. Reader goal: do it.
• Deep dive / "how we built" → problem → constraints → approach → tradeoffs → result with metrics. Reader goal: understand decisions.
• Opinion / architecture → thesis → evidence → counterargument → recommendation. Reader goal: be persuaded.
• Concept explainer → analogy → precise definition → example → common misconceptions. Reader goal: get it.
• Announcement → what's new in one line → why it matters → key features → migration/getting started. Reader goal: should I adopt this.

See references/post-types.md for full structures and worked skeletons.

Hook Heuristics (quick)

Lead with one of: a sharp question the reader is already asking, a surprising fact/number, a relatable failure, a bold claim you'll prove, or a tiny story. Promise the payoff explicitly within the first paragraph. See references/hooks.md.

Best Practices

• One takeaway per post. If you can't state it in a sentence, the post isn't ready.
• Show, don't assert: replace adjectives ("blazing fast") with numbers ("p99 dropped from 800ms to 90ms").
• Front-load value — readers skim; make each H2 a self-contained mini-point.
• Use "you" and active voice. Write like you'd explain it to a smart colleague.
• Code blocks: minimal, labeled language, tested, with expected output shown.
• Vary sentence length; short sentences land points.
• Add internal signposts ("First… Next… The catch…") for scannability.

Common Pitfalls

• Burying the lede under throat-clearing intro paragraphs.
• Trying to cover everything — scope creep kills focus.
• Abstract advice with no example.
• Untested or pseudo-code presented as runnable.
• Walls of text; no headers, no whitespace.
• Generic title ("Thoughts on X") that wins no clicks.
• Ending with a weak "Hope this helps!" instead of a real takeaway.

Supporting Files

• references/hooks.md — hook patterns with examples and anti-patterns.
• references/headlines.md — headline formulas, SEO and length rules.
• references/post-types.md — full per-type structures and skeletons.
• references/editing-checklist.md — line-by-line self-edit pass.
• templates/outline.md — fill-in outline to start any post.
• examples/sample-post.md — a complete worked post from brief to draft.
• scripts/readability.py — stdlib readability + filler-word metrics for a draft.