/X

metadata:
  short-description: "Read, search, post, and thread on X; publish Articles; fetch and sweep bookmarks into idea-issues; look up profiles."
name: X
evals:
  deterministic:
    - command: 'bun "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/X/Tools/post.ts" --dry-run "Testing my X setup"'
      falsifier: "the dry run does not print 'Dry run — all tweets valid. No posts sent.' and exit 0, so tweet validation is broken"
    - command: 'bun "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/X/Tools/bookmarks.ts" status'
      falsifier: "the last line is NOT READY and the exit code is 1, so the config, a required secret or the OAuth 2.0 grant is missing (read-only, prints names and states, never a value)"
  manual:
    reason: "X actions change a live account and external API state, so a real write must not be used as an automated test"
    falsifier: "the returned or fetched post, thread, bookmark, profile, or media state differs from the approved requested operation"
version: 1.4.3
description: Runs all X (Twitter) operations via X API v2 and the xurl CLI: post tweets and threads with media, publish X Articles, search, fetch bookmarks, sweep new bookmarks into idea-issues with LifeOS Upgrade analysis, look up profiles, read tweets. USE WHEN post to X, tweet, post thread, search X, search Twitter, X bookmarks, fetch bookmarks, pull bookmarks, check bookmarks, twitter bookmarks, what have I bookmarked, bookmarks for upgrades, tb, bookmark sweep, bookmark ideas, read tweet, X article, X profile, Twitter profile, lookup user, who is on X, authorize X. NOT FOR posting the same content to several platforms at once, writing social copy, Instagram/LinkedIn/TikTok data (Apify within each platform’s terms), bulk reads beyond what the X API plan allows (use your own exported data or a data product X licenses).

X — Unified X (Twitter) API

**Contents:** Ideal State · Intent Routing · Tools Reference · CLI: xurl · Data & Config · Gotchas · Examples

Handles every X (Twitter) operation through the X API v2 (direct `fetch()`) and the `xurl` CLI: post single tweets, threads and media, publish long-form Articles, search recent tweets, fetch bookmarks, look up user profiles, and read tweets by ID or URL. Other skills delegate their X work here, so the credentials, the auth handling and the OAuth 2.0 token store live in one place; if each skill wired up its own, the secrets would sprawl and the refresh chain would break.

Not for posting the same content to several platforms (`Broadcast`), writing social copy (a copywriting skill), or bulk collection beyond what the X API allows. X reads use the official API or the principal’s own exported data; when X refuses a read, the intent stops and reports it.

Ideal State

• Every X operation runs through this skill's tools or `xurl` on the auth mode it needs, and every X read goes through `Tools/read.ts`, never a web fetch or browser.
• Nothing reaches the account (a tweet, thread, media post or published Article) without the principal's confirmation, and a post is reported done only after reading it back.
• Posted text and URLs go out exactly as given, measured by X's weighted count; over-limit text is rejected, never cut.
• The OAuth 2.0 grant survives every run: one refresher per grant, and a missing scope or revoked grant ends in a surfaced re-authorization URL, never a guess.

Intent Routing

| Intent | Trigger | File | |----------|---------|------| | **Post** | "post to X", "tweet", "post tweet", "send tweet", "thread" | `Intents/Post.md` | | **Search** | "search X", "search twitter", "find tweets" | `Intents/Search.md` | | **Bookmarks** | "X bookmarks", "fetch bookmarks", "re-authorize bookmarks", "authorize X", "bookmark token expired" | `Intents/Bookmarks.md` | | **PullBookmarks** | "pull bookmarks", "check bookmarks", "bookmark sweep", "bookmarks for upgrades", "tb", "quick bookmark check" | `Intents/PullBookmarks.md` | | **Profile** | "X profile", "twitter profile", "lookup user", "who is @user" | `Intents/Profile.md` | | **Read** | "read tweet", "get tweet", "fetch tweet" | `Intents/Read.md` | | Article | "X article", "Twitter article", "long-form on X", "publish an article to X" | `Tools/article.ts`: `create --file piece.md` drafts (the default), `--publish` publishes, then read the post back with `Tools/read.ts`. Publishing is irreversible through the API. |

| File | Read when | |------|-----------| | `Setup.md` | first-time setup: the token-store Config.md, the X app and its secrets, and the first-run proof |

Tools Reference

All tools are in `~/.claude/skills/X/Tools/` and run with `bun`. Each intent carries the command for its own tool (`post.ts`, `search.ts`, `profile.ts`, `read.ts`, `bookmarks.ts`, and `bookmark-issue.ts` for the sweep's `check`, `create`, `skip` and `audit`); this table holds only the tools no intent owns. Which auth mode each path uses is in Gotchas.

| Tool | Purpose | Usage | |------|---------|-------| | `x-client.ts` | Credential loader, token store, auth helpers | Imported by the other tools | | `media.ts` | Chunked media upload (video/image/GIF) | `bun run media.ts upload clip.mp4` | | `article.ts` | Long-form X Articles: markdown to `content_state`, draft, publish | `bun run article.ts create --file piece.md --publish` | | `delete.ts` | Delete tweets by id | `bun run delete.ts <id> [<id> ...]` | | send gate, video PII gate | What stops a post and how each block is reported | Post intent § Tool contract (`Intents/Post.md`) |

CLI: xurl

`xurl` is the official X CLI. Use for quick API calls not covered by tools:

# Quick lookups
xurl /2/users/me
xurl /2/tweets/1234567890

# Search
xurl "/2/tweets/search/recent?query=from:<username>&max_results=10"

# Post (use Tools/post.ts instead for threads)
xurl -X POST /2/tweets -d '{"text":"Hello"}'

Data & Config

Config: `LIFEOS/USER/CUSTOMIZATIONS/SKILLS/X/Config.md` (a fenced `yaml` block choosing the OAuth 2.0 token store: `local`, a 0600 fi