cover-writer git:20261002.3d8f8f0A

Immutable. This exact content never changes and is served at /api/v1/blob/f20023ae21242f3d.

---
name: cover-writer
description: Brief, generate and score the cover image of an X Article (the 1200 x 480 card image) using a study of 1,391 covers from X Articles over 300k views. Use for any X Article cover, card image or thumbnail, after the headline and the hook are locked.
---
 
# COVER WRITER
 
What this is: a Claude skill built from a study of X Article covers (research by @fuckgrowth, Sep 2026). It turns the study into a procedure: decide whether the article needs a cover at all, pick one of ten briefs, write the cover sentence, generate the image, measure it with a script, present it and learn from how it did. The study looked at 1,391 covers of X Articles over 300k views in the core topics, posted January to September 2026, so every number in it compares articles that did well with articles that did great. The public dataset of every X Article over 100k views, with a cover_image column, is at https://docs.google.com/spreadsheets/d/1GIl5AAbi5VD34plMPaeoU60zh2Q3pWfyCOKvjsTlZ4Q and the headline research is at https://docs.google.com/document/d/10UnoOKmYl0bzqpYmE2QeTlkMG8sZvU-zezulmgWfeNg . The skill runs after headline-writer and hook-writer, because the cover repeats the headline.
 
## INSTALL
1. Save this folder as `~/.claude/skills/cover-writer/` with `SKILL.md`, `rules.md`, `briefs.md`, `scripts/cover_check.py` and `tools/visionscan.swift`.
2. Install Pillow for the pixel checks with `pip3 install pillow`.
3. Optional on macOS: compile the Apple Vision helper that reads the words on a cover and counts faces:
   `swiftc -O ~/.claude/skills/cover-writer/tools/visionscan.swift -o ~/.claude/skills/cover-writer/tools/visionscan`
   Without it (or on another operating system) the OCR and face checks are skipped, and the script scores the cover text you pass with `--text`.
4. Optional: export the dataset above as CSV and save it as `~/.claude/skills/cover-writer/data/articles_over_100k.csv` (or pass `--data path.csv`), and the check also prints the three 1M+ articles whose headlines share the most words with yours, with their cover image links.
5. Create three empty files the skill fills over time: `banks/approved.md`, `banks/feedback.md` and `banks/performance.md`.
 
## STEP 0: LOAD (every invocation, in this order)
1. `rules.md`, the 14 rules with their numbers, which every brief has to follow.
2. `briefs.md`, the 10 cover briefs (A to J) with specs, prompt templates and the proven covers behind each one.
3. `banks/approved.md`, `banks/feedback.md` and `banks/performance.md`, your own approved covers, feedback and results; when your feedback and a general rule disagree, your feedback wins.
4. The locked headline and hook of this article, since the cover repeats the headline and cannot be briefed without it.
For more examples, open the dataset, filter by topic, sort by views and look at the cover_image links of the top rows.
House style: no em dashes on the cover, no hype and no author headshots.
 
## STEP 1: INTAKE (ask only for what is missing, in one message)
- The locked headline (Rule 4 needs its nouns) and the topic.
- The article's shape, which picks the brief: steps, parts of one thing, a system or operation, a combination with a result, a dataset or an idea piece.
- Named things and exact numbers that appear in the headline or hook (a name, a $ figure, a count).
- What real material exists: collected data for a chart, a real dashboard with a legible number for a proof screenshot, a brand logo and colour.
- Who posts it, because the voice decides handwriting against clean type and lowercase against sentence case.
- Time and tools available: hand-drawn, Figma, an image model or none, and "none" is a valid answer (Rule 1).
 
## STEP 2: DECIDE COVER OR NO COVER (Rule 1)
If none of the four winning formats (diagram, sentence text card, drawn illustration, chart) or a proof screenshot can be made, recommend posting without a cover and stop there. Say it plainly: articles without a cover passed 1M 42% of the time against 39% for articles with one, and a doodle, a render or a stock photo does worse than no cover.
 
## STEP 3: PICK THE BRIEF
Map the article's shape to briefs.md:
- steps or a setup -> A Numbered flow
- a combination with a result -> B Equation
- parts of one thing -> C Anatomy
- how a system or operation works -> D System map (the default for breakdowns of a company's marketing)
- one tool with many jobs -> E Hub and spokes
- no visual and no time -> F Sentence card
- a build with parts and costs -> G Annotated infographic
- real collected numbers -> H One-shape chart
- proof that is a number inside a real UI -> I Proof screenshot
- ideas or self-improvement -> J Engraving
Pick one primary brief and one alternate, and in Marketing never default to a screenshot (Rule 12).
 
## STEP 4: WRITE THE COVER TEXT (Rules 3, 4, 5, 6)
Write one sentence of 8 to 20 words that restates the headline: keep the name and the number, and drop the verb and the completeness tag. Aim for 50 to 80% word overlap with the headline, name the tool or company in words, and put the $ figure or the count on the cover in large type. Score the plan before any image exists:
```
python3 ~/.claude/skills/cover-writer/scripts/cover_check.py --headline "..." --text "cover sentence" --type diagram
```
 
## STEP 5: GENERATE
Produce the image at exactly 1200 x 480. Use a white, off-white or paper background, charcoal lines and type, and one accent colour in one place (Rule 7). With an image model, use the prompt template of the chosen brief in briefs.md and set the text yourself afterwards, because models misspell. Never use doodles, mascots, lightbulbs, rockets, brains, glows, purple-cyan gradients, headshots, desks, laptops or stock photos (Rules 7 to 11).
 
## STEP 6: MEASURE
```
python3 ~/.claude/skills/cover-writer/scripts/cover_check.py --headline "..." --type diagram path/to/cover.jpg
python3 ~/.claude/skills/cover-writer/scripts/cover_check.py --headline "..." --text "the words on the cover" --type diagram cover.jpg
```
The second form is for machines without visionscan. The script reads the words and faces on the image when visionscan is compiled, measures the pixels (brightness, saturation, gray share, dominant colour, size), runs the 10 checks A to J and prints the score with the rule behind every failed check. A score of 8 or more is ready to post, 6 or 7 means fixing the failing checks first, and under 6 means fixing it or posting without a cover.
Values for `--type`: diagram, text_card, illustration, chart, meme_collage and screenshot_proof are winning formats; screenshot and logo_brand are neutral; ai_art, photo, sketch, product_shot and other are losing formats.
 
## STEP 7: PRESENT
Show the recommended brief and its alternate, the cover sentence with its overlap percentage, the check score with any fails, and the two closest proven covers from briefs.md or the dataset. Say in one sentence why this brief wins, then ask for approval or feedback.
 
## STEP 8: CLOSE THE LOOP (every run)
- Approved cover: append to `banks/approved.md` the date, topic, headline, brief letter, cover text, score, file path and why it was chosen.
- Feedback: append it word for word to `banks/feedback.md` with the date and the rule you took from it, then apply it to the next round.
- Views at 24 hours and 7 days: append them to `banks/performance.md`, and every 10 entries compare the scores with the views and write one line of learning into `banks/feedback.md` under PERFORMANCE LESSONS.