A Claude skill that teaches Claude to write X (Twitter) posts engineered against the open-source For-You ranker.
X open-sourced its For-You feed algorithm twice: the legacy stack in March 2023, and the new Grok-powered Phoenix transformer in May 2026. This skill reads both, the active Community Notes bridging algorithm, and 10+ public analyses — then distills everything into a workflow your Claude can run on every post you draft.
The result: posts engineered to survive the banger screen, score high on the Phoenix transformer, embed into the right SimClusters communities, and trigger the engagement velocity that opens out-of-network distribution.
When you ask Claude to write or review an X post, the skill:
- Drafts against 29 named, enforceable policies derived from the algorithm code (e.g., P-15: "Reply hand-typed to every reply within first hour —
reply_engaged_by_authoris +75 weight, 150× a like"). - Runs a 15-checkbox pre-flight scan before you post, citing the exact policy ID for any failure.
- Cites the algorithm directly — every recommendation is anchored to a code path (
home-mixer/scorers/ranking_scorer.rs) or a published weight (2023 release), with confidence markers (🟢 confirmed / 🟡 likely / 🟠 reasoned).
Examples:
- "Write me a launch post for [product]" → drafts → pre-flight scans → revises until every check passes → recommends timing + media plan.
- "Improve this tweet" → scores it against the algorithm → cites specific policy failures → proposes rewrites with magnitude estimates.
- "Should this be a thread?" → walks through the AuthorDiversityScorer math (
(1−0.25) × 0.5^position + 0.25— 5th tweet runs at ~30% of standalone score) and DedupConversationFilter behavior, defaults to "no" unless each tweet stands alone.
You: Write me an X post announcing a new open-source tool.
Claude (with x-algorithm-skill loaded):
Draft v1:
"Excited to announce our new open-source tool! It does X, Y, and Z. 🚀
Check it out: github.com/..."
[Pre-flight scan:]
✗ P-1 slop-vocab: "Excited to announce" is a high slop_score trigger
✗ P-2 stop-scroll: first 6 words = "Excited to announce our new open" — generic, doesn't stop scroll
✗ P-5 quotable: no self-contained quotable line
✗ P-6 reply-bait: no disagreeable position
✗ M-1 video: no media attached
✓ M-2 native screenshot: N/A (no media yet)
...
Draft v2 (rewritten — sounds like a person, not a press release):
"built [Tool] because every existing option made me [do the annoying thing]
and I finally snapped.
it does [specific thing] using [specific approach] instead of [the obvious
default] — which is the one decision that makes it [concrete benefit].
honestly didn't expect that to matter as much as it does.
works with [X], [Y] and [framework Z]. open source.
github.com/..."
[Pre-flight scan: all 17 pass — including the human-voice checks (16-17)]
[Timing recommendation: 14:00 UTC weekday]
[Media plan: 20s vertical screen recording showing the tool. Self-reply with
architecture diagram screenshot 30-45 min after.]
Note the rewrite has no em-dash bullet list and no "three things" triplet — those are AI-writing tells that trip the banger classifier's
slop_score. The skill's #1 rule (P-20) is to sound like a human, not like optimized copy. A robotic-but-"optimized" post loses.
⚠️ Two steps. Both required. Don't skip step 1. Claude Code uses a marketplace-based plugin system; you must register this repo as a marketplace before you can install the plugin from it.
Step 1 — register this repo as a marketplace:
/plugin marketplace add ceoguy/x-algorithm-skill
Step 2 — install the plugin from the marketplace:
/plugin install x-algorithm@ceoguy-x-algorithm-skill
Then restart Claude Code so the new plugin loads. (Installing/updating a plugin requires a restart to apply — there is no live-reload command.)
Verifying the install worked:
/plugin marketplace list # should list "ceoguy-x-algorithm-skill"
/plugin list # should list the "x-algorithm" plugin
This plugin ships both a skill (auto-activated) and a slash command (explicit).
The skill is model-invoked: it loads automatically when you mention X posts, tweets, threads, the For-You feed, or distribution. Examples:
Write me an X post announcing my new open-source CLI.
Improve this tweet: "..."
Should this be a thread or one post?
Why isn't my last post getting any reach?
Claude detects the intent, loads the skill, and runs the policy workflow.
/x-algorithm write a launch post for my new app that does X
/x-algorithm review this draft: "Excited to announce..."
/x-algorithm # with no args, explains itself and asks what you need
The command takes either a draft (to review + rewrite) or a topic/goal (to write from scratch), runs the 15-checkbox pre-flight scan, and returns a post that passes every check + a timing/media plan.
/plugin marketplace update ceoguy-x-algorithm-skill # pull the latest version
/plugin update x-algorithm@ceoguy-x-algorithm-skill # apply it (then restart)
/plugin uninstall x-algorithm@ceoguy-x-algorithm-skill
/plugin marketplace remove ceoguy-x-algorithm-skill # optional — also drop the marketplace
| Error | Cause | Fix |
|---|---|---|
Marketplace "ceoguy/x-algorithm-skill" not found |
You ran step 2 without step 1 first. The argument to install is a plugin-in-a-marketplace, not a GitHub repo. |
Run step 1 first: /plugin marketplace add ceoguy/x-algorithm-skill |
Marketplace "ceoguy-x-algorithm-skill" not found (note the hyphen) |
Same cause — marketplace not yet registered. | Run step 1 first. |
/plugin install ceoguy/x-algorithm-skill doesn't work |
This isn't valid syntax in Claude Code v2.1+. The <owner>/<repo> form looks for a marketplace name, not a plugin source. |
Use the two-step sequence above. |
Failed to parse marketplace file ... owner: expected object OR Failed to install ... invalid manifest ... repository: expected string |
You added the marketplace while a cached copy had an older/broken manifest. | Refresh the cache: /plugin marketplace update ceoguy-x-algorithm-skill (or remove then add again), then install. |
| Skill / command doesn't appear after install | A restart is required to apply a new install. | Restart Claude Code, then check /plugin list. |
| Want to verify the manifests yourself | Clone the repo and run claude plugin validate <path-to-clone> — it should print ✔ Validation passed. |
Claude Code's plugin system is marketplace-based, not direct-from-git. A marketplace is a curated catalog of plugins, often hosting many in one repo. A single-plugin GitHub repo (like this one) acts as its own one-plugin marketplace via the .claude-plugin/marketplace.json file in the repo root.
This means:
- Step 1: register the marketplace (Claude Code fetches the repo, reads
marketplace.json, registers the marketplace under thenamefield — which for this repo isceoguy-x-algorithm-skill) - Step 2: install a specific plugin from that registered marketplace using
<plugin-name>@<marketplace-name>syntax (which for this skill isx-algorithm@ceoguy-x-algorithm-skill)
There is no one-step /plugin install github:... shortcut in v2.1+.
You don't need Claude Code at all. The docs/ folder is self-contained markdown. Read directly:
docs/algorithm-deep-dive.md— the full algorithm reference (~600 lines)docs/policies.md— 30 named, enforceable policies (incl. P-20: sound human)docs/pre-flight-scan.md— 17-checkbox final reviewdocs/glossary.md— every term defined with sourcesdocs/published-weights.md— the full 2023 Heavy Ranker numerical anchor tabledocs/seed-lists.md— how to build named-entity seed lists + find cluster-central accounts for your niche (the methodology behind P-10 and P-19)docs/related-repos.md— every related public X/xAI repo and what it's fordocs/further-reading.md— curated academic papers + independent analyses
You can also clone the repo and feed any of these into your LLM of choice as a reference document:
git clone https://github.com/ceoguy/x-algorithm-skill
# then load docs/ as context in your tool of choice| # | Rule | Why |
|---|---|---|
| 1 | TweepCred ≥ 65 | Below this account-reputation threshold, only ~3 of your tweets are eligible for distribution at a time. Most important single threshold in X. |
| 2 | Optimize for reply_engaged_by_author |
When someone replies to your post and you reply back, that's a +75 weight signal — 150× a like. Reply hand-typed from the app within the first hour. |
| 3 | Aim for 10 replies in 15 minutes | Triggers the out-of-network amplification cascade. Engineer reply-bait into every post. |
| 4 | Never trigger report |
−369 weight = one report wipes ~700 likes of positive signal. Verifiable, defensible claims only. |
POST PUBLISHED
│
├─→ Grox content-understanding (runs once, in parallel):
│ ├─ BangerInitialScreen — Grok scores quality_score (≥0.4 passes)
│ ├─ SafetyPtosCategory (VLM) — 7-category policy detection
│ ├─ PostSafetyDeluxe — second-pass critical model
│ ├─ GrokUpaActionWithLabels — applies distribution labels
│ └─ MultimodalEmbedderV5 — 1024-dim text+image+transcript embedding
│
↓
PER-VIEWER FOR-YOU REQUEST
│
├─→ Query hydration: blocked/muted users, follow list, mutual-follow MinHash,
│ served history, impression bloom, engagement history sequences, demographics
│
├─→ Candidate sources (parallel):
│ ├─ ThunderSource — in-network posts (followed accounts)
│ ├─ PhoenixSource — OON via two-tower retrieval
│ ├─ PhoenixMOESource — OON via mixture-of-experts variant
│ ├─ PhoenixTopicsSource — topic-targeted OON
│ └─ TweetMixerSource — legacy fallback
│ (~85% of OON candidates flow from SimClusters' 145k communities)
│
├─→ Hydration: engagement velocity (5-10 min cache TTL), mutual-follow Jaccard,
│ tweet-type bitset (author-follower buckets at 100/1k/10k/100k/1M cliffs),
│ has_media, video duration, language code
│
├─→ Pre-scoring filters (14): age, duplicates, blocked authors, muted keywords,
│ self-tweet, retweet dedup, ineligible subscription, previously seen (bloom)
│
├─→ Scoring (4 scorers chained):
│ ├─ PhoenixScorer — Grok transformer predicts ~22 action probs
│ ├─ WeightedScorer — Σ weight × P(action) + offset
│ ├─ AuthorDiversityScorer — (1−floor) × decay^position + floor
│ └─ VMRanker (+ OON) — value model with DPP diversity
│
├─→ Selection: top-K + blender (posts + ads + WTF + prompts)
│
└─→ Post-selection: VFFilter (drops on `DO_NOT_AMPLIFY`, `NSFA_COMMUNITY_NOTE`,
12 other safety labels), DedupConversationFilter
│
↓
RANKED FEED
The skill loads the full structure of this pipeline + every published weight + every confidence-tagged assumption + 29 named policies derived from the code.
- 🟢
xai-org/x-algorithm— May 2026 Grok-powered For-You ranker - 🟢
twitter/the-algorithm— March 2023 legacy release (SimClusters still live in production, ~85% of OON candidate generation) - 🟢
twitter/communitynotes— Birdwatch bridging algorithm (drivesNSFA_COMMUNITY_NOTEdistribution suppression) - 🟡
igorbrigadir/awesome-twitter-algo— annotated 2023 release with extracted constants - 🟡 SimClusters paper (KDD 2020)
- 🟡 Birdwatch paper (2022)
- 🟠 Standard recsys literature on DPP (Chen et al. 2017), MaskNet, two-tower retrieval
x-algorithm-skill/
├── README.md # this file
├── LICENSE # MIT
├── CONTRIBUTING.md # how to contribute updates / new sources
├── CHANGELOG.md
├── .claude-plugin/
│ ├── marketplace.json # makes the repo act as its own marketplace
│ └── plugin.json # Claude Code plugin manifest
├── skills/
│ └── x-algorithm/
│ └── SKILL.md # the skill Claude loads on trigger (auto-activated)
├── commands/
│ └── x-algorithm.md # the /x-algorithm slash command (explicit)
├── docs/
│ ├── algorithm-deep-dive.md # the full algorithm reference (~600 lines)
│ ├── policies.md # 29 named, enforceable policies
│ ├── pre-flight-scan.md # 15-checkbox final review
│ ├── glossary.md # every term defined with sources
│ ├── published-weights.md # full 2023 Heavy Ranker numerical anchor table
│ ├── related-repos.md # every related public X/xAI repo + what it's for
│ └── further-reading.md # curated academic papers + independent analyses
└── examples/
├── 01-launch-post-rewrite.md # before/after with every policy cited
├── 02-thread-vs-single.md # why one banger > 10-tweet thread (with math)
├── 03-reply-engagement.md # the +75 reply_engaged_by_author signal in action
├── 04-low-reach-diagnosis.md # 10-step debug sequence for underperforming posts
├── 05-account-warming.md # path from new account to TweepCred ≥ 65
├── 06-edge-cases-faq.md # hashtags, mentions, polls, quote tweets, links, etc.
└── 07-sound-human-not-ai.md # the most important rewrite: kill the AI tells
- Writes like a human, not like AI. Rule Zero (policy P-20) bans the AI-writing tells — em-dash bullet lists, staccato fragments, parallel triplets, "Here's the thing:" cadence — because the banger classifier's
slop_scorecatches them and real people don't engage with content that reads as machine-written. Sounding human IS the optimization, and it overrides every structural rule when they conflict. - Policy-driven, not vibe-driven. Every recommendation cites a code path and a policy ID. No "X likes engagement" hand-waving.
- Confidence markers throughout. You know what's 🟢 confirmed from xAI vs 🟡 likely (2023 anchor still believed valid) vs 🟠 reasoned from standard recsys practice.
- Multi-round researched. The wiki the skill is built from went through 5 deep-read rounds covering the entire
xai-org/x-algorithmrepo + the 2023 release + public analyses + Community Notes. - Covers the full distribution stack, not just the ranker: SimClusters candidate generation, Phoenix retrieval, the Grox content-understanding pipeline (banger screen, safety PTOS, spam detection, reply ranking), the brand-safety verdict computation (4 levels, 14 Medium-Risk labels including
DO_NOT_AMPLIFY), ads-adjacency dynamics, and Community Notes bridging. - Vertical-agnostic. Examples cover product launches, takes, threads, and engagement bait without assuming a niche.
- Honest about unknowns. When a value isn't public (production ranker weights, exact DPP theta, Phoenix production dimensions, classifier prompt bodies), the skill says so and cites the closest public anchor.
It isn't — it's not an ML model. It's:
- A long-form domain prompt (
skills/x-algorithm/SKILL.md) that Claude reads when activated, defining workflow + hard rules. - A reference corpus (
docs/) that Claude pulls from when answering specific questions or running the pre-flight scan. - Worked examples (
examples/) that demonstrate the workflow on concrete posts.
This is the standard Claude Code Skill format — natural-language instructions + documents Claude can load on demand.
The "training" is the research that went into deriving the policies from the open-source code. The skill is just the distillation. You can re-derive it from the public sources listed above.
- Add a
/x-pre-flight <post>slash command for one-shot scanning - Vertical-specific seed-list packs (DeFi, AI/dev, gaming, B2B SaaS, indie hacker, news)
- Automated TweepCred estimation from public account signals
- Hooks for Claude to fetch a draft's predicted Phoenix scores from a community endpoint (if one exists)
- Re-clone xai-org/x-algorithm quarterly and diff for structural changes
- Optional Python utility to score draft posts against the policies programmatically
PRs welcome, especially:
- New policy additions when xAI publishes algorithm changes
- Counter-examples that show the policies in action (or where they're wrong)
- Vertical-specific examples (one-shot launches, thread examples, reply-game examples)
- Translations of the SKILL.md to other languages
- Constants updates when better-sourced numerical values appear publicly
Open an issue first for substantial changes. For policy edits, cite the source code path or the public source.
Q: Does this skill guarantee my posts will go viral? A: No. The algorithm is probabilistic and continuously trained. This skill maximizes the probability of distribution by satisfying the policies the public algorithm code reveals. Beyond that, content quality and account reputation matter.
Q: Will this work for accounts with low follower counts? A: Yes, but the most important constraint for low-follower accounts is account reputation (TweepCred). The skill includes account-level policies (A-1..A-8) for this. The single-post tactics matter less if your TweepCred is below 65.
Q: How is this different from generic "Twitter growth" tips? A: Generic tips like "post consistently" or "use hashtags" don't cite the algorithm. This skill grounds every recommendation in a code path or a published weight. Where a published number doesn't exist, it's tagged 🟠 (reasoned assumption from standard recsys practice) so you know.
Q: Does this work for X Premium / Blue Verified accounts differently? A: Yes — Blue Verified gets a 4× in-network multiplier and 2× OON multiplier (2023 published). This is documented in the skill but tactics are otherwise the same.
Q: Why doesn't the skill cover ads?
A: This is for organic distribution. Paid promotion is a separate system (the open-source home-mixer/ads/ blender code is covered briefly in docs/algorithm-deep-dive.md for context on how ads compete with organic posts for monetization-zone density, but not for buying placements).
Q: Will the skill stay accurate as X updates the algorithm?
A: The structure is stable (open-source code shows it). Specific numeric weights drift continuously (they're learned, not configured in production). Re-clone xai-org/x-algorithm quarterly. Significant releases will require a skill update.
Q: Can I fork and customize for my niche? A: Yes — that's encouraged. Fork, add a vertical-specific seed-list pack, and contribute back.
Q: Does this leak any insider information? A: No. Everything is derived from the public open-source releases + public analyses. Nothing in this skill comes from inside X or any company that uses X.
MIT. See LICENSE.
This skill exists because xAI and (pre-acquisition) Twitter chose to open-source their feed ranker. Both 2023 and 2026 releases. That transparency is rare and valuable.
Built from:
- The full source code of
xai-org/x-algorithm - The full source code of
twitter/the-algorithm - The active
twitter/communitynotesrepo - Igor Brigadir's annotated mirror
- Published analyses by Tanay Jaipuria, Knight First Amendment Institute, Sumit's Diary, Sol Messing, the Birdwatch paper, and 2026's Quality-Sensitive Matrix Factorization for Community Notes
- Academic recsys literature on DPP, SimClusters (KDD 2020), and two-tower retrieval
If you find an error, open an issue. If you find a new public source that should be incorporated, send a PR.
Built for Claude. Released under MIT. Sourced entirely from public materials.