--- name: x-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, or ask which headline is stronger. ChatGPT edition, generated from the model-neutral canonical skill: works in any AI system that can read these files; scripts and the dataset are optional accelerators, not requirements. version: 1.0.0 source: "research and original skill by @fuckgrowth (Sep 2026); see SOURCES.md" toolkit: x-article-toolkit generated_from: skills/headline-writer/SKILL.md adapter: chatgpt --- # 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) and the research doc with every number and the method are linked in `references/SOURCES.md`. This is the canonical, model-neutral edition. It describes WHAT to do; this copy is the ChatGPT adapter edition; see the runtime notes at the end. Nothing here depends on a particular model, a particular folder on disk or the ability to run code. ## WHAT YOU NEED Required (in `references/`): `references/rules.md`, `references/templates.md`. Optional accelerators: - `scripts/headline_check.py` (only if this ChatGPT surface can run Python; see the runtime notes) scores candidates mechanically (Python 3, standard library). If you cannot run code, apply THE HEADLINE CHECK and the level definitions from `references/rules.md` by hand; they are written so a reader can score without the script. - The public dataset (not bundled; see `references/DATASET.md`) works as a swipe file and powers "nearest winners". Without it, skip the swipe-file step and the nearest-winner column; every rule still applies. - A state store (`references/STATE.md`) holding the user's approved headlines, feedback and results. Only read and write it when one is connected; never claim learning from files that aren't there. ## STEP 0: LOAD (every run, in this order) 1. `references/rules.md`: the seven moves, the four failure marks, the five levels and every number behind them, which you treat as fixed. 2. `references/templates.md`: fill-in templates by shape, each with the moves it carries and real winners with their views. 3. If the dataset is available: 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 `references/rules.md`. 4. If a state store is connected: the headlines the user approved, their verbatim feedback and real results. When the user's recorded feedback and `references/rules.md` disagree, the user's feedback wins. ## STEP 1: INTAKE Accept either a finished draft or structured notes about the article. If you get a finished draft, take everything below from the text yourself and ask nothing unless something is genuinely unknowable from the draft (typically only the completeness question and the voice). Do not interrogate the user about things the draft already answers. What you need, from the draft or from the user (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. ## 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 `references/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 when the dataset is available check the newest rows of your topic for it, since the name that wins rotates every few months. When it isn't available, say which name you assumed and why. - 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 With code execution, if available in this ChatGPT surface: ``` python3 scripts/headline_check.py "headline one" "headline two" python3 scripts/headline_check.py --names "jev,acme" --file candidates.txt python3 scripts/headline_check.py --json "headline one" # machine-readable, for adapters and state ``` 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, when the dataset is present, the three nearest winners. `--names` adds the article's own searched things to check A. Without code execution: for each candidate, count the move families and failure marks using the definitions in `references/rules.md` to get the level, then score the ten checks A to J listed under THE HEADLINE CHECK in `references/rules.md`, one point each. Report both. 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 (when available) the nearest winner it echoes with its views. Explain the relevant rules in one or two sentences, not a lecture. Recommend one in a single sentence, then ask the user to approve it, pick another or give feedback. ## STEP 6: LOCK AND RECORD - When the user approves a headline, it is LOCKED. Restate it verbatim and label it `Locked headline:` so a later step (hook-writer, cover-writer, the publishing package) can pick it up unchanged. - If a state store is connected, record the date, topic, locked headline, its level and moves, the alternatives shown, and why the user chose it, following the schema in `references/schemas/`. Record feedback verbatim with the rule you take from it. Record views at 24 hours and 7 days when the user supplies them. - If no state store is connected, skip this step silently. Do not describe the toolkit as learning or remembering. ## 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. Only continue automatically when the user asked for the full pipeline (see `references/workflow.md`); when they asked for headlines only, stop here. ## CHATGPT RUNTIME NOTES (adapter layer; not part of the methodology) This package was generated from the canonical skill `skills/headline-writer/` in the x-article-toolkit repository (https://github.com/kenashe/x-article-toolkit). The repository is the source of truth; if this file and the repository disagree, the repository wins and this package should be rebuilt with `adapters/chatgpt/build.py`. What is different in ChatGPT: - **Files.** The rule files are in `references/` of this skill package. Read `references/rules.md` and `references/templates.md` before writing. - **Scripts.** `scripts/headline_check.py` is included for environments where ChatGPT can execute Python. Do not assume it can: when you cannot run code, score by hand using the check lists in the references (they are written for that) and say "scored by hand" in your output. Never report a script score you did not compute. - **Dataset.** The public dataset is NOT bundled (3.5 MB, external, see `references/DATASET.md`). Without it, skip the swipe-file steps and the "nearest winners" column. If the user uploads `articles_over_100k.csv` to the conversation and code execution is available, pass it with `--data`. - **State.** Assume no persistent store. Do not claim to remember approved headlines, feedback or results from earlier conversations. Carry locks verbatim within the conversation (`Locked headline:`, `Locked hook:`, `Locked cover:`). If the user keeps their own records (a spreadsheet), they will paste what matters. - **Other stages.** This package is one stage. The sibling skills are `x-headline-writer`, `x-hook-writer` and `x-cover-writer`; the full pipeline is described in `references/workflow.md`. Run only the stage the user asked for unless they asked for the whole pipeline. - **Images.** Do not generate or measure cover images unless the user asks and the surface supports it; the brief, cover text, prompt and specs are the deliverable.