HOOK WRITER

What this is: an opening-line procedure built from 40,478 X Articles: 6,835 over 100k views and 33,643 under, Jan 1 to Sep 26, 2026, research by @fuckgrowth (the X article "how to write better headlines"). The dataset, whose preview column holds the first 300 characters of every winner's opening, and the research doc are linked in SOURCES.md at the repository root.

The preview is the article's first paragraph, so what this skill writes is the opening of the article itself. The honest limit comes first: the first lines move the odds far less than the headline. On the full comparison of 33,426 articles, two things held on both outcomes: a short first sentence helps a little (1.07x), and a question in the first line hurts (0.84x on views, 0.77x on 500 likes). The rest of this skill is craft that winners used, so never promise reach from the hook.

This is the canonical, model-neutral edition. How a given AI system loads these files is the job of adapters/.

WHAT YOU NEED

Required (in this folder): rules.md, templates.md, and a LOCKED HEADLINE. Optional accelerators:

• scripts/hook_check.py renders the card and scores candidates (Python 3, standard library). Without code execution, apply THE HOOK CHECK from rules.md by hand and count the visible 130 characters yourself.
• The public dataset (shared/data/) as a swipe file of winning openings (the preview column). Without it, use templates.md only.
• A state store (state/README.md) for approved hooks, feedback and results. Only when connected.

STEP 0: LOAD (every run, in this order)

1. rules.md: how the card cuts the preview, what the full comparison measured, and the rules that follow from it.
2. templates.md: two-sentence openings that winners used, each with its measured status.
3. If the dataset is available: filter by the article's topic, then read the preview column of the top winners whose headline has the same shape as yours (the shape column).
4. If a state store is connected: the hooks the user approved, their verbatim feedback and real results. When recorded feedback and rules.md disagree, the feedback wins.

STEP 1: INTAKE

This skill expects a locked headline. If you were handed one (labelled Locked headline: by headline-writer or stated by the user), use it verbatim. If there is none, say so and run headline-writer first (or ask the user to pick one), because the hook is written against the headline.

Take the rest from the article draft and ask once only for what is genuinely missing:

• The headline's shape: how to, guide or course, receipt, announcement, or a claim.
• One concrete thing the headline did not say: a number, a name, a date or a place. Pull these from the draft.
• The reader's moment: where they are, what they're doing wrong and what it costs them.
• The topic and the case of the headline.

STEP 2: CHOOSE THE OPENING

Pair it with the headline's shape, using the pairing table in rules.md:

• how to: the old way and what it costs, with a number;
• guide or course: what's inside, in four to six nouns;
• receipt: the result and its number in the first sentence, then how it happened;
• announcement: what the thing does, in one plain sentence that names it;
• claim: the reader in a scene, or a dated event with the writer in it.

STEP 3: GENERATE

Write 8 candidates, each two sentences with a line break after the first:

• Sentence one is short and complete, six words or fewer where the material allows and never more than twelve, because that is the one opening that helped on both outcomes.
• Sentence two is longer, starts to deliver, and crosses the cut at about 130 characters, so the reader clicks to finish it.
• No question in the first line, and avoid "The" as the first word (0.87x).
• At least 2 candidates carry a number or a name that isn't in the headline, and at most 1 restates the headline.
• Keep the case of the headline, so a lowercase headline gets a lowercase hook.
• Borrow shapes from the preview column when the dataset is available: find the closest winning opening for your headline's shape and swap every slot.
• Use the article's own facts. Never invent a number, a name or a result to make the hook land.

STEP 4: SCORE

With code execution (from the repository root):

python3 skills/hook-writer/scripts/hook_check.py --headline "locked headline" "line one\nline two" "..."
python3 skills/hook-writer/scripts/hook_check.py --headline "..." --file candidates.txt
python3 skills/hook-writer/scripts/hook_check.py --headline "..." --json "line one\nline two"

In a file, put one candidate per line and use a literal \n for the line break. Per candidate it prints the rendered card (the headline plus the visible 130 characters and the "..."), the check A to J, the opening move with its measured status, penalties, and the three nearest winning openings when the dataset is present.

Without code execution: render the card yourself (headline, then the first 130 characters of the hook followed by "..."), then score the ten checks A to J from rules.md, one point each.

Drop anything under 6/10, then fix and re-score.

STEP 5: PRESENT

Show the top 4 as rendered cards, each with its score, its opening move and (when available) the winning opening it echoes with views. Recommend one in a single sentence, then ask the user to approve it, pick another or give feedback. State plainly that the hook is for the reader who already opened the article; it does not predict reach.

STEP 6: LOCK AND RECORD

• When the user approves a hook, it is LOCKED. Restate it verbatim, labelled Locked hook:. The approved hook becomes the first two lines of the article; do not change anything else in the article body unless the user asked for editing.
• If a state store is connected, record the date, headline, hook, opening move, score and why the user chose it, following shared/schemas/. Record feedback verbatim. Record views at 24 hours and 7 days when supplied.
• If no state store is connected, skip silently.

AFTER THE HOOK IS LOCKED

Run cover-writer with the locked headline and hook when the user asked for the full pipeline (see workflows/x-article-publishing.md). When they asked for the hook only, stop here.