Twitter/X API Skill

Interact with X (Twitter) via API v2 for reading, posting, replying, DMs, search, and analytics.

Setup

Credentials

Store credentials in environment variables or ~/.config/twitter/credentials.json:

export TWITTER_API_KEY="your-api-key"
export TWITTER_API_SECRET="your-api-secret"
export TWITTER_ACCESS_TOKEN="your-access-token"
export TWITTER_ACCESS_SECRET="your-access-secret"
export TWITTER_BEARER_TOKEN="your-bearer-token"  # For read-only operations

Or create credentials file:

mkdir -p ~/.config/twitter
cat > ~/.config/twitter/credentials.json << 'EOF'
{
  "api_key": "your-api-key",
  "api_secret": "your-api-secret",
  "access_token": "your-access-token",
  "access_secret": "your-access-secret",
  "bearer_token": "your-bearer-token"
}
EOF
chmod 600 ~/.config/twitter/credentials.json

Install Dependencies

pip install tweepy

Quick Reference

Scripts

tweet.py

Main script for all Twitter operations. Run with --help for details:

{baseDir}/scripts/tweet.py --help
{baseDir}/scripts/tweet.py post --help

Common Workflows

Post a simple tweet:

{baseDir}/scripts/tweet.py post "Hello, world!"

Post with image:

{baseDir}/scripts/tweet.py post "Check this out!" --media photo.png
{baseDir}/scripts/tweet.py post "Multiple images" --media img1.png --media img2.png

Reply to a tweet:

{baseDir}/scripts/tweet.py reply 1234567890 "Great point!"

Post a thread:

{baseDir}/scripts/tweet.py thread \
  "First tweet in thread" \
  "Second tweet" \
  "Third tweet"

Read your mentions:

{baseDir}/scripts/tweet.py mentions --count 50

Search for tweets:

{baseDir}/scripts/tweet.py search "openclaw agent" --count 20
{baseDir}/scripts/tweet.py search "#AI lang:en" --count 20

Get user info:

{baseDir}/scripts/tweet.py user elonmusk

Send a DM:

{baseDir}/scripts/tweet.py dm username "Hello from OpenClaw!"

View tweet analytics:

{baseDir}/scripts/tweet.py analytics 1234567890

API Tiers & Limits

Free tier can only post tweets (no read access to timeline/mentions). Basic tier required for reading mentions, timeline, and search. Write-only operations work on free tier.

See {baseDir}/references/api-limits.md for detailed rate limits.

Error Handling

Common errors:

Notes

• Rate limits: X API has strict rate limits. Scripts include retry logic.
• Media uploads: Images must be <5MB (PNG/JPG) or <15MB (GIF). Videos <512MB.
• Character limit: 280 characters per tweet. Threads for longer content.
• DMs: Require OAuth 1.0a user context (not Bearer token).
• Search operators: {baseDir}/references/search-operators.md for advanced queries.

Related Files

• {baseDir}/scripts/tweet.py - Main CLI for all operations
• {baseDir}/references/api-limits.md - Detailed rate limits by endpoint
• {baseDir}/references/search-operators.md - Twitter search syntax