--- name: headline-writer description: > Write, score and improve headlines for X Articles (and other long posts) with rules measured on 40,478 X Articles: 6,835 that passed 100k views and 33,643 that stayed under 100k. Use whenever you need a headline or a title, want headline options for a draft, ask which headline is stronger, or type /headline-writer. Self-learning: approved headlines, verbatim feedback and real view counts feed the banks every run. --- # HEADLINE WRITER What this is: a headline 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"). Every rule compares winners with failures from same-size accounts in the same topic, so a big account or a hot topic can't make a pattern look good. The dataset (every article over 100k views, tagged with the moves, failure marks and level used below) is at https://docs.google.com/spreadsheets/d/1GIl5AAbi5VD34plMPaeoU60zh2Q3pWfyCOKvjsTlZ4Q and as csv at https://docs.google.com/spreadsheets/d/1GIl5AAbi5VD34plMPaeoU60zh2Q3pWfyCOKvjsTlZ4Q/export?format=csv&gid=0 and every number, with the method, is in the research doc: https://docs.google.com/document/d/10UnoOKmYl0bzqpYmE2QeTlkMG8sZvU-zezulmgWfeNg ## INSTALL Save the files of this skill as ~/.claude/skills/headline-writer/ (SKILL.md, rules.md, templates.md, scripts/headline_check.py), then download the dataset next to SKILL.md: ``` curl -L -o ~/.claude/skills/headline-writer/articles_over_100k.csv "https://docs.google.com/spreadsheets/d/1GIl5AAbi5VD34plMPaeoU60zh2Q3pWfyCOKvjsTlZ4Q/export?format=csv&gid=0" mkdir -p ~/.claude/skills/headline-writer/banks && touch ~/.claude/skills/headline-writer/banks/{approved,feedback,performance}.md ``` ## STEP 0: LOAD (every run, in this order) 1. `rules.md`: the seven moves, the four failure marks, the five levels and every number behind them, which you treat as fixed. 2. `templates.md`: fill-in templates by shape, each with the moves it carries and real winners with their views. 3. `articles_over_100k.csv`, which works as the swipe file: filter by the article's topic, sort by views, and read the top winners at level L3 and L4 in that topic, then the winners from accounts under 10k followers (column followers_at_scan). The moves, failure_marks and level columns use the same definitions as rules.md. 4. `banks/approved.md`, `banks/feedback.md`, `banks/performance.md`: the headlines your user approved, their verbatim feedback and real results. When feedback and rules.md disagree, feedback wins. ## STEP 1: INTAKE (ask once for whatever is missing) - The article's promise in one sentence: "after reading this, you can ___." - The named thing readers are searching for this month: the tool, company, person or event the article is about. - Numbers that are true: results, money, counts, sample sizes. - A timeframe: how long the result took, or how long the reader needs. - Whether the article really is complete (a full guide, course, template or setup). Only a complete article may carry a completeness tag. - The topic (ai, marketing, crypto and so on) and the voice: lowercase for a personal receipt, Title Case for a guide. If you get a finished draft instead, take these from the text yourself. ## STEP 2: CHOOSE THE SHAPE Pick a shape that promises something: an announcement with "introducing" (2.16x as often), a receipt like "i built" (1.57x), a guide or course (1.54x) or a how to (1.51x). Skip the question (0.73x) and the "Label: subtitle" (0.89x). A plain statement is 53% of all headlines and reaches 100k 0.92x as often, because it names a topic and promises nothing. Use "introducing" only when you are actually launching something. ## STEP 3: GENERATE Write 10 candidates: - At least 6 come from templates.md with every slot filled truthfully. - Aim for L3 or L4: a promise shape, the named thing and one specific (a clock, a round dollar figure or a receipt), plus the completeness tag when the article is complete. - Keep every failure mark out: no question mark, no "why" or "from" opener and no "why" anywhere, no "Label:" colon, no "recap" or "weekly". - Use this month's name, and check the newest rows of your topic in the dataset for it, since the name that wins rotates every few months. - Keep the case consistent inside each candidate. - Clone a shape, never the words: find the closest winner in your topic with the same shape and swap every slot. Of 100 headlines that two or more accounts posted word for word, 50 had a copy that died under 10k views. ## STEP 4: SCORE ``` python3 ~/.claude/skills/headline-writer/scripts/headline_check.py "headline one" "headline two" python3 ~/.claude/skills/headline-writer/scripts/headline_check.py --names "jev,acme" --file candidates.txt ``` Per headline it prints the level (L0 to L4) with the moves and failure marks it found, the 10-point check A to J, a weighted score and the three nearest winners from the dataset. `--names` adds the article's own searched things to check A. Drop anything below L2 or under 5/10 on the check, then fix and re-score. The score is a floor, and a true L3 headline beats an L4 that promises more than the article delivers. ## STEP 5: PRESENT Show the top 5 as a table with the headline, its level, its moves, the score and the nearest winner it echoes (with views). Recommend one in a single sentence, then ask your user to approve it or give feedback. ## STEP 6: CLOSE THE LOOP (every run) - Approved: append to `banks/approved.md` the date, topic, headline, level, moves and why your user chose it. - Feedback: append your user's words verbatim to `banks/feedback.md` with the date and the rule you take from them, then apply that rule in the next round. - Views at 24 hours and at 7 days: append to `banks/performance.md`. Every 10 entries, compare levels with views and write one line of learning into `banks/feedback.md`. - When the dataset updates, download the csv again. ## AFTER THE HEADLINE IS LOCKED Run hook-writer against the locked headline, because the first two lines of the article sit on the card right under it.