engagement-prediction
Scores draft tweets and threads on a 1-100 scale with per-dimension breakdown and improvement suggestions. Use when the user asks to score a tweet, predict engagement, rate a tweet, estimate impressions, or wants to know if a draft will perform well on X/Twitter.
Engagement Prediction Skill
You are an expert X/Twitter engagement analyst. Your job is to score a draft tweet or thread on a 0-100 scale, provide a per-dimension breakdown, estimate impressions, and give actionable improvement suggestions.
Step 1: Accept the Draft Tweet
The user's draft tweet is provided via $ARGUMENTS. If $ARGUMENTS is empty or missing, ask the user to provide the tweet text they want scored.
If the user also specifies a follower count, extract it. Otherwise default to 1000 followers.
Step 2: Run the Structural Scoring Script
Execute the scoring engine to get a quantitative baseline:
python ${CLAUDE_SKILL_DIR}/scripts/predict_engagement.py "$ARGUMENTS" [follower_count]
Parse the script output to get the structural analysis scores. This gives you the mechanical scoring based on pattern detection, length analysis, keyword matching, and algorithm weight modeling.
Step 3: Apply Qualitative Assessment
The script handles structural signals, but you must layer on qualitative judgment that code cannot capture. Evaluate these three qualitative dimensions and use them to adjust the structural scores up or down by a few points per dimension:
Content Originality Assessment
Ask yourself: Is this a fresh take, or is it something hundreds of accounts post daily?
Indicators of HIGH originality (adjust scores up by 1-3 points per dimension):
- Specific personal experience with concrete details (dates, numbers, project names)
- A non-obvious connection between two ideas most people would not link
- Original data, benchmarks, or measurements the author ran themselves
- A contrarian position backed by reasoning, not just stated for shock value
- Real code snippets from an actual project, not generic "Hello World" examples
Indicators of LOW originality (adjust scores down by 1-3 points per dimension):
- Generic motivational advice ("just ship it", "consistency is key")
- Restating well-known best practices without adding new context
- Vague claims without specifics ("this tool changed my life")
- Engagement-farming formats copied verbatim from viral templates
- AI-generated feel: overly polished, no rough edges, no specific details
Timing Relevance Assessment
Consider whether the tweet connects to current events, trends, or conversations in the developer community:
HIGH timing relevance (boost Hook Strength and Share Potential by 1-3 points):
- References a tool, framework, or service that launched or had news in the last 48 hours
- Connects to an ongoing community debate or controversy
- Relates to a seasonal pattern (hiring seasons, conference season, year-end retrospectives)
- Responds to a viral tweet or trending topic with a unique angle
LOW timing relevance (no adjustment needed, this is the baseline):
- Evergreen content with no time hook
- References outdated trends or tools that peaked months ago
Voice Authenticity Assessment
Does this sound like a real person with opinions, or a content-generation machine?
HIGH authenticity (boost Audience Match and Reply Potential by 1-2 points):
- Uses natural language with personality (mild humor, self-deprecation, genuine excitement)
- Includes qualifiers and nuance ("mostly", "in my experience", "your mileage may vary")
- Has a clear point of view that not everyone would agree with
- Specific enough that you can tell the author actually did/experienced what they describe
LOW authenticity (reduce Algorithm Fit and Audience Match by 1-3 points):
- Reads like a press release or marketing copy
- Every sentence is perfectly structured with no conversational flow
- Uses corporate buzzwords without substance
- Could have been written by anyone about anything with search-and-replace on the topic
Step 4: Compare Against Benchmarks
Load the benchmark data from references/benchmarks.md and compare the tweet's predicted performance against the user's follower bracket.
Determine:
- Which follower bracket the user falls into
- Whether the predicted score is above or below the median for that bracket
- Whether the tweet has potential to reach the top 10% threshold
- What the "viral" threshold is for their bracket size
Step 5: Generate the Scorecard
Output a complete scorecard in this exact format:
== ENGAGEMENT PREDICTION SCORECARD ==
Draft: "[first 80 chars of tweet]..."
TOTAL SCORE: [0-100] / 100 [Rating Label]
--- Per-Dimension Breakdown ---
Hook Strength: [0-20] / 20 [one-line explanation]
Reply Potential: [0-20] / 20 [one-line explanation]
Share Potential: [0-20] / 20 [one-line explanation]
Save Potential: [0-15] / 15 [one-line explanation]
Algorithm Fit: [0-15] / 15 [one-line explanation]
Audience Match: [0-10] / 10 [one-line explanation]
--- Impression Estimate ---
Follower count: [N]
Estimated range: [low] - [high] impressions
Bracket benchmark: [median for bracket] (your score is [above/below] average)
Top 10% threshold: [threshold for bracket]
--- Top 3 Improvements ---
1. [Specific action] — [Why this matters, referencing algorithm weights]
2. [Specific action] — [Why this matters, referencing algorithm weights]
3. [Specific action] — [Why this matters, referencing algorithm weights]
--- Verdict ---
[2-3 sentence summary of overall assessment and single most impactful change]
Rating Labels
Use these labels based on total score:
| Score Range | Label |
|---|---|
| 85-100 | Excellent — high viral potential |
| 70-84 | Strong — well above average engagement expected |
| 55-69 | Good — solid engagement expected |
| 40-54 | Below Average — needs optimization before posting |
| 25-39 | Weak — significant improvements needed |
| 0-24 | Poor — complete rework recommended |
Scoring Rubric: Hook Strength (0-20)
This measures how effectively the first line stops the scroll.
16-20 (Exceptional hook):
- Opens with a specific, surprising data point or personal result
- Creates an immediate curiosity gap that demands reading more
- Uses a proven hook pattern (contrarian take, story opener, numbered list) with original content
- First line is under 100 characters for maximum above-the-fold visibility
11-15 (Good hook):
- Has a clear hook pattern but execution is average
- Opens with something interesting but not scroll-stopping
- Decent curiosity element but somewhat predictable
6-10 (Mediocre hook):
- Starts with context or background instead of the payoff
- Generic opener that could apply to thousands of tweets
- No curiosity gap or reason to keep reading
0-5 (No hook):
- Starts with "I think" or similar weak opener
- Buries the interesting part after the first line
- Reads like the middle of a conversation, not the start
Scoring Rubric: Reply Potential (0-20)
Replies carry the highest engagement weight in the algorithm (54x multiplier).
16-20 (Reply magnet):
- Contains a clear, debatable opinion that informed people could disagree on
- Asks a specific question that has multiple valid answers
- Makes a claim with enough specificity that people want to add their experience
- Invites "what about X?" responses naturally
11-15 (Likely replies):
- Has an opinion but it is fairly mainstream
- Contains a question but it is somewhat open-ended
- People might reply but are not compelled to
6-10 (Few replies):
- Informational content with no discussion prompt
- States facts without inviting perspective
- Question is rhetorical or has an obvious answer
0-5 (No reply incentive):
- Pure announcement with nothing to discuss
- So generic that nobody feels the need to respond
- Engagement bait that people actively avoid replying to
Scoring Rubric: Share Potential (0-20)
Shares (retweets and quote tweets) carry 20x weight and dramatically expand reach.
16-20 (Highly shareable):
- Contains a framework, mental model, or insight people want to be associated with sharing
- Includes original data, benchmarks, or results that are useful to reference
- Quotable — can stand on its own without context
- Valuable enough that sharing it makes the sharer look smart
11-15 (Moderately shareable):
- Contains useful information but framing is not particularly quotable
- Good content but sharing it does not enhance the sharer's reputation
- Would get shared by close followers but not widely
6-10 (Low shareability):
- Too personal or specific to the author's situation
- Content is fine but there is no "I need others to see this" impulse
- Missing the "social currency" element
0-5 (Not shareable):
- Inside joke or context-dependent content
- Too generic to be worth sharing
- Controversial in a way that makes sharing risky
Scoring Rubric: Save Potential (0-15)
Bookmarks carry 40x weight — the second highest signal after replies.
12-15 (High save value):
- Contains a code snippet, command, or configuration someone would reference later
- Lists resources, tools, or links worth coming back to
- Step-by-step instructions or a reusable framework
- Reference material (cheat sheet, comparison, benchmark data)
8-11 (Moderate save value):
- Contains one useful tip worth remembering
- Has a good insight but not something you need to reference again
- Useful in the moment but not reference-worthy
4-7 (Low save value):
- Interesting to read but nothing to come back to
- Opinion or commentary without actionable takeaways
- Entertaining but not utilitarian
0-3 (No save value):
- Pure opinion with no reference value
- Announcement that is time-sensitive and expires
- Conversational tweet with no lasting utility
Scoring Rubric: Algorithm Fit (0-15)
How well the tweet is optimized for X's ranking algorithm signals.
12-15 (Algorithm-optimized):
- Optimal length (71-240 characters for single tweet)
- No external links (or links moved to reply)
- 0-2 relevant hashtags maximum
- Media indicator present (image, video, code screenshot)
- No engagement bait patterns
- Clean formatting that encourages dwell time
8-11 (Mostly aligned):
- Acceptable length but not in the sweet spot
- Minor algorithm friction (one hashtag too many, slightly long)
- No major penalties triggered
4-7 (Algorithm friction):
- External link in the main tweet body
- Too many hashtags (3+)
- Very short tweet that gets scrolled past quickly
- Formatting issues that reduce dwell time
0-3 (Algorithm hostile):
- Engagement bait phrases that trigger suppression
- Multiple external links
- Excessive hashtags (5+)
- Extremely short tweet with no stopping power
Scoring Rubric: Audience Match (0-10)
How well the content targets the developer audience on X.
8-10 (Perfect audience fit):
- Uses specific technical vocabulary (language names, framework names, tool names)
- Addresses a pain point developers actually experience
- References the dev workflow or toolchain directly
- Speaks the community's language naturally
5-7 (Good audience fit):
- Clearly tech-related but somewhat generic
- Uses some technical terms but could be more specific
- Relevant to developers but also to a broader audience
2-4 (Weak audience fit):
- Tangentially related to tech
- Uses business or marketing language instead of dev language
- Topic is relevant but framing does not resonate with developers
0-1 (No audience fit):
- Not developer-related content
- Generic life advice or motivation with no tech angle
- Content that would perform the same in any niche
Thread Scoring Adjustments
When scoring a thread (multiple tweets separated by line breaks or numbered):
- Score the first tweet as the "hook tweet" — it carries 60% of the total impression weight
- Evaluate the thread arc: does it build, or does it repeat the same point?
- Check for a strong closing tweet with a CTA or summary
- Optimal thread length: 3-7 tweets for developer content
- Each tweet in the thread should be independently valuable, not just filler
Adjust scores:
- Strong thread arc with clear progression: +3 to Share Potential, +2 to Save Potential
- Weak thread that could be a single tweet: -5 to Algorithm Fit, -3 to Share Potential
- Thread over 10 tweets without exceptional depth: -3 to Algorithm Fit
- Thread with a resource list or code walkthrough: +3 to Save Potential
Example Scorecards
Example 1: Weak Tweet (Score ~30)
Draft: "Just started learning React. It's pretty cool! #react #javascript #webdev #coding #frontend #programming"
== ENGAGEMENT PREDICTION SCORECARD ==
Draft: "Just started learning React. It's pretty cool! #react #javascript ..."
TOTAL SCORE: 28 / 100 Weak — significant improvements needed
--- Per-Dimension Breakdown ---
Hook Strength: 3 / 20 Generic opener with no curiosity gap or specific detail
Reply Potential: 2 / 20 No question, no opinion, nothing to respond to
Share Potential: 2 / 20 No insight or value that makes someone want to share
Save Potential: 1 / 15 Nothing to bookmark or reference later
Algorithm Fit: 6 / 15 Six hashtags triggers heavy penalty; tweet is too short
Audience Match: 6 / 10 Mentions React and JavaScript but adds no substance
--- Impression Estimate ---
Follower count: 1,000
Estimated range: 400 - 900 impressions
Bracket benchmark: 800 median (your score is below average)
Top 10% threshold: 3,200 impressions
--- Top 3 Improvements ---
1. Share a specific thing you learned — "I just learned React re-renders
on every state change, not just when the value is different" drives
replies from people who want to add nuance (reply weight: 54x).
2. Cut hashtags to 2 maximum — you have 6, and each excess hashtag
adds a -10x penalty in the algorithm scoring.
3. Add a question to drive replies — "What surprised you most when you
first learned React?" gives people a reason to engage.
--- Verdict ---
This tweet has no hook, no value, and heavy algorithm penalties from
excessive hashtags. The single most impactful change: replace the generic
reaction with one specific thing you learned about React and ask others
to share their experience.
Example 2: Average Tweet (Score ~55)
Draft: "After mass-migrating 200+ components from class components to hooks, here's what I learned: useState is not always the answer. useReducer saved us from 3 major state bugs. Don't mass-migrate — do it incrementally."
== ENGAGEMENT PREDICTION SCORECARD ==
Draft: "After mass-migrating 200+ components from class components to hooks..."
TOTAL SCORE: 57 / 100 Good — solid engagement expected
--- Per-Dimension Breakdown ---
Hook Strength: 14 / 20 Strong story opener with specific numbers (200+), creates curiosity
Reply Potential: 10 / 20 Opinionated stance on useState vs useReducer invites debate
Share Potential: 12 / 20 Practical migration lesson with specific takeaway, quotable
Save Potential: 8 / 15 Has actionable advice but lacks a reference-worthy code snippet
Algorithm Fit: 10 / 15 Good length, no links or excess hashtags, clean formatting
Audience Match: 8 / 10 React hooks, useState, useReducer — strong dev vocabulary
--- Impression Estimate ---
Follower count: 1,000
Estimated range: 1,200 - 4,500 impressions
Bracket benchmark: 800 median (your score is above average)
Top 10% threshold: 3,200 impressions
--- Top 3 Improvements ---
1. Add a direct question at the end — "Have you done a similar migration?
What surprised you?" would push Reply Potential from 10 to 15+
(replies are the 54x signal).
2. Include a before/after code snippet showing the useReducer fix —
code screenshots drive bookmarks (40x weight) and would push Save
Potential from 8 to 12+.
3. Consider making this a 3-tweet thread — the migration story has
enough depth for a thread arc which would boost Share Potential
and Algorithm Fit.
--- Verdict ---
Solid tweet with a strong hook and real experience backing the claims.
The specific numbers (200+ components, 3 bugs) add credibility. The
single most impactful change: add a question at the end to convert
readers into repliers, since replies carry the highest algorithm weight.
Example 3: Strong Tweet (Score ~85)
Draft: "I analyzed 50,000 GitHub PRs to find what actually gets merged fast.\n\nThe data surprised me:\n\n- PRs under 200 lines: 89% merged in <24h\n- PRs over 500 lines: only 34% merged in a week\n- Adding screenshots to PR description: 2.3x faster review\n- PRs with failing CI: 12x more likely to be abandoned\n\nThe biggest factor wasn't code quality. It was PR size.\n\nSmall PRs are a superpower. Here's the framework I now use for every PR I submit (saved me ~5h/week in review cycles):"
== ENGAGEMENT PREDICTION SCORECARD ==
Draft: "I analyzed 50,000 GitHub PRs to find what actually gets merged fast..."
TOTAL SCORE: 84 / 100 Strong — well above average engagement expected
--- Per-Dimension Breakdown ---
Hook Strength: 19 / 20 "I analyzed 50,000" is a data-lead story opener with massive
curiosity gap; specific number signals real research
Reply Potential: 16 / 20 Debatable claims backed by data invite "but what about..."
responses; developers love arguing about PR practices
Share Potential: 18 / 20 Original data that makes sharers look informed; quotable
stats people will reference in their own discussions
Save Potential: 13 / 15 Framework promise + specific data points worth bookmarking;
would score 15 if the actual framework were included
Algorithm Fit: 12 / 15 Clean formatting, list structure drives dwell time, no links
or hashtag penalties, good length for a thread opener
Audience Match: 10 / 10 GitHub, PRs, CI, code review — perfectly targeted at the
developer audience with language they use daily
--- Impression Estimate ---
Follower count: 1,000
Estimated range: 2,800 - 9,600 impressions
Bracket benchmark: 800 median (your score is well above average)
Top 10% threshold: 3,200 impressions (this tweet should exceed it)
--- Top 3 Improvements ---
1. Deliver on the framework promise — the thread continuation needs to
include the actual framework with specific steps, not just the data.
Unfulfilled promises tank trust and future engagement.
2. Add an image or chart visualizing the PR size vs merge time data —
media attachments get a 2x algorithm boost and data visualizations
are highly shareable.
3. End the thread with a concrete question — "What's your PR size
cutoff?" to capture replies from the large audience this will reach.
--- Verdict ---
This is a strong tweet with original data, excellent hook, and high
shareability. The specific numbers create credibility and the list
format drives dwell time. The single most impactful addition: include
a data visualization chart as media, which would push this into the
85-90 range with both algorithm boost and increased save/share rates.
Important Guidelines
- Always run the script first for the structural baseline, then adjust with qualitative judgment
- Never inflate scores to be nice — honest scoring helps the user improve
- When the script output and your qualitative assessment conflict, explain why you are adjusting
- Always provide exactly 3 improvement suggestions, ordered by impact
- Frame improvements in terms of algorithm weights (e.g., "replies carry 54x weight") so the user understands the reasoning
- If the user provides a thread, score the hook tweet individually AND the thread as a whole
- If the tweet is clearly not developer-focused content, still score it but note the audience mismatch
- Reference the scoring model in
references/scoring-model.mdfor detailed dimension explanations - Reference benchmarks in
references/benchmarks.mdfor follower bracket comparisons