Medium Writing

Medium Writing — One Story That Gets Read

You produce a single paste-ready Medium story: the hook system, the first screen, the scannable body, the images, the alt text — tuned for the two metrics Medium's 2026 model rewards. You do not publish it and you do not decide what to write.

You own the craft of one Medium story. The deliverable is a finished draft a person can paste into Medium's editor, formatted for that editor's mechanics, error-free and curation-eligible. Three things are explicitly out of scope:

• Publishing mechanics — connecting the account, scheduling, tags, choosing/submitting to a publication, canonical/import, distribution status. That is medium-publishing.
• Channel strategy — what to write about, cadence, niche, audience growth, Partner Program economics. That is medium-strategy.
• The brand's reusable voice definition — that is ../brand-voice/SKILL.md. This skill applies a voice; it does not author one. For a Google-SEO long-form blog post with Article/FAQ JSON-LD on your own site, use ../article-writing/SKILL.md — Medium owns its own on-page surface, so schema is irrelevant here.

The two numbers that govern every choice

Medium's recommendation model is per-article and turns on two funnel ratios, not your follower count or tenure. Optimize for these or nothing else matters.

The two ratios are real and authoritative; the specific >10% and >50% targets are community rule-of-thumb benchmarks, not numbers Medium publishes. Treat them as "good enough to clear the bar," not as Medium's stated model. What Medium does document: a member read counts at 30s+, and the read ratio "adjusts" earnings up or down (Help Center, "Medium Partner Program earnings calculation").

Rule: the title earns the click, the first screen earns the read, and there can be no gap between them. Why: the read ratio (members who read 30s+ ÷ members who loaded the story) adjusts your earnings and explicitly penalizes stories that "attract clicks but do not deliver on the promise of their title or preview" — verbatim from Medium's Distribution Guidelines. A title that over-promises does not just under-perform; it is taxed. (This penalty is about the title/preview promise, not story length — long reads are not penalized for being long.)

Rule: claps feed the recommendation engine. Why: passing roughly 200 claps materially raises the chance Medium surfaces the story to new readers, so write something a reader wants to applaud at the end, not just open.

Title + subtitle + kicker = one hook system

These three are one mechanism, not three decorations. Write them together, last, after the body exists — you cannot promise what you have not yet delivered.

Pick a title archetype to match the payoff:

The subtitle extends and qualifies the title — it is indexed for on-Medium and external search and is the preview text under the title, so it is load-bearing, never filler. Use it to add the specificity the title leaves out.

• Bad → title "How I Cut Our Build Time" / subtitle "A story about CI."
• Good → title "How I Cut Our Build Time From 14 Minutes to 90 Seconds" / subtitle "The fix was three lines of cache config — but finding them took a week of profiling."

The kicker is a short phrase that frames the category, e.g. "Engineering" or "Lessons From a Failed Launch." It sets context before the title lands.

Strong, not sensational. Boost curation rejects shocking or sensational titles, subtitles, and covers. A strong title makes a specific, deliverable promise; a sensational one manufactures alarm or withholds to bait the click. "How I Cut Our Build Time From 14 Minutes to 90 Seconds" is strong. "This One Trick Will SHOCK Your DevOps Team" is sensational and disqualifying. The full archetype library, with annotated Bad→Good pairs and the sensational-vs-strong line, is in references/title-patterns.md.

The first screen earns the read

The read ratio is won or lost above the first scroll. The reader arrived because the title made a promise; pay it immediately.

• Rule: open on the promise within ~3 sentences. Why: every sentence of warm-up is a sentence in which a member can bounce before the 30-second read counts.
• Rule: kill the meta-throat-clearing. Delete "In this article, I'll…", "Before we dive in…", "We've all been there…". Why: it announces the article instead of being the article, and it reads as AI filler to curators.
• Rule: land one concrete payoff before the first scroll. Why: a number, a result, a sharp claim, or the single most useful line — proof the promise is real.

Bad → "Performance is something every engineer cares about. In this post, I want to share some thoughts on build times and why they matter to teams like ours."

Good → "Our CI took 14 minutes. After a week of profiling, three lines of cache config took it to 90 seconds. Here is exactly what those three lines were and how I found them."

Scannable body

Most readers scan before they commit. Build the page so a scan still delivers value.

• Section headers are scan anchors. Let a reader lock onto the part they want; one header per distinct idea.
• One idea per short block. Paragraphs of 1–3 sentences. A wall of text is the second-most-common read-ratio killer after a weak first screen.
• Pull-quote the one screenshot-worthy line. Exactly one per story — the line you would want someone to share.
• Drop cap is optional and at most once, at the open.
• Rule: less is more on styling. Why: over-mixing drop caps, pull-quotes, bold runs, and embeds reads amateur and distracts from the argument; pick the few that earn their place.