Pull tweet performance data, calculate growth, find patterns, and give executable directions for next week.Data-driven, no guessing.
Upgrade content review for a personal X account from "posted it and that's it, guessing which one will blow up" to "pull data every week, find reproducible patterns, and use patterns to set next week's direction." The value of this skill is not in beautiful number tables, but in reading from the numberswhat to do next。
Usage
/ray-metrics # 默认:本账号近 7 天周报
/ray-metrics @youraccount # 指定 handle
/ray-metrics @youraccount 30d # 近 30 天,含周环比对比
/ray-metrics 6/28-7/4 # 指定时间窗
If no handle is given, use the default account (ask the user, or read the last record). The default time window is "last 7 days vs the previous 7 days" so week-over-week changes can be calculated.
Iron rule: Data is either real, or explicitly stated as unavailable
This is at the very top because it is the only thing this skill cannot violate.xapi is unstable (common transport error / timeout / empty return). If any step fails to pull data, do not use estimated values, past impressions, or "reasonable guesses" to fill the gap and pass them off as real data. If it cannot be pulled, use the fallback in Step 1b and mark the gap truthfully in the report. An honest "half a table + gap explanation" is a hundred times more valuable than a polished "complete weekly report"—the latter will make you set the wrong direction based on fake data.
Step 1: Pull data
1a. Normal path (xapi reachable)
First get the user id and account-level metrics:
mcp__xapi__get_users_by_username(
username="youraccount",
user.fields="public_metrics,created_at,description"
)
→ 拿到 id、followers_count、following_count、tweet_count
Use the id to pull tweets within the time window (including each tweet's public_metrics):
mcp__xapi__get_users_posts(
id="<上一步的 id>",
max_results=100, # 单页上限 100,不够就翻 pagination_token
start_time="2026-06-28T00:00:00Z", # 近 14 天,ISO 8601 UTC,覆盖本周+上周
end_time="2026-07-12T00:00:00Z",
exclude="retweets", # 默认排除转推;是否含 replies 见下
post.fields="created_at,public_metrics,text,referenced_tweets"
)
Key points:
- Pull 14 days(this week + last week), split into two segments by created_at to calculate week-over-week changes.
exclude="retweets": retweets are not your own output.Replies are kept by default but categorized separately—the spread logic of pure replies differs from original tweets, and mixing them into averages will pollute attribution.- A single account's tweet timeline can go back about 3,200 tweets at most; a recent window is enough.
- Each
public_metricsincludes impression_count / like_count / retweet_count / reply_count / quote_count / bookmark_count.Note that impression_count is only available on your own account's tweets, and is subject to time window limits—see references/metrics-glossary.md for definition details. - Use
search_posts_all(query="from:youraccount")for cross-validation or to fill in history, but full-archive search is permission-sensitive and failures are normal; don't treat it as the main path.
1b. Fallback (xapi unreachable)
If any of the above calls errors out, times out, or returns something clearly incomplete,stop, do not pretend you pulled it. Tell the user truthfully and offer alternative paths:
- Have the user export CSV (preferred): X → Premium/Analytics → export a tweet-level CSV by time range, and give you the file path. For the mapping from CSV column names to metrics, see references/metrics-glossary.md. Once obtained, you can run Steps 2-4 as usual.
- Browser read: If the browser MCP is installed, open
x.com/i/account_analytics's Content page and read the table numbers by time window (suitable for a small number of tweets or when export is unavailable). - Degraded delivery: The user may also have screenshots/numbers of a few key tweets—clearly label "Data source = manually provided by user"; when the sample is small, handle it according to the minimum sample rule in Step 3.
Whichever fallback is used, the report must state clearly at the beginningthe actual data source, without ambiguity.
Step 2: Calculate—growth and distribution
With the raw tweet array, calculate the following (for the unified calculation basis, engagement rate formula, and impression definition, see references/metrics-glossary.md; read it when executing this step or when encountering missing fields):
- Account-level week-over-week: This week vs. last week's net follower growth, total impressions, total engagement, and number of tweets posted. Give absolute values + percentages.
- Per-tweet engagement rate: For each
(like+RT+reply+quote+bookmark) / impression. Engagement rate compares better across "big and small tweets" than absolute like counts—a tweet with 500 impressions and 50 likes may be more worth replicating than one with 50,000 impressions and 200 likes. - Top 3 / Bottom 3: Rank once by impressions and once by engagement rate (the two lists are often different, and the difference itself is a clue).
- Sense of distribution: Is this week "one viral hit lifting everything" or "a broad, even rise"? How far apart are the median and the mean? This determines whether attribution should look at a single point or at the whole surface.
Step 3: Attribution—find reproducible patterns, not a story invented for a single chance hit
This is the step where the whole skill is most likely to go off the rails. The goal is to findpatterns that can be copied next week, not to invent a pleasant explanation after the fact for a viral hit that already happened.
Bucket this week's tweets (and, if necessary, the past 30 days) by these dimensions, and see which bucket'smedian engagement rateis clearly higher:
| Dimension | Bucket examples | What to look at |
|---|---|---|
| Voice | Substance/opinion/build-in-public/casual interaction | Which voice has a high median engagement rate, and which is diluting |
| Topic | AI Agent / going global / infrastructure / meta-reflection… | Which topic brings volume, and which is self-indulgent |
| Hook form | Number opening/counterintuitive assertion/question/showing results/list format | Which opening keeps people around |
| Posting time slot | By created_at, split into morning/noon/evening × weekday/weekend | Whether there is a stable peak time slot |
| Format | Single tweet/long tweet/with image/with link/thread first tweet | Whether images increase performance, and whether adding links decreases it |
Minimum sample discipline (hard requirement): Fewer than 2-3 tweets in a bucket is not enough to call it a "pattern"—that is noise. When the sample is insufficient, honestly say "this week's data volume does not support attribution on dimension X," and givehow much data needs to be collected to be enough(for example, "run for another two weeks, or post at least 3 tweets for each voice"), rather than forcing a plausible-looking pattern out of 2 tweets. Better to report only one "the only significant outlier this week is this one; the reason remains to be verified" than to pretend to have seen through everything.
For a viral hit to become a "pattern," it must meet at least one of these: ① the same type has repeated in the past; ② there is a clear mechanism explanation and it can be falsified in advance. If it appears only once and has no mechanism, mark it as "to be verified," list it among the hypotheses to test next week, and do not write it into the conclusions.
Step 4: Recommendations for next week—2-3 executable actions
Attribution lands on actions. Each recommendation is anexecutable, verifiableactions, not correct-but-empty platitudes like "post more high-quality content." Use the three categories "Scale / Stop / Test":
- Scale: double down on validated patterns. Example: "The build-in-public segment's median engagement rate is 2.1x the account average; next week, go from 1 to 3 posts."
- Stop: stop or rework whatever keeps dragging things down. Example: "All 4 pure reposts with a one-line comment have the lowest engagement; stop next week, and if you want to repost, rewrite it as a tweet with your own take."
- Test: design "to-be-validated" hypotheses as falsifiable experiments. Example: "Suspect 9-11 PM is the peak; next week, post 3 tweets of the same type at this fixed time slot and compare against other time slots to validate."
Boundary — no ghostwriting: Recommendations go as far as "direction + format + hypotheses to test" — that's analysis output and can be delivered in full. Butdon't write the actual tweet copy for the author here— that involves the author's external voice. If a recommendation needs an example tweet, give only the structural skeleton with blanks:【你的话:____】, leaving the flesh to the author.
Step 5: Output — structured weekly report
# X 数据周报 · @<handle>
数据来源:<xapi 实时 / 用户导出CSV / 手工提供> | 抓取时间窗:<本周 6/28–7/4> vs <上周 6/21–6/27> | 生成于:<时间>
## 一、账号大盘(周环比)
| 指标 | 本周 | 上周 | 环比 |
|---|---|---|---|
| 净增粉 | … | … | +X% |
| 总曝光 | … | … | … |
| 总互动 | … | … | … |
| 发推数 | … | … | … |
| 均互动率 | … | … | … |
## 二、Top / Bottom
- 🔥 Top(按互动率):<推文摘要> — 曝光X / 互动率Y% — 为什么好:<归因>
- 🧊 Bottom:<推文摘要> — 为什么差:<归因>
（曝光榜与互动率榜不一致时,两个都列并点出差异)
## 三、规律(可复现的才写这里)
- <维度>:<哪个桶显著高/低,附样本数> → <可复制的规律>
- 待验证假设:<只出现一次、机制未证的,列这里,进下周去测>
## 四、下周行动(增/停/测)
1. 增:…(可验收标准:…)
2. 停:…
3. 测:…（怎么算测成功:…）
## 五、数据说明
- 口径:互动率 = (赞+转+评+引+收藏)/曝光;<impression 可得性/缺失字段说明>
- 缺口:<哪些数没拉到、为什么、如何补>
Discipline checklist
- Source of truth first: if the numbers can't be pulled, use a fallback and label the source; never make up numbers. Every number in the report must be traceable to a scraping source.
- State the methodology clearly: note the time window, whether replies are included, and the definition of impression. If the methodology is inconsistent, the week-over-week comparison is fake.
- Patterns must pass the sample threshold: fewer than 2-3 instances doesn't count as a pattern; a one-off viral hit goes into "to be validated," not "conclusions."
- Recommendations must be verifiable: each next-week action carries a "how do we count this as done" criterion, otherwise next week's review is impossible.
- No ghostwriting: don't write the copy's flesh, leave
【你的话:____】; here, deliver only data, attribution, and direction. - Sensitive information (follower demographics, private account data): remind the user — private at first, don't just post the table publicly.