| name | engaging-craft |
| description | Apply proven copywriting techniques to long-form technical content so it holds attention from sentence to sentence — and humanize prose that reads AI-generated. Covers AIDA, PAS, Before-After-Bridge, Bencivenga's pyramid, Sugarman's slippery slide, Schwartz's awareness levels, hook engineering, voice and tonality calibration, the concrete-over-abstract discipline, and the AI-prose-tell catalog (banned high-frequency AI words like delve / underscore / pivotal / leverage; AI transitions like "that being said" / "at its core"; reflex hedges; academic filler verbs; buzzwords like revolutionize / cutting-edge / seamless integration; the six structural fingerprints; the sniff test). Use when the user asks to make an article more engaging, write a hook, calibrate voice, humanize AI-generated prose, remove AI tells, fix robotic or generic copy, replace abstract claims with concrete examples, or apply a copywriting formula. NOT for outlining or section structure (use long-form-structure). NOT for line-level clarity editing of short-form work writing (use communication/clarity-editing). NOT for research or sourcing (use technical-research). NOT for narrative storytelling craft (use storytelling). |
Engaging Craft
Engagement is earned sentence by sentence. The reader's attention is renewed every paragraph; if a paragraph doesn't earn the next one, the reader leaves. Most technical articles fail not because the structure is wrong, but because the prose is generic enough that any paragraph could be cut without loss.
This skill covers the sentence-and-paragraph-level craft of long-form technical writing — the proven copywriting techniques that translate to technical content, and the disciplines that distinguish prose written to be read from prose written to be archived.
Core principle
Engagement is concrete, specific, and earned. Abstract assertions need to be paid for in concrete examples. Named things beat generic things. Demonstrated claims beat asserted ones. Sentences that could appear in any article about anything will be skipped.
The proven formulas
Copywriters spent the 20th century cataloging what makes prose hold attention. Most of that craft transfers to technical content; almost none of it is taught to engineers.
The five formulas worth learning:
AIDA — Attention, Interest, Desire, Action
The oldest formula. Originated in advertising; widely applied to long-form persuasion.
| Phase | Reader's state | Your job |
|---|
| Attention | "Why should I look at this?" | A hook that creates curiosity |
| Interest | "Why should I read more?" | A promise that the topic affects the reader |
| Desire | "Why should I want this?" | The payoff matters; the reader sees themselves benefiting |
| Action | "What should I do now?" | A clear next step |
In technical content: Attention is the hook. Interest is the promise. Desire is the development that builds the case. Action is the close.
PAS — Problem, Agitate, Solve
The high-conversion direct-response formula. Especially useful in opinion pieces and case studies.
| Phase | Move |
|---|
| Problem | Name the problem the reader has |
| Agitate | Make the cost of the problem visible — what it's costing them now, what it'll cost in 6 months, what it's already cost |
| Solve | Present the solution as the relief |
In technical content: works for "your CI is slow" → "compounded across your team it's costing N engineer-weeks per quarter" → "here's how to halve it."
Caution: agitation must be honest. Manufactured urgency feels manipulative; real cost-naming feels like the writer respects the reader's situation.
BAB — Before, After, Bridge
A gentler cousin of PAS. Useful for tutorials and case studies.
| Phase | Move |
|---|
| Before | The reader's current state |
| After | What life looks like after applying this |
| Bridge | The path from Before to After (the article's content) |
Bencivenga's pyramid (skepticism gradient)
Gary Bencivenga's insight: every reader starts skeptical. Each claim spends a little credibility; each piece of evidence earns it back. Sequence matters — claims that seem outlandish on first read can land if you've earned credibility first.
| Position in piece | What lands |
|---|
| Opening | Hyper-specific, verifiable claims (low credibility cost) |
| Early development | Conventionally believable claims with strong evidence |
| Mid-development | Conventionally believable claims with mixed evidence |
| Late development | Outlandish-seeming claims that follow from accumulated evidence |
| Payoff | The reframing that wouldn't have worked if stated up front |
Practical: don't lead with your most controversial claim. Lead with the verifiable observation that implies the controversial claim, build the case, then state the controversial claim where the reader is ready for it.
Sugarman's slippery slide
Joseph Sugarman: every sentence has one job — to get the reader to read the next sentence. The reader is on a slide; you're greasing it.
Practical implications:
- Short, punchy openers hold attention better than long, balanced ones.
- Curiosity gaps (questions, partial reveals) pull the reader forward.
- Concrete language is grippier than abstract.
- White space and short paragraphs are part of the slide — long unbroken text adds friction.
For technical writing, Sugarman's discipline is corrective: technical writers tend to over-pack sentences. Sugarman trains you to break sentences open, give the reader breathing room, and let the slide carry them.
Schwartz's awareness levels
Eugene Schwartz: the reader's awareness of the problem and the solution determines how you frame the piece. Five levels:
| Level | Reader's awareness | Frame your hook around |
|---|
| Unaware | Doesn't know the problem exists | The symptom; the cost; "here's what's happening" |
| Problem-aware | Knows the problem; doesn't know solutions | The problem named precisely; "you've felt this; here's why it happens" |
| Solution-aware | Knows solutions exist; doesn't know yours | The differentiator; "here's a different way" |
| Product-aware | Knows your specific solution; not convinced | The objection-handling; "here's why this is different / better" |
| Most aware | Already convinced; needs the next step | The action; "here's what to do this week" |
Most technical articles are pitched at Problem-aware or Solution-aware readers. A common failure is pitching to Most-aware (assuming the reader already cares deeply about the problem); the article reads as preaching to a choir that isn't listening.
See references/proven-formulas.md for full applications of each formula with worked examples.
Hook engineering
Hooks are the highest-leverage 200 words in any article. A weak hook loses readers who would have valued the rest.
Eight hook types
| Type | When it works | Example pattern |
|---|
| Misconception | Reader has a wrong model | "Most engineers think X. The reality is more interesting." |
| Surprising fact | Specific, citable | "In 2023, the average X was Y. Not Z. Y." |
| In-medias-res | Narrative, case study | "At 02:47 AM on a Sunday, our database stopped accepting writes." |
| Question | The reader has implicitly wondered | "You know X is bad. Have you ever looked at exactly why?" |
| Artifact | Code, output, chart that creates curiosity | A terminal output showing the surprising number |
| Failed expectation | Story-shaped | "We did X. We expected Y. We got Z." |
| Consequential question | High stakes | "If your CI is 12 minutes, what does that cost you per quarter?" |
| Intellectual provocation | Opinion | "There is no such thing as X. There is only Y being paid by Z." |
See references/hooks-and-openers.md for the full library with selection guidance and worked examples.
Hooks that don't work
- "In today's fast-paced digital landscape…"
- "Have you ever wondered…" (rhetorical and presumptuous)
- "We all know that…"
- "It's no secret that…"
- "Picture this:" (followed by something unmemorable)
- "Imagine you're a [role] who…"
- "Once upon a time…" (in a non-narrative piece)
These signal generic content. Readers notice within three seconds and bounce.
Voice and tonality
Voice is the consistent personality the writing presents. Tonality is its register at a given moment. Both are choices, not happenstance.
Voice axes
Decide where your piece sits on each axis. Pick deliberately; commit consistently.
| Axis | Pole A | Pole B |
|---|
| Formality | Academic | Conversational |
| Authority signal | Confident | Hedged |
| Distance | Detached | Personal |
| Stake | Observed | Lived |
| Pace | Patient | Urgent |
| Affect | Neutral | Opinionated |
A "patient, conversational, lived" voice produces in-the-trenches engineering blog. A "confident, detached, neutral" voice produces a whitepaper. Neither is right or wrong; mismatched voice is wrong.
Mid-piece voice drift
A common failure: the hook is conversational, the body switches to academic. The reader feels the seam. Fix in revision: pick the voice the body wants and rewrite the hook to match.
See references/voice-and-tonality.md for the voice calibration framework, register-shifting techniques, and worked examples.
Concrete over abstract
The single most important sentence-level discipline.
The principle
| Abstract | Concrete |
|---|
| "Performance was significantly improved." | "P99 dropped from 480ms to 120ms." |
| "Many engineers struggle with this." | "I've watched four teams hit this in the last year." |
| "The migration was challenging." | "The migration broke 47 tests; we fixed 41 in two weeks; the remaining 6 took six months." |
| "Code quality matters." | "We had three production incidents in Q3 attributable to a single function nobody had reread since 2021." |
| "Modern systems are complex." | "Our microservices stack has 12 services; tracing a single user request touches 8." |
Concrete prose grips. Abstract prose washes over. The discipline is to find the concrete equivalent of every abstract sentence — and almost always there is one.
Three substitutions
- Numbers replace adjectives. "Significantly faster" → "3x faster" or "40ms faster on P99."
- Names replace categories. "A modern framework" → "Next.js 14" or "the Phoenix LiveView team."
- Demonstrations replace assertions. "X is hard to debug" → "Here's a 20-line repro that fails in three different ways depending on timing."
When abstract is right
Abstract has its place — when generalizing across many specifics. "Many production systems exhibit this pattern" is appropriate after you've shown three. The discipline is to earn the abstract by paying for it in concrete.
See references/concrete-over-abstract.md for substitution patterns, the "why this not that" diagnostic, and the abstract-to-concrete revision pass.
AI-prose tells (the humanization pass)
Modern technical readers can spot LLM-generated prose in seconds. The cost of getting caught is high — the article reads as effortless to produce, which means it reads as un-earned. Five categories of leak:
| Category | Examples (cut these) |
|---|
| High-frequency AI words | delve, underscore, pivotal, realm, harness, illuminate, leverage, navigate (figurative), myriad, plethora, landscape (figurative), paradigm, ecosystem |
| AI transitions | "That being said…", "At its core…", "From a broader perspective…", "It's important to note that…", "In today's fast-paced…", "Moreover", "Furthermore" |
| Reflex hedges | "Generally speaking", "Typically", "Tends to", "Arguably", "To some extent", "Broadly speaking", "It seems", "It's worth considering" |
| Academic filler verbs | shed light on, facilitate, refine, bolster, differentiate, streamline, encompass, demonstrate, utilize, ascertain |
| Buzzwords | revolutionize, innovative, cutting-edge, state-of-the-art, game-changing, transformative, seamless integration, scalable solution, robust, comprehensive |
The discipline is not "avoid AI words because AI bad." It's: specific language carries voice; generic language carries nothing. Every banned phrase above is banned because it was picked by the model to sound smart, and the cost of "sounding smart" is "sounding like every other article on the topic."
Six structural AI fingerprints
Beyond vocabulary, AI prose has structural tells:
- Balanced everything — every claim has a counterclaim; every advantage paired with disadvantage.
- Smooth gradient — no jolts, no breaks, no surprise sentences.
- List-of-three syndrome — every list has exactly three parallel items.
- Executive summary tone — no first-person, no anecdotes, no stake.
- Polite hedge cascade — multiple hedges stacked per sentence.
- Predictable formatting — title-case headings, three-bullet lists, every section closes with a smooth transition.
The sniff test (run before publishing)
- Does {delve, underscore, pivotal, realm, harness, illuminate, leverage, navigate, myriad, plethora} appear more than twice? Cut.
- Does {That being said, At its core, From a broader perspective, In today's fast-paced, It's important to note} appear at all? Cut all instances.
- More than one hedge per 100 words? Cut at least half.
- Any of {revolutionize, innovative, cutting-edge, game-changing, transformative} appear? Replace with a specific descriptor or cut.
- Zero first-person pronouns in a piece that should have them? Add stake.
- All your lists three items long? Vary.
- Opening sentence resembles "In today's…" / "In recent years…" / "In the rapidly evolving…"? Rewrite.
The single best diagnostic question, when you suspect AI prose: Could this paragraph appear in any article on this topic written by anyone? If yes, it's leaking.
See references/ai-tells-and-substitutions.md for the full catalog with concrete substitutions, worked transformations, and structural-pattern fixes.
Sentence-level pacing
Long sentences are slow; short sentences are fast. Vary deliberately.
The slow-down
Long sentences with multiple clauses slow the reader. Use them when introducing complexity, when the reader needs to absorb a model, or when the prose itself benefits from rhythm.
"VACUUM, the maintenance operation that exists because Postgres uses MVCC and MVCC means dead
tuples accumulate, runs in two modes — autovacuum, the background daemon that triggers based on
thresholds, and manual VACUUM, the one you run when autovacuum couldn't keep up — and the
distinction matters for diagnosing the failure mode we're about to walk through."
That sentence introduces three concepts. The length signals "absorb this."
The speed-up
Short sentences accelerate. Use them at section breaks, in transitions, when delivering payoffs, and when emphasizing.
"VACUUM didn't run.
That was the bug."
Two sentences, eight words. Maximum velocity.
The varied paragraph
Mix in the same paragraph. Long-then-short is satisfying; short-then-long takes a deeper breath.
"Postgres MVCC keeps both versions of an updated row, so concurrent readers see consistent
snapshots even as writes happen — that's the elegant part. Then come the dead tuples.
They accumulate. VACUUM cleans them up, but only if it can run. And when can it not run?
When a transaction stays open."
Long-then-short. The reader absorbs the model in the long sentence; the short sentences underline the punchline.
Callbacks and motifs
A motif is an image, phrase, or example that recurs through the piece. Callbacks reward the careful reader.
Section 1: "...like a librarian shelving books that nobody can read until they're catalogued."
Section 4: "...so the librarian is still shelving, but nobody's catalogued anything since
yesterday."
Section 7: "Find the librarian. Free the librarian."
The same image, three times, takes on meaning each time. The reader who's been paying attention feels rewarded; the reader who hasn't still gets the point.
Motif rules:
- Earn the first instance with concrete utility (it explains something).
- Don't force callbacks just because. The third instance must do work.
- Keep the motif's vocabulary stable. "The librarian" each time, not "the librarian / the cataloger / the bookshelf-keeper."
✅ Use for
- Making an existing article more engaging (sentence-level)
- Engineering a hook for a piece in progress
- Calibrating voice and tonality
- Replacing abstract claims with concrete examples
- Applying AIDA / PAS / BAB / Bencivenga / Sugarman / Schwartz to a draft
- Fixing prose that feels generic or asserted
- Humanizing AI-generated prose — removing the high-frequency AI words (delve, underscore, pivotal), AI transitions ("that being said"), reflex hedges, academic filler, and buzzwords (revolutionize, cutting-edge) that signal generic LLM output
- Adding callbacks and motifs
❌ NOT for
- Outlining or section-level structure — use long-form-structure
- Line-level clarity editing (active voice, hedge removal) — use long-form-polish or communication/clarity-editing
- Research, sourcing, or citation — use technical-research
- Narrative storytelling craft (character arcs, scene construction) — use storytelling
- UI microcopy, button labels — use ux-writing
Anti-patterns
The AI-prose tell
What it looks like: Smooth, balanced, hedge-laden prose. Every sentence has equal weight. Every claim is qualified. The piece reads as if it were averaging across all possible articles on the topic.
Why it's wrong: The reader feels that no specific person wrote this. Engagement requires a voice, and AI-by-default writing lacks one.
What to do instead: Read the draft aloud. Where does it sound like a human? Where does it sound like a press release? Rewrite the press-release sentences with stake, opinion, and specific details. Cut hedges. Use first-person where appropriate. Pick a voice and commit.
The asserted authority
What it looks like: "It's well-known that…" "Most experts agree…" "Industry best practice is…" — claims about consensus that the reader can't check.
Why it's wrong: Authority should be demonstrated, not asserted. Each "well-known" claim spends credibility without earning it.
What to do instead: Replace authority claims with specific evidence. "Three Postgres committers I asked separately said…" beats "well-known among Postgres experts." Or remove the framing entirely and just make the claim with evidence.
Abstract everywhere
What it looks like: Three pages of generic prose. "Performance," "complexity," "tradeoffs," "modern systems," "engineering teams." No numbers, no names, no specific examples.
Why it's wrong: The reader could replace any noun with any other noun and the article would still parse. That means none of the nouns are doing real work.
What to do instead: Run the abstract-to-concrete pass. For every abstract noun, find the concrete equivalent. If you can't, the prose may be hiding that you don't have the specifics.
Listicle prose
What it looks like: "First, X is important. Second, Y is also important. Third, Z is important too." Each "point" gets a paragraph; the paragraphs don't build on each other.
Why it's wrong: Looks like development; actually accumulation. The reader collects items rather than absorbing an argument.
What to do instead: Decide which point is the thesis and which are evidence for the thesis. Restructure so the thesis is stated and the others support.
The deflated payoff
What it looks like: A 3000-word build-up that lands on "...so the answer is, it depends."
Why it's wrong: The reader spent 15 minutes for a non-answer.
What to do instead: If the answer really is "it depends," promise a framework for thinking about it up front. Then deliver the framework. The reader who wanted "depends on what?" is satisfied; the reader who wanted a single answer was misaligned with the article from the start.
Voice drift
What it looks like: A conversational hook gives way to a corporate-academic body that gives way to a punchy close. The piece feels like three different writers.
Why it's wrong: The reader unconsciously feels the seams. Trust erodes; engagement drops.
What to do instead: Pick the voice the body wants (it's hardest to change). Rewrite the hook and close to match.
Sugarman violation: the long unbroken paragraph
What it looks like: A 200-word paragraph with no break, no list, no breathing room.
Why it's wrong: The reader's eye sees a wall and bounces. Even if the content is excellent, the visual signal is "this is going to be hard."
What to do instead: Break long paragraphs at logical pivots. Aim for 50-100 word paragraphs in the development sections. Use short paragraphs to deliver punch lines.
Workflow
- Confirm voice. Before drafting, decide the six voice axes.
- Engineer the hook. Pick a hook type; draft 2-3 candidates; pick the best.
- Pick a formula if relevant (AIDA, PAS, BAB) and lay out the moves.
- Draft with concrete bias. When you reach for an abstract noun, ask "what's the concrete?"
- Sentence-level pass — vary length, break long unbroken paragraphs, deliver short punch lines at key beats.
- Callback engineering — identify a motif; reuse it across sections.
- Read aloud. Find the bumps. Rewrite the bumps.
- Hand off to long-form-polish for pacing, scan-ability, and the cut.
References
| File | Contents |
|---|
references/proven-formulas.md | AIDA, PAS, BAB, Bencivenga's pyramid, Sugarman's slippery slide, Schwartz's awareness levels — full applications with technical-content examples |
references/hooks-and-openers.md | Eight hook types with selection guidance and worked openers |
references/voice-and-tonality.md | Voice calibration framework (six axes), register-shifting, mid-piece drift detection |
references/concrete-over-abstract.md | The substitution disciplines, the abstract-to-concrete revision pass, when abstract is correct |
references/ai-tells-and-substitutions.md | Full catalog of AI-prose vocabulary tells (high-frequency words, transitions, hedges, academic filler, buzzwords) plus the six structural AI fingerprints, the sniff test, and worked humanization transformations |
Related skills
- technical-research — concrete examples come from research; you can't write specific without sourcing specific.
- long-form-structure — engagement at sentence level depends on structural payoff at article level.
- long-form-polish — pacing across paragraphs and sections after the draft exists.
- distribution-craft — title and dek inherit voice from the body.
- storytelling (skillstack) — narrative craft for non-technical pieces; engaging-craft is the technical-content cousin.
- communication/clarity-editing (skillstack) — line-level clarity editing for short-form work writing.
