1---
2name: twitter
3version: 2.0.1
4description: "Twitter/X (x.com) data lookup — fetch tweets by URL or ID, search tweets, user profiles, followers, replies. Use for ANY x.com or twitter.com URL."
5delivery: script
6metadata:
7  starchild:
8    emoji: "🐦"
9    skillKey: twitter
10    requires:
11      env:
12        - TWITTER_API_KEY
13 
14user-invocable: false
15disable-model-invocation: false
16---
17 
18# Twitter / X (script-mode)
19 
20Read-only access to twitterapi.io endpoints. 13 functions covering tweets,
21users, followers, replies, threads, quotes, articles, and trends.
22 
23All requests go through sc-proxy via `core.http_client.proxied_get`. The
24`TWITTER_API_KEY` env var is auto-injected server-side, no local key needed
25on the agent machine.
26 
27## Script Usage
28 
29Standard invocation pattern:
30 
31```bash
32python3 - <<'EOF'
33import sys, json
34sys.path.insert(0, "/data/workspace/skills/twitter")
35from exports import twitter_user_info, twitter_user_tweets
36 
37profile = twitter_user_info(username="vitalikbuterin")
38print(json.dumps(profile, indent=2))
39 
40recent = twitter_user_tweets(username="vitalikbuterin")
41print(f"got {len(recent.get('tweets', []))} tweets")
42EOF
43```
44 
45Tweet ID extraction from URL: the last path segment of any
46`x.com/{user}/status/{id}` or `twitter.com/{user}/status/{id}` URL is the
47tweet ID. Pass it as a string (Python int will lose precision on long IDs).
48 
49## Function Reference (signatures)
50 
51All 13 functions live in `exports.py`. Returns are dicts straight from
52twitterapi.io — keys vary per endpoint, inspect once before scripting.
53 
54### Tweet endpoints
55 
56| Function | Description |
57|---|---|
58| `twitter_search_tweets(query, cursor=None)` | Advanced search. Operators: `from:user`, `to:user`, `#tag`, `$cashtag`, `lang:en`, `has:media`, `has:links`, `is:reply`, `min_faves:N`, `since:YYYY-MM-DD`, `until:YYYY-MM-DD`. |
59| `twitter_get_tweets(tweet_ids)` | Fetch one or more tweets by ID. `tweet_ids` = list of strings (also accepts comma-string). |
60| `twitter_tweet_replies(tweet_id, cursor=None)` | Replies to a tweet. |
61| `twitter_tweet_retweeters(tweet_id, cursor=None)` | Users who retweeted. |
62| `twitter_tweet_thread_context(tweet_id)` | Full thread context (parents + direct replies). |
63| `twitter_tweet_quote(tweet_id, cursor=None)` | Quote tweets. |
64| `twitter_get_article(tweet_id)` | Long-form X article body. |
65| `twitter_get_trends(woeid=None, country=None, category=None, limit=None)` | Trending topics; all filters optional. |
66 
67### User endpoints
68 
69| Function | Description |
70|---|---|
71| `twitter_user_info(username)` | Profile: bio, follower/following counts, tweet count, verified. |
72| `twitter_user_tweets(username, cursor=None)` | User's recent tweets. |
73| `twitter_user_followers(username, cursor=None)` | Follower list. |
74| `twitter_user_followings(username, cursor=None)` | Accounts followed. |
75| `twitter_search_users(query, cursor=None)` | Search users by name/keyword. |
76 
77`username` is the handle WITHOUT `@` (e.g. `"elonmusk"`, not `"@elonmusk"`).
78Pagination: when a response includes `next_cursor`, pass it back as `cursor`
79on the next call.
80 
81## When to use this skill
82 
83- ANY `x.com/...` or `twitter.com/...` URL → start here, NOT `web_fetch`
84  (Twitter blocks scrapers).
85- Single tweet detail → `twitter_get_tweets([tweet_id])`.
86- "What's @user been posting?" → `twitter_user_tweets`.
87- KOL discovery / cashtag mentions → `twitter_search_tweets("$SOL min_faves:50")`.
88- Trending topics → `twitter_get_trends`.
89 
90## Error handling
91 
92- `402 Credits is not enough` → upstream proxy credits exhausted; tell user
93  to top up. Don't retry.
94- `429` → rate limited; surface to user, don't auto-retry.
95- `404 user not found` → suggest verifying the handle spelling.
96 
97## Version Policy (hard rule)
98 
99This skill is **script-mode** (`delivery: script`). It does NOT register
100runtime tools — agent must `read_file` SKILL.md and call functions via
101`bash` + `python3`. The legacy `tools.py` / `__init__.py` files are kept
102for backward compatibility but are no longer the preferred entry point.
103 
104Bump rules:
105- Any signature change, env-var change, or sc-proxy contract change → MAJOR
106- New function added, response schema clarified → MINOR
107- Bug fix or doc-only change → PATCH
108