Twitter/X Reader Skill

A comprehensive skill for reading and extracting data from X (formerly Twitter) tweets using multiple reliable data sources.

Overview

This skill extracts complete tweet information including text content, author details, engagement statistics, media attachments, and quoted tweets from X/Twitter URLs. It uses a multi-tier approach for maximum reliability and data completeness.

When to Use

Primary Triggers:

User shares a tweet URL (x.com//status/ or twitter.com//status/)
User asks to "read this tweet" with a URL
User requests tweet analysis, summary, or data extraction
User mentions getting information from a specific tweet

Example User Requests:

"What does this tweet say? https://x.com/elonmusk/status/123456789"
"Can you read this tweet for me?"
"Summarize this Twitter thread"
"What are the engagement stats on this tweet?"
"Extract the media from this tweet"

Capabilities

Data Extracted

Tweet Content: Full text with proper formatting
Author Information: Display name and handle (@username)
Timestamps: Both human-readable and original format
Engagement Stats: Likes, retweets, replies, quote tweets
Media Attachments: Photos and videos with direct URLs
Quote Tweets: Full quoted tweet content and author info
Thread Context: When available

Supported URL Formats

https://x.com/username/status/1234567890
https://twitter.com/username/status/1234567890
URLs with query parameters (e.g., ?s=20, ?t=abc123)
Mobile URLs (m.twitter.com automatically handled)

Usage Examples

Basic Usage

# Read a single tweet
./scripts/read_tweet.sh "https://x.com/username/status/1234567890"

# Read a full thread (follows reply chain from the same author)
./scripts/read_thread.sh "https://x.com/username/status/1234567890"

# Fallback method using Nitter
./scripts/read_tweet_nitter.sh "https://x.com/username/status/1234567890"

Agent Instructions

When a user provides a tweet URL:

Validate the URL format - ensure it's a valid X/Twitter status URL
Use the primary script - scripts/read_tweet.sh first
Handle failures gracefully - if primary fails, try scripts/read_tweet_nitter.sh
Present data clearly - format the output for human consumption
Preserve context - include engagement stats and media references

Sample Response Format

The scripts return structured JSON with this format:

{
  "success": true,
  "tweet": {
    "text": "Tweet content here...",
    "author": {
      "name": "Display Name",
      "handle": "username"
    },
    "timestamp": {
      "formatted": "2024-01-15 14:30:25 UTC",
      "original": "Mon Jan 15 14:30:25 +0000 2024"
    },
    "url": "https://x.com/username/status/1234567890",
    "engagement": {
      "likes": 1250,
      "retweets": 340,
      "replies": 89,
      "quotes": 45
    },
    "media": {
      "photos": ["https://pbs.twimg.com/media/..."],
      "video": "https://video.twimg.com/..."
    },
    "quoted_tweet": {
      "text": "Quoted tweet text...",
      "author": {
        "name": "Quoted Author",
        "handle": "quoted_user"
      },
      "url": "https://x.com/quoted_user/status/987654321"
    }
  },
  "source": "fxtwitter",
  "fetched_at": 1705327825
}

Agent Response Example

**Tweet from @elonmusk:**
> "Just had a great meeting about sustainable transport. The future is electric! ⚡🚗"

**Posted:** January 15, 2024 at 2:30 PM UTC
**Engagement:** 1,250 likes • 340 retweets • 89 replies • 45 quotes

**Media:** 1 photo attached
- Photo: https://pbs.twimg.com/media/example.jpg

**Quote Tweet from @teslaofficial:**
> "Our latest Model S update includes new charging optimizations..."

Technical Implementation

Primary Method: FxTwitter API

Endpoint: https://api.fxtwitter.com/{username}/status/{tweet_id}
Advantages: No authentication, comprehensive data, reliable
Rate Limits: Generous for personal use
Response: Complete JSON with all tweet metadata

Fallback Method: Nitter Scraping (Best-Effort)

Instances: Multiple public Nitter instances as backup
Advantages: Works when FxTwitter is unavailable
Limitations: Basic data extraction, no engagement stats
Usage: Automatic fallback when primary method fails
⚠️ Note: Most public Nitter instances have shut down or become unreliable since 2024. This fallback is best-effort and may not return results. The FxTwitter API should be considered the only reliable method.

Error Handling

Invalid URL format detection
Network timeout handling
API error response parsing
Graceful fallback between methods
Clear error messages for users

Dependencies

Required System Tools:

curl - HTTP requests to APIs
jq - JSON parsing and formatting
bash - Script execution environment
grep/sed - Text processing (Nitter fallback only)

Optional Enhancements:

gdate (GNU date via Homebrew on macOS) - Better timestamp formatting

Security & Privacy

Security Features

✅ No external data collection - Data stays on your system
✅ No analytics or telemetry - No tracking or usage reporting
✅ Fully auditable code - Open source, readable shell scripts
✅ Minimal network calls - Only to FxTwitter API and Nitter instances
✅ No sensitive data exposure - Scripts don't store or log personal info
✅ Safe URL handling - Proper URL validation and sanitization

Network Connections

Approved External Hosts:

api.fxtwitter.com - Primary data source (FxTwitter API)
nitter.net and other Nitter instances - Fallback scraping
No other external connections made

Data Flow:

User provides tweet URL
Script extracts username/ID from URL
Makes API request to FxTwitter or Nitter
Parses response locally
Returns formatted JSON (never stored permanently)

Audit Trail

All network requests include:

Clear user-agent identification
Minimal necessary headers only
No authentication tokens or personal identifiers
Requests only to extract public tweet data

Error Scenarios & Handling

Common Errors

Invalid URL Format:

{
  "error": "Invalid Twitter/X URL format",
  "expected": "x.com/user/status/123456789 or twitter.com/user/status/123456789"
}

Tweet Not Found:

{
  "error": "API Error",
  "code": 404,
  "message": "NOT_FOUND"
}

Network Failure:

{
  "error": "Failed to fetch tweet data",
  "details": "Network request failed"
}

Fallback Needed:

{
  "error": "All Nitter instances failed",
  "suggestion": "Try the main script with FxTwitter API, or wait for Nitter instances to recover"
}

Agent Error Handling

When errors occur:

Parse the error JSON to understand the issue
Try the fallback method if primary fails
Explain to the user what went wrong in plain language
Suggest alternatives (try again later, check URL format, etc.)

Advanced Features

Thread Reading

Full thread unrolling is supported via read_thread.sh:

Given any tweet URL in a thread, walks UP the reply chain via replying_to fields
Only collects tweets from the same author (self-reply threads)
Returns tweets in chronological order as a JSON array
Safety limit of 50 tweets per thread (configurable via second argument)
Usage: ./scripts/read_thread.sh "https://x.com/user/status/123" [max_depth]

Media Handling

Photos: Direct URLs via media.photos array (full-resolution)
Videos: Links to MP4 files via media.videos with thumbnails and duration
All media: Combined media.all array with type annotations for complete coverage
Article covers: Long-form X posts ("articles") have media.article_cover extracted
GIFs: Handled as video content
External Links: Preserved in tweet text

Quote Tweet Recursion

The skill can extract nested quote tweets up to reasonable depth to avoid infinite loops.

Performance Notes

Response Times

FxTwitter API: Typically 200-500ms
Nitter Scraping: 1-3 seconds per instance
Network Dependent: May vary based on connection quality

Caching Considerations

No persistent caching implemented by default
Consider temporary caching for repeated requests
Respect rate limits of external services

Troubleshooting

Common Issues

"No tweet data in API response"

Tweet may be deleted or protected
Check URL format and tweet ID
Try fallback method

"Network request failed"

Check internet connection
FxTwitter API may be temporarily down
Fallback to Nitter method

"All Nitter instances failed"

Nitter instances may be blocked or down
Wait and retry with FxTwitter API
Check firewall/proxy settings

Debug Mode

For debugging, run with verbose output:

bash -x scripts/read_tweet.sh "https://x.com/username/status/123"

Development & Customization

Adding New Data Sources

To add additional fallback methods:

Create new script in scripts/ directory
Follow same JSON output format
Update main skill logic to include new method
Test thoroughly and update documentation

Modifying Output Format

The JSON structure can be customized by modifying the final jq command in each script. Maintain consistency across all methods.

Adding Features

Consider these enhancement areas:

Sentiment analysis of tweet content
Hashtag and mention extraction
Link expansion and preview
Image OCR for text in media
Translation support for non-English tweets

Version History

v1.1 - Thread following (read_thread.sh), comprehensive media extraction (photos, videos, all media, article covers)
v1.0 - Initial release with FxTwitter API and Nitter fallback
Multi-source reliability with comprehensive data extraction
Full security audit compliance
Production-ready for ClawHub distribution